bmad-shard-doc

To split a large markdown document into smaller files, this Skill sections the content by level 2 headings. It generates a hierarchical set of files with an index.md for navigation, preserving the original section order and names to maintain context.

The best way to break down long architecture docs is to shard the markdown into per-section files. This enables easier navigation, versioning, and reuse in automation by providing targeted access to individual sections rather than a monolithic document.

Yes, you can automate content management of sharded markdown files without losing context. The process preserves the original section order and names, creating an index.md to ensure deterministic execution and quick navigation across the sectioned files.

The markdown sectioning process does not automatically delete the original document. It handles the original file according to your chosen policy, allowing you to delete, archive, or keep the source document after the destination outputs are validated.

You need to shard markdown documents into section-based files when working with long-form docs like design or process guides. This simplifies collaboration, enables per-section access, and allows targeted automation downstream by dividing the content by level 2 headings.

A limitation of sharding markdown files by level 2 headings is that it sections content strictly based on H2 tags. Documents lacking a clear H2 structure will not shard effectively, and users must manage the original document policy manually after validation.