shard-document

name	shard-document
description	Break large documents into smaller, manageable shards with maintained relationships and navigation, improving document usability and maintenance for PRDs, specs, and technical documentation. Use when large documents (>5000 words) need splitting for better maintainability, navigation, or when documentation becomes difficult to navigate.
acceptance	[{"shards_created":"Document split into logical, focused shards"},{"navigation_provided":"Index/navigation document created for shard discovery"},{"relationships_maintained":"Cross-references and dependencies preserved"},{"metadata_complete":"Each shard includes metadata (title, purpose, dependencies)"},{"validation_passed":"All internal links verified, no broken references"}]
inputs	{"source_document":{"type":"string","required":true,"description":"Path to document to be sharded (absolute path)"},"sharding_strategy":{"type":"string","required":false,"description":"logical | size-based | semantic | custom (default: logical)","default":"logical"},"max_shard_size":{"type":"number","required":false,"description":"Maximum lines per shard (for size-based strategy, default: 500)","default":500},"output_directory":{"type":"string","required":false,"description":"Directory for shard output (default: <source>-shards/)"},"preserve_original":{"type":"boolean","required":false,"description":"Keep original document alongside shards (default: true)","default":true}}
outputs	{"sharding_complete":{"type":"boolean","description":"Whether sharding completed successfully"},"shard_count":{"type":"number","description":"Number of shards created"},"output_location":{"type":"string","description":"Directory path containing shards and index"},"index_file":{"type":"string","description":"Path to navigation index file"},"broken_references":{"type":"array","description":"List of broken cross-references found during validation"}}
telemetry	{"emit":"skill.shard-document.completed","track":["source_document","sharding_strategy","shard_count","output_location","broken_references_count","duration_ms"]}

Shard Document Skill

Purpose

Break large, monolithic documents into smaller, manageable shards that are easier to navigate, maintain, and understand. Particularly valuable for lengthy PRDs, technical specifications, architecture docs, and API documentation.

Core Principles:

• Logical boundaries (shard by topic/section, not arbitrary size)
• Relationship preservation (maintain cross-references)
• Navigation clarity (create clear index and links)
• Metadata richness (each shard self-describes purpose)
• Validation rigor (verify all references work)

---

Prerequisites

• Source document exists and is readable
• Document has clear structure (headings, sections)
• Output directory is writable
• workspace/ directory available for shard storage

---

Workflow

Step 1: Analyze Document Structure

Action: Parse document to understand structure, identify logical boundaries, and assess sharding approach.

Key Activities:

1. Parse Document Hierarchy

   Example document structure:
   
   # Product Requirements Document
   ## 1. Executive Summary (200 lines)
   ## 2. Vision & Objectives (150 lines)
   ## 3. User Personas (400 lines)
   ### 3.1 Persona: Sarah (SaaS Admin)
   ### 3.2 Persona: Mike (End User)
   ### 3.3 Persona: Lisa (Manager)
   ## 4. Market Analysis (600 lines)
   ### 4.1 Competitive Landscape
   ### 4.2 Market Segmentation
   ### 4.3 Differentiation Strategy
   ## 5. Feature Specifications (1200 lines) ⚠️ Large
   ### 5.1 Feature: Authentication
   ### 5.2 Feature: Dashboard
   ### 5.3 Feature: Reporting
   ### ... (20 more features)
   ## 6. Technical Requirements (800 lines)
   ## 7. Success Metrics (300 lines)
   
   Total: ~3,650 lines (too large for single document)
   

2. Identify Shard Boundaries