Comprehensive Guide to Agent Skills: Standards, Build Process, and Design Patterns

What Is an Agent Skill?

Agent Skills are structured, behavior‑oriented packages that go beyond simple prompts. Each Skill consists of a name and a description that define the task, required tools, workflow, and output boundaries, plus a SKILL.md file that contains the actionable instructions.

Official Specification

The Skill format follows the Anthropic standard released in December 2025 and is already adopted by more than 30 agents (Claude Code, OpenAI Codex, GitHub Copilot, VS Code, Cursor, Gemini CLI, Kiro, etc.). A minimal Skill directory contains:

skill-name/
├── SKILL.md      # YAML front‑matter + Markdown body (required)
├── scripts/      # optional executable scripts
├── references/   # optional reference documents
└── assets/       # optional static resources

YAML Front‑Matter Fields

name (required): unique identifier, 1‑64 characters, lowercase alphanumerics and hyphens only, no leading/trailing or consecutive hyphens, must match the folder name.

description (required): clear, keyword‑rich description of what the Skill does and when to use it, 1‑1024 characters, must contain trigger keywords.

license (optional): license identifier or file reference.

compatibility (optional): runtime environment constraints, up to 500 characters.

metadata (optional): custom key‑value pairs.

allowed-tools (optional, experimental): space‑separated list of pre‑authorized tools.

Naming Rules for name

1‑64 characters.

Only lowercase letters, digits, and hyphens.

No leading or trailing hyphen.

No consecutive hyphens.

Must match the parent directory name.

Good examples:

name: pdf-processing
name: data-analysis
name: code-review

Bad examples:

name: PDF-Processing   # uppercase not allowed
name: -pdf            # leading hyphen
name: pdf--processing # consecutive hyphens

Description Guidelines

1‑1024 characters.

Explain the Skill’s purpose and when to invoke it.

Include trigger keywords that the model can recognise.

Good description:

description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

Bad description:

description: Helps with PDFs.

Three‑Layer Progressive Loading

The core innovation is a three‑level loading strategy that mirrors UI progressive disclosure, dramatically reducing token usage.

L1 (Directory) : loads name + description at agent startup (system prompt). Cost ≈ 50‑100 tokens per Skill.

L2 (Instruction) : loads the full SKILL.md body when the user’s request matches the description. Suggested cost < 5000 tokens.

L3 (Resources) : loads files under scripts/, references/, assets/ on demand; cost depends on file size.

Even with 20 Skills, the initial load consumes only ~1‑2 K tokens – about a 90 % reduction compared with monolithic prompts.

Trigger Mechanism

The description drives model‑driven activation. The model decides whether the current user intent matches the description; no hard‑coded keyword matching is required. Effective descriptions use imperative language (e.g., “Use this skill when …”) and embed essential trigger terms.

Skill‑Creator Engine

Skill‑Creator is Anthropic’s “Skill‑building Skill”. It brings software‑engineering practices – CI/CD, A/B testing, performance benchmarks – into prompt engineering.

Full Development Lifecycle (6 stages)

Requirement Capture : clarify intent, output format, and validation criteria.

Skill Authoring : create SKILL.md and supporting resources.

Test Execution : design 2‑3 test cases, run parallel with‑skill and without‑skill agents (A/B test).

Evaluation : Grader scores assertions, Comparator performs blind A/B comparison, Analyzer extracts insights.

Iterative Improvement : incorporate feedback, avoid over‑fitting, rewrite the Skill.

Optimization & Release : description tuning, train/test split, final packaging into a .skill file.

Agent Roles

Grader Agent : validates each assertion, produces PASS/FAIL grades, and flags weak passes.

Comparator Agent : blind comparison of two runs, scores content (1‑5) and structure (1‑5), aggregates to a 1‑10 total.

Analyzer Agent : post‑hoc analysis, categorises issues, suggests improvements, highlights statistical patterns.

Practical Example: Building a Code‑Review Skill

The article walks through a complete workflow:

Prompt Claude to create a Skill for code review.

Define a minimal SKILL.md (name + description).

Add 2‑3 test cases.

Run evaluation (with‑skill vs without‑skill) and view results in the Eval Viewer.

Iterate using the generated feedback.json.

Package the final Skill.

Packaging command:

python -m scripts.package_skill path/to/code-review

Advantages and Known Limitations

Advantages

Complete methodology – brings ML‑style training/validation to prompt engineering.

Rigorous evaluation – three specialised agents provide quantitative feedback.

Zero‑dependency, pure‑Python implementation (standard library + claude CLI).

Human‑in‑the‑loop design – Eval Viewer lets users verify quality while automation handles repetitive work.

Known Limitations (community‑reported)

High token cost : a single description‑optimisation run with 20 eval queries (60 sessions) consumed ~69 % of a 5‑hour quota (GitHub #514). Suggested fix: use a cheaper model such as claude‑haiku for evaluation.

Complex workflow : multiple confirmation steps (review, feedback, re‑run) make simple Skills slower to develop than hand‑written SKILL.md.

Task‑type bias : “operational” Skills (e.g., script execution) often have 0 % recall because the base model handles the task directly, bypassing the Skill.

Skill bloat : iterative improvements can inflate a Skill from ~5 KB to ~50 KB, hurting latency.

Steep learning curve : users must understand three‑layer loading, JSON schema hierarchy, and the four‑agent ecosystem.

Design Patterns for Skills (Google ADK)

Five recurring patterns help structure Skills:

Tool Wrapper – load external standards or libraries on demand (e.g., FastAPI conventions).

Generator – template‑driven document creation with explicit user prompts for missing data.

Reviewer – separate “what to check” checklist from “how to check” logic, providing graded feedback.

Inversion – the Skill first asks the user for requirements before proceeding.

Pipeline – strict multi‑step workflow with mandatory checkpoints (e.g., API doc generation).

Choosing a Pattern

Match the problem to the pattern:

Expert knowledge → Tool Wrapper

Structured output → Generator

Automated audit → Reviewer

Ambiguous requirements → Inversion

Complex multi‑stage tasks → Pipeline

Pattern Combinations

Pipeline + Reviewer : add automatic quality check at the final step.

Generator + Inversion : collect information first, then fill a template.

Pipeline + Tool Wrapper : load expert knowledge at specific stages.

Inversion + Pipeline : gather requirements before entering the execution pipeline.

Key Takeaways

Agent Skills are structured behaviours, not mere prompts.

Three‑layer progressive loading solves context‑window bloat.

The description is the primary trigger; keep it concise and imperative.

Skill‑Creator provides a rigorous, ML‑inspired development loop.

Design patterns guide reusable Skill architecture.

References

Agent Skills Specification – https://agentskills.io/specification

Anthropic Skills Repository – https://github.com/anthropics/skills

Superpowers Framework – https://github.com/obra/superpowers

Google ADK Design Patterns – https://x.com/GoogleCloudTech/status/2033953579824758855

Awesome Agent Skills – https://github.com/VoltAgent/awesome-agent-skills