Writing Custom Skills
Relevant source files
The following files were used as context for generating this wiki page:
Custom skills enable an agent to perform specific tasks through structured instructions, progressive disclosure of information, and bundled resources. A skill wrangles determinism out of a stochastic system to ensure the agent follows a predictable process. Predictability serves as the root virtue of skill design, ensuring the agent takes the same procedural path even if output varies.
Sources: skills/write-a-skill/SKILL.md:1-5, skills/writing-great-skills/SKILL.md:7-9, skills/writing-great-skills/GLOSSARY.md:11-14
Core Architecture and Structure
Each skill resides in its own directory. The primary instruction file is SKILL.md. You include additional files to maintain a lean hierarchy and prevent information sprawl.
The diagram shows the standard file structure for a custom skill. Sources: skills/write-a-skill/SKILL.md:20-27
File Layout Components
| File/Folder | Requirement | Description |
|---|---|---|
SKILL.md | Required | Contains frontmatter (name/description) and main instructions. |
REFERENCE.md | Optional | Provides detailed documentation for complex logic. |
EXAMPLES.md | Optional | Includes usage examples to anchor agent behavior. |
scripts/ | Optional | Houses utility scripts for deterministic operations like validation. |
Sources: skills/write-a-skill/SKILL.md:20-30, skills/writing-great-skills/GLOSSARY.md:119-123
Invocation Models
You must choose between two invocation methods, which trade off between context load and cognitive load.
Model-Invoked Skills
The agent fires these skills autonomously based on a machine-readable description. These descriptions contribute to permanent context load because they remain in the agent's window every turn. You use this when the agent must reach the skill on its own or if other skills need to trigger it.
Sources: skills/writing-great-skills/SKILL.md:13-16, skills/writing-great-skills/GLOSSARY.md:23-31
User-Invoked Skills
The agent cannot see these skills. Only a human typing the skill name can invoke it. This results in zero context load but higher cognitive load, as you must remember the skill exists. Use disable-model-invocation: true in the frontmatter to strip the agent's reach.
Sources: skills/writing-great-skills/SKILL.md:17-20, skills/writing-great-skills/GLOSSARY.md:34-39
The Information Hierarchy
A skill organizes content into a ladder ranked by how immediately the agent needs the material.
- In-skill steps: Ordered actions in
SKILL.md. Each step must end with a checkable completion criterion. - In-skill reference: Definitions or rules in
SKILL.mdconsulted on demand. - External reference: Material pushed into separate files to maintain legibility (Progressive Disclosure).
This diagram illustrates the tiered importance of content within a skill. Sources: skills/writing-great-skills/GLOSSARY.md:79-92
Steering Agent Behavior
Leading Words (Leitwort)
Leading words are compact concepts already present in the model's pretraining (e.g., tracer bullets, fog of war). You repeat these tokens throughout the skill to anchor behavioral principles in fewer tokens. Leading words serve predictability by recruiting priors the model already holds.
Sources: skills/writing-great-skills/SKILL.md:86-97, skills/writing-great-skills/GLOSSARY.md:162-171
Completion Criteria
Every step ends with a condition that tells the agent the work is done. You must ensure criteria are:
- Checkable: The agent can distinguish "done" from "not-done."
- Exhaustive: The criteria demand full coverage (e.g., "every modified model accounted for").
Sources: skills/writing-great-skills/SKILL.md:46-49, skills/writing-great-skills/GLOSSARY.md:177-185
Pruning and Failure Modes
You must maintain a pruning discipline to prevent skill degradation.
| Failure Mode | Description | Remedy |
|---|---|---|
| Premature Completion | Ending a step before it is genuinely done due to visible future steps. | Sharpen completion criteria or split the sequence to hide future steps. |
| Sprawl | Skill is too long, hurting readability even if content is unique. | Use progressive disclosure to push reference behind context pointers. |
| Sediment | Stale layers of old content that are never cleared. | Perform aggressive relevance checks and delete no-op sentences. |
| No-Op | Instructions that change nothing because the model obeys them by default. | Run the no-op test: does the line change behavior vs default? |
Sources: skills/writing-great-skills/SKILL.md:68-84, skills/writing-great-skills/GLOSSARY.md:139-146, skills/writing-great-skills/GLOSSARY.md:195-202, skills/writing-great-skills/GLOSSARY.md:237-248
Implementation Workflow
- Gather Requirements: Ask the user about the task domain, specific use cases, and reference materials.
- Draft SKILL.md: Include a concise description and workflows. Keep the main file under 100 lines.
- Add Scripts: Use utility scripts for deterministic operations like formatting or validation to save tokens.
- Review Checklist: Verify the description includes triggers ("Use when..."), terminology is consistent, and no time-sensitive info exists.
The sequence shows the interactive process of creating a new skill. Sources: skills/write-a-skill/SKILL.md:7-18
Code Standards for Skills
When writing code within or for skills, apply surgical change principles:
- Root-cause fixes: Fix the source, not the visible symptom.
- Mock ban: Tests and verification must cross the real production interface; do not use mocks or fakes.
- Minimal diff: Changes should be the smallest possible set of hunks to solve the problem.
- No placeholders: Do not leave
TODO,FIXME, or temporary bypasses in shippable code.
Sources: CLAUDE.md:31-48, skills/production-code/SKILL.md:66-72