How to design an agent skill

How to design an agent skill is now a practical workflow question, not just an AI customization question.

OpenAI's Build skills documentation, Anthropic's Claude Agent Skills documentation, and VS Code's Agent Skills documentation all describe skills as reusable packages of instructions and supporting resources that agents can load when relevant.

The pattern now appears across ChatGPT, Codex, Claude, and GitHub Copilot surfaces. The common authoring format makes a working method easier to inspect and move, but it does not make every runtime identical. Each product can discover skills from different locations and expose different tools, permissions, and distribution models.

The useful design question is simple: what repeated job should the agent perform, and how will the team know it was done correctly?

Start with one workflow

Do not start by designing a general company skill.

Start with one repeated workflow that has a clear trigger and a clear outcome. Examples include preparing an approval packet, checking a ticket, formatting a report, classifying an intake, or producing a weekly status summary.

If the workflow cannot be described in one sentence, it is probably too broad for a first skill.

For example, “manage resource planning” is too broad. “Prepare a weekly allocation proposal from approved demand and capacity inputs, flag conflicts, and stop for the resource owner to approve it” is narrow enough to design and test.

Write a sharp trigger

The description is not decoration.

Across skills-compatible tools, the description helps the agent decide when the skill should be used. A vague description creates accidental invocation. A sharp description gives the agent a reliable route.

Good descriptions usually say:

• what the skill does
• when to use it
• what kind of input it expects
• what output it should produce
• when not to use it

That is the first layer of AI workflow governance.

Test the description with both positive and negative prompts. A resource-allocation skill should activate for a request to prepare the weekly proposal. It should not activate for a general question about hiring, an instruction to change payroll data, or a request to commit an allocation without approval.

Give the skill a small, visible structure

A portable skill normally begins as a directory containing a SKILL.md file. Its required metadata identifies the skill and explains what it does and when it should be used. The body contains the operating procedure. Supporting files sit beside it only when the procedure refers to them.

resource-allocation-proposal/
├── SKILL.md
├── references/
│   └── allocation-rules.md
├── templates/
│   └── proposal.md
└── scripts/
    └── validate-proposal.sh

The exact supported folders and metadata fields vary by agent surface. Keep the core method in the common format, then document any product-specific installation path or optional field separately. That preserves useful portability without promising identical behaviour everywhere.

Keep the instructions procedural

A good skill should read like a practical operating guide.

It should tell the agent how to inspect the input, what steps to follow, which evidence to check, what output to create, and when to stop for human review.

Avoid motivational language and broad principles. The agent needs procedure, not slogans.

A useful procedure names:

1. the accepted inputs and their source
2. the checks that must run before work begins
3. the transformation or analysis steps
4. the evidence that must accompany the result
5. the conditions that require the agent to stop
6. the person or role that owns the next decision

Include an expected output shape. “Prepare the report” leaves too much room for interpretation. A named template with required fields makes the result reviewable and makes omissions easier to detect.

Add resources only when they earn their place

Skills can include references, scripts, templates, examples, and assets. That does not mean every skill needs all of them.

Add resources when they reduce real ambiguity:

• a script that validates output
• a template that standardizes reports
• examples that show accepted quality
• a reference file that defines domain rules
• a checklist that keeps review consistent

If a resource is not used by the workflow, leave it out.

Keep credentials, tokens, and durable business records outside the skill. The skill can explain how to request data from an approved source or invoke a bounded tool, but it should not become a hidden store for sensitive values, live capacity, customer commitments, or final decisions.

Separate the skill from its authority

A skill teaches an agent how to perform a task. It does not grant the agent authority to perform every action mentioned in the instructions.

Automatic skill invocation is therefore not approval. Tool access should remain limited to the job, and consequential writes should require the confirmation appropriate to the surrounding workflow.

Define the review boundary

Human in the loop AI workflows need explicit stopping points.

The skill should explain what the agent can prepare and what the human must approve. That boundary is especially important when the workflow touches compliance, money, customer commitments, hiring, safety, or production systems.

If the agent is allowed to take action through a tool, the skill should be even clearer about confirmation and evidence.

Review every bundled script and external dependency as code. A shared skill can contain unsafe instructions, unexpected network access, or commands that exceed its stated purpose. Pin or version external material where possible, record its origin, and review updates before adopting them.

For a resource-allocation proposal, the agent might collect approved inputs, identify double-booking, calculate remaining capacity, and prepare options. It should stop when an input is missing, two sources disagree, a policy exception is required, or the requested change would create a commitment. The resource owner—not the skill—approves the allocation.

Make the skill versionable

The best custom AI workflows improve over time.

Keep the skill in a place where the team can review changes, discuss behavior, and update examples as the workflow matures. For many teams, that means keeping skills near the project or repository they support.

SwarmCraft's own packet and skills direction follows this pattern: keep the work visible, keep the workflow scoped, and keep the reusable agent behavior inspectable.

Versioning also makes failures actionable. When an output changes, the team should be able to identify the skill version, input set, tools used, validation evidence, and reviewer. Without that trace, teams can see that an answer is wrong but cannot reliably improve the method that produced it.

Test the workflow, not just the wording

A skill is not ready because its instructions look complete. Run representative tasks and inspect the evidence.

At minimum, test:

• a normal request with complete inputs
• an incomplete request that should stop
• a near match that should not trigger the skill
• conflicting evidence that should be surfaced rather than resolved silently
• a request that exceeds the agent's authority
• the output validator and human handoff

Record what success looks like before testing. For an allocation proposal, that could mean every demand item has a source, every person or constrained resource has a capacity basis, conflicts are visible, assumptions are labelled, and no commitment is written back before approval.

Tests should cover the host environment as well as the shared files. A skill that works in one agent may meet a different tool set, filesystem location, network policy, or approval model in another. Portability is an authoring advantage, not a substitute for runtime validation.

A simple agent skill checklist

Before a skill is ready, check:

• the trigger is specific
• the workflow has one clear outcome
• the instructions are procedural
• the required inputs are named
• the output format is defined
• review points are explicit
• authority and system-of-record boundaries are named
• scripts or references are included only when useful
• failure cases tell the agent when to stop
• positive, negative, and failure-path tests pass
• the result includes evidence a reviewer can inspect

That checklist is often more valuable than a bigger AI workflow platform.

The practical takeaway

Designing an agent skill is mostly workflow design.

Pick one repeated job, define how it should be done, give the agent only the resources and authority it needs, and keep review visible. That is how AI agents for workflow automation become useful without recreating SaaS sprawl under a new name.

In resource planning, that means keeping the skill focused on a repeatable stage such as proposal preparation. The wider resource allocation workflow still owns demand, capacity, routing, approval, commitment, change, and reconciliation. If unclear ownership has already produced duplicate trackers and planning tools, the problem is better understood through resource-planning sprawl.

Where to go next

For the full category framing, read AI agent skills: the new workflow layer. For terminology and ownership boundaries, read Skills vs tools vs MCP vs agents.