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.

What is a Skill?

A skill is a reference guide for proven techniques, patterns, or tools. Skills help future agent 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

SKILL.md Structure

Frontmatter (YAML):

• Two required fields: name and description
• name: Use letters, numbers, and hyphens only
• 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
  • Keep under 500 characters if possible

Body format: Use pure Markdown headings for structure. Prefer ## Purpose, ## When to Use, ## Workflow, and ## Verification. Do not use XML-like tags such as <Purpose>, <Workflow>, or <Use_When> as normal top-level sectioning. Use XML-like delimiters only for nested examples, quoted input, external documents, or machine-readable prompt payloads.

---
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 / When NOT to use

## Core Pattern
Before/after comparison or step-by-step

## Quick Reference
Table or bullets for scanning common operations

## Common Mistakes
What goes wrong + fixes

Claude Search Optimization (CSO)

Critical: The description field must help agents decide whether to load the skill. It should ONLY describe triggering conditions — never summarize the workflow.

# BAD: Summarizes workflow - agent may follow this instead of reading the full skill
description: Use when executing plans - dispatches subagent per task with review between tasks

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

Why this matters: When a description summarizes the skill's workflow, agents may follow the description instead of reading the full skill content.

File Organization

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

Keep inline: Principles, concepts, code patterns under 50 lines, everything else.

Separate files for: API docs/reference over 100 lines, reusable scripts/utilities.

The Iron Law

NO SKILL WITHOUT A FAILING TEST FIRST

This applies to NEW skills AND EDITS to existing skills.

RED-GREEN-REFACTOR for Skills

TDD Concept	Skill Creation
Test case	Pressure scenario with subagent
RED	Agent violates rule without skill (baseline)
GREEN	Agent complies with skill present
REFACTOR	Close loopholes while maintaining compliance

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 addressing those specific rationalizations. Don't add extra content for hypothetical cases. Verify agent now complies.

REFACTOR: Close Loopholes

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

Skill Creation Checklist

RED Phase:

• Run baseline scenario WITHOUT skill — document violations verbatim

GREEN Phase:

• name uses only letters, numbers, hyphens
• YAML frontmatter with name and description
• Pure Markdown body with headings, not XML-like top-level section tags
• Description starts with "Use when..." — no workflow summary
• Keywords throughout for discovery
• Clear overview with core principle
• Run scenarios WITH skill — verify compliance

REFACTOR Phase:

• Identify new rationalizations from testing
• Add explicit counters for discipline skills
• Build rationalization table

Common Mistakes

Anti-Pattern	Why Bad
Narrative storytelling	Too specific, not reusable
Multi-language examples	Mediocre quality, maintenance burden
Generic labels (step1, helper2)	No semantic meaning
Description summarizing workflow	Agent follows description, skips full skill

When to Create a Skill

Create when:

• Technique wasn't intuitively obvious
• You'd reference this again across projects
• Pattern applies broadly (not project-specific)

Don't create for:

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