writing-skills

# Writing Skills

## Overview

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

You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), 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.

**Shannon enhancement**: Quantitative validation of skill effectiveness.

## What is a Skill?

A **skill** is a reference guide for proven techniques, patterns, or tools. Skills help future Claude instances find and apply effective approaches.

**Skills are**: Reusable techniques, patterns, tools, reference guides

**Skills are NOT**: Narratives about how you solved a problem once

## 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 (baseline) |
| **Test passes (GREEN)** | Agent complies with skill present |
| **Refactor** | Close loopholes while maintaining compliance |

## When to Create a Skill

**Create when**:
- Technique wasn't intuitively obvious to you
- You'd reference this again across projects
- Pattern applies broadly (not project-specific)
- Others would benefit
- **Shannon**: Complexity >0.4 or used >3 times

**Don't create for**:
- One-off solutions
- Standard practices well-documented elsewhere
- Project-specific conventions (put in CLAUDE.md)

## SKILL.md Structure (Shannon Enhanced)

**Frontmatter (YAML)**:
```yaml
---
name: skill-name-with-hyphens
description: Use when [specific triggers and symptoms] - [what it does and how it helps, third person]
---
```

**Max 1024 characters total**
**Name**: Letters, numbers, hyphens only
**Description**: Third-person, starts with "Use when..."

**Body structure**:
```markdown
# Skil