Guide · Agent skill
How to use the Rewrite Plan Author agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The rewrite-plan skill makes an AI agent write a structured plan before it edits a codebase for a large migration or conversion. It is aimed at developers turning a design or prototype into production code, and at teams running multi-file refactors. After this guide you will know what the skill produces, how to install it, how to trigger it, and where it fits in the Open Design pipeline.
Rewrite Plan Authornexu-io/open-design · Apache-2.0 Download the skill Quick start
- 1Install the skill. Download the ZIP and unzip the rewrite-plan folder into ~/.claude/skills/ or a project's .claude/skills/, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 2Start the Open Design daemon. The runner is implemented in apps/daemon/src/plugins/atoms/rewrite-plan.ts, so the daemon must be available for the skill to run.
- 3Confirm prior outputs exist. Check that code/index.json from code-import and token-map/*.json from token-map are present, since the plan is built from them.
- 4Ask for a plan in plain language. Request a rewrite plan before any edits, describing the migration and stating that no files should change yet.
- 5Review plan.md. Read the narrative first to understand the reasoning behind the approach.
- 6Check ownership and steps. Confirm ownership.json classifies every file and steps.json has small per-component steps ending in build-test with accurate risk levels.
- 7Hand off to patch-edit. Proceed to the patch-edit stage, which reads steps.json one entry per iteration, only after you are satisfied with the plan.
What an agent skill is and what this one does
An agent skill is a folder containing a SKILL.md file and any supporting files that an agent can load when a task matches the skill's description. This one is named rewrite-plan and its description is: author a long-running multi-file rewrite plan that subsequent patch-edit, diff-review and build-test stages will execute, with explicit ownership boundaries and patch-safety guarantees.
The skill does not perform the rewrite. It writes the plan. Later editing stages are meant to follow that plan one step at a time, so changes stay bounded and reviewable instead of sprawling.
- plan/plan.md: a human-readable narrative of the plan.
- plan/ownership.json: classifies each file by layer (leaf, shared, route or shell), separating files that belong to a single component from shared infrastructure.
- plan/steps.json: an ordered list of steps, each with an id, files, rationale and a risk level of low, medium or high.
- plan/meta.json: generatedAt, atomDigest and tokenMapDigest.
Install the rewrite-plan skill
Download the ZIP for this skill from the page where you found this guide. Unzip it so the rewrite-plan folder (containing SKILL.md) sits in one of these locations: ~/.claude/skills/ for your user account, or .claude/skills/ inside a specific project if you want the skill to apply only there.
Alternatively, in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.
- Personal install: ~/.claude/skills/rewrite-plan/
- Project install: <your-project>/.claude/skills/rewrite-plan/
- Claude apps: Settings → Capabilities → Skills → upload
Prepare the inputs the skill needs
The skill expects outputs from two earlier Open Design stages. Without them the plan has nothing to base its ownership and token decisions on. The skill's inputs are code/index.json from the code-import stage and token-map/*.json from the token-map stage, plus the active design system DESIGN.md and your tune intent, which is usually a short brief.
The skill also requires the Open Design daemon. Its runner is implemented in apps/daemon/src/plugins/atoms/rewrite-plan.ts.
- code/index.json (from code-import)
- token-map/*.json (from token-map)
- DESIGN.md for the active design system
- A short brief describing what you want changed
Trigger the skill with a natural request
Agents load a skill when your request matches its description, so ask for planning in plain language before any edits happen. Mention the migration, the scope and the fact that you want a plan first. Naming the skill directly is also reasonable.
The skill is designed for the planning stage of the Open Design pipeline, so the request should make clear that the files are a multi-file conversion rather than a quick fix.
- "Before you edit anything, write a rewrite plan for converting this prototype into production components."
- "Use the rewrite-plan skill to plan the multi-file migration from the design tokens to our component library."
- "Draft a step-by-step plan with ownership boundaries for this refactor. Don't change any files yet."
Read and review the plan
Read plan/plan.md first for the reasoning, then check ownership.json and steps.json. The skill's own rules say a plan should break work into per-component steps rather than one step called rewrite the whole component library, should classify ownership for every file, and should end with a build-test step. If a plan breaks any of these, ask the agent to revise it before moving on.
The skill's convergence rule is that the plan is complete when plan.md is non-empty and steps.json contains at least one step. That is a minimum check, not a quality check, so your review still matters.
- Every step has a clear files list and rationale.
- No step rewrites a whole component library in one go.
- Shell-layer files are flagged as high risk.
- The plan ends with a build-test step.
Safety notes: scripts and network
The skill's metadata says it runs scripts: yes and uses network: no. Its runner classifies ownership and writes plan.md, steps.json and ownership.json. Review the runner in apps/daemon/src/plugins/atoms/rewrite-plan.ts if you need to know exactly what runs on your machine.
The skill declares that patch-edit refuses to touch a shell-tier file unless the matching step has risk high and the user explicitly confirmed. That guard applies in the later editing stage, so keep the plan's risk labels accurate.
- Runs scripts: yes (the daemon runner).
- Uses network: no, according to the skill metadata.
- Shell-tier files need a high-risk step and explicit confirmation before patch-edit touches them.
What people use it for
- Converting a design prototype into production components while keeping each component's changes in its own step.
- Planning a multi-file refactor that needs explicit ownership of shared infrastructure versus single components.
- Producing an audit trail of planned changes before the Open Design patch-edit and build-test stages run.
- Breaking a large token migration into ordered, low-, medium- or high-risk steps for review.
Frequently asked questions
How do I install the rewrite-plan agent skill?
Download the ZIP from the page and unzip the rewrite-plan folder into ~/.claude/skills/ for your user account, or into a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills.
Is the rewrite-plan skill free to use and what is its licence?
The item is licensed under Apache-2.0, as listed on this page. This guide does not state pricing, so check the source repository for any terms beyond the licence.
Does rewrite-plan rewrite my code?
No. The skill only writes the plan as plan.md, steps.json, ownership.json and meta.json. The source text provided says the file has no editing logic of its own; later patch-edit, diff-review and build-test stages are meant to execute the plan.
What does rewrite-plan require to run?
It requires the Open Design daemon, whose runner is at apps/daemon/src/plugins/atoms/rewrite-plan.ts. It also needs prior outputs from code-import (code/index.json) and token-map (token-map/*.json), plus the active DESIGN.md and your brief.
Can I use rewrite-plan outside the Open Design pipeline?
The skill refers to stages named code-import, token-map, patch-edit and build-test. Those may not exist in another setup, so the skill is not a good fit outside the Open Design pipeline.
When should I not use this skill?
Skip it for small single-file edits, where a plan adds overhead without benefit. It is meant for large migrations or conversions with multiple files and components.
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 rewrite-plan if you are converting a design or prototype into production code inside the Open Design pipeline and want a reviewable, per-component plan with ownership boundaries before any files change. Pick something else for quick single-file edits, for tasks outside the Open Design stages, or if you want a skill that performs the rewrite itself.
Download the skill