Writing Skills

This is test-driven development applied to writing documentation. Instead of testing code, you're testing whether agents actually follow your instructions. You write pressure scenarios with subagents, watch them fail without your skill present, then write the skill document to address those specific failure modes. The approach catches the gap between what you think you communicated and what agents actually understood. It includes solid guidance on skill structure, Claude search optimization, and when skills are worth creating versus just putting notes in project files. The TDD mapping table alone makes the mental model click.

install copies · 90 days. Times the install command was copied on this site in the last 90 days, bots filtered.: 22
skills.sh installs: 231.3K
GitHub stars: 315.2K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add obra/superpowers --skill writing-skills --agent claude-code

Installs into .claude/skills of the current project.

Files

Writing Skills

Overview

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

Personal skills live in your runtime's skills directory (~/.claude/skills/ on Claude Code) — see codex-tools.md or gemini-tools.md for the path on those runtimes. Codex, Copilot CLI, and Gemini CLI all also recognize ~/.agents/skills/ as a cross-runtime alias.

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.

SKILL.md on GitHub