Writing Skills

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.

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

What is a Skill?

A skill is a reference guide for proven techniques, patterns, or tools.

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

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

TDD Mapping for Skills

When to Create a Skill

Create when:

• Technique wasn't intuitively obvious
• You'd reference this again across projects
• Pattern applies broadly
• Others would benefit

Don't create for:

• One-off solutions
• Standard practices elsewhere
• Project-specific conventions (put in CLAUDE.md)

Directory Structure

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

SKILL.md Structure

Frontmatter (YAML)

---
name: skill-name-with-hyphens
description: Use when [specific triggering conditions and symptoms]
---

Rules:

• Only two fields: name and description
• Max 1024 characters total
• Start description with "Use when..."
• Describe triggering conditions, NOT what skill does

Sections

• Overview: What is this? Core principle in 1-2 sentences
• When to Use: Symptoms and use cases
• The Process: Step-by-step instructions
• Quick Reference: Table or bullets for scanning
• Common Mistakes: What goes wrong + fixes
• Red Flags: STOP conditions

Claude Search Optimization

Description field is critical - Claude reads it to decide which skills to load.

# ❌ BAD: Summarizes workflow
description: Use when executing plans - dispatches subagent per task

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

Include keywords: Error messages, symptoms, tools, synonyms

The Iron Law

NO SKILL WITHOUT A FAILING TEST FIRST

This applies to NEW skills AND EDITS.

No exceptions:

• Not for "simple additions"
• Not for "just adding a section"
• Delete untested changes

Testing All Skill Types

Discipline-Enforcing Skills (TDD, debugging)

Test with:

• Academic questions
• Pressure scenarios
• Multiple pressures combined
• Identify rationalizations

Technique Skills (how-to guides)

Test with:

• Application scenarios
• Variation scenarios
• Missing information tests

Reference Skills (documentation/APIs)

Test with:

• Retrieval scenarios
• Application scenarios
• Gap testing

RED-GREEN-REFACTOR for Skills

RED: Write Failing Test

Run pressure scenario with subagent WITHOUT the skill. Document:

• What choices did they make?
• What rationalizations did they use?
• Which pressures triggered violations?

GREEN: Write Minimal Skill

Write skill that addresses those specific rationalizations. Run 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

**No exceptions:**
- Don't keep it as "reference"
- Don't "adapt" it while running tests
- Delete means delete

Address "Spirit vs Letter"

Add early:

**Violating the letter of the rules is violating the spirit of the rules.**

Build Rationalization Table

Capture from baseline testing:

| Excuse | Reality |
|--------|---------|
| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |

Common Mistakes

Quick Reference

Integration

• superpowers:test-driven-development - Required background
• superpowers:systematic-debugging - For testing discipline skills

Converted and distributed by TomeVault — claim your Tome and manage your conversions.