57 lines
2.8 KiB
Markdown
57 lines
2.8 KiB
Markdown
---
|
|
name: agent-docs-verification
|
|
description: 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.
|