writing-skills
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.
More from obra/superpowers
brainstorming
You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.
152.5Kusing-superpowers
Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions
92.8Ksystematic-debugging
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
92.1Kwriting-plans
Use when you have a spec or requirements for a multi-step task, before touching code
91.4Krequesting-code-review
Use when completing tasks, implementing major features, or before merging to verify work meets requirements
80.5Ktest-driven-development
Use when implementing any feature or bugfix, before writing implementation code
79.9K