Skill Design Principles¶
Effective skills share common design patterns. These principles emerge from the constraints of agent cognition and context management.
One Level Deep¶
Supporting files should be directly reachable from SKILL.md, not nested in deep hierarchies.
✓ Good ✗ Avoid
skill/ skill/
├── SKILL.md ├── SKILL.md
├── reference.md └── docs/
└── docs/ └── advanced/
└── configuration.md └── reference/
└── api-details.md
Deep nesting creates navigation overhead. The agent must read intermediate files to discover what exists, consuming context without providing value. Flat structures let SKILL.md directly reference any supporting resource.
Split by Scenario, Not by Depth¶
When content grows too large for a single file, divide by use case rather than by abstraction level.
Consider an architecture skill:
✓ Scenario-based ✗ Depth-based
├── patterns.md ├── overview.md
├── workflows.md ├── details.md
└── decisions.md └── deep-dive.md
Scenario-based splitting means the agent loads only the file matching the current task. A user asking about design patterns gets patterns.md; a user making technology decisions gets decisions.md. Neither loads unnecessary content.
Depth-based splitting forces the agent to determine which "level" applies, often loading multiple files to assemble a complete picture.
Metadata as Discovery Interface¶
The skill description functions as a search query that the agent matches against user intent. Write descriptions that answer "when should this skill activate?"
# Effective: describes both capability and trigger
description: Manages git worktrees for isolated feature development, including creation, switching, and cleanup
# Less effective: describes only capability
description: Git worktree management utilities
The first description helps the agent recognize when a user is working on isolated features. The second requires the agent to already know what worktrees are for.
Scripts as Context Boundaries¶
Executable scripts create natural boundaries that prevent code from consuming context. The agent runs the script and receives only its output.
Agent context includes: Agent context excludes:
- Script invocation command - Script source code
- Script output/results - Script dependencies
- Error messages if any - Implementation details
A 500-line validation script might produce "All checks passed" or a list of specific failures. Either way, the agent gains actionable information without the implementation overhead.
This makes scripts ideal for:
- Validation (check conditions, report results)
- Detecting environment characteristics
- Data format transformation
- Multi-step initialization and setup tasks
Self-Contained Main Instructions¶
SKILL.md should answer common questions without requiring supporting files. The 80/20 principle applies: 80% of uses should complete with Layer 2 alone.
This means including:
- The primary workflow for the skill's main purpose
- Quick reference for frequently needed information
- Common variations, options, and basic troubleshooting
Supporting files handle exhaustive configuration reference, edge cases, integration with other systems, and historical context.
Explicit Resource References¶
When SKILL.md references supporting files, make the reference explicit and contextual:
Not:
Explicit references tell the agent exactly what file to read and why. Vague references force exploratory reading.
Bounded Main Instructions¶
A practical upper limit of 500 lines for SKILL.md maintains focus:
| Line Count | Implication |
|---|---|
| < 200 | Appropriately focused |
| 200-400 | Normal range |
| 400-500 | Consider extracting specialized content |
| > 500 | Refactor into supporting files |
Beyond 500 lines, the skill likely contains content that belongs in Layer 3. Common candidates for extraction:
- Detailed API reference
- Extensive configuration options
- Multiple independent workflows
- Background or rationale
Composable Skills¶
Skills can reference other skills, creating composable capabilities:
Composition allows basic skills to support advanced ones, common patterns to be defined once, and dependencies between capabilities to be explicit.
The agent loads composed skills based on the same progressive disclosure rules - only when the current skill's instructions indicate they're needed.
Clear Capability Boundaries¶
Each skill should have a defined scope. When capabilities blur across skills, the agent struggles to select the right one.
✓ Clear boundaries ✗ Overlapping scope
git-worktrees: create/manage git-workflows: all git operations
worktree-flow: lifecycle phases git-advanced: complex git stuff
Clear boundaries let descriptions be specific, improving discovery accuracy. Overlapping scope creates ambiguity where multiple skills might apply.
Failure Modes to Avoid¶
Context explosion happens when too much content loads upfront, leaving insufficient space for the actual task.
Deep file hierarchies create navigation overhead, requiring multiple reads to locate information.
Implicit knowledge is another pitfall: assuming the agent knows things not stated in loaded content.
Monolithic instructions force full file reads for simple tasks by trying to cover every scenario in one place. Similarly, vague descriptions in metadata prevent the agent from determining relevance.
These anti-patterns share a common thread: they work against progressive disclosure by front-loading information or obscuring what's available.