What happened
The code agent's initial commit on PR #6202 (91ebe5c) created a single file (skills/authoring-skills/SKILL.md) without updating any existing documentation. The human's rewrite (e57c3a9) also modified 3 documentation files:
docs/guides/user/bring-your-own-agent.md — added a "Tuning agents with augmentation skills" section (+45 lines)docs/guides/user/customizing-with-skills.md — added an "Authoring skills that augment defaults" section (+36 lines)docs/guides/README.md — updated guide index links
Without these cross-references, users would need to independently discover the new skill exists. The code agent treated the task as "create one file" when the complete deliverable was "integrate a new skill into the documentation surface."
What could go better
The repo's AGENTS.md currently has guidance about updating docs/.vitepress/config.ts sidebar config when adding new docs (line 19), and about grepping for stale references when removing features (line 20). But there is no guidance about updating existing user guides with cross-references when adding a new skill.
The issue (#6193) did not ask for documentation updates — it requested a skill. The human recognized that a skill without documentation integration is incomplete, but this is tacit knowledge the code agent lacks.
I am moderately confident this guideline would help: the code agent follows AGENTS.md rules and would likely check the listed files if told to. I am less confident about the scope — new skills may not always need the same set of doc updates, and an overly prescriptive checklist could lead to unnecessary boilerplate changes.
Proposed change
Add a rule to AGENTS.md in the "How to work in this repo" section, near the existing documentation guidance:
- When adding a new skill under `skills/`, check the user-facing guides for relevant cross-reference opportunities: `docs/guides/user/customizing-with-skills.md` (skill catalog and usage), `docs/guides/user/bring-your-own-agent.md` (agent composition and tuning), and `docs/guides/README.md` (guide index). Add a brief cross-reference or section pointer if the new skill fills a gap in those guides.
This is deliberately phrased as "check for opportunities" rather than "you must update all three files" to avoid unnecessary boilerplate when a skill does not warrant user-guide integration.
Validation criteria
The next code agent PR that adds a new skill under skills/ should include at least one documentation cross-reference update in the user guides, or explicitly note in its PR description why no doc update is needed. Verify on the next 2 skill-addition PRs.
Generated by retro agent from #6202
What happened
The code agent's initial commit on PR #6202 (
91ebe5c) created a single file (skills/authoring-skills/SKILL.md) without updating any existing documentation. The human's rewrite (e57c3a9) also modified 3 documentation files:docs/guides/user/bring-your-own-agent.md— added a "Tuning agents with augmentation skills" section (+45 lines)docs/guides/user/customizing-with-skills.md— added an "Authoring skills that augment defaults" section (+36 lines)docs/guides/README.md— updated guide index linksWithout these cross-references, users would need to independently discover the new skill exists. The code agent treated the task as "create one file" when the complete deliverable was "integrate a new skill into the documentation surface."
What could go better
The repo's AGENTS.md currently has guidance about updating
docs/.vitepress/config.tssidebar config when adding new docs (line 19), and about grepping for stale references when removing features (line 20). But there is no guidance about updating existing user guides with cross-references when adding a new skill.The issue (#6193) did not ask for documentation updates — it requested a skill. The human recognized that a skill without documentation integration is incomplete, but this is tacit knowledge the code agent lacks.
I am moderately confident this guideline would help: the code agent follows AGENTS.md rules and would likely check the listed files if told to. I am less confident about the scope — new skills may not always need the same set of doc updates, and an overly prescriptive checklist could lead to unnecessary boilerplate changes.
Proposed change
Add a rule to
AGENTS.mdin the "How to work in this repo" section, near the existing documentation guidance:This is deliberately phrased as "check for opportunities" rather than "you must update all three files" to avoid unnecessary boilerplate when a skill does not warrant user-guide integration.
Validation criteria
The next code agent PR that adds a new skill under
skills/should include at least one documentation cross-reference update in the user guides, or explicitly note in its PR description why no doc update is needed. Verify on the next 2 skill-addition PRs.Generated by retro agent from #6202