refactor-plan Skill for Claude: Plan a Multi-File Refactor Before Editing

Makes Claude investigate your code and write a phased refactor plan, then stop and wait for your go-ahead before it edits anything.

Installs: 13K; on skills.sh
Stars: 40.7K; on GitHub
Updated: Oct 2026; last repo commit

refactor-plan is a short instruction skill in the github/awesome-copilot collection. When you ask Claude to plan, scope or safely carry out a refactor across several files, it searches the codebase first and does not edit files while it plans. It then prints a plan in a fixed format and asks "Shall I proceed with Phase 1?".

The plan has a current state, a target state, a table of affected files, four phases (types and interfaces, implementation, tests, cleanup) with a verify step each, a rollback plan and risks. The skill bundles no scripts. If you already asked Claude to implement, it still produces the plan first unless you explicitly said to continue without review after the plan.

Good for

Developers about to change code across many files who want a plan to review first
Tech leads who want a rollback plan and risks written down before work starts
Teams that want Claude to stop and ask before it touches a large codebase
Anyone refactoring unfamiliar code who needs the hidden coupling listed

Install refactor-plan

Claude Code

Copy this prompt.

Install the refactor-plan skill in Claude Code. Run this command:

npx skills add https://github.com/github/awesome-copilot --skill refactor-plan

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

Create a concrete plan before starting a multi-file refactor. Use when the user asks to plan, sequence, scope, or safely execute a refactor across multiple files; always investigate first, output the plan, and wait for confirmation before making code changes.

Sections in SKILL.md

Instructions
Output Format
Refactor Plan: [title]
Current State
Target State
Affected Files
Execution Plan
Rollback Plan
Risks

Key facts

Author: Not named in SKILL.md; listed in github/awesome-copilot
Repository: github/awesome-copilot
Installs on skills.sh: 12,987 as of 2026-11-02
GitHub stars: 40,666 for the whole repo, 2026-11-02
License: MIT (repo metadata)
Last commit to the repo: 2026-10-30
Files: 1 file (SKILL.md)
Plan format: Current state, target state, affected files table, 4 phases, rollback plan, risks

What it includes

Searches the codebase and does not edit files while planning
Claude reads implementation, tests, configuration and docs so the plan fits your repository, and finds affected files, ownership boundaries and hidden coupling.
Try: “Plan a refactor that moves our auth checks out of the route handlers into middleware.”
Read · Investigate first
Contracts and types first, then implementations, callers, tests, cleanup
Orders the work so each phase can be checked before the next one starts, with verification steps between phases and a final validation command.
Safe sequencing
Current state, target state, affected files table, phases, rollback, risks
Prints the plan in a set markdown layout with checkbox steps. The example has four phases: Types and Interfaces, Implementation, Tests and Cleanup, and the first three end with a Verify step.
Plan output format
Ends the plan by asking: Shall I proceed with Phase 1?
Claude stops after the plan and waits for your confirmation before implementing, even when you asked it to implement, unless you explicitly said to continue without review after the plan.
Confirmation stop
Asks short questions when the request is too vague to plan safely
If the request is too ambiguous, Claude asks instead of editing files.
Clarifying questions

From the official docs

Questions

What does the refactor-plan skill do?

It makes Claude research your codebase and write a phased refactor plan with verification and rollback steps, then wait for your confirmation before changing code.

How do I install refactor-plan in Claude Code, the Claude app or Codex?

Use the install box at the top of this page. The skill is one SKILL.md file.

Does it edit my files?

Not while planning. SKILL.md says not to edit files while preparing the plan, and to stop and ask for confirmation before implementing.

Does it need an API key or any tools?

SKILL.md names no API key and bundles no scripts. Claude searches and reads your repository to build the plan.

Is it safe?

It tells Claude to read your code and write a plan before any edit, and it bundles no scripts. The awesome-copilot README says its contents come from third-party developers and asks you to inspect them before installing, so read the SKILL.md first.

How is it different from Claude Code plan mode?

The SKILL.md does not mention plan mode. This skill fixes the plan layout (phases, verify steps, rollback, risks) and the closing question, whichever client you use.

Information

updated Nov 2, 2026

Repository: github/awesome-copilot
Folder: skills/refactor-plan

github/awesome-copilot skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 2

refactor-plan SKILL.md · github.com
awesome-copilot README · github.com