How to use the Writing Plans agent skill (writing-plans)

What agent skills are and what writing-plans makes the agent do

An agent skill is a folder containing a SKILL.md file. The file holds instructions that an agent loads when a request matches the skill's description. This skill's description reads: use when you have a spec or requirements for a multi-step task, before touching code.

When the skill applies, the agent is asked to write the plan for an engineer who has not seen the codebase or the spec. The plan records the decisions the implementer could not make alone: which files to create or modify, which names and signatures to use, which values from the spec apply, and which tests prove each task. Work is split into bite-sized tasks with small steps such as writing a failing test, running it, implementing, and committing. The source also names DRY, YAGNI, TDD and frequent commits as guiding principles.

• Plans are saved to docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md by default, unless your own preferences set another location.
• Every plan begins with a header that includes a Goal, Architecture, Tech Stack and a link to the spec, plus Global Constraints and a Review Focus section.
• Each task lists its Files and an Interfaces block describing what it consumes and produces.

Install the writing-plans skill

Download the ZIP for this skill from this page. The skill package contains one file, SKILL.md. Unzip it so that the writing-plans folder with SKILL.md inside ends up in one of the locations below.

For a personal install that applies to all your projects, place it in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder. In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/writing-plans/SKILL.md
• Project only: <your-project>/.claude/skills/writing-plans/SKILL.md
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Trigger the skill with a natural request

You do not need a special command. The agent decides to use the skill when your request matches its description, so describe the task and mention that you have a spec or requirements. Stating that the work touches several steps or files helps the match.

Make sure the spec exists first. The skill assumes a written spec or requirements; without one, the agent has nothing to plan from.

• "I have a spec for adding CSV export to the reports page. It has several steps. Write an implementation plan before we change any code."
• "Here are the requirements for the new login rate limiter. Plan the work as small tests-first tasks before coding."
• "Create an implementation plan for this spec, with exact file paths, function signatures and the tests for each task."

What a finished plan looks like

A good plan can be handed to another engineer or to a sub-agent and followed without questions. Check that each task names exact file paths, exact function names and signatures, and the tests that prove it. Check that each step is a single action with a result you can verify, such as running a test and expecting it to fail.

The source states that when working in an isolated worktree, that worktree should have been created with the superpowers:using-git-worktrees skill at execution time. The plan's header also points to executing skills, superpowers:subagent-driven-development or superpowers:executing-plans, which carry out the plan task by task.

• Each task ends with an independently testable deliverable.
• Steps include a verification command and the output that means it passed.
• The agent runs a self-review against the spec for coverage, consistency and edge-case inputs.

Safety notes: scripts and network access

This skill runs no scripts and uses no network access, according to its listing. It is a set of written instructions only. The plan it produces may include shell commands such as git add and git commit, and pytest runs in examples. Those commands are for you or the agent to run in your project, so review them as you would any other commands before running them.

• Runs scripts: no
• Uses network: no
• Requires: nothing listed

Tips for better plans

The quality of the plan depends on the spec you give it. Specific values, names and acceptance criteria in the spec carry through into the plan. Vague requirements produce vague tasks.

Use the skill for real multi-step work, not for quick edits. A plan for a one-line fix adds overhead without value.

• Put version floors, naming rules and other project-wide requirements in the spec so they appear in Global Constraints.
• Keep the spec for each independent subsystem separate; the skill suggests splitting specs into separate plans when they cover unrelated subsystems.
• If you prefer another plan location, say so in your request, because user preferences override the default folder.