Guide · Agent skill
How to use the writing-plans agent skill: install and run it
Updated · written with AI from the project's own documentation and checked against our catalogue data
The writing-plans skill is a set of instructions that tells an AI coding agent how to turn a written requirements spec into a detailed implementation plan before any code is written. It is useful for developers who want a clear, test-driven breakdown of a multi-step task, and for teams that hand work to other engineers or sub-agents. By the end of this guide you will know what the skill does, how to install it, how to ask for it in plain language, and what it needs to work well.
Writing Implementation PlansjnMetaCode/superpowers-zh · MIT Download the skill Quick start
- 1Confirm you have a written spec. Write the requirements for the multi-step task in a document. The skill assumes this exists and does not invent requirements.
- 2Install the skill folder. Download the ZIP from this page, unzip it, and place the folder in ~/.claude/skills/ or the project's .claude/skills/, or upload it under Settings → Capabilities → Skills.
- 3Ask for a plan in plain language. Name the spec file and ask for an implementation plan before any code changes.
- 4Review the file structure and tasks. Check that the listed files and paths match your codebase conventions before approving the plan.
- 5Check the Review Focus section. Confirm the five failure cases chosen are the ones that matter to your users, and that a test covers each.
- 6Choose an execution method. Pick subagent-driven or native execution, then follow the companion skill the plan names.
What is an agent skill, and what does writing-plans make the agent do?
An agent skill is a folder containing a SKILL.md file. The file holds instructions that an AI agent reads when a task matches the skill's description. This one is named writing-plans and is described in Chinese as: use it when you have a specification or requirements for a multi-step task, before writing code.
When the skill applies, the agent writes an implementation plan for an engineer who has never seen the codebase or the spec. The plan records the decisions already made: which files to create or change, the names and signatures, the specific values from the spec, and which tests prove each task. Work is split into small tasks, and each task is made of checkable steps such as writing a failing test, running it, implementing the minimum code, running the tests again, and committing.
- File structure is decided before tasks are defined, with each file given one clear responsibility.
- Each plan starts with a header stating the goal, architecture, tech stack and the spec it implements.
- A self-review checks spec coverage, placeholder steps, type and name consistency, and plan length compared with the spec.
- After the plan is saved, the agent offers a choice of execution method: subagent-driven or native execution.
Install the writing-plans skill
Download the ZIP for this skill from this page and unzip it. The skill folder contains SKILL.md. Place the folder in one of these locations:
You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.
- Personal: unzip into ~/.claude/skills/ so it is available across your projects.
- Project only: unzip into the project's .claude/skills/ folder so it applies to that repository.
Trigger the skill with natural requests
You do not need a special command. The agent matches your request against the skill's description, so ask for a plan in plain language once you have a written spec. Mention the spec file so the agent can read it.
The skill expects the spec to exist already. If you only have a vague idea, write the requirements first, then ask for the plan.
- "Here is the spec in docs/feature-x.md. Write an implementation plan before we change any code."
- "Using our requirements document, plan the multi-step change to the export module as small test-driven tasks."
- "Break this spec into tasks an engineer or sub-agent can follow without asking questions."
What the saved plan looks like
By default the skill saves the plan to docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md. A user preference for a different location takes priority over this default.
Each task lists the files to create, modify and test, followed by numbered steps. A test step shows the test code, a run step gives the command and the expected result, and a commit step gives the git commands. The example below shows the format of a task step as written in the source.
- Header: goal, architecture, tech stack, and the spec path.
- Global constraints copied from the spec, one per line.
- Review Focus: up to five likely failure cases the spec implies but no task covers, each with a test added to the responsible task.
- Tasks: exact file paths, checkable steps, and commits.
- [ ] **步骤 2：运行测试验证失败**
运行：`pytest tests/path/test.py::test_name -v`
预期：FAIL，报错 "function not defined"Review the plan and choose how to execute it
After saving the plan, the agent asks you to review it and pick an execution method, unless you already gave one. Subagent-driven execution gives each task a fresh sub-agent and a fresh reviewer before the next task starts, with a final review of the whole branch. Native execution has the current session implement each task, with a final independent review at the end.
The source names the companion skills subagent-driven-development and executing-plans for these paths. Those files are not included with this skill, so you will need them separately if you choose either path.
What people use it for
- Turning a feature spec into a file-by-file plan before a developer starts coding.
- Writing a plan that a sub-agent can follow step by step without asking questions.
- Saving a reviewable markdown plan for a team lead to approve before implementation begins.
- Checking a spec for requirements that no planned task covers, using the self-review step.
Frequently asked questions
How do I install the writing-plans skill?
Download the ZIP from this page and unzip it. Put the folder in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder for one repository. You can also upload it in the Claude apps under Settings → Capabilities → Skills.
What does writing-plans require?
It requires a written spec or requirements document for the task and Git, because the plan includes commit steps. It also refers to companion skills named brainstorming, subagent-driven-development and executing-plans, whose files are not included here.
Is writing-plans free to use?
The skill is released under the MIT licence, as stated in its SKILL.md. The source does not list any price, so check the licence text for the terms.
Does writing-plans run scripts or use the network?
According to our assessment, it runs no scripts and uses no network access. It consists of a single SKILL.md file of instructions.
Why doesn't the skill trigger for my request?
The skill is matched to requests involving a written spec for a multi-step task. Name the spec file and say you want a plan before code is written. If you have no spec, the skill is not designed for that case, so write requirements first.
Is writing-plans a good choice for small fixes?
No. A formal plan adds overhead to small one-off edits or quick fixes. It is intended for multi-step work with a written spec. For projects without a spec, the skill's assumptions do not hold.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use writing-plans if you start features from a written spec and want a test-driven, file-by-file plan that another engineer or sub-agent can follow. Pick something else for small edits, projects without a spec, or codebases whose paths and test conventions differ from the plan's assumptions.
Download the skill