agentleFS
Sign inStart free
marlonvidalmarlonvidal/tech-manager-os/.agents/skills/bmad-shard-doc/SKILL.md

bmad-shard-doc

Skill17 starsChanged 4 months agoMITView on GitHub

Splits large markdown documents into smaller, organized files based on level 2 (default) sections. Use if the user says perform shard document

We split this skill into the rules it gives an agent

21 rules. 0 are common, 19 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 19

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    DO NOT skip steps or change the sequence

    line 13
  2. Distinctive:

    Ask user for the source document path if not provided already

    line 21
  3. Distinctive:

    Verify file exists and is accessible

    line 22
  4. Distinctive:

    Verify file is markdown format (.md extension)

    line 23
  5. Distinctive:

    If file not found or not markdown: HALT with error message

    line 24
  6. Very specific:

    Ask user for the destination folder path ([y] to confirm use of default: [suggested-path], else enter a new path)

    line 30
  7. Distinctive:

    If user accepts default: use the suggested destination path

    line 31
  8. Distinctive:

    If user provides custom path: use the custom destination path

    line 32
  9. Distinctive:

    Verify destination folder exists or can be created

    line 33
  10. Distinctive:

    Check write permissions for destination

    line 34
  11. Distinctive:

    If permission denied: HALT with error message

    line 35
  12. Distinctive:

    If command fails: HALT and display error to user

    line 42
  13. Distinctive:

    Check that destination folder contains sharded files

    line 46
  14. Distinctive:

    Verify index.md was created in destination folder

    line 47
  15. Distinctive:

    If no files created: HALT with error message

    line 49
  16. Distinctive:

    Delete the original source document file

    line 78
  17. Very specific:

    Ask: Archive location ([y] to use default: [default-archive-path], or provide custom path)

    line 86
  18. Distinctive:

    If user accepts default: use default archive path

    line 87
  19. Distinctive:

    If user provides custom path: use custom archive path

    line 88
  20. Distinctive:

    Create archive directory if it does not exist

    line 89
  21. Distinctive:

    Consider deleting or archiving the original document

    line 100

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Shard Document

Goal: Split large markdown documents into smaller, organized files based on level 2 sections using npx @kayvan/markdown-tree-parser.

CRITICAL RULES

  • MANDATORY: Execute ALL steps in the EXECUTION section IN EXACT ORDER
  • DO NOT skip steps or change the sequence
  • HALT immediately when halt-conditions are met
  • Each action within a step is a REQUIRED action to complete that step

EXECUTION

Step 1: Get Source Document

  • Ask user for the source document path if not provided already
  • Verify file exists and is accessible
  • Verify file is markdown format (.md extension)
  • If file not found or not markdown: HALT with error message

Step 2: Get Destination Folder

  • Determine default destination: same location as source file, folder named after source file without .md extension
    • Example: /path/to/architecture.md --> /path/to/architecture/
  • Ask user for the destination folder path ([y] to confirm use of default: [suggested-path], else enter a new path)
  • If user accepts default: use the suggested destination path
  • If user provides custom path: use the custom destination path
  • Verify destination folder exists or can be created
  • Check write permissions for destination
  • If permission denied: HALT with error message

Step 3: Execute Sharding

  • Inform user that sharding is beginning
  • Execute command: npx @kayvan/markdown-tree-parser explode [source-document] [destination-folder]
  • Capture command output and any errors
  • If command fails: HALT and display error to user

Step 4: Verify Output

  • Check that destination folder contains sharded files
  • Verify index.md was created in destination folder
  • Count the number of files created
  • If no files created: HALT with error message

Step 5: Report Completion

  • Display completion report to user including:
    • Source document path and name
    • Destination folder path
    • Number of section files created
    • Confirmation that index.md was created
    • Any tool output or warnings
  • Inform user that sharding completed successfully

Step 6: Handle Original Document

Critical: Keeping both the original and sharded versions defeats the purpose of sharding and can cause confusion.

Present user with options for the original document:

What would you like to do with the original document [source-document-name]?

Options:

  • [d] Delete - Remove the original (recommended - shards can always be recombined)
  • [m] Move to archive - Move original to a backup/archive location
  • [k] Keep - Leave original in place (NOT recommended - defeats sharding purpose)

Your choice (d/m/k):

If user selects d (delete)

  • Delete the original source document file
  • Confirm deletion to user: "Original document deleted: [source-document-path]"
  • Note: The document can be reconstructed from shards by concatenating all section files in order

If user selects m (move)

  • Determine default archive location: same directory as source, in an archive subfolder
    • Example: /path/to/architecture.md --> /path/to/archive/architecture.md
  • Ask: Archive location ([y] to use default: [default-archive-path], or provide custom path)
  • If user accepts default: use default archive path
  • If user provides custom path: use custom archive path
  • Create archive directory if it does not exist
  • Move original document to archive location
  • Confirm move to user: "Original document moved to: [archive-path]"

If user selects k (keep)

  • Display warning to user:
    • Keeping both original and sharded versions is NOT recommended
    • The discover_inputs protocol may load the wrong version
    • Updates to one will not reflect in the other
    • Duplicate content taking up space
    • Consider deleting or archiving the original document
  • Confirm user choice: "Original document kept at: [source-document-path]"

HALT CONDITIONS

  • HALT if npx command fails or produces no output files

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free