5 Skill Design Patterns

Five reusable structural templates for organizing SKILL.md content in agent systems

Every agent skill follows the same SKILL.md specification — YAML frontmatter, markdown instructions, and optional resource directories. But the same format can serve very different purposes. These five patterns each structure the content differently: different instruction styles, different resource types, and different relationships between instructions and supporting files.

Choosing the Right Pattern Decision guide for SKILL.md design Start Produces output? YES NO From a template? NO YES Tool Wrapper api_call Generator document_create Evaluates existing input? YES NO Reviewer book_open Needs user input first? YES NO Inversion flip_perspective Has ordered steps? YES NO Pipeline step_sequence Tool Wrapper api_call

Pattern 1: Tool Wrapper — Teach the Agent a Library

Package a library or tool’s conventions into on-demand knowledge that the agent loads when working with that technology.

Pattern 1: Tool Wrapper Teach the agent a library SKILL.md Trigger keywords Review + Write instructions load_skill _resource references/ conventions.md Best practices & rules Knowledge applied Agent applies rules Domain expert behavior when skill is loaded No scripts, no templates — pure knowledge

Key Characteristics:

  • Simplest pattern — instructions + reference files
  • No templates or scripts required
  • Uses references/ directory for detailed convention docs
  • Agent becomes an instant expert when the skill activates

When to use: When consistency matters for a specific library or framework across your codebase.

Real-world examples: FastAPI best practices, Terraform patterns, security policies, database query optimization.

skill/
  SKILL.md            # Instructions: when to apply, key rules
  references/
    conventions.md    # Detailed patterns, anti-patterns, examples

Pattern 2: Generator — Produce Structured Output

Generate documents, reports, or configurations by filling a reusable template with consistent structure every time.

Pattern 2: Generator Produce structured output from templates SKILL.md Step-by-step generation process HOW to write WHAT to produce references/ style-guide.md Tone, formatting rules assets/ report-template.md Output structure Fill template Structured Output Report, doc, or config filled Template enforces structure, style guide enforces quality

Key Characteristics:

  • Uses both assets/ (output template) and references/ (style guide)
  • Instructions orchestrate the template-filling process
  • Enforces structure over creativity
  • Swap template files to change output without modifying instructions

When to use: Output requires fixed structure and consistency matters more than flexibility.

Real-world examples: Technical reports, API documentation, commit messages, project scaffolding.

skill/
  SKILL.md            # Instructions: how to fill the template
  assets/
    template.md       # Output skeleton with placeholders
  references/
    style-guide.md    # Tone, formatting, terminology rules

Pattern 3: Reviewer — Evaluate Against a Standard

Evaluate code or content against a checklist stored in references/, producing scored findings grouped by severity.

Pattern 3: Reviewer Evaluate against a standard User's Code Input to review code_file Submit SKILL.md Review protocol Load, Apply, Report Load rules Produce references/ review-checklist.md Rules by severity Review Report Findings by severity Score + Recommendations Swap the checklist to get a different review type

Key Characteristics:

  • Separates WHAT to check (checklist file) from HOW to check (review protocol)
  • Produces severity-classified findings (error, warning, info)
  • Supplies line numbers, explanations, and specific fixes
  • Checklist drives behavior, not agent pre-training

When to use: Anywhere a human reviewer would work from a checklist.

Real-world examples: Code quality reviews, security audits, editorial reviews, governance validation.

skill/
  SKILL.md            # Instructions: review protocol, output format
  references/
    checklist.md      # What to check, severity classifications

Pattern 4: Inversion — The Skill Interviews You

Flip the interaction — the skill instructs the agent to ask structured questions through defined phases before producing any output.

Pattern 4: Inversion The skill interviews you Phase 1: Discovery Q1: Problem? Q2: Users? Q3: Scale? All answered Phase 2: Constraints Q4: Platform? Q5: Stack? Q6: Reqs? All answered Phase 3: Synthesis Load template Fill → Confirm Agent asks → User answers → Skill drives the conversation Gather requirements through structured questions Narrow scope with technical constraints Generate output from collected answers Unlike other patterns, Inversion reverses control — the skill asks questions before producing output

Key Characteristics:

  • Multi-turn interaction where the agent gathers context first
  • Phased structure (phases must complete sequentially)
  • Uses explicit gates like “DO NOT start building until all phases complete”
  • Prevents agents from generating output based on assumptions

When to use: Agent needs comprehensive context from the user before producing useful work.

Real-world examples: Requirements gathering, diagnostic interviews, configuration wizards, system design interviews.

skill/
  SKILL.md            # Instructions: phases, questions, gate conditions
  assets/
    question-bank.md  # Structured questions per phase

Pattern 5: Pipeline — Enforce a Multi-Step Workflow

Define a sequential workflow where each step must complete before the next begins, with explicit gate conditions preventing step skipping.

Pattern 5: Pipeline Enforce a multi-step workflow with gates Step 1 Step 2 Step 3 Step 4 search_code Parse & Inventory Gate 1 Yes edit_document Generate Docstrings Gate 2 Yes merge_documents Assemble Docs verified Quality Check User confirms? User approves? Gate conditions prevent skipping validation

Key Characteristics:

  • Most complex pattern (uses all three optional directories)
  • Steps execute sequentially with diamond gate conditions
  • “User confirms?” gates prevent validation bypass
  • Each step loads only needed resources

When to use: Multi-step processes where order matters and skipping validation would produce incorrect output.

Real-world examples: Documentation generation, data processing, deployment workflows, agent onboarding.

skill/
  SKILL.md            # Instructions: step sequence, gate conditions
  references/
    standards.md      # Quality criteria per step
  assets/
    output-template.md
  scripts/
    validate.sh       # Automated validation between steps

Choosing the Right Pattern

PatternUse when…Directories usedComplexity
Tool WrapperAgent needs expert knowledge about a specific technologyreferences/Low
GeneratorOutput must follow a fixed template every timeassets/ + references/Medium
ReviewerCode or content needs evaluation against a checklistreferences/Medium
InversionAgent must gather context from the user before actingassets/Medium
PipelineWorkflow has ordered steps with validation gatesreferences/ + assets/ + scripts/High

Patterns compose. A Pipeline can include a Reviewer step. A Generator can use Inversion to gather inputs. A Tool Wrapper can be embedded as a reference file inside a Pipeline. Production systems typically combine 2-3 patterns.

If you’re unsure, start with Tool Wrapper — it’s the simplest and most widely adopted. Graduate to other patterns as complexity requires.

FAQ

Can skills work across different agent tools? Yes. Skills following the agentskills.io specification work across 30+ tools including Claude Code, Gemini CLI, Cursor, GitHub Copilot, and others.

Can patterns be combined? Yes. A Pipeline skill can include Reviewer steps. A Generator can use Inversion for input gathering. Production systems use a median of 2 patterns per skill.

What is the difference between skills and tools? Tools give agents the ability to take actions — call APIs, read files, query databases. Skills teach agents when and how to use those tools effectively.

Which pattern should I start with? Start with Tool Wrapper — just instructions plus reference files. Wrap your team’s coding conventions or a library’s best practices into a SKILL.md with a references/ directory.

How do I test a skill’s effectiveness? Create test cases, run each with and without the skill, and measure the pass rate delta.

References

Was this page helpful?
Edit on GitHub