bluecraft/skills/agent-docs-consistency/SKILL.md

name, description

name	description
agent-docs-consistency	Use when checking the AGENTS.md and agent-docs graph for reachability, cycles, depth, duplicate authority, routing clarity, or rule-doc versus inventory-doc consistency.

Agent Docs Consistency

Overview

Use this skill for structural consistency checks across AGENTS and agent-docs. It focuses on the document graph and authority model, not repository behavior.

When to Use

• The user asks whether there are cycles
• The user asks for document depth or routing structure
• The user asks whether two docs both own the same rule
• The user asks whether two sibling docs both apply to the same task
• The user asks whether a doc has become a secondary router or mixed-shape document

Workflow

1. Read the root AGENTS.md.
2. Read the active child docs in scope.
3. Read ../agent-docs/references/consistency-checklist.md.
4. Read ../agent-docs/references/severity-model.md.
5. Read ../agent-docs/references/report-format.md.
6. Inspect:
   • root reachability
   • shortest routing depth
   • direct cycles and high-noise cross-links
   • duplicate authority candidates
   • equally specific overlapping docs
   • out-degree hotspots
   • rule-doc vs inventory-doc shape mismatches
7. Apply the default structure budget unless a narrower doc explicitly justifies an exception:
   • recommended shortest root-to-leaf routing depth: <= 3
   • recommended active downstream references from one doc: <= 7
   • treat budget overruns as structural warnings, then decide whether they remain acceptable or now require refactor
8. Distinguish:
   • blocking structural ambiguity such as duplicate authority or equally specific overlapping docs
   • other high-noise structural problems
   • acceptable cross-references
9. Report the structural findings without drifting into repository implementation review. Use the consistency shape from report-format.md. Use agent-docs-repo-alignment for repo-fact comparison.

Output

• Reachability summary
• Cycle summary
• Blocking structural ambiguity findings
• Structural warnings such as depth or out-degree overruns
• Other duplicate-authority or shape findings
• Residual risk assessment