Menu
Compare doc versions across git history. Use when reviewing changes, tracking evolution, or understanding modifications.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Generate cross-reference graph showing relationships between design documents. Use when visualizing doc dependencies, finding related docs, or understanding documentation structure.
Validate design doc structure and frontmatter. Use when checking design docs for compliance, ensuring proper formatting, or verifying metadata before commits.
Comprehensive quality audit for CLAUDE.md context files. Use when performing thorough quality checks, preparing for releases, ensuring context efficiency, or verifying token optimization.
Style rules for LLM context files (CLAUDE.md, AGENTS.md and their .local variants). Fires automatically when these files are opened. Enforces on-demand loading patterns, proper @-reference syntax and lean context structure.
Split large CLAUDE.md into child files. Use when context files exceed word limits, are too verbose, or cover multiple distinct topics that should be separate.
Validate CLAUDE.md structure, formatting, and quality. Use when checking context files for compliance, ensuring proper structure, or verifying before commits.
| name | design-compare |
| description | Compare doc versions across git history. Use when reviewing changes, tracking evolution, or understanding modifications. |
| allowed-tools | Read, Bash(git *), Bash(diff *), Bash(cat *), Bash(sed *), Bash(grep *) |
| context | fork |
| agent | design-doc-agent |
Compares design document versions across git commits, branches, or tags to track evolution and understand changes over time.
This skill compares document versions by validating git references, loading document content from different versions, performing line-by-line or semantic diffs, analyzing changes for significance, and generating comprehensive comparison reports with metrics and highlights.
Compare with main branch:
/design-docs:design-compare observability.md --ref=main
Compare two commits:
/design-docs:design-compare doc.md --from=abc123 --to=def456
Semantic comparison:
/design-docs:design-compare doc.md --ref=v1.0.0 --format=semantic
doc: Document filename to comparemodule: Module name (default: inferred from current context)ref: Git reference to compare against (commit, branch, tag) (default: main)from: Starting git reference for two-point comparisonto: Ending git reference for two-point comparisonformat: Comparison format - unified, side-by-side, semantic, summary
(default: unified)High-level comparison process:
For detailed implementation steps, see supporting documentation below.
When you need detailed information, load the appropriate supporting file:
See instructions.md for:
Load when: Performing comparisons or need implementation details
See comparison-formats.md for:
Load when: Need format specifications or output structure details
See examples.md for:
Load when: User needs examples or clarification
ERROR: Git reference not found: {ref}
Valid references:
- Commit hash: abc123
- Branch name: main, feature-branch
- Tag name: v1.0.0
Check: git log or git branch -a
ERROR: Document not tracked by git
Document: {doc}
Ensure document is committed before comparing versions.
INFO: No changes between versions
Document: {module}/{doc}
References: {from} → {to}
The document is identical in both versions.
Works well with:
/design-docs:design-review - Review documents before/after changes/design-docs:design-validate - Validate both versions/design-docs:design-sync - Understand sync evolution over time/design-docs:design-update - See update historyA successful comparison: