design-to-code

Agent Skills: A Complete Guide

A consolidated reference on what agent skills are, why they exist, how they work, and how to write effective ones.

---

1. What agent skills are

An Agent Skill is a folder containing a SKILL.md file (YAML frontmatter + markdown instructions), plus optional subfolders for scripts, references, and assets that the agent loads on demand.

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code (CLIs, validators, helpers)
├── references/       # Optional: detailed docs loaded only when needed
└── assets/           # Optional: templates, fonts, static files

Skills are an open standard (agentskills.io), originally created by Anthropic and adopted by OpenAI Codex, Cursor, Gemini CLI, Microsoft Agent Framework, Google ADK, and 40+ other agent products. The core folder and SKILL.md format are portable, but optional behavior such as invocation control can be client-specific.

---

2. Why this abstraction exists

Base LLMs are generalists. Real work requires procedural knowledge, organizational context, and repeatable workflows. Every prior alternative had a failure mode:

Approach	Problem
Stuff it into the system prompt	Always loaded → context bloat at scale
Re-paste instructions each session	No version control, no consistency
Fine-tuning	Slow, expensive, opaque, vendor-locked
MCP servers alone	Give the agent tools but no workflows for using them

Skills solve four problems at once:

• Context efficiency, instructions load only when relevant
• Repeatability, multi-step procedures become auditable workflows
• Composability, multiple skills combine at runtime per task
• Portability, same files work across vendors and surfaces

Mental model: skills are to LLMs what man pages, runbooks, and team handbooks are to engineers, reference material loaded into working memory only when the task demands it.

---

3. How they work, progressive disclosure

The architectural core. Three-stage loading:

Level 1, Discovery (~100 tokens per skill, always in context): Only name + description from frontmatter are injected into the system prompt at startup. Agent knows the skill exists and when it applies. You can install dozens of skills with negligible overhead.

Level 2, Activation (<5,000 tokens, loaded on match): When the user's request matches a skill's description, the agent reads the full SKILL.md body into context.

Level 3, Execution (unbounded, on demand): The agent reads referenced files (references/foo.md) or runs scripts (scripts/validate.py) only as needed. Scripts can execute without their source being loaded into context at all.

This is why bundled content has no practical limit. Files don't consume tokens until accessed.

---

4. SKILL.md anatomy

---
name: skill-name
description: What this skill does AND when to use it. Include trigger phrases the user will say.
---

# Skill Name

## Quick start
[Minimal working example]

## Workflow
[Step-by-step procedure with checklists]

## Output format
[What the user/agent should expect back]

## Advanced
[Link to references/ for rarely-needed detail]

Frontmatter constraints:

• name is lowercase, hyphens only, 1 to 64 chars, exactly matches the parent folder name
• Avoid < and > in frontmatter (they can inject into the system prompt)
• Invalid YAML silently prevents loading
• Never put : (colon + space) inside an unquoted description, strict YAML parsers (e.g. Pi's) reject it as a nested mapping ("Nested mappings are not allowed in compact mappings"), even though lenient parsers (Claude Code) accept it. If the text needs a mid-sentence colon, single-quote the whole value and double any inner apostrophes: description: 'Differentiator: measures prod state, does not change it.'

Manual-only invocation is client-specific

disable-model-invocation: true is not part of the core Agent Skills specification. It is a client extension supported by Claude Code and VS Code/Copilot. In those clients, put it in SKILL.md frontmatter to prevent automatic invocation while keeping explicit invocation available.

OpenAI Codex uses a separate file at agents/openai.yaml inside the skill:

policy:
  allow_implicit_invocation: false

For a manual-only skill shared across Claude Code, VS Code/Copilot, and Codex, include both configurations. Never assume a client-specific frontmatter field works in every Agent Skills implementation; verify each target client's documentation and test implicit invocation in each runtime.

---

5. Two design philosophies

Skills tend to fall into one of two patterns. Both are valid; they solve different problems.

Pattern A, Capability primitives (tool wrappers)

The skill is a thin wrapper over a deterministic CLI or script. Logic lives in code. SKILL.md teaches the agent how to invoke it.

• Adds: new capabilities (search, email, browser, API access)
• Reliability via: shell tools, not prompts
• Typical length: 30 to 80 lines, mostly command examples
• Use when: the bottleneck is "the agent can't do X"

Pattern B, Process primitives (cognitive disciplines)

The skill encodes a methodology the agent should follow. Pure prompt engineering, no scripts needed.

• Adds: structured workflows (TDD, code review, design alignment, debugging loops)
• Reliability via: explicit procedure, checklists, validation loops
• Use when: the bottleneck is "the agent's output quality or process is bad"

A mature setup uses both. Pattern A gives the agent better tools. Pattern B gives it better methods for using them.

---

6. How to write effective skills, do this

Description as routing contract

The description is the only thing the agent sees before deciding to load the skill. If your skill doesn't trigger, the description is wrong 95% of the time, not the body.

Include three elements:

1. What the skill does (one phrase)
2. When to use it (trigger phrases, situations)
3. Differentiator vs related skills (prevents routing conflicts)

Pattern: "X via Y. Use for [situations]. [Differentiator: no Z required / faster than W / handles edge case V]."

Never summarize the full workflow in the description. If the description contains a step-by-step summary of how the skill works, the agent tends to follow that summary and skip loading the body. Describe what and when, never how. The description answers "should I open this skill now?", not "what are the steps?"

Keep SKILL.md lean

• Beyond a certain length, you're usually encoding logic that should be in a script or referenced file

Bash-first, prose-second

Concrete command examples with inline comments beat prose explanations. The agent pattern-matches on syntax. Show, don't describe.

Push determinism into code

Anything fragile, repetitive, or where variation is a bug → script. Use markdown only for tasks requiring judgment.

Match strictness to task fragility (degrees of freedom)

Scale instruction rigidity to how costly a wrong move is:

• Loose natural-language heuristics when many approaches are valid (e.g. code review).
• Pseudocode or templates when there's a preferred pattern but variation is acceptable (e.g. report format).
• Exact scripts and strict step lists when the workflow is fragile, error-prone, or consistency-critical (e.g. migrations, document patching).

Build validation loops

The single biggest output quality improvement: state a verify → fix → re-verify loop explicitly.

• Document skills: visual QA pass before delivery
• Code skills: tests pass + zero type errors before completion
• Data skills: schema validation before output

State-check before action

Don't assume setup is done. Instruct the agent to verify state, then branch:

First check if X is configured: [command]
If not, walk the user through setup: [steps]

Just-in-time loading with explicit pointers

Tell the agent exactly when to read each referenced file:

For standard cases, follow the steps below.
For [specific edge case], read references/edge-cases.md first.

Keep references one level deep

Link referenced files directly from SKILL.md. Never build chains (SKILL.md → advanced.md → details.md → actual.md), the agent may preview nested files only partially and miss critical instructions. Add a table of contents to any reference file longer than 100 lines.

Document output formats

If your script returns structured data, show the agent what it looks like. Enables reliable downstream parsing.

Defer to --help for completeness

List the 80% common operations in SKILL.md. Tell the agent to run tool --help for the rest. Keeps SKILL.md small without losing functionality.

Compose primitives, don't bundle workflows

One skill = one capability or one discipline. Resist bundling concerns into "the X workflow." Multiple small skills combine at runtime; one large skill is rigid.

Cite established principles when applicable

If your skill encodes a known engineering methodology (TDD, DDD, red-green-refactor), name the source. Gives the agent a coherent model to align with and gives users a way to verify the design.

Persistent artifacts for cross-session memory

Skills can write to repo-level files (CONTEXT.md, ADRs, decision logs) that future agent sessions read. This is how you fight the "agents have no memory" problem at the architecture level.

---

7. What not to do, anti-patterns

Don't re-teach what the model already knows

Every line in SKILL.md should provide context the model doesn't already have. No Python syntax tutorials. No "what is git." Challenge every paragraph.

Don't include human-facing docs

No README.md, no CHANGELOG.md, no INSTALLATION_GUIDE.md inside the skill folder. Skills are for agents.

Don't write vague descriptions

• Bad: "A helpful skill for documents"
• Good: "Fill PDF form fields, extract form data, flatten completed PDFs. Use when the user mentions PDF forms, fillable forms, or programmatic field population."

Don't bundle library code

If you need a parsing library, install via npm/pip. Don't paste source into the skill.

Don't write monolithic mega-skills

If one skill does design + planning + implementation + testing + deployment, you've built a framework, not a skill. Split it.

Don't assume the agent will infer

Be explicit about every step that matters.

• Bad: "Then deploy it."
• Good: "Run npm run deploy:staging and wait for HTTP 200 from /healthz before reporting success."

Don't write style-only variants

A skill that just changes tone or formatting belongs in user preferences or a system prompt, not a skill.

Don't ignore failure modes

For every workflow step that can fail, document what failure looks like and what to do. Happy-path-only skills break in production.

Don't include time-sensitive information

"As of Q4 2024..." rots fast. Fetch live data via script or omit.

Don't use absolute paths

Always relative. Forward slashes regardless of OS. Use runtime placeholders for skill-directory references.

Don't trust unfamiliar skills

Skills can execute arbitrary code and steer agent behavior. A malicious skill is a data exfiltration vector. Audit scripts/ for unexpected network calls, file access outside expected scope, or hidden instructions in references. Watch for typosquatted skill names. Sandbox execution environments.

---

8. Authoring workflow

1. Identify the gap. Run your agent on real tasks. Where does it consistently fail or need re-prompting? That's a skill candidate.
2. Decide the pattern. Capability primitive (need new tools) or process primitive (need better methodology)?
3. Draft the description first. What + when + differentiator. Read it back: would the agent know when to fire it?
4. Write the smallest body that works. Add only when testing reveals gaps.
5. Move detail to references/ once SKILL.md grows too long.
6. Test triggering. Ask the agent something the skill should handle without invoking it explicitly. If it doesn't fire, fix the description.
7. Test execution. Invoke explicitly. If output is wrong, fix the body.
8. Adversarial test. Have another LLM ask: "What edge cases break this skill?" Patch the gaps.
9. Version control. Treat skills as code. Tag, branch, review.

---

9. Testing and debugging

• "Which skill did you use?", ask the agent post-task. Fastest routing debug.
• Routing fails → description problem. Add specific trigger phrases.
• Execution fails → body problem. Add explicit steps, examples, or validation.
• Skills snapshot at session start. Edits during a session require a restart.
• Test against the weakest model you'll deploy on. Stronger models forgive vague skills; weaker models expose them.
• Run an eval suite. A handful of representative prompts that should and shouldn't trigger the skill, with expected outputs.

---

10. Composition

Skills compose at runtime, the agent loads multiple skills as needed for a single task. Design for this:

• One skill = one concern. Resist bundling.
• Define interfaces between skills. If skill A produces artifacts that skill B consumes, document the shape.
• Use a repo-level config substrate. A shared file (e.g., AGENTS.md, CONTEXT.md, settings.json) that multiple skills read and write coordinates them without explicit handoffs.
• Loops over menus. A coordinated set of skills forming a workflow (align → spec → build → verify → refactor) drives adoption far better than an unrelated catalog of capabilities.

---

11. Security checklist

Before installing any third-party skill:

• Read every file in the folder
• Audit scripts/ for outbound network calls, file access outside expected scope, command execution
• Check references for prompt injection ("ignore previous instructions...")
• Verify the skill name isn't typosquatting a popular one
• Run in a sandboxed environment first
• Pin to a specific version/commit, not latest

---

12. Ship checklist

Before publishing a skill:

• [ ] Frontmatter name matches folder name
• [ ] Description includes what + when + differentiator
• [ ] Description includes likely user trigger phrases
• [ ] No human-facing docs inside the skill folder
• [ ] No time-sensitive information
• [ ] Relative paths only
• [ ] State-check before action where applicable
• [ ] Validation loop documented
• [ ] Output format documented if relevant
• [ ] Tested with weak and strong models
• [ ] Tested for both correct triggering and correct execution
• [ ] Skill does one thing
• [ ] Composes cleanly with related skills
• [ ] Version controlled

---

13. First principles, compressed

1. The description routes; the body executes. Get both right independently.
2. Tokens are scarce; files are cheap. Push detail out of context until it's needed.
3. Determinism comes from code; judgment comes from prompts. Put each in its right place.
4. One skill, one concern. Composition beats bundling.
5. Agents have no memory. Use persistent artifacts to give them one.
6. The model knows a lot. Don't re-teach. Only add what's missing.
7. Validate before completing. Self-correction loops dominate output quality.
8. Skills are code. Version, test, audit, and review them as such.

---

14. This workspace

Skills live in .claude/skills/<name>/SKILL.md. Author them there.

Workspace conventions on top of the general guidance above:

• Follow .claude/rules/writing-style.md in skill bodies too. No em-dashes or en-dashes, no emojis, bullets over paragraphs.
• Skills that touch prod are read-only by default. Encode the read-only access path (for example SSM plus a read-only dump), never a prod shell.
• Skills that run shell commands should show them with the rtk prefix.
• Set disable-model-invocation: true unless the skill genuinely should fire on its own. The default here is manual.
• After adding a skill, add a one-line entry to .claude/skills/README.md and re-run /context-budget to confirm the per-turn cost did not move. Skill bodies are invoked-only, but descriptions are always loaded.