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.
View on GitHubskills/python-file-splitter/SKILL.md
January 21, 2026
Select agents to install to:
npx add-skill https://github.com/OhadRubin/skills/blob/main/skills/python-file-splitter/SKILL.md -a claude-code --skill python-file-splitterInstallation paths:
.claude/skills/python-file-splitter/# Python File Splitter
Requires `ast-grep`: `npm install -g @ast-grep/cli`
## Full Workflow
### Phase 1: Parse & Plan
0. If you have not yet read the file in question DO NOT READ IT YET. IT MIGHT BE TOO BIG, WAIT AFTER YOU RUN parse.
1. Copy `scripts/split_module.py` to working directory (using cp)
2. Run parse:
```bash
python split_module.py parse path/to/module.py
```
3. Analyze output, apply grouping heuristics (see below)
4. Create `groupings.json`
5. Present proposed structure to user, wait for confirmation
- **(Mode 1 stops here if user just wants to see the plan)**
### Phase 2: Split & Iterate
6. Run split:
```bash
python split_module.py split path/to/module.py groupings.json package.module Class1 Class2
```
7. If imports succeed → done!
8. **If imports fail → rollback happens automatically**, then:
- **Fix `groupings.json`** (add missing items to `base`, adjust groups)
- **Re-run step 6**
- Repeat until imports pass
### The Retry Loop
```
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.
## CLI Reference
```bash
# 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 ...]
```
## Groupings JSON format
```json
{
"base": ["BaseClass", "helper_func"],
"groups": {
"group_name": ["ClassA", "ClassAVariant"],
"other": ["ClassB"]
},
"init_extras": ["get_instance", "create_thing"]
}
```
## Grouping heuristics
Apply in order:
1. **Base classes** → `base`: parent is `ABC`/`Protocol`/`BaseModel`, or name contains `Base`/`Mixin`
2. **Inheritance chains** → same group: class + all subclasses that inherit from it
3. **Naming patterns** → same group: `FooRenderer`, `FooVLRenderer`, `FooDisableThinkingRenderer`
4. **Helper functio