Agent Skills
Agent Skills is a modular packaging specification—originated by Anthropic and formalized as the open agentskills.io standard—for equipping AI agents with domain workflows, operational guardrails, reference docs, and helper scripts. Anchored by a SKILL.md file, the format is widely supported across coding agents such as Claude Code, Codex CLI, and Cursor.
Directory Layout and SKILL.md Anatomy
An Agent Skill is a self-contained directory centered on SKILL.md:
my-skill/
├── SKILL.md # Required: YAML frontmatter (name, description) + Markdown instructions
├── scripts/ # Optional: deterministic Python/Bash helpers
├── references/ # Optional: domain manuals loaded only when needed
└── assets/ # Optional: templates, configs, or static fixtures
SKILL.md has two layers:
- YAML Frontmatter: Declares
nameanddescriptionmetadata used to match tasks and decide when to trigger the skill. - Markdown Body: Encodes step-by-step instructions, verification checklists, constraints, and usage patterns.
Progressive Disclosure in Context
Stuffing dozens of domain playbooks into a permanent system prompt wastes context window capacity and degrades recall. Agent Skills relies on three-stage progressive disclosure for disciplined context engineering:
- Discovery: At startup, the runtime loads only the lightweight
nameanddescriptionmetadata of installed skills. - Activation: When a prompt matches a skill description (or the user invokes
/skill-name), the agent reads the fullSKILL.mdbody into context. - Execution: During execution, the agent selectively opens files in
references/or runs deterministic utilities inscripts/.
Comparing Agent Skills, MCP, and Prompts
| Dimension | Agent Skills (SKILL.md) |
MCP (Model Context Protocol) | Static Prompt Templates |
|---|---|---|---|
| Core Purpose | How to execute a workflow (procedures, checklists, scripts) | How to connect live tools and data (standardized RPC) | One-off single-turn framing |
| Runtime Footprint | Plain filesystem directories; no background server | Separate stdio or HTTP/SSE server process | Raw text snippet |
| Context Overhead | Progressive loading (metadata-only until triggered) | Tool schemas loaded for active servers | Pasted manually |
| Synergy | Skills often teach an agent how to orchestrate multiple MCP tools | Handles credentials, I/O, and execution boundaries | Best for isolated tasks |
Engineering and Security Practices
- Write Sharp Trigger Descriptions: Clearly specify both when a skill should activate and when it does not apply so unrelated prompts do not pull unnecessary instructions into context.
- Offload Determinism to Scripts: Place linting, build, packaging, or parsing steps inside
scripts/rather than asking the model to improvise fragile shell pipelines from scratch. - Audit Third-Party Skills: Because skills can bundle executable scripts and high-priority instructions, inspect
SKILL.mdandscripts/before installing community packages to guard against prompt injection or unsafe commands.
Further Reading
- Agent Skills Open Specification (agentskills.io) — Standard specification for
SKILL.mdand progressive loading - Equipping Agents for the Real World with Agent Skills (Anthropic) — Design patterns and engineering rationale
- Model Context Protocol (MCP) — Complementary open protocol for tool and data connectivity