Writing Skills

TDD Mapping for Skills

When to Create a Skill

Create when:

• Technique wasn't intuitively obvious
• You'd reference again across projects
• Pattern applies broadly (not project-specific)
• Others would benefit

Don't create for:

• One-off solutions
• Standard practices well-documented elsewhere
• Project-specific conventions (put in CLAUDE.md)
• Mechanical constraints (enforceable with regex/validation? Automate it)

Skill Types

Technique

Concrete method with steps (condition-based-waiting, root-cause-tracing)

Pattern

Way of thinking about problems (flatten-with-flags, test-invariants)

Reference

API docs, syntax guides, tool documentation

Directory Structure

skills/
  skill-name/
    SKILL.md              # Main reference (required)
    supporting-file.*     # Only if needed

Flat namespace - all skills in one searchable namespace

Separate files for:

1. Heavy reference (100+ lines) - API docs, comprehensive syntax
2. Reusable tools - Scripts, utilities, templates

Keep inline: Principles, code patterns (< 50 lines), everything else

SKILL.md Structure

Frontmatter (YAML):

• Two required fields: name and description (see agentskills.io/specification)
• Max 1024 characters total
• name: Letters, numbers, hyphens only
• description: Third-person, ONLY when to use (NOT what it does)
  • Start with "Use when..."
  • Include specific symptoms, situations, contexts
  • NEVER summarize skill's process or workflow (see CSO section)
  • Keep under 500 chars if possible

---