Effective Agent Skills

Agent Skills: A Complete Guide

When to Use

• Use when creating, editing, reviewing, or debugging an agent SKILL.md file.
• Use when you need quality guidance for triggers, examples, limitations, and safety notes.

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. A skill written once works across all compatible agents.

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:

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–64 chars, exactly matches the parent folder name
• Avoid < and > in frontmatter (they can inject into the system prompt)
• Invalid YAML silently prevents loading

Optional standard fields:

• disable-model-invocation: true — stops the agent from auto-loading the skill based on the conversation; it can only be triggered manually (e.g. /skill-name). Now a standard Agent Skills spec field, so it works across spec-compliant clients (Claude Code, Copilot, etc.), not just Claude. Caveat: it prevents auto-invocation, but some clients (Claude Code, open bug) still inject the description into context, so it doesn't always save the discovery-level tokens. Use for manual-only utilities you don't want firing automatically.

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–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.