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

name, description

name	description
agent-docs-verification	Use when AGENTS.md or agent-docs have been changed and you need post-change validation evidence such as diff cleanliness, routing checks, cycle checks, or summary of what was verified.

Agent Docs Verification

Overview

Use this skill after changing AGENTS or agent-docs to gather verification evidence and report exactly what was checked. It is the completion gate for documentation-tree changes.

When to Use

• A doc refactor is complete and needs verification
• The user asks whether the change is really done
• You need to summarize what was validated versus what was not

Workflow

1. Read ../agent-docs/references/verification-checklist.md.
2. If the change edited this skill suite itself, also read ../agent-docs/references/skill-maintenance-checklist.md.
3. Run the strongest repository validation that actually applies.
4. At minimum for docs-only work:
   • run git diff --check
5. When the change touched routing or structure, also re-check:
   • root reachability
   • stale references
   • direct cycles if relevant
   • duplicate authority or document-shape regressions when relevant
6. When the change touched repository-dependent claims, confirm those claims against current files, config, scripts, or command output rather than memory.
7. Treat the following as behavior-check-required changes:
   • root routing changes
   • child-doc reference changes
   • conflict-resolution changes
   • workflow changes that affect required follow-up skills such as refactor -> consistency -> repo-alignment -> verification
8. For behavior-check-required changes, run a small behavior check with 1 to 3 representative prompts and inspect whether the agent:
   • reads the root entrypoint before choosing a specialized workflow
   • follows the intended route and required follow-up checks
   • escalates duplicate-authority or routing ambiguity instead of guessing
   • states any unverified remainder explicitly
9. When the change edited the agent-docs skill suite itself, also confirm:
   • each agents/openai.yaml still matches its SKILL.md
   • every shared reference still has a direct reference path from the relevant skill
   • no stale filenames, old skill names, or outdated terms remain after renames or splits
   • one concept still uses one term across SKILL.md, agents/openai.yaml, and references/
10. Report command evidence and exact scope:

• what was verified
• what was not verified
• whether the claim is limited to docs structure only
• whether representative behavior was checked or only static structure was reviewed

Reporting Rules

• Do not say a change is complete without fresh evidence from the current turn.
• Name the commands that were run.
• If only a minimum docs-only gate was available, say so explicitly.