Split large Python files into multiple files organized as a package. Use when user says "split this file", "this file is too big", "break this into multiple files", or similar requests for Python (.py) files.
This skill inherits all available tools. When active, it can use any tool Claude has access to.
scripts/split_module.pyRequires ast-grep: npm install -g @ast-grep/cli
scripts/split_module.py to working directory (using cp)python split_module.py parse path/to/module.py
groupings.jsonpython split_module.py split path/to/module.py groupings.json package.module Class1 Class2
groupings.json (add missing items to base, adjust groups)split → test fails → rollback → fix groupings.json → repeat
NEVER edit generated files. They get deleted on rollback. Only groupings.json survives - that's your source of truth.
# Parse: print definitions JSON
python split_module.py parse <file.py>
# Split: write files, test imports, rollback on failure
python split_module.py split <file.py> <groupings.json> <module> <Name1> [Name2 ...]
{
"base": ["BaseClass", "helper_func"],
"groups": {
"group_name": ["ClassA", "ClassAVariant"],
"other": ["ClassB"]
},
"init_extras": ["get_instance", "create_thing"]
}
Apply in order:
base: parent is ABC/Protocol/BaseModel, or name contains Base/MixinFooRenderer, FooVLRenderer, FooDisableThinkingRendererbaseinit_extras: get_*, create_*, make_*, build_*module.py → re-export stub (backwards compat)
module/
├── __init__.py # re-exports + factory functions
├── base.py # imports + base classes + shared utils
└── <group>.py # from .base import * + group members
Q: Imports failed. Can I just edit base.py to fix it?
A: No. Rollback deletes generated files. Edit groupings.json instead, then re-run. That's the whole point of the retry loop.
Q: Why does rollback exist?
A: It protects you. Failed state = broken code in the repo. Rollback restores clean state so you can iterate on groupings.json safely.
Q: cmd_parse didn't capture something (type aliases, constants, etc). What do I do?
A: This will happen. When imports fail, read the error, figure out what's missing, and either add it to base in groupings.json or fix the script's parse_definitions() if it's a pattern you'll hit often.
Q: What if I need to edit split_module.py to capture new patterns?
A: Prefer using ast-grep patterns over regex. The script already uses run_ast_grep() for classes and functions. Add new patterns following the existing style (see parse_definitions()).