refactor
Skill1 starsChanged 5 months agoMITView on GitHub
Split a file that holds more than one responsibility into modules that each hold one. The decision is always about what's in the file (its responsibilities), never its length. Run the cohesion test first; if the file has one purpose, stop and leave it alone.
195 other projects use a version of this.
Adopted by
Most recently taken up by
- chuckplayer/claude-agent-packtheir own version, first seen Nov 16, 2026
- Archont561/skillstheir own version, first seen Nov 15, 2026
- nazmirket/skillstheir own version, first seen Nov 15, 2026
- qivora-labs/agentinittheir own version, first seen Nov 15, 2026
- NomadicDaddy/aiddtheir own version, first seen Nov 15, 2026
- zircote-plugins/refactortheir own version, first seen Nov 15, 2026
Used with
Projects with it also use ascii-diagram, debug-fix and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
SethGammonSkillascii-diagram
Generate perfectly aligned ASCII diagrams — architecture, flow, sequence, box-and-arrow. Uses a programmatic character-grid approach so alignment is guaranteed by math, not token prediction. Includes post-render verification.
Also in 4 projects that use this
zebbernSkilldebug-fix
Find and fix a bug or issue — from any source (GitHub issue, error message, user report, or observed behavior)
Also in 4 projects that use this
parcadeiSkillagent-context-isolation
Agent Context Isolation
Also in 3 projects that use this
parcadeiSkillagentica-infrastructure
Reference guide for Agentica multi-agent infrastructure APIs
Also in 3 projects that use this
- +8 more from parcadei
Other versions195 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 195
- github/awesome-copilot★ 41ksame name
- unkeyed/unkey★ 5.5ksame name
- parcadei/Continuous-Claude★ 3.9ksame name
- parcadei/Continuous-Claude-v2★ 3.9ksame name
- parcadei/Continuous-Claude-v3★ 3.9ksame name
- adobe/S3Mock★ 1.2ksame name
- SethGammon/Citadel★ 927same name
- poshan0126/dotclaude★ 871same name
- JordanCoin/codemap★ 715same name
- membrane/api-gateway★ 658same name
185 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository3 other files it gives its agents.
- architecture-reviewSkill
- guardSkill
- handoff-updateSkill
The file
We split this skill into the rules it gives an agent
5 rules. 0 are common, 4 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 170 edited versions we read keep these.
4
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
Every candidate gets the cohesion test below before any split is proposed.
- Very specific: line 23
One-sentence purpose: Write what the file does. If the honest sentence is "X and Y and Z" where X/Y/Z are unrelated, each is a seam.
- Distinctive: line 48
Isolate the work: if your VCS supports it (a worktree or a branch), so a half-done split never touches the live tree.
- Distinctive: line 50
Run the cohesion test: If the file passes (single purpose), STOP, report "cohesive as-is, no split" with the one-sentence purpose as the …
- Distinctive: line 92
Test fixtures / sample files: never refactor, split, or autoformat.
“Common” is measured: kept by at least 6 in 10 of the 170 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Refactor
Splits a file that holds more than one responsibility into modules that each hold one. The decision is always about what's in the file (its responsibilities), never its length. A 5000-line single-purpose module is healthy; a 200-line file that mixes three unrelated concerns is not.
Line count is only a smoke detector: it tells you where to look, not what to do. There is no line limit. Every candidate gets the cohesion test below before any split is proposed.
Not Claude-specific. Packaged as a skill, but it's a procedure. The cohesion test and the reference-repointing discipline are the transferable parts; adapt the tooling steps to your stack.
The cohesion test, run this first, every time
A file is cohesive (leave it alone) when you can state its purpose in one sentence with no "and" joining unrelated concerns. Four lenses:
- One-sentence purpose. Write what the file does. If the honest sentence is "X and Y and Z" where X/Y/Z are unrelated, each is a seam. If it's a single "X" (even a complex X with many steps), it's cohesive.
- Cluster the defs. Group the top-level functions by what they operate on and what calls them. Many private helpers all feeding one entry point → cohesive. Two or more independent entry points over different data, whose helper groups don't call each other → splittable.
- Docstring drift. Compare the actual contents to the module docstring's stated purpose. Functions outside that stated purpose are concerns that drifted in: the prime extraction targets, and the way a "cohesive" judgment goes stale over time.
- Growth axis. Cohesion includes how the file will grow. Growing by more cases of the same concern
(another rule, another step, another syntactic case) keeps it cohesive; leave it. But if it would grow
along an orthogonal axis (per-language, per-framework, per-target variation), that axis doesn't belong
inline. A cohesive orchestrator that starts accreting
if framework == .../if language == ...branches isn't honestly growing one concern; it's missing a delegation boundary, and the fix is to push that axis behind a driver/adapter, not to split the orchestrator by step.
Cohesive shapes, do NOT split (large is fine): a state machine or orchestrator with one entry point; a parser with many syntactic cases; one validator with many rules; one algorithm expressed as sequential pipeline stages; a schema module (data types plus their own validation).
Splittable shapes, propose a split: function groups that never call each other and could each be
imported independently; a catch-all (utils/helpers/misc), undefined scope by name; concerns that
drifted past the docstring's stated purpose; multiple unrelated transforms behind a mode/kind switch.
Protocol
- Isolate the work if your VCS supports it (a worktree or a branch), so a half-done split never touches the live tree. If not, proceed in place; the test gate at the end still catches regressions.
- Run the cohesion test. If the file passes (single purpose), STOP, report "cohesive as-is, no split" with the one-sentence purpose as the evidence. Only continue if it genuinely mixes responsibilities.
- Propose the split, naming the groups, not vague "logic": "[File] mixes [Responsibility A] and [Responsibility B]. Moving [A's function group] to [new module]." Get approval before proceeding.
- Move and repoint in the same change, leave no shim. Move the logic to the new module and repoint importers at it directly, deleting the moved code from the original file in the same commit. Do not retain the original entry point as a re-export wrapper "for revertability"; that's the backwards-compat shim the contract forbids. Keep a re-export at the old path only when that module is a deliberate, documented public facade, never as the default outcome of a split. When moved code and what stays behind share a helper, extract it to a shared module and import it from both; never copy a function body forward.
- Repoint every reference form, not just imports (see below).
- Regenerate derived state (the structure map, any index) so it reflects the new module layout.
- Run the test gate on just the test files covering the modules the split touched: the original's tests, the new module's tests, and any importer tests you repointed. Green there means the refactor is complete from the implementation side.
A move breaks references in more than one form
This is the step that bites sessions later, so do it deliberately. When you move or remove a name, code reaches
it in three forms, and a from X import Y grep (and most import-aware tooling) only sees the first:
- Imports:
from module import X, both top-level and inline/function-local. - String references:
mock.patch("module.X"),patch.object(...). String literals; no import tool sees them, and they fail only when the patched test actually runs. - Attribute access:
module.Xreached viafrom package import moduleorimport package.module as m.
Forms 2 and 3 are how a move silently breaks tests that weren't in your targeted gate: they passed at extraction time and surface much later. After any move, grep every moved name across all three forms and repoint each to the new module. For a patched name, target where the code-under-test looks it up, not the old path.
The subtlest case: patches of the moved code's dependencies. A mock patches where a name is looked up, so
moving a function also relocates the lookup site of every helper it calls. A test that stubs
"module.helper" to fake a dependency silently becomes a no-op once the function moves to module_x and
resolves helper there instead. So the patch-string scan must cover not just the moved names but the names the
moved code imports; repoint those to the new module too. (A small per-project ref-check script makes this
mechanical; the skill owns the decision, the script owns the audit.)
Out of scope by file kind
These exclusions are about the kind of file, so they stay true as the code changes:
- Test fixtures / sample files: never refactor, split, or autoformat. Fixtures that intentionally preserve a source layout (including deliberately malformed cases) lose their meaning if you reshape them.
- Test files: splitting scatters closely related assertions; only revisit if one file mixes unrelated subjects.
- Flat-by-nature files: shell scripts, prompt/content files. They aren't code modules with extractable function groups.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

