md-split

Split Markdown files into numbered documents at H2 headings with slug-based filenames and an index.

6|1|Updated Jan 5, 2026
One-click install
npx skills add https://github.com/JordanGunn/skills --skill md-split
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: md-split
Source: https://github.com/JordanGunn/skills/tree/main/skills/md/split
Command: npx skills add https://github.com/JordanGunn/skills --skill md-split

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve?

Long Markdown documents can be hard to navigate and reuse. md-split provides deterministic chunking by H2 headings, producing focused documents and a navigable index.

Core Features & Use Cases

  • Splits a source Markdown file at each H2 heading into standalone sections.
  • Generates an index (.INDEX.md) and can scaffold a summary workflow (.SUMMARY.md).
  • Produces consistent, slug-based filenames for easy reference in automation workflows.

Quick Start

Run the split utility on your Markdown document to produce per-section files and an index.

Frequently Asked Questions about md-split

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

FAQPage Schema
How do I split a Markdown file into separate pages by H2 headings?

Splitting a Markdown file by H2 headings requires chunking the document at each second-level heading to produce standalone section files. This approach generates focused documents and a navigable index for easier reuse.

What is the best way to generate a navigable index from a long Markdown document?

Generating a navigable index from a long Markdown document involves splitting the content into deterministic chunks by H2 headings. This process automatically produces an .INDEX.md file and consistent slug-based filenames for easy reference.

Does splitting Markdown documentation by headings work with automation workflows?

Splitting Markdown documentation by headings works with automation workflows by enforcing deterministic, slug-based filenames and frontmatter-based discovery. This produces predictable file structures ideal for automated indexing and script-driven generation.

How do I scaffold a summary workflow for chunked Markdown files?

To scaffold a summary workflow for chunked Markdown files, run a split utility that produces per-section files alongside an index. This generates a .SUMMARY.md file to guide navigable documentation structure.

Why use slug-based filenames when chunking Markdown by headings?

Using slug-based filenames when chunking Markdown by headings ensures consistent naming across generated documents. This consistency enables reliable frontmatter-based discovery and easy reference within automation workflows.

When should I avoid splitting a Markdown file into multiple documents?

You should avoid splitting a Markdown file into multiple documents when the content relies heavily on continuous context or lacks H2 headings. Splitting documents without clear second-level headings will fail to produce a navigable structure.