Agent skill
related-docs-sync
Maintain bidirectional references in related_docs frontmatter across documentation. Use when linking documents together or when the user asks to sync related docs.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/related-docs-sync
SKILL.md
Related Documents Sync Skill
Purpose: Maintain bidirectional references in
related_docsfrontmatter across documentation. When doc A references doc B, ensure doc B references doc A.
Trigger
When: Document's related_docs section is modified
Context Needed: Changed document, old/new references, target docs
MCP Tools: read_file, replace_string_in_file, mcp_payment-syste_get_doc_context
Related Docs Structure
related_docs:
database_schema: "docs/technical/backend/database/04-INVENTORY-SCHEMA.md"
api_design: "docs/technical/backend/api/INVENTORY-API.md"
ux_flow: "docs/technical/frontend/ux-flows/INVENTORY-UX.md"
sync_strategy: "docs/technical/architecture/INVENTORY-SYNC.md"
feature_design: "docs/technical/backend/features/FEAT-002-INVENTORY.md"
adr: "docs/technical/architecture/adr/003-INVENTORY-STRATEGY.md"
Relationship Types
| Field | Points To | Reverse Field |
|---|---|---|
database_schema |
*-SCHEMA.md | feature_design |
api_design |
*-API.md | database_schema |
ux_flow |
*-UX.md | api_design |
sync_strategy |
*-SYNC.md | ux_flow |
feature_design |
FEAT-*.md | database_schema |
adr |
NNN-*.md | feature_design |
Sync Rules
Adding Reference
Doc A adds: related_docs.database_schema = "path/to/B.md"
↓
Doc B gets: related_docs.feature_design = "path/to/A.md"
Removing Reference
Doc A removes: related_docs.database_schema = ""
↓
Doc B removes: related_docs.feature_design = ""
Renaming/Moving
Doc B renamed: old_path → new_path
↓
All docs referencing old_path → update to new_path
Workflow
- Detect change - Which related_docs changed?
- Parse diff - Added vs removed references
- Load targets - Read referenced documents
- Update targets - Add/remove reverse references
- Validate - Check all links resolve
- Report - List all changes made
Validation
After sync:
# Doc A references Doc B
A.related_docs.database_schema: "B.md"
# Doc B must reference Doc A
B.related_docs.feature_design: "A.md"
Orphan Detection
Find docs with broken references:
- Reference points to non-existent file
- Reference is not bidirectional
- Document has no related_docs
Output Report
{
"synced": [{ "from": "A.md", "to": "B.md", "field": "database_schema" }],
"orphans": [{ "doc": "C.md", "broken_ref": "deleted.md" }],
"missing_reverse": [{ "doc": "D.md", "refs": "E.md", "missing_in": "E.md" }]
}
Reference
- DOCUMENTATION-WORKFLOW.md
- docs.instructions.md
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?