writing-skills

A skill in obra/superpowers · 321,873 stars on GitHub

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

Security grade of this SKILL.md: SAFE · how we grade

How to install writing-skills

npx skills add obra/superpowers --skill writing-skills -a claude-code

The skills CLI copies this one skill into Claude Code (use -a for another agent). Or read its SKILL.md on GitHub.

What the SKILL.md says

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.

Other skills in obra/superpowers

  • brainstorming You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning…
  • diagnosing-superpowers Use when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results,…
  • dispatching-parallel-agents Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
  • executing-plans Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, o…
  • finishing-a-development-branch Use when implementation is complete, all tests pass, and you need to decide how to integrate the work
  • receiving-code-review Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable…
  • requesting-code-review Use when completing tasks, implementing major features, or before merging to verify work meets requirements
  • subagent-driven-development Use when executing implementation plans with independent tasks in the current session
  • systematic-debugging Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
  • test-driven-development Use when implementing any feature or bugfix, before writing implementation code
  • using-git-worktrees Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated w…
  • using-superpowers Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clari…
  • verification-before-completion Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and…
  • writing-plans Use when you have a spec or requirements for a multi-step task, before touching code