public/bluecraft
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

optimize agent-docs

Browse Source
This commit is contained in:
Ge Song
2026-04-23 02:16:39 +08:00
parent 2c22fcc4c3
commit c14adfc633
31 changed files with 734 additions and 377 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
skills/agent-docs-verification/SKILL.md
View File

@@ -19,38 +19,55 @@ Use this skill after changing AGENTS or `agent-docs` to gather verification evid
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:
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`
5. When the change touched routing or structure, also re-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
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:
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`
8. For behavior-check-required changes, run a small behavior check with 1 to 3 representative prompts and inspect whether the agent:
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
9. When the change edited the `agent-docs` skill suite itself, also confirm:
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/`
10. Report command evidence and exact scope:
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.

2
skills/agent-docs-verification/agents/openai.yaml
View File

@@ -1,4 +1,4 @@
interface:
display_name: "Verify agent-doc changes"
short_description: "Run post-change validation for agent-docs"
default_prompt: "Use $agent-docs-verification to run post-change validation for AGENTS.md and agent-docs and summarize the evidence."
default_prompt: "Use $agent-docs-verification to run applicable validator and diff checks for AGENTS.md and agent-docs, add representative behavior checks when required, summarize evidence, and state the verification result level."