How do I install the Refactor skill?

Run npx skillmds@latest add engsimsoft/refactor 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 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?

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 free to use?

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

Who published Refactor?

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

Refactor by engsimsoft — Agent Skill

Name: Refactor
Author: engsimsoft

Refactor

Use this skill ALWAYS whenever improving code structure without changing externally visible behavior — renaming, extracting, simplifying, deduplicating, reorganizing modules. Trigger this skill EVEN if user just says "clean up X" or "improve Y" without mentioning the refactor process.

engsimsoft 02b1460 2.1 KB Updated Sep 17, 2026

File contents

Refactor workflow

Refactor = improving structure WITHOUT changing externally visible behavior.

1. Identify exact scope

Files involved (use Glob/Grep/Serena find_references)
External interface (public API, exported functions, DB schema, HTTP routes)
Internal-only structure that can change

2. State invariants (must NOT change)

HTTP API contract (paths, params, response shape)
Public function signatures
DB schema (unless this IS a schema migration)
Test outputs (existing tests must still pass)

Write invariants to .claude-data/invariants-session.md so PreCompact preserves them.

3. Small reversible changes (R12 per task)

ONE change at a time
After EACH change: run tests + mypy + ruff
If a change breaks something → revert that one change, not the whole work
Commit-able state at every step (even if you don't commit)

4. Update navigation if needed

If files moved → update docs/agent/05_module_map.md
If new module created → add to module map
If responsibility shifted between modules → update both

5. ADR if architectural boundary changes

Moved auth logic from api/ to dedicated auth/ package = architectural = ADR
Renamed function = not architectural = no ADR
Reorganized internal helpers = not architectural = no ADR

6. Do NOT mix in feature work (R3)

If you see a bug while refactoring — log to docs/agent/06_known_issues.md, do not fix in this commit
If you see a missing feature — log to backlog, do not add
Refactor commit must be reviewable as "structure only"

Anti-patterns

✗ "Big bang" refactor of 30+ files in one session
✗ Mixing rename + bugfix + new feature in one commit
✗ Refactoring without running tests (assumed they'll pass)
✗ Renaming public API without checking call sites

---name: refactordescription: Use this skill ALWAYS whenever improving code structure without changing externally visible behavior — renaming, extracting, simplifying, deduplicating, reorganizing modules. Trigger this skill EVEN if user just says "clean up X" or "improve Y" without mentioning the refactor process.---# Refactor workflowRefactor = improving structure WITHOUT changing externally visible behavior.## 1. Identify exact scope- Files involved (use Glob/Grep/Serena `find_references`)- External interface (public API, exported functions, DB schema, HTTP routes)- Internal-only structure that can change## 2. State invariants (must NOT change)- HTTP API contract (paths, params, response shape)- Public function signatures- DB schema (unless this IS a schema migration)- Test outputs (existing tests must still pass)Write invariants to `.claude-data/invariants-session.md` so PreCompact preserves them.## 3. Small reversible changes (R12 per task)- ONE change at a time- After EACH change: run tests + mypy + ruff- If a change breaks something → revert that one change, not the whole work- Commit-able state at every step (even if you don't commit)## 4. Update navigation if needed- If files moved → update `docs/agent/05_module_map.md`- If new module created → add to module map- If responsibility shifted between modules → update both## 5. ADR if architectural boundary changes- Moved auth logic from `api/` to dedicated `auth/` package = architectural = ADR- Renamed function = not architectural = no ADR- Reorganized internal helpers = not architectural = no ADR## 6. Do NOT mix in feature work (R3)- If you see a bug while refactoring — log to `docs/agent/06_known_issues.md`, do not fix in this commit- If you see a missing feature — log to backlog, do not add- Refactor commit must be reviewable as "structure only"## Anti-patterns- ✗ "Big bang" refactor of 30+ files in one session- ✗ Mixing rename + bugfix + new feature in one commit- ✗ Refactoring without running tests (assumed they'll pass)- ✗ Renaming public API without checking call sites

Frequently asked questions