modularize

Refactor and split oversized source and test files into cohesive sub-modules.

1|Updated Aug 24, 2026
One-click install
npx skills add https://github.com/yamcodes/the-hat --skill modularize-yamcodes
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: modularize
Source: https://github.com/yamcodes/the-hat/tree/main/skills/modularize
Command: npx skills add https://github.com/yamcodes/the-hat --skill modularize-yamcodes

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Large files that grow past roughly 200 lines become hard to navigate, review, and maintain. This Skill evaluates whether a file should be split, then refactors it into smaller, cohesive modules without breaking public APIs or existing tests. ## Core Features & Use Cases - Heuristic-Based Decisions: Evaluates logical cohesion, function size, nesting complexity, and fragmentation risk before refactoring, with an abort condition for files that logically belong together (e.g., constant dictionaries or large switch statements). - Test Suite Splitting: Splits large test files by behavior or topic (e.g., coercion.test.ts, arrays.test.ts) and extracts shared setup into helper files only when duplication is real. - Source Module Refactoring: Isolates UI prompts, file system adapters, API clients, and reporters into discrete sub-modules while keeping the original file as a high-level orchestrator. - Use Case: A 600-line test file is split into topic-focused files, barrel exports preserve the public API, and typecheck, build, lint, and tests all pass afterward. ## Quick Start Ask the AI to modularize a specific oversized file, for example: split packages/core/src/create-env.test.ts into topic-focused test files and verify all tests still pass.

Frequently Asked Questions about modularize

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I split a large test file into smaller files?▼

Split large test suites by behavior or topic into separate files named after the feature under test, such as coercion.test.ts or options.test.ts. Extract shared setup like beforeEach hooks into a helper file only when duplication is significant, then run each new test file individually.

When should I refactor a file that is too long?▼

Use roughly 200 lines as a warning signal, then evaluate logical cohesion, function sizes, and nesting complexity. Refactor when the file contains independent blocks; skip it if the file is a configuration dictionary, constants list, or single switch statement that belongs together.

How do I split a module without breaking its public API?▼

Preserve the public contract by keeping the original exports and using a barrel file such as index.ts to re-export the split sub-modules. Consumers continue importing from the same path while the internals are reorganized into discrete modules.

When should I not modularize a file?▼

Avoid splitting when the file is predominantly a configuration dictionary, list of constants, or one massive switch statement that logically belongs together. Also avoid speculative abstractions before multiple active callers exist, since over-splitting cohesive units causes jump-to-definition fatigue.

How do I verify a refactoring did not break anything?▼

Run the targeted tests for the affected files first, then execute typechecking, the package build step to confirm ESM/CJS module resolution, and linting and formatting checks. Check compilation at each incremental extraction step rather than only at the end.