4.4 KiB
| name | description |
|---|---|
| writing-skills | Create, edit, test, or debug agent skills - SKILL.md frontmatter and body structure, when a skill is warranted, skill types, discovery optimization (the description is the only part always loaded, and it is hard-capped at 500 characters), flowchart usage, and common mistakes. Use whenever authoring or revising a skill, or when a skill is not triggering. Triggers: create a skill, write a skill, edit this skill, my skill is not firing, improve the skill description. |
Writing skills IS test-driven development applied to process documentation. You write test cases (pressure scenarios), watch them fail (baseline behavior without the skill), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).
Core principle: if you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.
Background: understand the test-driven-development skill first — this skill adapts red-green-refactor to documentation.
What Is a Skill?
A reference guide for a proven technique, pattern, or tool — reusable, not a narrative about how you solved a problem once.
TDD Mapping for Skills
| TDD Concept | Skill Creation |
|---|---|
| Test case | Pressure scenario with a subagent |
| Production code | The skill document |
| Test fails (RED) | Agent violates the rule without the skill (baseline) |
| Test passes (GREEN) | Agent complies with the skill present |
| Refactor | Close loopholes while maintaining compliance |
When to Create a Skill
Create when: the technique wasn't intuitively obvious to you, you'd reference it again across projects, the pattern applies broadly (not project-specific), others would benefit. Don't create for: one-off solutions, standard practices already well-documented elsewhere, project-specific conventions (put those in project instructions instead), or mechanical constraints enforceable by regex/validation (automate those, save docs for judgment calls).
Skill Types
Technique (concrete method with steps), Pattern (way of thinking about problems), Reference (API docs/syntax guides).
SKILL.md Structure (frontmatter + body)
Frontmatter: name (letters/numbers/hyphens only) and description (third-person, describes ONLY when to use — start with "Use when...", never summarize the workflow itself).
Critical: description = when to use, NOT what the skill does. If the description summarizes the workflow, agents may follow the description as a shortcut instead of reading the full skill and doing the complete process. Keep descriptions under ~500 characters, focused purely on triggering conditions/symptoms.
Body sections: Overview (what + core principle in 1-2 sentences), When to Use (bullets with concrete symptoms; small inline flowchart only for genuinely non-obvious decision points), Core Pattern (before/after comparison for techniques), Quick Reference (table for scanning), Implementation (inline for simple patterns, link out for heavy reference), Common Mistakes, Real-World Impact (optional).
Discovery Optimization
- Rich, third-person description starting with "Use when..."
- Keyword coverage: include error messages, symptoms, synonyms, and actual tool/command names an agent would search for
- Descriptive, active naming: verb-first / gerund style (
condition-based-waitingnotasync-test-helpers,creating-skillsnotskill-creation) - Token efficiency: keep frequently-loaded skills concise; move verbose details to references or --help output rather than inline; use cross-references instead of repeating another skill's content
- Cross-reference other skills by name with explicit markers like "REQUIRED SUB-SKILL: use X" or "REQUIRED BACKGROUND: understand X" rather than vague "see" links
Flowchart Usage
Use small inline flowcharts ONLY for non-obvious decision points or "when to use A vs B" choices. Never for reference material (use tables/lists), code examples (use code blocks), or linear instructions (use numbered lists).
Code Examples
One excellent, complete, well-commented, realistic example beats several mediocre ones. Choose the most relevant language for the domain.
Common Mistakes
Writing a skill as a narrative of one past incident instead of a reusable reference. Descriptions that summarize the workflow (agents skip the actual body). Bloated frequently-loaded skills that burn context on every conversation. Vague or missing triggering conditions that make the skill undiscoverable.