Five Best Design Patterns for AI Agent Skills

When building SKILL.md files for AI agents, developers often focus first on format—YAML correctness and directory layout—while the real challenge lies in designing the skill’s internal behavior. As dozens of agent tools adopt similar skill structures, the article presents five design patterns that guide logic organization, context loading, user prompting, and checkpoint enforcement.

Pattern 1: Tool Wrapper

A tool wrapper provides on‑demand context for a specific library, framework, or internal guideline. The skill watches for trigger keywords (e.g., FastAPI, Next.js, Tailwind) and, when activated, loads the appropriate reference file from references/ and injects those rules as high‑priority context.

Example: a FastAPI wrapper skill loads references/conventions.md containing routing, dependency‑injection, error‑handling, and response conventions, ensuring code generation stays aligned with team standards without burdening every conversation with the full spec.

# skills/api-expert/SKILL.md
---
name: api-expert
description: FastAPI development best practices and conventions. Used for building, reviewing, or debugging FastAPI apps, REST APIs, or Pydantic models.
metadata:
  pattern: tool-wrapper
  domain: fastapi
---
You are a FastAPI development expert. Apply the following conventions to the user's code or question.

## Core Conventions
Load `references/conventions.md` to obtain the full FastAPI best‑practice list.

## When reviewing code
1. Load the conventions reference.
2. Check the user's code against each rule.
3. For every violation:
   - Cite the specific rule.
   - Explain the issue.
   - Offer a remediation suggestion.

## When writing code
1. Load the conventions reference.
2. Strictly follow all conventions.
3. Add type annotations to all function signatures.
4. Use `Annotated` style for dependency injection.

Pattern 2: Generator

The generator pattern fixes the output structure so the agent fills a template rather than improvising. Two optional directories are used: assets/ for output templates (e.g., report frameworks) and references/ for style guides (tone, required sections, prohibited words). The skill acts like a project manager: load the template, load the style guide, ask the user for missing variables, then render the final document.

This reduces randomness for tasks such as API documentation, technical reports, or project retrospectives, ensuring each generated artifact contains all required sections.

# skills/report-generator/SKILL.md
---
name: report-generator
description: Generate structured Markdown technical reports. Used when a user asks to write, create, or draft a report, summary, or analysis document.
metadata:
  pattern: generator
  output-format: markdown
---
You are a technical report generator. Follow these steps strictly:

## Step 1: Load style guide
Load `references/style-guide.md` to obtain tone and formatting rules.

## Step 2: Load report template
Load `assets/report-template.md` to obtain the required output structure.

## Step 3: Ask for missing information
Prompt the user for:
- Topic or research object
- Key findings or data points
- Target audience (technical, managerial, or general)

## Step 4: Fill the template
Populate the template according to the style guide.

## Step 5: Return the report
Return the completed Markdown document.

Pattern 3: Reviewer

The reviewer separates “what to check” from “how to check.” A checklist file (e.g., references/review-checklist.md) defines the criteria, and the skill loads it, iterates through the items, and produces structured feedback grouped by severity (P0, P1, P2 or error, warning, info).

By swapping the checklist, the same skill can become a Python code reviewer, a security audit tool (OWASP checklist), or a UI accessibility reviewer.

# skills/code-reviewer/SKILL.md
---
name: code-reviewer
description: Review Python code quality, style, and common issues. Used when a user submits code for review, feedback, or audit.
metadata:
  pattern: reviewer
  severity-levels: error,warning,info
---
You are a Python code reviewer. Follow this process strictly:

## Step 1: Load review checklist
Load `references/review-checklist.md` to obtain the full set of review standards.

## Step 2: Read the code carefully
Understand the code’s purpose and overall logic before asking questions.

## Step 3: Apply each rule
For every rule in the checklist, check the code and, for each issue, provide:
- Line number or approximate location
- Severity (error, warning, info)
- Explanation of why it is a problem
- Concrete fix suggestion with corrected code example

## Step 4: Output structured results
Include sections:
### Summary – overall purpose and quality rating
### Findings – grouped by severity (errors, warnings, info)
### Score – 1‑10 rating with brief rationale
### Top 3 Recommendations – most impactful improvements

Pattern 4: Inversion

Inversion flips the usual flow: instead of the user feeding information, the agent first asks targeted questions to gather all necessary context before any generation begins. Strict gate rules prevent the agent from proceeding until each question is answered.

A project‑planner skill exemplifies this: it asks about the problem to solve, target users, scale, deployment environment, tech‑stack preferences, and non‑negotiable constraints before producing a plan.

# skills/project-planner/SKILL.md
---
name: project-planner
description: Collect structured requirements and create a plan for a new software project. Triggered by phrases like “I want to build”, “help me plan”, or “design a system”.
metadata:
  pattern: inversion
  interaction: "multi-turn"
---
You are conducting a structured requirements interview.
Do not start building a solution until all phases are completed.

## Phase 1 – Problem discovery
Ask one question at a time and wait for the user’s answer.
1. What problem does this project solve?
2. Who are the primary users and what is their technical level?
3. What scale is expected (daily users, data volume, request rate, etc.)?

## Phase 2 – Technical constraints (only after Phase 1 is finished)
4. What deployment environment will you use?
5. Any preferred tech stack?
6. Non‑negotiable requirements (latency, availability, compliance, budget, …)?

## Phase 3 – Integrated solution (only after all questions are answered)
1. Load `assets/plan-template.md` for output format.
2. Fill each section with the gathered information.
3. Present the full project plan.
4. Ask the user if the plan accurately reflects their needs and what should be modified.
5. Iterate until the user confirms.

Pattern 5: Pipeline (Workflow)

Complex tasks are split into a strict multi‑step workflow with checkpoint nodes that pause execution until confirmation or a condition is met. The SKILL.md file itself defines the workflow, loading different references/ and assets/ at each step.

Example: a documentation pipeline parses Python code, generates docstrings using a style guide, assembles an API reference, and finally runs a quality checklist before delivering the final document.

# skills/doc-pipeline/SKILL.md
---
name: doc-pipeline
description: Generate API documentation from Python source through a multi‑step pipeline. Used when a user requests module documentation, API docs, or code‑based docs.
metadata:
  pattern: pipeline
  steps: "4"
---
You are running a documentation pipeline. Execute each step in order; do not skip steps. If a step fails, stop.

## Step 1 – Parse and inventory
Analyze the provided Python code, extract all public classes, functions, and constants. Present the list and ask the user: “Is this the complete public API you want documented?”

## Step 2 – Generate docstrings
For each function missing a docstring:
1. Load `references/docstring-style.md` for required format.
2. Generate a docstring following the style guide.
3. Show each generated docstring to the user for confirmation.
Do not proceed to Step 3 until the user confirms.

## Step 3 – Assemble documentation
Load `assets/api-doc-template.md` for output structure. Compile all classes, functions, and docstrings into a complete API reference.

## Step 4 – Quality check
Use `references/quality-checklist.md` to verify:
- Every public symbol is documented.
- Each parameter has a type and description.
- Every function includes at least one usage example.
Report the results. If issues are found, fix them before presenting the final document.

Choosing the Right Pattern

If you need the agent to master a library, framework, or team guideline, use the Tool Wrapper.

If you need stable, structured output, use the Generator.

If you need the agent to follow a checklist for code or plan review, use the Reviewer.

If requirements are incomplete and premature generation would cause rework, use Inversion.

If the task has explicit steps with mandatory checkpoints, use the Pipeline.

Combining Patterns

Patterns are not mutually exclusive. A pipeline skill can end with a reviewer step to validate its own output. A generator can start with an inversion step to collect missing variables before filling the template. This composability enables complex, reliable agent behavior without overloading the system prompt.

By breaking a monolithic prompt into structured patterns, agents load only the necessary context at each stage, keeping the interaction lightweight and predictable.