14 Markdown skills and working rules
Jesse Vincent (GitHub account obra) has long studied collaboration workflows for AI coding agents, developing a complete set of practices including red-green TDD, planning steps and self-updating memory notes. After Claude Code introduced plugins, he packaged these practices into Superpowers. The GitHub project description is "An agent skills framework and software development methodology that actually works."
The framework has 14 composable Markdown skills in skills/, requiring no slash commands. Each skill defines a working rule: brainstorming uses Socratic questions to clarify requirements, test-driven-development enforces RED-GREEN-REFACTOR, systematic-debugging requires four-stage root cause analysis, and subagent-driven-development lets agents dispatch subagents to work continuously and autonomously for two hours or more. These skills trigger automatically without special commands.
The official README lists the design principles: write tests first, always; systematic work over improvisation; reducing complexity as the primary goal; and evidence over claims of completion. Superpowers enforces completion of every stage in order, without making output speed its goal. Critical code review issues block progress, and quality verification takes priority over speed.
Brainstorm
Plan
Execute
Review
Debug
Verify
Finish
Write tests first, always. Systematic work over improvisation; evidence over claims.
Platform installation commands
Superpowers is available in Claude's official plugin marketplace. Run the following command in Claude Code; the skills take effect automatically after installation, without requiring you to remember skill commands.
# Claude Code: Install from the official marketplace
/plugin install superpowers@claude-plugins-officialSeparate installation for each agent platform
Superpowers is a cross-platform framework, but it does not synchronize automatically across tools. Install it separately in each coding agent you use, with the corresponding command below.
# Factory Droid
droid plugin marketplace add https://github.com/obra/superpowers
droid plugin install superpowers@superpowers
# Gemini CLI
gemini extensions install https://github.com/obra/superpowers
# GitHub Copilot CLI
copilot plugin marketplace add obra/superpowers-marketplace
copilot plugin install superpowers@superpowers-marketplace
# Cursor
/add-plugin superpowers
# Codex CLI: Search for "superpowers" in /plugins14 composable skills by lifecycle stage
Superpowers skills are enforced working rules: clarify requirements before writing code, require a failing test before implementation, find the root cause before fixing a bug, and verify before declaring completion. The 14 skills are grouped by lifecycle stage; you do not need to remember their names because agents load them automatically at the corresponding stage.
Brainstorm · 01
brainstorming
Socratic requirements clarification
Use questions to clarify vague ideas before writing any code, confirm the problem to solve, then proceed.
Plan · 02
writing-plans
Implementation plans
Produce implementation plans that follow TDD and YAGNI, presenting specifications in sections people can read, review and approve.
Execute · 03
executing-plans
Plan execution
Execute the approved plan item by item, with systematic reviews between tasks, without departing from the agreed scope.
Execute · 04
subagent-driven-development
Autonomous subagent development
Dispatch tasks to subagents for continuous autonomous work lasting two hours or more; the main agent only coordinates and oversees quality.
Execute · 05
dispatching-parallel-agents
Parallel dispatch
Divide independent work among multiple agents running in parallel to reduce overall delivery time.
Execute · 06
using-git-worktrees
Worktree isolation
Use Git worktrees for parallel development branches so work can proceed simultaneously without interfering with other work.
Quality · 07
test-driven-development
RED-GREEN cycle
The test-first rule: a test must fail before implementation. Red → green → refactor; no skipped steps.
Quality · 08
systematic-debugging
Four-stage root cause analysis
Four-stage root cause analysis. The rule: no fixes before identifying the root cause.
Review · 09
requesting-code-review
Requesting review
Proactively request code review between tasks to catch problems before proceeding to the next step.
Review · 10
receiving-code-review
Handling review feedback
Handle review feedback systematically: critical issues block progress until fixed.
Verify · 11
verification-before-completion
Pre-completion verification
Verify with evidence before saying the work is done; a claim of completion is insufficient.
Finish · 12
finishing-a-development-branch
Finishing branches
Finish the development branch: organize, verify and integrate it to complete that stage of work.
Meta · 13
writing-skills
Writing new skills
Use consistent standards to write new Superpowers skills so your own workflows can be packaged and triggered.
Meta · 14
using-superpowers
Framework entry point
Framework usage conventions and the starting point for skill orchestration, telling agents when to invoke each working rule.
Four principles and their corresponding skills
Each Superpowers design principle has a corresponding skill that enforces it, rather than merely recommending it. When a condition is violated, the skill blocks further progress.
| Design principle | Enforcing skill | Blocking condition |
|---|---|---|
| Write tests first, always | test-driven-development | No implementation before a test fails |
| Systematic work over improvisation | systematic-debugging | No fixes before identifying the root cause |
| Evidence over claims | verification-before-completion | No claim of completion before verification |
| Clarify the problem first | brainstorming → writing-plans Clarify requirements, create a plan, then wait for approval before starting |
8 operating tips from documentation and community observations
Simon Willison covered Superpowers in a dedicated article in 2025/10, Marc Nuri called it "a Claude Code skills framework shipped as Markdown", and it is listed on Claude's official plugin page. The following tips come from the official README and public blogs, ordered by priority.
Task descriptions and automatic triggering
Superpowers skills trigger automatically without requiring you to remember names such as brainstorming or test-driven-development. Describe the feature to implement, and the agent loads the corresponding skill at the corresponding stage.
Source · Official README · Automatic triggering
Separate installation for each agent
It is a cross-platform framework, but it does not synchronize automatically. If you use Claude Code and Cursor, install it in both; an agent without the installation does not have these working rules.
Source · Official README · Installation
Requirements clarification before implementation
brainstorming uses Socratic questions, asking follow-up questions before the first line of code to clarify requirements. The extra time at this stage usually avoids the cost of a full rewrite later.
Source · Official README · brainstorming skill
TDD's test-first rule
test-driven-development enforces RED-GREEN-REFACTOR: a test must fail before implementation. The skill blocks agents that try to skip steps and implement a feature directly.
Source · Official README · TDD skill
Root cause analysis before fixes
systematic-debugging enforces four-stage root cause analysis. No fixes are allowed before identifying the actual cause, preventing speculative changes.
Source · Official README · Systematic debugging
Continuous autonomous subagent work
Simon Willison's observation: subagent-driven-development lets agents work continuously and autonomously from an approved plan for two hours or more, with automatic code reviews in between, rather than asking you questions every few minutes.
Source · simonwillison.net 2025-10 article
Custom workflow skills
The repo includes writing-skills, a skill for writing a Superpowers skill. Turn your team's recurring working rules into new skills, and agents apply them automatically at the appropriate time.
Source · Official README · writing-skills
Restrictions on new skill PRs
The README states that contributors should use writing-skills to write skills for their own use; submissions of new skills are generally not accepted. For customization, fork and extend locally rather than submit a PR and wait for it to merge.
Source · Official README · Contributing
Full workflow from a vague request to a tested PR
This adapted scenario starts with a single request: "Add a CSV export feature." Superpowers does not ask which skill command you want. It automatically brainstorms, creates a plan for your approval, enforces TDD, runs subagents continuously, reviews between tasks and finishes only after verification.
$ You ›
Add a CSV export feature.
claude: Claude ›
Before writing code, I need to confirm a few things:
hl: · Which table? All columns or a subset?
hl: · Who exports it? Are there permission levels?
hl: · How much data? Should we stream over ten thousand rows?
hl: · What should the time zone and amount format match?
$ You ›
The invoice table; only administrators can export it. It may contain over ten thousand rows. Use the ledger's amount format.
claude: Claude ›
Plan(following TDD + YAGNI), presented in sections:
1. Permission guard: return 403 for non-admins(write the test first)
2. Streaming export: write in batches, without loading everything into memory
3. Formatting: match amounts/time zones to the ledger
hl: I will start only after you approve the plan. What should change?
$ You › Approved. Start.
ok: GREEN · Add permission guard → Pass
ok: GREEN · Stream in batches → Pass
claude: REVIEW · Issue found: amounts use floating point, but the ledger requires fixed point
ok: GREEN · Use Decimal → Pass · Rerun the full test suite
ok: Branch finished cleanly · PR opened · Awaiting your final review
Start with a single "Add an export" request; receiving-code-review catches the floating-point amount issue between tasks and allows progress only after the fix and rerun.
Workflow breakdown
The entire workflow uses three inputs and no slash commands; skills trigger automatically at the corresponding stage. The checkpoints are requirements clarification, a failing test first, and review blocking progress after catching the amount type error until it is fixed and tests rerun.
The framework distinguishes a "methodology" from a "prompt collection": the workflow requires verification evidence before declaring completion.
Workflow completeness, quality and speed tradeoffs
Five paths for extending and customizing skills
Every skill is plain Markdown in skills/; read, modify or add custom working rules without writing code. The MIT license permits forks. According to the official README, the author usually does not accept new skill PRs, so a fork for your own use is the expected customization method.
Advanced configuration paths
1. Use writing-skills for team working rules. Turn rules for common team problems (naming conventions, release checks and data migrations) into new skills using the writing-skills standards, and agents apply them automatically at the appropriate time.
2. Fork and extend locally. Clone into your own maintenance branch and add company rules to existing skills. Handle divergence yourself when upgrading upstream rather than submitting a PR and waiting for a merge.
3. Keep platforms consistent. For consistent delivery quality, install the same Superpowers version on every platform if your team uses Claude Code and Cursor / Gemini; this lets different agents follow the same workflow.
4. Use worktrees for parallel work. Combine using-git-worktrees with dispatching-parallel-agents to split independent work into parallel development tracks and reduce overall delivery time.
5. Make brainstorming a requirements check. Set the team rule "No plan before brainstorming" to avoid starting projects before requirements are clear.
Three further readings
① obra/superpowers README: Official explanation of the framework's purpose, installation matrix and design principles. ② Simon Willison: Superpowers (2025-10): An external analysis of the framework's practical effects. ③ skills/ directory: Original Markdown for the 14 skills; read it before modifying them.
Superpowers aims to enforce completion of every stage in the prescribed order, not to increase agents' output speed.