refactoring-analysis — Claude Code skill: what it does, how to install
Audits architectural health and Fowler code smells, writing prioritized refactoring plans to docs/_refacs/. Built for planning refactoring while preserving existing behavior.
npx skills add pedronauck/skills --skill refactoring-analysis -a claude-codeWhat refactoring-analysis does
This skill reviews codebases for Fowler code smells and structural debt that increase maintenance costs. It rejects abstract textbook labels without demonstrable consequences, requiring source evidence and concrete improvements. For large projects, it maps dependencies and hotspots without pausing for confirmation at 50 files, noting any unsampled areas directly.
The analysis evaluates coupling, ownership, call sites, and public boundaries using built-in catalogs and checklists. SOLID guidelines apply strictly to domain models rather than ordinary utility code. Confirmed refactoring opportunities are ranked by impact, frequency, risk, and effort, then documented in docs/_refacs/<YYYYMMDD>-<slug>.md.
Formatting rules, security reviews, and performance profiling are deliberately excluded from this workflow. If a project requires vulnerability scans or memory benchmarks, look elsewhere.
What it helps with
- identify Fowler code smells backed by concrete source evidence
- generate prioritized refactoring reports in
docs/_refacs/ - trace ownership, call boundaries, and tight coupling across modules
- plan structural refactoring while preserving existing behavior
Example prompts for the agent
- Run a refactoring analysis on the core modules and write findings to docs/_refacs/
- Audit code smells across recent changes and rank them by maintenance risk
- Map coupling and dependency hotspots in the project before we refactor
How to install refactoring-analysis
1Skills CLI (Vercel)
npx skills add pedronauck/skills --skill refactoring-analysis -a claude-code2Manually: put the files in place
~/.claude/skills/refactoring-analysis/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/refactoring-analysis/
1Skills CLI (Vercel)
npx skills add pedronauck/skills --skill refactoring-analysis -a codex2Manually: put the files in place
.agents/skills/refactoring-analysis/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add pedronauck/skills --skill refactoring-analysis -a cursor2Manually: put the files in place
.cursor/skills/refactoring-analysis/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install pedronauck/skills refactoring-analysis2Manually: put the files in place
.github/skills/refactoring-analysis/SKILL.md1Skills CLI (Vercel)
npx skills add pedronauck/skills --skill refactoring-analysis -a gemini-cli2Platform CLI
gemini skills install https://github.com/pedronauck/skills --path skills/mine/refactoring-analysisManually: put the files in place
.devin/skills/refactoring-analysis/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add pedronauck/skills --skill refactoring-analysis -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about refactoring-analysis
How to install refactoring-analysis in Claude Code?
Run npx skills add pedronauck/skills --skill refactoring-analysis -a claude-code.
What does refactoring-analysis do?
It detects Fowler code smells, maps architectural boundaries, and writes a prioritized refactoring plan directly to docs/_refacs/.
Does refactoring-analysis cover security or performance audits?
No, the skill intentionally excludes performance optimization, security audits, and automated code formatting.
