How do I install the Refactor Expert skill?

Run npx skillmds@latest add nguyenthienthanh/refactor-expert in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Refactor Expert safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Refactor Expert?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Refactor Expert free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Refactor Expert?

nguyenthienthanh (@nguyenthienthanh) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Refactor Expert by nguyenthienthanh

Name: Refactor Expert
Author: nguyenthienthanh

File contents

AI-consumed reference. Optimized for Claude to read during execution. Human-readable explanation: see docs/architecture/HIERARCHICAL_PLANNING.md or docs/getting-started/ depending on topic.

Skill: Refactor Expert

Safe, incremental refactoring. Improve quality without changing behavior.

Commands

Command	Output
`refactor:analyze <file>`	`.claude/logs/refactors/{target}-analysis.md`
`refactor:plan <file>`	`.claude/logs/refactors/{target}-plan.md`
`refactor:docs <file>`	Analysis + Plan + Summary
`refactor:quick <file>`	Skip approvals
`refactor:performance <file>`	Performance-focused
`refactor:structure <file>`	Structure-focused

Decision

Signal	Action
Code smell detected	Identify specific smell
Tests passing	Safe to refactor
No tests	Write tests FIRST
Large change	Break into small steps

Golden Rule: Never refactor and add features simultaneously.

Code Smells -> Refactoring

Smell	Refactoring
Long Method	Extract Method
Large Class	Extract Class
Long Parameter List	Parameter Object
Duplicate Code	Extract Method/Class
Feature Envy	Move Method
Primitive Obsession	Replace with Object
Switch Statements	Polymorphism
Dead Code	Delete it

Safe Process

1. Ensure tests pass
2. ONE small change
3. Run tests
4. Commit
5. Repeat

Never multiple changes between test runs.

Checklist

Before: Tests exist and pass, understand current behavior, identify smell. During: One change at a time, test after each, commit frequently. After: All tests pass, code cleaner, behavior unchanged.

Related Rules

rules/core/simplicity-over-complexity.md — the point of refactoring: Rule of 3 before abstracting, delete before extracting, flatten before nesting
rules/core/tdd-workflow.md — refactor only when tests are green
rules/core/verification.md — tests must still pass after every step
rules/workflow/cross-review-workflow.md — refactorer ≠ reviewer
skills/code-simplifier/SKILL.md — companion skill for pure simplification passes

---name: refactor-expertdescription: Guide safe, incremental refactoring that improves code quality without changing behavior.---> **AI-consumed reference.** Optimized for Claude to read during execution.> Human-readable explanation: see [docs/architecture/HIERARCHICAL_PLANNING.md](../../../docs/architecture/HIERARCHICAL_PLANNING.md)> or [docs/getting-started/](../../../docs/getting-started/) depending on topic.# Skill: Refactor ExpertSafe, incremental refactoring. Improve quality without changing behavior.---## Commands| Command | Output ||---------|--------|| `refactor:analyze <file>` | `.claude/logs/refactors/{target}-analysis.md` || `refactor:plan <file>` | `.claude/logs/refactors/{target}-plan.md` || `refactor:docs <file>` | Analysis + Plan + Summary || `refactor:quick <file>` | Skip approvals || `refactor:performance <file>` | Performance-focused || `refactor:structure <file>` | Structure-focused |---## Decision| Signal | Action ||--------|--------|| Code smell detected | Identify specific smell || Tests passing | Safe to refactor || No tests | Write tests FIRST || Large change | Break into small steps |**Golden Rule:** Never refactor and add features simultaneously.---## Code Smells -> Refactoring| Smell | Refactoring ||-------|-------------|| Long Method | Extract Method || Large Class | Extract Class || Long Parameter List | Parameter Object || Duplicate Code | Extract Method/Class || Feature Envy | Move Method || Primitive Obsession | Replace with Object || Switch Statements | Polymorphism || Dead Code | Delete it |---## Safe Process```1. Ensure tests pass2. ONE small change3. Run tests4. Commit5. Repeat```Never multiple changes between test runs.---## Checklist**Before:** Tests exist and pass, understand current behavior, identify smell.**During:** One change at a time, test after each, commit frequently.**After:** All tests pass, code cleaner, behavior unchanged.---## Related Rules- `rules/core/simplicity-over-complexity.md` — the point of refactoring: Rule of 3 before abstracting, delete before extracting, flatten before nesting- `rules/core/tdd-workflow.md` — refactor only when tests are green- `rules/core/verification.md` — tests must still pass after every step- `rules/workflow/cross-review-workflow.md` — refactorer ≠ reviewer- `skills/code-simplifier/SKILL.md` — companion skill for pure simplification passes---

Frequently asked questions

Refactor Expert