Writing Skills
Use when creating new skills, editing existing skills, or verifying skills work before deployment.
Quick Start
Understand in 30 Seconds
Writing skills is test-driven development applied to process documentation.
Core Principle: If you haven't seen an agent fail without the skill, you don't know if the skill teaches the right thing.
When to Use
- Creating new skills
- Editing existing skills
- Verifying skills work before deployment
Complete Guide
What is a Skill?
A skill is a reference guide for validated techniques, patterns, or tools.
Skills are: Reusable techniques, patterns, tools, reference guides Skills are not: Narratives about how you solved a problem once
SKILL.md Structure
Frontmatter (YAML):
- Only two fields supported:
nameanddescription name: Use only letters, numbers, hyphensdescription: Third person, describe when to use
Iron Law
No skill without a failing test firstRED-GREEN-REFACTOR for Skills
- RED: Write failing test (baseline)
- GREEN: Write minimal skill
- REFACTOR: Close loopholes
Related Skills
Required Background
- test-driven-development - Defines basic RED-GREEN-REFACTOR cycle