Writing Skills

---
name: writing-skills
description: Use when creating new skills, editing existing skills, or verifying skills work before deployment
---

# Writing Skills

## Overview

Writing skills IS Test-Driven Development applied to process documentation.

**Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.

## TDD Mapping for Skills

| TDD Concept | Skill Creation |
|-------------|---------------|
| Test case | Pressure scenario with subagent |
| Production code | Skill document (SKILL.md) |
| Test fails (RED) | Agent violates rule without skill |
| Test passes (GREEN) | Agent complies with skill present |
| Refactor | Close loopholes while maintaining compliance |

## SKILL.md Structure

**Frontmatter (YAML):**
- Two required fields: `name` and `description`
- `name`: Use letters, numbers, and hyphens only
- `description`: Start with "Use when..." to focus on triggering conditions

## Key Sections
- Overview with core principle
- When to Use / When NOT to Use
- Core Pattern with before/after comparisons
- Quick Reference table
- Common Mistakes with fixes
- Red Flags for self-checking

## RED-GREEN-REFACTOR for Skills

RED: Run pressure scenario WITHOUT the skill - document exact behavior and rationalizations.
GREEN: Write minimal skill addressing those specific issues - re-test.
REFACTOR: Close loopholes as new rationalizations emerge.

## The Iron Law
NO SKILL WITHOUT A FAILING TEST FIRST