Skill Anatomy¶

A skill consists of three layers, each serving a distinct purpose in the progressive disclosure hierarchy. Understanding these layers clarifies how to structure knowledge for agent consumption.

Layer 1: Metadata¶

The metadata layer is a YAML frontmatter block at the top of SKILL.md:

---
name: skill-name
description: Brief description of what this skill does and when to use it
---

This layer has unique characteristics:

Metadata for all skills loads at system startup, regardless of whether the skill will be used.

The agent scans descriptions to determine relevance. A well-written description acts as a query interface, matching user intent against skill descriptions.

At roughly 100 tokens per skill, metadata scales efficiently. A system with 50 skills only adds ~5000 tokens to the base context.

Descriptions must be written in third person because they're injected into the system prompt as-is. "Manages git worktrees for isolated development" works; "I help you manage worktrees" does not.

The description serves two audiences simultaneously: the agent deciding whether to load the skill, and potentially humans browsing available capabilities.

Layer 2: Main Instructions (SKILL.md)¶

The main body of SKILL.md contains the core instructions:

skill-name/
└── SKILL.md    ← Metadata + main instructions

This layer loads when the agent determines the skill is relevant.

The main instructions should be self-contained enough that 80% of tasks complete using only SKILL.md, with supporting files handling the remaining 20%. Structure matters for scanning - agents read quickly, so clear headings, summary tables, and explicit sections help locate relevant information without reading everything. Keep files bounded to roughly 500 lines; beyond that, content should move to supporting files.

Typical SKILL.md organization:

Section	Purpose
Overview	What this skill does, when to use it
Quick reference	Summary table or checklist
Main workflow	Step-by-step for the primary use case
Variations	Alternative approaches or options
Common issues	Troubleshooting frequent problems

The structure prioritizes answering "what do I do?" over exhaustive reference material. Detailed specs belong in Layer 3.

Layer 3: Supporting Resources¶

Supporting resources extend the skill without bloating the main instructions:

skill-name/
├── SKILL.md
├── reference.md           ← Detailed specifications
├── advanced.md            ← Complex scenarios
├── docs/
│   ├── configuration.md   ← Specialized topics
│   └── integration.md
├── scripts/
│   ├── helper.py          ← Executable tools
│   └── validator.sh
└── templates/
    └── config.example     ← Reusable artifacts

This layer has special properties:

The agent reads these files only when SKILL.md mentions them or when the task explicitly requires them.

Since files live on the filesystem, there's no practical limit to supporting documentation depth.

Executable scripts are particularly efficient. The agent runs them and receives only the output. A 1000-line Python script might produce 10 lines of output, keeping context lean.

File Types in Layer 3¶

Type	Extensions	Purpose	Examples
Documentation	`.md`	Detailed reference material	API specs, configuration options, integration guides
Scripts	`.py`, `.sh`, `.ts/.js`	Executable capabilities	Validation tools, setup helpers, data transformers
Templates	various	Reusable starting points	Configuration files, project scaffolds, common patterns

Example Structure¶

Consider a skill for managing development environments:

dev-environment/
├── SKILL.md                    # Layer 2: Core setup workflow
├── reference.md                # Layer 3: All configuration options
├── docs/
│   ├── docker-setup.md         # Layer 3: Docker-specific details
│   ├── local-setup.md          # Layer 3: Non-Docker alternative
│   └── troubleshooting.md      # Layer 3: Problem resolution
└── scripts/
    ├── detect-platform.py      # Layer 3: Platform detection
    └── validate-setup.sh       # Layer 3: Environment validation

For a simple setup request, the agent loads only SKILL.md. For Docker-specific questions, it additionally loads docker-setup.md. For validation, it runs validate-setup.sh and interprets the output.

Context Economics¶

The layered structure creates predictable context usage:

Scenario	Layers Loaded	Approximate Tokens
Skill not relevant	1 only	~100 (metadata)
Standard task	1 + 2	~3,500
Complex task	1 + 2 + one L3 file	~5,500
Deep specialization	1 + 2 + multiple L3	~8,000+

The agent's context grows proportionally to task complexity, not to the skill's total documentation size.

Relationship Between Layers¶

Each layer serves a distinct question. Layer 1 answers "Should I use this skill?" Layer 2 answers "How do I accomplish this task?" Layer 3 answers "What are the details for this specific aspect?"

Information should live at the layer matching its question. Putting detailed configuration options in Layer 2 wastes context on irrelevant information. Putting workflow steps in Layer 3 forces unnecessary file reads for common tasks.