5 Agent Skill Design Patterns for Reliable Workflows

The five most useful agent skill design patterns are fastest truth path, evidence-first completion, reference pack, stop-rule ladder, and feedback loop. Together, they turn a skill from "please do this well" into a reusable operating procedure that an agent can discover, run, verify, and improve.

That distinction matters because skills now sit between three layers that are easy to blur. A prompt asks for one result. A tool or MCP server gives the agent a capability, such as reading GitHub, querying a database, or creating a ticket. A skill defines the repeatable job: where to start, what source wins, what evidence is required, when to stop, and how the next version should improve. If you need the category definition first, start with What Is an Agent Skill?. If you are separating skills from connectors or scripts, Agent Skill vs Tool and Agent Skill vs Code cover the neighboring boundaries.

OpenAI's Codex skills documentation describes a skill as a directory with SKILL.md plus optional scripts/, references/, and assets/. The open Agent Skills specification uses the same basic shape: discovery starts from the skill name and description, activation loads the full SKILL.md, and execution may load supporting files or run bundled code. Anthropic's Agent Skills overview frames custom skills as packaged domain expertise and organizational knowledge. The patterns below are the practical design moves inside that package.

LangChain's skills pattern is a useful cross-check: use skills when one agent needs many on-demand specializations, and use heavier routing, graph, or subagent patterns when execution order and handoffs must be enforced in code.

The fastest truth path pattern tells the agent which source to inspect first, which source to trust next, and which tempting source to avoid.

Use it when the workflow touches code, docs, analytics, CRM records, issue trackers, design files, or policy documents. These jobs fail when the agent starts from whatever is easiest to search instead of whatever is most authoritative. A documentation-review skill that starts from old blog posts can produce polished lies. A support-triage skill that starts from a customer's last Slack message but never checks the account record can misclassify the case.

Template:

Start with these sources in order:
1. <source with highest authority for current truth>
2. <source that explains recent changes>
3. <source that gives historical context>
Do not rely on <weak source> unless the first two sources are unavailable.
If sources disagree, report the conflict instead of choosing silently.

For a docs review skill, the rule might be:

First inspect the published API reference, then the SDK source, then the
migration guide draft. Do not infer parameter names from old examples.

For a revenue-ops skill, it might be:

Read the CRM opportunity first, then billing status, then call notes.
Never use the call transcript alone to decide contract status.

The tradeoff is maintenance. A fastest truth path gets stale when teams move docs, rename dashboards, or change source-of-truth ownership. Keep the source names concrete enough to guide the agent, but avoid brittle page titles when stable directories, API endpoints, or system names exist. If your skill is for a codebase, prefer file paths and commands. If it is for a business process, name the system of record and the freshness rule.

This is the same principle behind Skillfully's guide to designing the skill contract: the skill should not merely describe the desired output. It should tell the agent which inputs and sources are allowed to support that output.

Evidence-first completion defines what the agent must show before it can say the work is done.

This pattern is mandatory for workflows where a human reviewer needs trust, not just a confident summary. Code review, data analysis, security triage, docs publishing, customer escalation, and QA all need visible proof. Google's ADK evaluation docs are a useful parallel: agent behavior can be judged through tool trajectory, response quality, groundedness, safety, and task success. OpenAI's guide to testing agent skills with evals makes the same point for skills: a useful run leaves a trace, artifacts, checks, and a score you can compare over time.

Completion evidence can include:

• changed file paths
• test commands and results
• screenshots or preview URLs
• source citations
• before/after examples
• artifact names
• skipped checks with reasons
• a decision label such as ship, revise, or block

Template:

Before reporting completion, include:
1. Result: what changed or what decision was made
2. Evidence: files, sources, screenshots, commands, or records inspected
3. Verification: checks run and exact result, or reason not run
4. Risk: remaining uncertainty or blocker

Example for a pull-request review skill:

Return findings only if each finding names severity, file, line, issue,
and evidence. If you did not run tests, include the skipped-test reason.

Example for a customer-feedback-to-issue skill:

Return the created issue link, customer quote, duplicate search result,
product area, severity reason, and missing information.

The tradeoff is verbosity. If every small task requires a courtroom brief, the skill becomes annoying and agents may waste time proving obvious facts. Make evidence proportional to risk. A skill that drafts internal meeting notes may only need source links and a "not verified" note. A skill that proposes a production change should require commands, artifacts, and remaining risk.

Evidence-first completion is also the bridge between authoring and testing. How to Test an Agent Skill Before You Publish It is much easier to apply when the skill already returns stable sections that a reviewer or script can inspect.

The reference pack pattern keeps the core SKILL.md lean while moving bulky examples, templates, rubrics, schemas, and background material into supporting files.

This pattern exists because skills use progressive disclosure. Anthropic's engineering post on equipping agents with skills gives a concrete example: a PDF skill can keep its core instructions short while referring to separate files for form-filling details. OpenAI's Skills in API cookbook describes the same bundle shape: a required SKILL.md anchored by optional scripts, assets, templates, and sample inputs.

Use a reference pack when:

• examples are too long for the main skill
• the workflow needs templates, schemas, rubrics, or source docs
• different runs need different reference files
• deterministic helpers belong in scripts
• the skill would otherwise become a long manual

Common structure:

my-skill/
  SKILL.md
  references/
    examples.md
    review-checklist.md
    output-template.md
    domain-glossary.md
  scripts/
    validate-output.ts
  assets/
    report-template.docx

The key is not merely placing files beside the skill. The main instructions must say when each file matters.

Good:

If the task involves enterprise pricing, read references/pricing-policy.md
before drafting. If the output is a customer memo, use
references/customer-memo-template.md.

Weak:

Read all files in references before starting.

The second version defeats progressive disclosure. It loads too much context and increases the chance that stale or irrelevant detail competes with the current task. Anthropic's skill authoring best practices make the same point from another angle: concision still matters once the skill is loaded because every token competes with the active conversation and task context.

The tradeoff is discoverability inside the skill. If the reference tree gets too deep, the agent may miss the right file. Use obvious names, short decision rules, and one or two canonical examples in SKILL.md. Put the long example library in references/.

The stop-rule ladder tells the agent what to do when a prerequisite is missing, a source is unavailable, permission is blocked, or the next action would be unsafe.

Weak skills assume the happy path. Strong skills name the blocker path before the agent encounters it. This matters because agents often try to be helpful by substituting weaker evidence: a stale cache for a live record, a memory of the policy for the current policy, a guess about a missing field, or a draft action where a human approval is required.

Template:

If <required input> is missing, ask for it.
If <primary source> is unavailable, use <fallback> and mark confidence lower.
If both are unavailable, stop and report the blocker.
If the next step would publish, send, delete, charge, merge, or notify,
prepare the evidence but wait for explicit approval.
Never invent <critical field>.

This pattern fits especially well with tool-rich agents. The MCP tools specification explains that tools can let models query databases, call APIs, or perform computation, and it recommends visible human control for tool invocations. The skill should define the business rule for when capability is not enough. MCP can expose linear.createIssue or github.mergePullRequest; the skill decides when the agent may prepare the action, when it may execute it, and when it must stop.

LangGraph's interrupts documentation shows the runtime version of this idea: pause graph execution, persist state, wait for external input, and resume later. A skill should not reimplement LangGraph, ADK callbacks, or MCP confirmations. It should state the domain rule that those mechanisms enforce.

Example for a release skill:

If CI is red, stop and report failing checks.
If changelog entries are missing, draft them but do not tag a release.
If the release affects billing, prepare the release notes and request approval.
Never publish from a dirty worktree.

Example for a support refund skill:

If the account lookup fails, stop.
If duplicate-charge evidence exists, draft the refund explanation.
Do not issue the refund unless the user explicitly approves the amount.

The tradeoff is friction. Too many stop rules can make the skill timid. Use a ladder, not a wall: ask when the missing input is easy to supply, fall back when the fallback is acceptable, mark confidence when partial work is still useful, and stop only when continuing would produce false confidence or unsafe action.

The feedback loop pattern turns real skill runs into product data for the next version.

A reusable skill is not finished because it worked once. It is a workflow asset, and workflow assets improve through repeated attempts. OpenAI's Codex use case for saving workflows as skills starts from a working example such as a PR thread, release checklist, runbook, or useful prior answer, then recommends using the skill and updating it when it uses the wrong command, misses a rule, or writes a draft you would not send. That is the right maintenance loop.

A practical skill feedback block is short:

After the task attempt, report:
- outcome: success, partial, or blocked
- rating: positive, neutral, or negative
- what worked
- what failed or slowed the run
- one suggested edit to this skill

For a shared skill, capture feedback in a place the author will actually inspect: a Skillfully feedback entry, a GitHub issue, a changelog note, or an internal review queue. The important part is that the run identifies the failing instruction, not just the failing output. "The answer was bad" is hard to act on. "The skill read the migration guide before the API reference and copied an old parameter name" points directly back to the fastest truth path.

Feedback also separates skill maintenance from agent blame. If five agents miss the same source, the source rule is probably unclear. If a skill gets invoked for the wrong tasks, the description may need stronger trigger words or negative examples. OpenAI's shell and skills tips describe skill descriptions as routing logic rather than marketing copy: they should say when to use the skill, when not to use it, and what output proves success.

The tradeoff is interruption. Do not make the agent stop mid-task to ask whether the skill is good. Put feedback after the attempt, while the run is fresh. Skillfully's install feedback collection guide uses the same principle: collect enough signal to improve the next version without derailing the current job.

If the skill fails because...	Use this pattern	Concrete fix
The agent starts in the wrong place	Fastest truth path	Name the source order and conflict rule
The final answer is hard to verify	Evidence-first completion	Require changed files, citations, checks, or artifacts
The skill is too long or overloaded	Reference pack	Move examples, templates, and scripts into supporting files
The agent guesses when blocked	Stop-rule ladder	Define ask, fallback, partial, and stop behavior
Failures repeat without improvement	Feedback loop	Capture outcome, blocker, and suggested skill edit

These patterns compound. A code-review skill might use fastest truth path to read the diff before project docs, evidence-first completion to require file-line findings and test results, reference pack to hold the severity rubric, stop-rule ladder to avoid touching unrelated code, and feedback loop to record which findings reviewers accepted.

Good agent skills are designed, not just written. Start with one repeatable job, then add the pattern that addresses the main failure mode. If the agent starts from bad sources, fix the truth path. If reviewers cannot trust the result, add evidence. If the skill is bloated, split references. If the agent guesses, add stop rules. If the same failure repeats, close the feedback loop.

The durable test is simple: could another agent run this skill next month, inspect the right sources, produce reviewable evidence, stop safely, and teach you what to improve? If yes, you have moved beyond a prompt. You have a reusable workflow worth publishing, testing, and maintaining.