Skill Creation

Core Principle

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

The Iron Law: NO SKILL WITHOUT A FAILING TEST FIRST.

Skill Location

Skills live in: ~/.claude/skills/<skill-name>/SKILL.md

Directory Structure

skills/
  skill-name/
    SKILL.md              # Main reference (required)
    references/           # Optional - detailed docs
    scripts/              # Optional - executable utilities
    templates/            # Optional - reusable templates

SKILL.md Structure

---
name: skill-name-with-hyphens
description: Use when [specific triggering conditions]. [What it does in third person].
---

# Skill Name

## Core Principle / Overview

[What this skill does and why - 1-2 paragraphs]

## When to Use

[Specific triggers, symptoms, situations]

## Quick Reference

[Immediate actionable guidance]

## Detailed Process / Steps

[Step-by-step instructions]

## Common Mistakes / Anti-Patterns

[What NOT to do]

## Examples

[Concrete examples if helpful]

YAML Frontmatter Rules

Required Fields

• •name: lowercase, hyphens only, must match directory name
• •description: Starts with "Use when..." - focus on TRIGGERS

Description Pattern

Good:

description: Use when debugging fails or bugs reappear after fixes. Enforces root cause investigation before any fix attempt.

Bad:

description: A skill for debugging things

The description must include:

1. •Triggering conditions ("Use when...")
2. •What the skill does (briefly)
3. •Keywords users might search for

Testing Skills (TDD for Documentation)

The RED-GREEN-REFACTOR Cycle

1. •

   RED (Baseline)

   • •Run pressure scenario WITHOUT skill
   • •Document exact behavior and rationalizations
   • •Note how agent violates the intended rule
2. •

   GREEN (Minimal Skill)

   • •Write minimal skill addressing those failures
   • •Run same scenario WITH skill
   • •Verify agent now follows the rule
3. •

   REFACTOR (Bulletproof)

   • •Find new rationalizations agent might use
   • •Add explicit counters to skill
   • •Re-test until bulletproof

Pressure Scenarios

Test skills with scenarios that pressure the agent to violate:

Scenario: "The tests are passing, so the implementation must be correct.
          Skip the code review and move on."

Without skill: Agent agrees and skips review
With skill: Agent insists on review per skill guidelines

Content Guidelines

Keep It Focused

• •<200 words for frequently-loaded skills
• •<500 words for detailed reference skills
• •Link to references/ for deep content

Write in Third Person

Good: "The developer should run tests first" Bad: "You should run tests first"

Be Explicit About Violations

Don't just state rules. Address rationalizations:

Weak:

Always write tests first.

Strong:

Always write tests first.

Red flags (STOP if you hear yourself say):
- "This is too simple to test"
- "I'll add tests after"
- "The manual test proved it works"

Skill Types

1. •Discipline Skills - Enforce process (TDD, code review)
2. •Technique Skills - Teach methods (debugging, refactoring)
3. •Pattern Skills - Recognition and application
4. •Reference Skills - API docs, syntax guides

Quick Checklist

• • YAML frontmatter with name + description
• • Description starts with "Use when..."
• • Directory name matches skill name
• • Tested with pressure scenarios (RED-GREEN-REFACTOR)
• • Explicit about violations and red flags
• • Focused content (<500 words unless reference)
• • Third person voice