bmad-shard-doc

This Skill splits large markdown documents by extracting level 2 headings into separate section files within a destination folder. It uses a markdown tree parser to automate the sharding process and generates an index for improved navigation.

The best way to break down a lengthy product spec is deterministic sharding, which explodes the single markdown file into a folder of section files. This approach improves repository modularization, editing, and reuse while generating an index.

You automate markdown file sharding by executing npx @kayvan/markdown-tree-parser to explode the source file into a destination folder. The process validates paths, permissions, and index creation before splitting the document.

Yes, you can archive or delete the original markdown file after sharding. Post-processing options allow you to delete, move to archive, or keep the source document, plus a completion report summarizes the outputs and any warnings.

Yes, the markdown sharding process includes robust validation of the source path, markdown format, destination creation, and write permissions. It enforces clear halt conditions on failure to ensure file management integrity.

You need to shard markdown documentation when long-form manuals or architecture documents become difficult to navigate and maintain. Splitting by level 2 sections makes per-section files easier to edit and import into other tools.