writing-skills

SKILL.md

Test-driven documentation for creating reusable agent techniques, patterns, and reference guides.

Write failing test scenarios first (baseline agent behavior without skill), then write minimal skill documentation to address specific violations, following RED-GREEN-REFACTOR cycle

Skills live in agent-specific directories and must include YAML frontmatter (name, description), overview, core patterns, quick reference, and common mistakes sections

Description field must start with "Use when..." and list only triggering conditions—never summarize workflow, as Claude may follow description instead of reading full skill content

Requires understanding superpowers:test-driven-development; discipline-enforcing skills need explicit loophole closures and rationalization tables to resist workarounds under pressure

Keep getting-started skills under 150 words, other frequently-loaded skills under 200 words total; use cross-references and tool help to compress token usage

Writing Skills

Overview

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

Personal skills live in agent-specific directories (~/.claude/skills for Claude Code, ~/.agents/skills/ for Codex)

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: For Anthropic's official skill authoring best practices, see anthropic-best-practices.md. 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.