How do I know if a split is necessary?

If a file exceeds size guidance (generally 300 lines; 500+ often warrants splitting) or contains multiple logical units, use the language-specific conventions to split.

Will splitting rename exports or break external code?

No. The process preserves external behavior by not renaming exported symbols; it only moves code and updates imports and re-exports accordingly.

What should I do after splitting to ensure everything works?

Run the project's linter/formatter and build, and verify there are no circular dependencies or broken imports, adjusting references as needed.

organize

Scanned

npx machina-cli add skill recrsn/agent-skills/organize --openclaw

Files (1)

SKILL.md

3.0 KB

Check the diff against origin/main, and identify large files that were added or modified in this branch. Run git fetch origin to make sure git context is up-to-date.

Here is the list of files changed in this branch: !git diff --name-only origin/main

For each changed file, read the full file and determine if it should be split based on the language conventions below. Then execute the splits, updating all imports and references across the project.

Language conventions

TypeScript / JavaScript / React

One React component per file, named after the component
Colocate component styles and tests alongside the component
Redux: prefer ducks pattern — slice file contains actions, reducers, and selectors for one domain
Separate types/interfaces into a types.ts when shared across multiple files
Barrel exports (index.ts) for public API of a directory

Swift / SwiftUI

One SwiftUI view per file, previews stay in the same file
One UIKit view controller per file
Protocols and their default extensions can share a file
Separate model types into individual files when they exceed trivial size

Java / Kotlin

One top-level class per file, file named after the class
Inner classes stay with their outer class unless they grow large and are used externally
Kotlin: data classes that are only used by one file can stay; shared ones get their own file

Python

One class per file when the class is substantial
Group small related data classes or enums in a single file
Separate CLI entry points from library code

Go

Group by responsibility: types, handlers, middleware, etc.
Keep interfaces near the code that depends on them, not the implementation
Test files mirror source files (foo.go → foo_test.go)

General (any language)

Files over ~300 lines are candidates for splitting
Files over ~500 lines should almost always be split
Keep tightly coupled code together — don't split just to hit a line count
Helper/utility functions used by only one caller stay with the caller

How to split

Identify logical groupings within the file
Create new files following the project's existing directory structure and naming conventions
Move code to the new files
Update all imports, references, and re-exports across the entire project
Verify no circular dependencies are introduced
Run the project's linter/formatter if configured

Rules

Only split files touched by the branch diff
Preserve external behavior exactly; all existing imports from other files must continue to work
Follow the project's existing naming and directory conventions over the guidelines above
Do not rename exported symbols — only move them
When in doubt about whether to split, leave the code together

Report at the end with a brief summary of files split and the rationale.

Source

git clone https://github.com/recrsn/agent-skills/blob/main/skills/organize/SKILL.mdView on GitHub

Overview

Organize automates splitting oversized or monolithic files into smaller, logically grouped modules following language conventions (TypeScript/JS, Python, Go, Swift, Java/Kotlin). This keeps code readable and maintainable while preserving external behavior by updating imports and references across the project.

How This Skill Works

On a branch diff, Organize reads each changed file to decide if a split is warranted using language-specific guidelines (one top-level unit per file, colocated tests/styles, etc.). It then creates new files, moves code, updates imports/re-exports across the project, and runs lints/formatters to ensure no circular dependencies or broken references remain.

When to Use It

A branch adds or modifies files that exceed typical size thresholds (300–500+ lines) and could benefit from modularization
Your codebase follows language-specific conventions (TypeScript/JS, Python, Go, Swift, Java/Kotlin) and you want to apply those rules systematically
You need to update imports and references across the entire project after moving code
You must verify that no circular dependencies were introduced after splitting
You want to preserve external behavior without renaming exported symbols

Quick Start

Step 1: Run Step 1: git diff --name-only origin/main to list changed files
Step 2: For each changed file, read the full content and decide if a split is warranted using the language conventions in the SKILL.md
Step 3: Create new files, move code, update imports/re-exports across the project, then run the linter/formatter

Best Practices

Only split files touched by the branch diff
Preserve external behavior; do not rename exported symbols
Follow language conventions (e.g., one top-level unit per file, colocate related tests and styles, etc.)
Update all imports and re-exports across the project
Run the project's linter/formatter and build to verify integrity

Example Use Cases

Split a monolithic TypeScript React component into a separate component file, its styles, and tests
Break a large Go file into grouped types, handlers, and middleware files
Separate a Python module's CLI entry points from its library code
Divide a Java class with many inner classes into multiple top-level files while preserving API
Create individual SwiftUI view files when a SwiftUI file grows too large

Frequently Asked Questions

Add this skill to your agents