Agent Skills
How skills work internally in Claude Code.
Skills are modular packages of instructions, scripts, and resources that extend Claude's capabilities. They are auto-discovered at startup and activated dynamically when relevant to the current task.
┌───────────────────────────────────────────────────────────────────────────────────────┐
│ AGENT + SKILLS + VIRTUAL MACHINE │
├─────────────────────────────────────────┬─────────────────────────────────────────────┤
│ Agent Configuration │ Agent Virtual Machine │
│ │ │
│ ┌───────────────────────────────────┐ │ use ┌─────────┬─────────┬─────────┐ │
│ │ Core System Prompt │──┼─computer─►│ Bash │ Python │ Node.js │ │
│ └───────────────────────────────────┘ │ └─────────┴─────────┴─────────┘ │
│ │ │
│ Equipped Skills │ File System │
│ ┌─────────┬──────┬────────────┐ │ ┌───────────────────┬───────────────────┐ │
│ │bigquery │ docx │ nda-review │ │ │ skills/bigquery/ │ skills/docx/ │ │
│ ├─────────┼──────┼────────────┤ │ │ - SKILL.md │ - SKILL.md │ │
│ │ pdf │ pptx │ xlsx │ │ │ - datasources.md │ - ooxml/ │ │
│ └────┬────┴──────┴────────────┘ │ │ - rules.md │ - spec.md │ │
│ │ │ ├───────────────────┼───────────────────┤ │
│ │ Contents of Skill directories │ │ skills/nda-review/│ skills/pdf/ │ │
│ └──live in the agent's ───────────┼─►│ - SKILL.md │ - SKILL.md │ │
│ file system │ │ │ - forms.md │ │
│ │ │ │ - reference.md │ │
│ Equipped MCP Servers │ │ │ - extract.py │ │
│ ┌─────────────────────────────────┐ │ └───────────────────┴───────────────────┘ │
│ │ ○ MCP server 1 │ │ │
│ │ ○ MCP server 2 │ │ │
│ │ ○ MCP server 3 │ │ │
│ └──────────┬──────────────────────┘ │ │
│ │ │ │
│ ▼ │ │
│ ┌──────────┬──────────┬──────────┐ │ │
│ │○ MCP 1 │○ MCP 2 │○ MCP 3 │ │ │
│ └──────────┴──────────┴──────────┘ │ │
│ Remote MCP servers (on the internet) │ │
└─────────────────────────────────────────┴─────────────────────────────────────────────┘A skill is a directory containing a SKILL.md file with organized folders of instructions, scripts, and resources that give agents additional capabilities.
┌──────────────────────────────────────────────────────────────────┐
│ SKILL DISCOVERY (on startup) │
│ │
│ ~/.claude/skills/ .claude/skills/ ~/.claude/plugins/ │
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
│ │ SKILL.md │ │ SKILL.md │ │ SKILL.md │ │
│ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘ │
│ │ │ │ │
│ └────────────────────┼────────────────────┘ │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ SKILL REGISTRY │ │
│ │ (name + description│ │
│ │ only, ~1KB each) │ │
│ └─────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘┌─────────────────────────────────────────────────────────────────────┐
│ SKILL ACTIVATION (on match) │
│ │
│ User: "create spreadsheet report" │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ CONTEXT WINDOW │ │
│ │ ┌─────────────────────────────────────────────────────┐ │ │
│ │ │ System prompt ~2-4K tokens│ │ │
│ │ ├─────────────────────────────────────────────────────┤ │ │
│ │ │ SKILL.md content (full) ~1-2K tokens│◄───┼────┤
│ │ ├─────────────────────────────────────────────────────┤ │ │
│ │ │ Supporting files (progressive load) as needed │ │ │
│ │ ├─────────────────────────────────────────────────────┤ │ │
│ │ │ Conversation history variable │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘SKILL.md Structure
┌─────────────────────────────────────────────┐
│ --- │
│ name: my-skill (max 64 chars) │ ◄─ indexed at startup
│ description: ... (max 1024 chars) │ ◄─ used for matching
│ allowed-tools: [...] (optional) │
│ --- │
│ │
│ # Instructions │ ◄─ loaded on activation
│ Full skill instructions here... │
│ Can reference supporting files │
│ │
└─────────────────────────────────────────────┘Progressive Disclosure Architecture
Skills employ a tiered information loading system to prevent context window bloat:
┌────────────────────────────────────────────────────────────────────────────────────────┐
│ SKILLS AND THE CONTEXT WINDOW │
├────────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Context Window │
│ ┌──────────────────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Agent's System Prompt │ │ │
│ │ └─────────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Short snippets ┌─────────┬──────┬────────────┬─────┬──────┬──────┐ │ │
│ │ from each Skill ────►│bigquery │ docx │ nda-review │ pdf │ pptx │ xlsx │ │ │
│ │ appended to └─────────┴──────┴────────────┴─────┴──────┴──────┘ │ │
│ │ system prompt │ │
│ │ │ │
│ │ Initial message ────►┌─────────────────────────────────────────────────────┐ │ │
│ │ from user │ User: Fill out this PDF based on what you know │ │ │
│ │ │ Attached: /mnt/uploads/order_form.pdf │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────┐ │ │
│ │ │ Claude: Certainly! I'll use the PDF Skill to help │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Claude decides ────►┌─────────────────────────────────────────────────────┐ │ │
│ │ to "trigger" the │ Tool use: Bash("cat /mnt/skills/pdf/SKILL.md") │ │ │
│ │ PDF Skill by └─────────────────────────────────────────────────────┘ │ │
│ │ reading it │ │
│ │ ┌─────────────────────────────────────────────────────┐ │ │
│ │ │ Tool result: {...contents of SKILL.md file...} │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Claude follows ────►┌─────────────────────────────────────────────────────┐ │ │
│ │ reference from │ Tool use: Bash("cat /mnt/skills/pdf/forms.md") │ │ │
│ │ SKILL.md to └─────────────────────────────────────────────────────┘ │ │
│ │ forms.md │ │
│ │ ┌─────────────────────────────────────────────────────┐ │ │
│ │ │ Tool result: {...contents of forms.md file...} │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ Skills are triggered in the context window via your system prompt. │
│ │
└────────────────────────────────────────────────────────────────────────────────────────┘| Level | What's Loaded | When |
|---|---|---|
| 1 | Skill name + description | At startup (in system prompt) |
| 2 | Full SKILL.md content | When Claude detects relevance |
| 3+ | Referenced files (forms.md, reference.md, etc.) | As needed during task |
How Skills Are Triggered
- Context window initially contains core system prompt + all skill metadata
- User sends a message (e.g., "Fill out this PDF")
- Claude matches task to skill description
- Claude invokes
Bash("cat /mnt/skills/pdf/SKILL.md")to read full instructions - Claude selectively loads bundled reference files based on task requirements
- Agent proceeds with task-specific instructions
Code Execution
Skills can bundle executable scripts (particularly Python). Claude runs these deterministically without loading script content into context, improving efficiency for operations like data sorting or PDF field extraction.
Key Points
- Discovery: only
name+descriptionloaded initially (lightweight) - Activation: full
SKILL.mdinjected into context when matched - Progressive: supporting files loaded only when referenced
- Restart required: changes take effect on next Claude Code start
Best Practices
- Start with evaluation: test agents on representative tasks, identify capability gaps, then build skills incrementally
- Structure for scale: split unwieldy
SKILL.mdfiles into separate referenced documents - Keep mutually exclusive contexts separate: reduces token usage
- Iterate collaboratively: work with Claude to capture successful approaches into reusable skill contexts
Security
Install skills only from trusted sources. Audit unfamiliar skills by reviewing bundled files, code dependencies, and external network connections before deployment.
References
- Equipping agents for the real world with Agent Skills - Anthropic Engineering Blog
- Agent Skills Docs