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. Read ../agent-docs/references/severity-model.md when the verification report includes findings or residual warnings.
4. Read ../agent-docs/references/report-format.md.
5. Read ../agent-docs/references/behavior-check-template.md when behavior checks are required.
6. Run the strongest repository validation that actually applies.
7. For repository AGENTS or agent-docs structure changes, run the validator at ../agent-docs/scripts/validate_agent_docs.py --repo-root <repo-root>.
8. If the change edited this skill suite itself, also run ../agent-docs/scripts/validate_agent_docs.py --skill-suite-root <skills-root>.
9. At minimum for docs-only work:
   • run git diff --check
10. 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

11. When the change touched repository-dependent claims, confirm those claims against current files, config, scripts, or command output rather than memory.
12. 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

13. 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

14. Record each representative prompt using behavior-check-template.md.
15. Treat the behavior check as failed if any representative prompt skips the root entrypoint, misses a required follow-up check, or resolves ambiguity by guessing.
16. 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/

17. Report command evidence and exact scope using the verification shape from report-format.md:

• 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
• whether any remaining findings are blocking, major, minor, or observation

Result Levels

• fully verified: required static checks passed and any required behavior check passed.
• structurally verified only: static checks passed and no behavior check was required for the change.
• behavior check failed: a behavior-check-required change was tested and at least one representative prompt failed the pass criteria.
• verification incomplete: required checks were skipped or the available evidence is not enough to classify the change as fully or structurally verified.

Reporting Rules

• Do not say a change is complete without fresh evidence from the current turn.
• Name the commands that were run.
• Do not describe a change as fully verified if a required behavior check was skipped or failed.
• Name the applicable result level in the report.
• If only a minimum docs-only gate was available, say so explicitly.