splitting-notes

The splitting-notes skill is a systematic refactoring agent designed to maintain and optimize large documentation repositories. It is primarily used when markdown files become too large (exceeding 1000 lines) or suffer from topic dilution, where multiple unrelated subjects are crammed into a single file. By applying progressive grouping principles, the agent breaks down monolithic structures into smaller, focused files—typically targeting 500 lines each—and generates index files that facilitate hierarchy-based navigation. This process significantly improves cognitive load management, searchability within the repository, and overall build performance during site generation.

• Automatically identifies large H2 chapters for extraction into independent files.

• Constructs standardized index files using a specific format: - Name - Description.

• Enforces strict frontmatter requirements including sidebar_position and tags.

• Supports multi-step refactoring workflows, requiring a Plan Mode phase to ensure structural integrity.

• Updates cross-file internal links and validates asset paths (e.g., images) after migration.

• Integrates with local development tools like pnpm build, linting suites, and Grep for verification.

• Always initiate the skill via EnterPlanMode to define the migration strategy before execution.

• Ideal for technical documentation, personal knowledge bases, or TIL (Today I Learned) archives.

• Input requirements include an existing markdown document with identifiable H2 headings.

• Output consists of a clean, modular directory structure with a dedicated index file acting as a table of contents.

• Constraints: Do not split files under 500 lines, maintain coherent topic grouping, and always verify via pnpm lint:content before finalizing.