Claude-skill-registry large-file-refactor

Use when Claude Code hits "File content exceeds maximum allowed tokens" error, or when files are too large to read. Helps analyze and break apart large files into smaller, focused modules.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/large-file-refactor" ~/.claude/skills/majiayu000-claude-skill-registry-large-file-refactor && rm -rf "$T"

manifest: skills/data/large-file-refactor/SKILL.md

Large File Refactoring

Guide for analyzing and breaking apart files that exceed Claude Code's read limits.

When This Applies

Token limit error: "File content (X tokens) exceeds maximum allowed tokens (25000)"
Files > 2000 lines: Likely to cause issues or be hard to maintain
User request: "break apart", "split", "refactor large file"

Quick Start Algorithm

1. Assess the File

# Get line count
wc -l <file>

# Get structure overview (Rust example)
grep -n "^pub fn\|^fn\|^impl\|^struct\|^enum\|^mod" <file>

Use

LSP documentSymbol

for accurate symbol outline.

2. Identify Natural Breakpoints

Look for cohesive groups:

Related functions (CRUD operations, handlers, validators)
Type + its impl blocks
Feature-specific code
Test modules

3. Plan the Breakout

Target: Each new file should be 200-500 lines (readable in one read).

Pattern	When to Use
Extract to submodule	Related impl blocks, feature code
Extract to sibling file	Independent utilities, types
Create package/directory	Multiple related modules

4. Execute Refactor

Create new file(s)
Move code with
```
Read
```
(offset/limit) +
```
Write
```
Update imports/exports
Update the original file's module declarations

5. Validate

All imports resolve (LSP hover, no red squiggles)
Tests pass
No circular dependencies
Original functionality preserved

Analysis Without Full Read

When you can't read the whole file:

Tool	Use For
`Grep`	Find definitions: `^fn` , `^class` , `^def` , `impl`
`LSP documentSymbol`	Get complete symbol outline
`Read` with offset/limit	Read specific sections
`wc -l`	Total line count

Example workflow:

1. wc -l file.rs                    # 3500 lines
2. grep -n "^impl" file.rs          # Find impl blocks at lines 100, 800, 2000
3. LSP documentSymbol file.rs       # Get full structure
4. Read file.rs offset=100 limit=200  # Read first impl block

Breakout Decision Matrix

File Size	Recommendation
< 500 lines	Usually fine as-is
500-1000 lines	Consider splitting if multiple concerns
1000-2000 lines	Should split unless highly cohesive
> 2000 lines	Must split for maintainability

Language-Specific Patterns

See

skills/large-file-refactor/references/breakout-patterns.md

for detailed examples.

Language	Primary Pattern
Rust	Submodules in directory, re-export from mod.rs
TypeScript	Separate files, barrel export from index.ts
Python	Package with init.py
Go	Multiple files in same package

Common Pitfalls

Breaking public API: Ensure exports remain accessible
Circular imports: Plan dependency direction before splitting
Lost context: Keep related code together (don't over-split)
Forgetting tests: Move/update test imports too

References

skills/large-file-refactor/references/analysis-strategies.md

- Detailed analysis techniques

skills/large-file-refactor/references/breakout-patterns.md

- Language-specific examples

skills/large-file-refactor/references/validation-checklist.md

- Pre/post refactor checks