Agent Skills: Concepts

1. What Are Agent Skills?

An Agent Skill is a folder containing a SKILL.md file. That file includes metadata (name and description) and instructions that tell an AI agent how to perform a specific task. Skills can also bundle scripts, templates, and reference materials.

The Agent Skills specification is an open format adopted by 33+ agent products including Claude Code, GitHub Copilot, Cursor, OpenAI Codex, Gemini CLI, VS Code, JetBrains Junie, Roo Code, OpenHands, and more.

Think of skills as portable expertise packages. They give agents domain-specific knowledge they wouldn't have otherwise — your company's API patterns, your team's deployment workflow, your project's edge cases.

2. Anatomy of a Skill

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
│   └── validate.sh
├── references/       # Optional: documentation
│   └── REFERENCE.md
└── assets/           # Optional: templates, resources
    └── template.json

Only SKILL.md is required. Everything else is optional and loaded on demand.

3. Progressive Disclosure

This is the core architectural principle behind Agent Skills. Every skills-compatible agent follows the same three-tier loading strategy:

Why This Matters

An agent with 20 installed skills doesn't pay the token cost of 20 full instruction sets upfront — only the ones actually used. With Tier 1, the agent knows what skills exist. With Tier 2, it knows how to use the relevant one. With Tier 3, it gets the detailed references only when needed.

What This Means for Skill Authors

• Description is everything — it's the only thing the agent sees before activation. If the description doesn't convey when to use the skill, the agent won't activate it.
• Keep SKILL.md lean — under 5,000 tokens. Move reference material to separate files.
• Tell the agent when to load files — "Read references/api.md if the API returns a non-200 status" is better than "see references/ for details."

4. The Skill Lifecycle

Every skill goes through five phases:

Phase 1: Discovery

At session startup, the agent scans skill directories and loads metadata (name + description) for each discovered skill. Agents scan multiple locations in priority order:

Project-level skills override user-level skills with the same name.

Phase 2: Catalog Injection

The agent builds a catalog of all discovered skills and injects it into the model's context (system prompt or tool description). The model now knows what skills are available.

Phase 3: Activation

When the model decides a skill is relevant (based on description matching), or the user explicitly invokes it (e.g., /skill-name), the full SKILL.md body is loaded into context.

Two activation mechanisms:

• Model-driven: The agent's LLM reads the catalog and decides which skill is relevant. This is the default for most agents.
• User-explicit: The user types /skill-name or $skill-name to force activation.

Phase 4: Execution

The agent follows the skill's instructions, loading referenced files (scripts, references) on demand. Scripts are executed via the agent's shell tools; references are read into context.

Phase 5: Context Management

Skill content stays in context for the rest of the session. Good implementations protect skill content from context compaction (truncation) to prevent degraded behavior mid-conversation.

5. Frontmatter Specification

Every SKILL.md starts with YAML frontmatter between --- delimiters:

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
compatibility: Requires Python 3.14+ and uv
metadata:
  author: example-org
  version: "1.0"
allowed-tools: Bash(git:*) Read
---

Name Rules

• Only lowercase letters (a-z), numbers (0-9), and hyphens (-)
• Cannot start or end with a hyphen
• No consecutive hyphens (--)
• Must match the parent directory name exactly

Agent-Specific Extensions

Some agents add their own frontmatter fields beyond the spec:

6. Writing the Body

The markdown body after the frontmatter contains the skill's instructions. There are no format restrictions — write whatever helps the agent perform the task. But certain patterns consistently produce better results.

Effective Patterns

Gotchas Sections

The highest-value content in many skills. These are concrete, environment-specific facts that defy reasonable assumptions:

## Gotchas

- The `users` table uses soft deletes. Always include `WHERE deleted_at IS NULL`.
- User ID is `user_id` in the DB, `uid` in auth, and `accountId` in billing.
- `/health` returns 200 even if DB is down. Use `/ready` for full health.

Output Templates

When the agent needs to produce output in a specific format, provide a template. Agents pattern-match well against concrete structures:

## Report structure

Use this template:

# [Analysis Title]

## Executive summary
[One-paragraph overview]

## Key findings
- Finding 1 with data
- Finding 2 with data

Validation Loops

Instruct the agent to validate its own work before proceeding:

1. Make your edits
2. Run: python scripts/validate.py output/
3. If validation fails, fix and re-run
4. Only proceed when validation passes

Plan-Validate-Execute

For batch or destructive operations, create an intermediate plan, validate it, then execute:

1. Extract form fields: python scripts/analyze.py input.pdf
2. Create field_values.json mapping each field
3. Validate: python scripts/validate.py form_fields.json field_values.json
4. If validation fails, revise and re-validate
5. Fill: python scripts/fill.py input.pdf field_values.json output.pdf

Anti-Patterns

• Generic instructions: "Handle errors appropriately" — the agent already knows this. Be specific.
• Option menus: "You can use A, B, or C..." — pick a default, mention alternatives briefly.
• Obvious knowledge: Don't explain what a PDF is or how HTTP works. Focus on what the agent wouldn't know without your skill.
• Exhaustive coverage: Concise step-by-step guidance with a working example beats comprehensive documentation.

7. Scripts & Executable Code

Scripts in scripts/ let skills perform deterministic operations. The agent executes them via shell tools — they cost zero context tokens (they run, not load).

Self-Contained Scripts

Bundle dependencies inline so scripts run with a single command:

Design Rules for Agentic Scripts

• No interactive prompts — agents can't respond to TTY input. Use flags and env vars.
• Document with --help — this is how the agent learns the interface.
• Structured output — JSON/CSV over free-form text. Data to stdout, diagnostics to stderr.
• Helpful errors — say what went wrong, what was expected, and what to try.
• Idempotent — "create if not exists" beats "create and fail on duplicate."
• Dry-run support — --dry-run for destructive operations.
• Meaningful exit codes — distinct codes for different failure types.
• Bounded output size — agent harnesses truncate at 10-30K chars. Default to summaries.

8. Descriptions & Activation

The description field carries the entire burden of triggering. If the description doesn't convey when the skill is useful, the agent won't know to reach for it.

Writing Effective Descriptions

# Bad
description: Helps with PDFs.

# Good
description: >
  Extract PDF text, fill forms, and merge files.
  Use when handling PDFs or when the user mentions
  documents, forms, or text extraction.

Principles

• Imperative phrasing: "Use this skill when..." not "This skill does..."
• User intent, not implementation: Describe what the user wants, not the skill's mechanics.
• Be pushy: "even if they don't explicitly mention 'CSV' or 'analysis'"
• Concise: A few sentences. Hard limit: 1,024 characters.

Testing Trigger Accuracy

Create eval queries labeled with should/shouldn't trigger:

[
  {"query": "analyze my sales spreadsheet", "should_trigger": true},
  {"query": "convert JSON to YAML", "should_trigger": false}
]

Run each query 3+ times (model behavior is non-deterministic) and compute a trigger rate. Use a 60/40 train/validation split to avoid overfitting the description to your test set.

9. Cross-Agent Compatibility

The Agent Skills format is adopted by 33+ agents, but each has quirks. Here's what you need to know.

Discovery Paths

Common Compatibility Issues

10. Evaluating Skills

A skill that "seems to work" on one prompt may fail on varied inputs. Structured evaluation gives you a feedback loop.

The Eval Loop

1. Write test cases: prompt + expected output + optional input files
2. Run with/without skill: each test case runs twice for baseline comparison
3. Write assertions: verifiable checks after seeing first outputs
4. Grade: PASS/FAIL with specific evidence for each assertion
5. Aggregate: compute pass rates, token costs, time deltas
6. Iterate: fix the skill based on failed assertions + execution transcripts

What Good Assertions Look Like

Key Metrics

{
  "with_skill":    { "pass_rate": 0.83, "tokens": 3800 },
  "without_skill": { "pass_rate": 0.33, "tokens": 2100 },
  "delta":         { "pass_rate": +0.50, "tokens": +1700 }
}

The delta tells you what the skill costs (tokens) and what it buys (pass rate). A +50% pass rate for +1,700 tokens is usually worth it.

11. Security Considerations

Skills are instructions injected into an agent's context. Untrusted skills pose real risks.

Threat Model

Mitigations

• Trust gating: Only load project-level skills from trusted repositories
• Capability declarations: Skills should declare what they need (network, file access, shell)
• Script review: Audit all bundled scripts before enabling a skill
• No hardcoded secrets: Never put API keys or tokens in SKILL.md or scripts
• Network policies: Declare which external hosts scripts need to reach

12. The Ecosystem

Compatible Agents (33+)

Claude Code, GitHub Copilot, Cursor, OpenAI Codex, VS Code, Gemini CLI, JetBrains Junie, Roo Code, OpenHands, Amp, Letta, Goose, Kiro, TRAE, Factory, Firebender, Spring AI, Databricks Genie Code, Snowflake Cortex Code, and more.

Further Reading

• Specification Reference
• Skill Gallery & Examples