bmad-shard-doc

Split large markdown documents into section files by level 2 headers.

Updated May 13, 2026
One-click install
npx skills add https://github.com/Markuson/ivo_corr --skill bmad-shard-doc-markuson
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: bmad-shard-doc
Source: https://github.com/Markuson/ivo_corr/tree/main/.agents/skills/bmad-shard-doc
Command: npx skills add https://github.com/Markuson/ivo_corr --skill bmad-shard-doc-markuson

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @kayvan/markdown-tree-parser.

What problem does it solve?

This Skill solves the issue of managing monolithic, oversized markdown files by automatically breaking them down into smaller, manageable, and logically organized section files.

Core Features & Use Cases

  • Automated Sharding: Splits markdown documents based on level 2 headers to improve readability and navigation.
  • Index Generation: Automatically creates an index.md file to maintain the structure of the original document.
  • Use Case: Use this when you have a massive technical specification or documentation file that is difficult to edit or navigate, allowing you to work on individual sections independently.

Quick Start

Ask the assistant to perform shard document on your target markdown file and follow the prompts to select your destination folder.

Frequently Asked Questions about bmad-shard-doc

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

FAQPage Schema
How do I split large markdown files into smaller organized sections?

To split large markdown files, this Skill decomposes them into smaller, organized files based on level 2 headers. It automates file decomposition and creates an index.md file to maintain the original document's structure.

How do I organize monolithic technical specification documents for easier editing?

Organizing monolithic technical specification documents involves sharding them into modular section files. This process breaks down oversized markdown files, allowing you to navigate and edit individual sections independently.

Do I need npx to shard markdown documents based on headers?

Yes, you need npx and the @kayvan/markdown-tree-parser package to execute the markdown sharding process safely. These dependencies are required to parse the document structure and split it by level 2 headers.

Can I automatically generate an index file when breaking down markdown documentation?

Yes, you can automatically generate an index file when breaking down markdown documentation. The Skill creates an index.md file during the sharding process to maintain the structure and navigation of the original document.

What is the best way to manage modular documentation generated from a single markdown file?

The best way to manage modular documentation is sharding the original file into smaller section files using a markdown-tree-parser. This approach creates an index.md file, facilitating modular documentation management and independent section editing.

Are there limitations when using markdown sharding for document decomposition?

A limitation of markdown sharding is that it specifically splits documents based on level 2 headers. If your oversized markdown file lacks a proper level 2 header structure, the automated file decomposition will not execute as intended.