refactor-plan
Create structured refactoring plans. Use when user wants to plan a refactor, needs a refactoring strategy, or mentions breaking down large changes into small commits. Don't use for implementing code changes directly, small one-line fixes, or renaming a single variable.
- Installs
- 47
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/helderberto/agent-skills --skill refactor-plan- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads refactor-plan automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Refactor Planning
Process
1. Understand Problem
- Get detailed description from user
- Ask about potential solutions they've considered
- Explore codebase to verify current state
2. Define Scope
- Interview user about implementation details
- Present alternative approaches — each approach as an option with trade-offs in description; use preview to show code sketches when applicable. Use AskUserQuestion when available; otherwise present as a numbered list.
- Define exactly what changes and what stays
- Check test coverage in affected areas
3. Break Down Work
Apply Martin Fowler's principle: "Make each refactoring step as small as possible, so that you can always see the program working."
- Create list of tiny commits
- Each commit leaves codebase working
- Sequential, not parallel changes
4. Create GitHub Issue
gh issue create --title "Refactor: <title>" --body "$(cat <<'EOF'
## Problem Statement
The problem from the developer's perspective.
## Solution
The approach from the developer's perspective.
## Commits
Detailed plan broken into the tiniest commits possible. Each leaves codebase working.
1. Add new interface type
2. Update service to accept new interface (keep old code path)
3. Add tests for new code path
4. Update consumers to use new interface
5. Remove old code path
## Implementation Decisions
- Modules to build/modify and their interfaces
- Architectural decisions
- Schema changes
- API contracts
Do NOT include file paths or code snippets -- they go stale.
## Testing Decisions
- What makes a good test (behavior, not implementation)
- Which modules need tests
- Prior art: similar test patterns in the codebase
## Out of Scope
What is explicitly not included.
EOF
)"
Rules
- Each commit must keep codebase functional
- No implementation details in plan (focus on behavior)
- Verify test coverage before starting
- Get user approval on approach
Error Handling
gh issue createfails -- rungh auth statusto verify auth; offer to print as markdown instead- Test coverage insufficient -- note gaps and add "add tests for X" as first commit
- Scope larger than expected -- revise plan with user before proceeding
See Also
- tdd -- implement refactored code using test-driven development
FAQ
What does the refactor-plan skill do?
Create structured refactoring plans. Use when user wants to plan a refactor, needs a refactoring strategy, or mentions breaking down large changes into small commits. Don't use for implementing code changes directly, small one-line fixes, or renaming a single variable.
How do I install refactor-plan?
Run npx skills add https://github.com/helderberto/agent-skills --skill refactor-plan in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/refactor-plan/ (personal) or .claude/skills/refactor-plan/ (project).
Which AI agents can use refactor-plan?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is refactor-plan safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains refactor-plan?
It is published by helderberto in helderberto/agent-skills. It has 47 recorded installs.
More from helderberto/agent-skills
code-review
helderberto/agent-skills
Correctness lens for a PR or diff, used by build and review — bugs, security, performance, and code quality. Use when asked to review a PR or give pull request feedback, even when the diff is pasted inline. Don't use for local uncommitted changes, creating PRs, or merging.
explain-code
helderberto/agent-skills
Explains code with visual diagrams and analogies. Use when explaining how code works, walking through a codebase area, or when the user asks "how does this work?" Don't use for modifying code, fixing bugs, generating new implementations, or multi-session concept learning (use /teach).
commit
helderberto/agent-skills
Group unstaged changes into atomic commits by concern, matching repository style. Use when asked to "commit", "create a commit", or "commit changes". Don't use for pushing or pull requests (/to-pr).
lint
helderberto/agent-skills
Open the skill to read its SKILL.md instructions.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.