Source: obra/superpowers · Maintainer: community: Jesse Vincent (Prime Radiant) · License: MIT · Checked: 24 October 2026
What is the writing plans skill?
The writing plans skill turns a spec or a set of requirements into an implementation plan that a coding agent can execute task by task: which files change, which names and signatures to use, which test proves each task, and when to commit. It runs before any code is touched.
It is the planning step of Superpowers, the open source skill library by Jesse Vincent and Prime Radiant, and it usually follows the brainstorming skill. The skill's description reads: "Use when you have a spec or requirements for a multi-step task, before touching code".
Its skills.sh page listed about 282,700 installs (snapshot, 24 October 2026), and all three security audits shown there (Gen Agent Trust Hub, Socket and Snyk) were Pass.
What does it do?
The SKILL.md tells the agent to write for "an engineer who has not seen this codebase or this spec." That reader can write good code once they know the exact interface and test. What they cannot know is what you decided, so the plan records those decisions. It sums up the style in four words: "DRY. YAGNI. TDD. Frequent commits."
The agent announces that it is using the skill, then works through these parts:
- Scope check. If the spec covers several independent subsystems, it suggests separate plans, each producing working, testable software on its own.
- File structure. Before any tasks, it maps which files will be created or changed and what each is responsible for. It prefers small, focused files, split by responsibility rather than by technical layer, and follows existing patterns in an established codebase.
- Task sizing. A task is "the smallest unit that carries its own test cycle and is worth a fresh reviewer's gate." Setup, config and docs fold into the task that needs them.
- Steps. Each step is one action with a checkable result: write the failing test, run it to see it fail, implement, run it to see it pass, commit.
Every plan starts with a fixed header: goal, architecture, tech stack, a link to the spec, a Global Constraints section copied verbatim from the spec, and a Review Focus section. Review Focus lists the five inputs or failure modes the spec implies but no test covers, most likely first, and each one then gets a test added to the task that owns the code.
Each task has a Files block (create, modify with line ranges, test) and an Interfaces block saying what it consumes from earlier tasks and what later tasks rely on. Steps use checkbox syntax, and every command has an expected result.
After writing, the agent runs a self-review against the spec: coverage, a scan for vague steps such as "TBD" or "handle edge cases", type and name consistency across tasks, the Review Focus list, and proportion. That last check matters: "A plan longer than the code it describes has written the code instead."
What's in the folder: just SKILL.md. There are no scripts, templates or reference files.
How do you install the writing plans skill?
As part of Superpowers in Claude Code. The Superpowers README installs it from Anthropic's official marketplace:
/plugin install superpowers@claude-plugins-official
Plugin skills are namespaced as /plugin-name:skill-name per the Claude Code skills docs, so it shows up as /superpowers:writing-plans. The README also documents the obra/superpowers-marketplace route and installs for Codex, Cursor, Gemini CLI and other agents.
Just this skill. The skills CLI can copy one folder, exactly as shown on the skills.sh page:
npx skills add https://github.com/obra/superpowers --skill writing-plans
Add -g to install for all projects and -a claude-code to target Claude Code. The folder lands in .claude/skills/writing-plans/ in your project, or ~/.claude/skills/writing-plans/ with -g. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.
In the Claude apps. It is a single MIT-licensed file, so you can zip the folder and upload it in Customize > Skills, following Anthropic's help article on skills.
Standalone, the skill still hands off to superpowers:subagent-driven-development or superpowers:executing-plans. Install the subagent driven development skill or the executing plans skill as well if you want the agent to run the plan it writes.
How do you use it?
Give it something to plan from: a design doc from brainstorming, a written spec, or detailed requirements. With Superpowers installed, the brainstorming skill invokes it automatically once you approve a design. You can also call it directly.
Example prompts (suggestions, not quotes from the repo):
/superpowers:writing-plans Write the plan for docs/superpowers/specs/2026-10-20-invites-design.md.We have the spec for rate limiting in SPEC.md. Plan it before touching code.Plan the migration from REST polling to webhooks. Keep each task independently testable.Write an implementation plan for this ticket, and put it in docs/plans/ instead of the default folder.
When it finishes, the agent links the plan and asks you to review it. If you haven't already chosen how to run it, it offers two options and recommends one:
| Option | What happens |
|---|---|
| Subagent-driven | A fresh subagent implements each task and a fresh reviewer checks it before the next one, then a whole-branch review. "Most thorough" |
| Native | The agent implements every task itself in the session, then one fresh reviewer checks the whole branch. "Cheapest and fastest" |
Requirements: none beyond a repo to write the plan into. The example task in the SKILL.md uses Python and pytest, but the format works with any language and test runner.
How is it different from Claude Code plan mode?
Claude Code's built-in plan mode, per the permission modes docs, "tells Claude to research and propose changes without making them." It is a mode for the current session: you review the proposal, approve it, and Claude starts editing. See our plan mode guide.
writing-plans produces a saved document with a fixed structure, written so a different agent, a subagent per task, or a later session can execute it. The two can work together. The Superpowers bootstrap skill tells the agent to run brainstorming before entering plan mode, and the plan file is what the execution skills read.
Tips and limits
From the files, not from testing:
- Plans are lean on purpose. The Superpowers README describes tasks with "complete code", but the current SKILL.md asks for signatures, test names and assertions instead of full function bodies. The SKILL.md is what the agent follows.
- Vague lines are bugs. "Add appropriate validation" or "write tests for the above" decide nothing, and the self-review is meant to catch them. Point them out if any slip through.
- Worktrees come later. The skill expects any isolated worktree to be created by
superpowers:using-git-worktreesat execution time, not during planning. - What runs. Nothing. The skill writes one Markdown file and runs no scripts.
- License. MIT, so you can copy and edit the skill if you keep the copyright notice.
Save it in your Kipt library
In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Kipt reads the SKILL.md; for a repo with many skills it shows a list to pick from, so you can take brainstorming and an execution skill in the same import. You can also drop the folder or a .zip. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:
npx skills add https://github.com/<you>/<repo>.git --all -g
Kipt is not affiliated with Jesse Vincent, Prime Radiant or Superpowers.
Similar skills
- Superpowers skills: the full workflow this plan format feeds.
- Grill me skill: settle every decision in a plan before you write it down.
- TDD skill: Matt Pocock's red-green loop, for the test-first steps in each task.
- Improve codebase architecture skill: find refactor candidates worth planning.