Agent skill · posthog
splitting-oversized-modules
Split an oversized Python module (a thousand-plus-line logic.py, models.py, api.py, or its test file) into a package of one module per concern, mechanically and provably without changing behavior. Use on a request to split / break up / decompose a god module or move functions out of one, once a human has agreed to split one before some other change, or before restructuring code inside a module already over roughly a thousand lines — breaking up a long function or extracting helpers in place leaves everything in the same file, so check the worth-it gate and propose the split first. Covers that gate, assigning symbols to concerns with an acyclic dependency graph, the AST plus tokenize move script, and proving the result is a pure move. Python only — for frontend files use writing-ui-components. Not for extracting a shared helper into common/, and not for moving code between products, which is isolating-product-facade-contracts.
What it needs
About 5k tokens when loaded.
What this skill does
Splitting oversized modules A module nobody wants to open taxes every change in it, and agents pay that tax on every task because they do not carry knowledge between them. A 3000-line logic.py beside a 3000-line testlogic.py is roughly 55k input tokens of reading before a line gets written. Splitting one measured case cut the read-set 81 to 97% depending on the concern touched, while total lines grew about 5% from the repeated import headers. So the goal is a small read-set for a typical change, not tidiness. Is it worth doing here? All three must hold: over roughly a thousand lines, several concerns that change independently, and something still actively changing in it. A big cohesive frozen file buys nothing. Skip generated files, and skip a file several people are mid-change in (git log --oneline -20 -- <file>). A complexity warning on one function is a symptom of this, not a separate job. Extracting that function into helpers leaves every helper in the same file, so the read-set is unchanged and the file gets longer. Measure the file first (wc -l), and when it clears the gate, propose the split instead of the in-place extraction. Splitting is a separate PR from whatever you came to do. Land the move as its own base PR and branch your work on top — see /stacking-prs. Never bundle it into a feature diff, and say what you are doing in one line before you start: which file, and that the split lands separately. Nobody minds the base PR; they mind finding it inside a feature diff. If a human has not asked for the split, propose it and let them decide. Method Commands assume the repo root. S=.agents/skills/splitting-oversized-modules/scripts. 1. Map the symbols and assign them to concerns Edit layout.json into modules named after concerns (baselines, quarantine, cistatus), not layers (helpers, utils, core). Put module-level state every module needs its own copy of — a logger, a compiled regex — under "shared". …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills posthog/splitting-oversized-modules