refactoring skill
Program source-code refactoring for an explicit structural code improvement to structure, ownership, types, or duplication that preserves identified executable behavior. Select only when the request requires a structural code change with project-specific invariant proof, or enters through a canonical handoff from another Keystone skill.
- GitHub stars
- 6
- Files
- 1
- Last commit
- Jul 28, 2026
- License
- MIT
- Allowed tools
- —
What does the refactoring skill do?
refactoring is an agent skill. Program source-code refactoring for an explicit structural code improvement to structure, ownership, types, or duplication that preserves identified executable behavior. Select only when the request requires a structural code change with project-specific invariant proof, or enters through a canonical handoff from another Keystone skill.
How to install the refactoring skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the refactoring skill in Plugin
/plugin marketplace add static-var/Keystone /plugin install keystone@keystone
Install the refactoring skill in Claude Code
~/.claude/skills/refactoring/SKILL.md
$ npx degit static-var/Keystone/skills/refactoring ~/.claude/skills/refactoringInstall the refactoring skill in Claude Code (project)
.claude/skills/refactoring/SKILL.md
$ npx degit static-var/Keystone/skills/refactoring .claude/skills/refactoringInstall the refactoring skill in Codex
~/.agents/skills/refactoring/SKILL.md
$ npx degit static-var/Keystone/skills/refactoring ~/.agents/skills/refactoringInstall the refactoring skill in Gemini CLI
~/.gemini/skills/refactoring/SKILL.md
$ npx degit static-var/Keystone/skills/refactoring ~/.gemini/skills/refactoringInstall the refactoring skill in Claude.ai
npx degit static-var/Keystone/skills/refactoring refactoring && zip -r refactoring.zip refactoring # claude.ai → Customize → Skills → + → Create skill → Upload a skill → refactoring.zip
SKILL.md
View on GitHubRefactoring
Core principle
Refactoring changes structure while preserving behavior. Improve design in small, reversible steps, with characterization or regression proof when behavior could drift.
Load when
Load for an existing software project when the user asks to improve code structure while preserving an identified behavior contract: extract or inline code, reduce duplication, clarify names or type boundaries, remove code smells, or reorganize ownership.
If the user wants behavior change, use implementation. If a failure cause is unknown, use root-cause-analysis. If the refactor is broad or risky, create a refactor doc before mutation.
At entry, use the full Keystone path when the work changes integrated project code and needs project-specific invariant proof. Handle isolated text cleanup, mechanical formatting, and standalone snippets directly. Explicit invocation selects the full Refactoring behavior.
Outcome contract
A complete refactor reports:
- the behavior invariant that must not change;
- smells or pressures addressed;
- isolation checked before mutation via
../_shared/gates/isolation.md; - characterization/regression proof used before risky edits;
- files changed and why each changed;
- verification commands/results or explicit proof gaps;
- checkpoint handoff to
change-reviewwhen review is needed.
Process
- Classify size and risk.
- Small/local: one area, clear invariant, existing proof likely enough.
- Large/cross-cutting: multiple boundaries, weak coverage, shared contracts, or context-window risk.
- Completion criterion: refactor path is either safe for direct mutation or documented first.
- For large refactors, write a refactor doc under
docs/keystone/refactors/YYYY-MM-DD-<slug>.mdbefore editing.- Include goal, invariants, smells, affected areas, slices, proof, rollback, and review focus.
- Completion criterion: doc is specific enough for
task-creationorimplementation.
- Pass isolation before mutation.
- Load/check
../_shared/gates/isolation.md. - Respect unrelated dirty files and protected scope.
- Completion criterion: mutation scope is safe.
- Load/check
- Establish behavior proof.
- Prefer existing behavior tests; add characterization coverage when the invariant lacks a tripwire.
- Completion criterion: there is a tripwire for accidental behavior change or a documented proof gap.
- Apply small refactorings.
- Prefer rename, extract, inline, move, split, consolidate, simplify conditionals, remove dead code, and clarify ownership.
- Keep public contracts stable unless explicitly approved.
- Completion criterion: each step is understandable and reversible.
- Use engineering standards.
- Load
../_shared/engineering-standards.mdfor architecture or ownership decisions. - Remove abstractions that lack current pressure.
- Completion criterion: the result has clearer ownership, state, naming, or boundaries.
- Load
- Verify.
- Load and pass
../_shared/gates/proof.mdfor the preserved invariant. - Completion criterion: behavior invariant is supported by observed evidence.
- Load and pass
- Checkpoint and hand off.
- Use
../_shared/gates/checkpoint.md. - Hand off to
change-reviewfor non-trivial refactors or leave an explicit review pointer.
- Use
Smell prompts
Investigate duplication, long functions, god objects, feature envy, primitive obsession, data clumps, shotgun surgery, divergent change, hidden control flow, speculative generality, vague managers/helpers, mixed abstraction levels, duplicated state, and unclear ownership.
Hard rules
- Preserve behavior unless the user explicitly approves a behavior change.
- Do not disguise feature work as refactoring.
- Do not perform broad refactors without a refactor doc.
- Do not trust “looks equivalent” without proof or an explicit proof gap.
- Do not introduce patterns for imagined futures.
Output format
## Refactor report
Invariant: ...
Size/risk: small / large
Smells addressed: ...
Files changed: ...
Verification: ...
Risks/gaps: ...
### Checkpoint
Current skill: refactoring
Completed gates: ...
Next required skill: change-review / implementation / none
Next check: ...
Action: continue now / ask user / pending pointer / stop
Files in this skill
1refactoring skill questions
How do I install the refactoring skill in Claude Code?
Run npx degit static-var/Keystone/skills/refactoring ~/.claude/skills/refactoring. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the refactoring skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.