Writing Skills

Overview

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

Personal skills live in agent-specific directories ($DOTFILE_REPO_ROOT/ai/files/skills)

Project skills live in .agents/skills/.

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. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.

Official guidance: Load the anthropic-best-practices resource from the writing-skills skill. This document provides additional patterns and guidelines that complement the TDD-focused approach in 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

First: Classify the Skill Type

Do this early, before writing sections.

Reference

Lookup material: APIs, syntax, command options, compatibility notes.

Workflow

Stepwise process to follow (often with gates/checklists).

Styleguide

Standards and conventions: naming, formatting, tone, structure.

Persona

Behavior profile for interaction style, priorities, and boundaries.

Technique/Pattern

Method or mental model for solving recurring problems.

If a skill spans multiple types, run this decision flow:

Ask intent first: Ask the user whether the multi-type scope is intentional, or whether they want to split the concept into separate focused skills.
If not splitting: Continue with one skill. Pick a primary type, make it explicit in the overview, and continue RED/GREEN/REFACTOR testing.
If splitting: Analyze the concept and propose multiple splice options (for example by audience, lifecycle phase, problem type, or artifact type).
Collaborate to choose: Work with the user to select the preferred split. Then produce temporary prompts for separate sessions, one prompt per new skill, each explicitly instructing the session to use this writing-skills skill.

TDD Mapping for Skills

For detailed TDD mapping table and concepts, load the tdd-mapping resource from the writing-skills skill.

Core concept: The entire skill creation process follows RED-GREEN-REFACTOR, adapting TDD's cycle to documentation.

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)

Directory Structure

skills/
  skill-name/
    SKILL.md
    references/
      extra-file.md
    scripts/
      codified-helper.sh
      known-steps-cli.js
    assets/
      possibly-a-circle-mask.png
      maybe-a-logo.png

Rule: A skill directory contains only SKILL.md.

Put everything else in categorized sibling folders:

references/ for heavy docs, guides, tables
scripts/ for executable helpers and generators
assets/ for diagrams, images, static files

Flat namespace - all skills in one searchable namespace

Keep inline in SKILL.md whenever possible:

Principles and concepts
Short code patterns (< 50 lines)
Decision criteria and anti-patterns

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). Must match the folder name.
description: Third-person, written as: {what it does}, {when to use it}, {what the result is}
- Keep it concrete and searchable (symptoms, contexts, outcomes)
- Avoid vague language and hype
- Keep under 500 characters if possible

---
name: Skill-Name-With-Hyphens
description: [what it does], [when to use it], [what the result is]
---

# Skill Name

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

## When to Use
[Small inline flowchart IF decision non-obvious]

Bullet list with SYMPTOMS and use cases
When NOT to use

## Core Pattern (for techniques/patterns)
Before/after code comparison

## Quick Reference
Table or bullets for scanning common operations

## Implementation
Inline code for simple patterns
Link to file for heavy reference or reusable tools

## Common Mistakes
What goes wrong + fixes

## Real-World Impact (optional)
Concrete results

Claude Search Optimization (CSO)

For comprehensive CSO guidance including description patterns, keyword coverage, and naming conventions, load the cso-guide resource from the writing-skills skill.

Key principles:

Description format: {what it does}, {when to use it}, {what the result is}
Write in third person for system prompt injection
Use concrete triggers, symptoms, and outcomes
Include searchable keywords: error messages, symptoms, tools

Flowchart Usage

Use flowcharts ONLY for:

Non-obvious decision points
Process loops where you might stop too early
"When to use A vs B" decisions

Never use flowcharts for:

Reference material → Tables, lists
Code examples → Markdown blocks
Linear instructions → Numbered lists

For graphviz style conventions, load the graphviz-conventions resource from the writing-skills skill.

Visualizing for your human partner: Use render-graphs.js from scripts/writing-skills/ to render flowcharts to SVG:

./scripts/writing-skills/render-graphs.js ./skills/some-skill           # Each diagram separately
./scripts/writing-skills/render-graphs.js ./skills/some-skill --combine # All diagrams in one SVG

Code Examples

One excellent example beats many mediocre ones

Choose most relevant language:

Testing techniques → TypeScript/JavaScript
System debugging → Shell/Python
Data processing → Python

Good example:

Complete and runnable
Well-commented explaining WHY
From real scenario
Shows pattern clearly
Ready to adapt (not generic template)

Don't:

Implement in 5+ languages
Create fill-in-the-blank templates
Write contrived examples

You're good at porting - one great example is enough.

File Organization

Self-Contained Skill

skills/defense-in-depth/
  SKILL.md

When: All content fits inline.

Skill with Reusable Tool

skills/condition-based-waiting/
  SKILL.md
scripts/condition-based-waiting/
  example.ts

When: Tooling is reusable code.

Skill with Heavy Reference

skills/pptx/
  SKILL.md
references/pptx/
  pptxgenjs.md
  ooxml.md
scripts/pptx/
  render-slides.js
assets/pptx/
  diagrams/

When: Reference material is too large for inline docs.

Invariant: skills/<skill-name>/ contains SKILL.md only.

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. Edit skill without testing? Same violation.

No exceptions:

Not for "simple additions"
Not for "just adding a section"
Not for "documentation updates"
Don't keep untested changes as "reference"
Don't "adapt" while running tests
Delete means delete

REQUIRED BACKGROUND: The superpowers:test-driven-development skill explains why this matters. Same principles apply to documentation.

Testing All Skill Types

For comprehensive testing methodology by skill type, load the testing-methodology resource from the writing-skills skill.

Quick reference:

Discipline-enforcing skills: Test under pressure (time, sunk cost, exhaustion)
Technique skills: Test application scenarios and edge cases
Pattern skills: Test recognition and counter-examples
Reference skills: Test retrieval and correct application

Critical principle: Test before deploying. No exceptions.

Bulletproofing Skills Against Rationalization

For detailed strategies on closing loopholes and addressing rationalizations in discipline-enforcing skills, load the rationalization-patterns resource from the writing-skills skill.

Key principles:

Close every loophole explicitly - forbid specific workarounds
Address "spirit vs letter" arguments with foundational principles
Build rationalization tables from baseline testing
Create red flags lists for self-checking
Update description with violation symptoms

RED-GREEN-REFACTOR for Skills

Follow the TDD cycle:

RED: Write Failing Test (Baseline) - Run pressure scenario with subagent WITHOUT the skill. Document exact behavior, rationalizations, and which pressures triggered violations.
GREEN: Write Minimal Skill - Write skill addressing 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.

For complete testing methodology including pressure types and meta-testing techniques, load the testing-methodology resource from the writing-skills skill.

Anti-Patterns

❌ Narrative Example

"In session 2025-10-03, we found empty projectDir caused..." Why bad: Too specific, not reusable

❌ Multi-Language Dilution

example-js.js, example-py.py, example-go.go Why bad: Mediocre quality, maintenance burden

❌ Code in Flowcharts

step1 [label="import fs"];
step2 [label="read file"];

Why bad: Can't copy-paste, hard to read

❌ Generic Labels

helper1, helper2, step3, pattern4 Why bad: Labels should have semantic meaning

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
Move to next skill before current one is verified
Skip testing because "batching is more efficient"

Deploying untested skills = deploying untested code.

Skill Creation Checklist (TDD Adapted)

For the complete checklist with all RED-GREEN-REFACTOR phases and quality checks, load the skill-checklist resource from the writing-skills skill.

Use TodoWrite to create todos for EACH checklist item.

Quick summary:

RED Phase: Create pressure scenarios, run baseline WITHOUT skill
GREEN Phase: Write minimal skill, run scenarios WITH skill
REFACTOR Phase: Close loopholes, re-test until bulletproof
Deployment: Commit, consider PR for broadly useful skills

Discovery Workflow

How future Claude finds your skill:

Encounters problem ("tests are flaky")
Finds SKILL (description matches)
Scans overview (is this relevant?)
Reads patterns (quick reference table)
Loads example (only when implementing)

Optimize for this flow - put searchable terms early and often.

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). Same benefits: Better quality, fewer surprises, bulletproof results.

If you follow TDD for code, follow it for skills. It's the same discipline applied to documentation.