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.

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.

REQUIRED BACKGROUND: You MUST understand superpowers:test-driven-development before using this skill.

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
Write test first	Run baseline scenario BEFORE writing skill
Watch it fail	Document exact rationalizations agent uses
Minimal code	Write skill addressing those specific violations

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

Don't create for:

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

Skill Types

• Technique: Concrete method with steps to follow
• Pattern: Way of thinking about problems
• Reference: API docs, syntax guides, tool documentation

Directory Structure

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

SKILL.md Structure

Frontmatter (YAML):

• Only two fields supported: name and description
• Max 1024 characters total
• name: Use letters, numbers, and hyphens only (no parentheses, special chars)
• description: Third-person, describes ONLY when to use (NOT what it does)
  • Start with "Use when..." to focus on triggering conditions
  • Include specific symptoms, situations, and contexts
  • NEVER summarize the skill's process or workflow

---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms]
---

# Skill Name

## Overview
What is this? Core principle in 1-2 sentences.

## When to Use
Bullet list with SYMPTOMS and use cases

## Core Pattern
Before/after code comparison

## Quick Reference
Table or bullets for scanning common operations

## Implementation
Inline code for simple patterns

## Common Mistakes
What goes wrong + fixes

Claude Search Optimization (CSO)

CRITICAL: Description = When to Use, NOT What the Skill Does

Testing revealed that when a description summarizes the skill's workflow, Claude may follow the description instead of reading the full skill content. The description should ONLY describe triggering conditions.

# ❌ BAD: Summarizes workflow
description: Use when executing plans - dispatches subagent per task with code review between tasks

# ✅ GOOD: Just triggering conditions
description: Use when executing implementation plans with independent tasks in the current session

Keyword Coverage:

• Error messages: "Hook timed out", "ENOTEMPTY", "race condition"
• Symptoms: "flaky", "hanging", "zombie", "pollution"
• Tools: Actual commands, library names, file types

The Iron Law (Same as TDD)

NO SKILL WITHOUT A FAILING TEST FIRST

This applies to NEW skills AND EDITS to existing skills.

Write skill before testing? Delete it. Start over.

No exceptions:

• Not for "simple additions"
• Not for "just adding a section"
• Not for "documentation updates"

Testing All Skill Types

Discipline-Enforcing Skills (rules/requirements)

• Academic questions: Do they understand the rules?
• Pressure scenarios: Do they comply under stress?
• Success criteria: Agent follows rule under maximum pressure

Technique Skills (how-to guides)

• Application scenarios: Can they apply the technique correctly?
• Success criteria: Agent successfully applies technique to new scenario

Reference Skills (documentation/APIs)

• Retrieval scenarios: Can they find the right information?
• Success criteria: Agent finds and correctly applies reference information

RED-GREEN-REFACTOR for Skills

RED: Write Failing Test (Baseline)

Run pressure scenario WITHOUT the skill. Document exact behavior:

• What choices did they make?
• What rationalizations did they use (verbatim)?

GREEN: Write Minimal Skill

Write skill that addresses those specific rationalizations. Run same scenarios WITH skill. Agent should now comply.

REFACTOR: Close Loopholes

Agent found new rationalization? Add explicit counter. Re-test until bulletproof.

Bulletproofing Against Rationalization

• Close Every Loophole Explicitly - Forbid specific workarounds, not just state the rule
• Address "Spirit vs Letter" Arguments - Add: "Violating the letter of the rules is violating the spirit"
• Build Rationalization Table - Every excuse agents make goes in the table
• Create Red Flags List - Make it easy for agents to self-check

Skill Creation Checklist

RED Phase:

• Create pressure scenarios (3+ combined pressures for discipline skills)
• Run scenarios WITHOUT skill - document baseline behavior verbatim
• Identify patterns in rationalizations/failures

GREEN Phase:

• Name uses only letters, numbers, hyphens
• YAML frontmatter with only name and description (max 1024 chars)
• Description starts with "Use when..." - no workflow summary
• Run scenarios WITH skill - verify agents now comply

REFACTOR Phase:

• Identify NEW rationalizations from testing
• Add explicit counters
• Build rationalization table
• Re-test until bulletproof

Deployment:

• Commit skill to git
• Consider contributing back via PR (if broadly useful)

STOP: Before Moving to Next Skill

After writing ANY skill, you MUST STOP and complete the deployment process. Do NOT create multiple skills in batch without testing each.

The Bottom Line

Creating skills IS TDD for process documentation.

Same Iron Law: No skill without failing test first. Same cycle: RED (baseline) ➜ GREEN (write skill) ➜ REFACTOR (close loopholes).