Individual skill

writing-skills

Use when creating new skills, editing existing skills, or verifying skills work before deployment

skills/writing-skills/SKILL.md

Read pinned source

Source commit 22f0b463e7a5e579904dd6211a520321035526f7

What was checked

Matches the observed repository HEAD: Yes
Scanner rules are current: Yes
Repository scan complete: No
Skill scan complete: No
Observed behavior: Network or broad shell
Last checked: Nov 6, 2026

These are observations at the recorded commit, not a guarantee of safety. Review the source before running it.

Install this skill

Choose an agent in your Stack or copy a command below. Commands fetch the pinned commit and copy only this skill directory. Existing destinations are refused. Copying a command does not install anything.

An install command is unavailable: current rules, complete repository and skill scans, an eligible behavior level and a permitted license are required.

Repository context

Repository stars (not skill ratings): 314,138
Repository last updated: Nov 3, 2026
License: MIT

Observed agent integration: No specific integration evidence. Standard SKILL.md installation does not imply verified compatibility.

ai Repository topic
brainstorming Repository topic
coding Repository topic
obra Repository topic
sdlc Repository topic
skills Repository topic
superpowers Repository topic
subagent-driven-development Repository topic
writing Derived category
devops Derived category

Files and excerpt

File metadata and permitted, redacted excerpts come from the recorded scan. Source links are pinned to that commit.

Browse files

SKILL.mdcore · 16,738 bytes
SKILL.mdcore · 16,738 bytes
SKILL.mdcore · 16,738 bytes
references/CLAUDE_MD_TESTING.mddoc · 5,423 bytes
references/anthropic-best-practices.mddoc · 46,197 bytes
references/bulletproofing.mddoc · 2,577 bytes
references/discovery.mddoc · 7,616 bytes
references/flowcharts.mddoc · 1,262 bytes
references/graphviz-conventions.dotasset · 5,970 bytes
references/persuasion-principles.mddoc · 5,901 bytes
references/testing-skills-with-subagents.mddoc · 12,557 bytes
render-graphs.jsruns · 4,968 bytes

Read excerpt


# 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](../using-superpowers/references/codex-tools.md) or [gemini-tools.md](../using-superpowers/references/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.