docs: add a write-docs authoring skill#26767
Conversation
Add .claude/skills/write-docs/SKILL.md, the authoring counterpart to the doc-check skill. It points at docs/.style/content-guidelines.md as the canonical source for scope and routing, and at the prose style guide for formatting, then walks the authoring workflow: establish ground truth, decide whether content belongs in docs and where, pick the Diataxis mode and manifest slot, draft with discovery-based pedagogy, and validate. It carries the "what not to write" routing, Premium signaling, emdash, and rename and redirect guardrails. Cross-link the skill from both AGENTS.md navigation locations. Filed via Coder Agents on Nick's behalf. Refs: DOCS-364
|
/coder-agents-review |
|
Chat: Review posted | View chat Review history
deep-review v0.9.0 | Round 6 | Last posted: Round 6, 15 findings (1 P2, 5 P3, 7 Nit, 2 Note), APPROVE. Review Finding inventoryFindings
Contested and acknowledged(none) Round logRound 1Panel. Netero (first pass) + 12-reviewer panel (Bisky, Hisoka, Mafu-san, Mafuuu, Pariston, Gon, Leorio, Robin, Zoro, Razor, Pen Botter, Kite). 1 P2, 4 P3, 4 Nit. Reviewed against e24bc5b..f68f354. Round 2Panel. Netero + 10-reviewer panel (Bisky, Hisoka, Mafu-san, Mafuuu, Pariston, Gon, Leorio, Razor, Pen Botter, Meruem). CRF-1 through CRF-9 addressed. 3 new Nits. Reviewed against e24bc5b..428a6ab. Round 3Panel. Netero + 10-reviewer panel (Bisky, Hisoka, Mafu-san, Mafuuu, Pariston, Gon, Leorio, Razor, Pen Botter, Chopper). CRF-10 through CRF-12 addressed. 1 new P3 (fix-chain regression from CRF-12), 1 Note. Reviewed against e24bc5b..91d6539. Round 4Panel. Netero + 6-reviewer panel (Bisky, Hisoka, Mafu-san, Mafuuu, Pariston, Kite). CRF-13 and CRF-14 addressed. No new findings. Reviewed against e24bc5b..48a5cfd. Round 5Panel. Netero + 5-reviewer panel (Bisky, Hisoka, Mafu-san, Mafuuu, Pariston). No open findings from R4. 1 new Note. Reviewed against e24bc5b..2236ecf. Round 6CRF-15 addressed (a51ea02). Netero + 3-reviewer panel (Bisky, Mafuuu, Pariston). No new findings. Reviewed against e24bc5b..a51ea02. About deep-reviewCRF = Coder Review Finding (P0-P4, Nit, Note)
|
![coder-agents-review[bot]](https://avatars.githubusercontent.com/in/3454270?s=60&v=4){kind=small}
There was a problem hiding this comment.
The skill is well-designed where it adds genuinely new content. The ground-truth-first workflow (step 1) targets the most expensive class of doc review churn: describing behavior you did not verify. The pedagogy patterns, anti-pattern list, and pre-handoff checklist fill a real gap that the existing canonical docs do not cover. The scope is proportional: one skill file, two cross-links, no drive-by edits.
Severity count: 1 P2, 4 P3, 4 Nit.
The central theme is internal consistency. The skill's preamble says "The canonical rules live outside this skill. Read them first; this skill only tells you how to apply them." Four sections then restate canonical rules inline instead of linking, and two of those restatements already differ from their counterparts in doc-check at merge time. Separately, "one concept per page" misquotes the canonical "one outcome per page" rule from the style guide.
Kite: "Requiring agents to read real source, run real commands, and capture real output before writing a single sentence targets the highest-cost class of doc review churn."
The workflow, pedagogy, and checklist sections are strong. The restatement sections are the weak spot, and fixing them tightens the skill rather than shrinking it.
🤖 This review was automatically generated with Coder Agents.
Address deep-review (coder-agents-review) Round 1 findings on the write-docs authoring skill: - CRF-1 (P2): replace the inline Premium, renames, and emdash restatements with one "Structural rules to apply" pointer to the canonical content-guidelines section, keeping only the rename application notes the canonical rules do not spell out. Removes the word-level divergences from doc-check present at merge time. - CRF-2/3/9: collapse "What not to write" to a pointer to the canonical exclusion catalog and routing table so the list cannot drift. This also stops dropping the known-bugs workaround clause and removes the reordered timeless/predictive wording, since nothing is restated. - CRF-4: correct "one concept per page" to the canonical "one outcome per page" in step 3 and the pre-handoff checklist. - CRF-5/7: rename the AGENTS.md nav entry to "Docs authoring" (noun phrase) and differentiate it from "Docs prose" by trigger (new or restructured pages vs prose-only edits). - CRF-6: restore the "Diátaxis" accent in all four occurrences. - CRF-8: normalize the read-when-relevant trigger to "(when writing docs/)". - Add a back-reference from doc-check to write-docs so the counterpart pairing is bidirectional. Refs: DOCS-364 Filed via Coder Agents on Nick's behalf.
|
/coder-agents-review |
There was a problem hiding this comment.
All 9 R1 findings addressed in 428a6ab. The fix was class-level, not instance-level: instead of patching individual misquotes and divergences, the author removed every restated section and replaced them with canonical links. The explicit anti-drift directive ("Do not reproduce the catalog here, so it cannot drift from the source") shows the lesson generalized.
The AGENTS.md nav differentiation is clean: "Docs prose" for prose-only edits, "Docs authoring" for new/moved/restructured pages or when unsure. The doc-check cross-link makes the counterpart pairing bidirectional.
3 new Nits below (no blockers).
Mafu-san: "Instead of individually correcting each divergent restatement, it removed all restatements and linked. The agent fixed the class, not the instances."
🤖 This review was automatically generated with Coder Agents.
Address deep-review (coder-agents-review) Round 2 nits (PR already approved, no blockers): - CRF-10: rename the H1 to "Documentation Authoring Skill" (noun phrase), matching the sibling "Documentation Check Skill" convention. - CRF-11: add the "#follow-the-diátaxis-framework" anchor to the step 3 content-guidelines link, consistent with the other cross-file links. - CRF-12: scope the read-when-relevant trigger to "for new or restructured docs/ pages" so it matches the nav routing. Refs: DOCS-364 Filed via Coder Agents on Nick's behalf.
|
/coder-agents-review |
There was a problem hiding this comment.
CRF-10 through CRF-12 all addressed in 91d6539. The corrections retained well across all three rounds with no regressions on prior fixes.
One new P3 below: the CRF-12 fix over-narrowed the read-when-relevant trigger by dropping "moved," which the nav entry includes and the skill explicitly covers. One Note about an incomplete enumeration.
Pariston: "I tried to build a case against this change and could not. The problem is correctly understood, the solution is proportional, and the fix is at the right level."
🤖 This review was automatically generated with Coder Agents.
Address deep-review (coder-agents-review) Round 3:
- CRF-13 (P3): restore "moved" to the read-when-relevant trigger so it
matches the nav routing ("new, moved, or restructured docs/ pages")
and the skill's own page-move guidance. Fixes a scope regression from
the Round 2 CRF-12 fix.
- CRF-14 (Note): add "auto-generated content" to the structural-rules
summary so the enumeration covers all five canonical rules.
Refs: DOCS-364
Filed via Coder Agents on Nick's behalf.
|
/coder-agents-review |
There was a problem hiding this comment.
All 14 findings resolved across 4 rounds. No new issues from the R4 panel (Netero + 6 reviewers, all clean).
The skill is in good shape. It fills a real gap between doc-check ("do I need docs?") and the canonical sources ("what are the rules?") by adding a workflow that sequences the rules into actionable steps, plus pedagogy patterns and an anti-pattern catalog drawn from real review cycles. The design principle held: link to canonical sources, don't restate them.
Mafu-san noted the CRF-12 to CRF-13 regression chain as a fix-without-sibling-check pattern, but the agent diagnosed the class of failure in the commit message, not just the instance.
🤖 This review was automatically generated with Coder Agents.
…write-docs Lessons from the Quickstart review (Ben Potter, Kayla): - Prefer the lowest-maintenance correct presentation; brittle references (hard-coded line numbers, screenshots of copyable text) rot. A screenshot still earns its place when a UI step genuinely needs it; weigh the upkeep, and flag the gap if you cannot capture one rather than omitting it silently or treating "no screenshot" as policy. - Orient the reader inside a multi-page series; never ship a dead-end page. Added a matching pre-handoff checklist item. Refs: DOCS-364 Filed via Coder Agents on Nick's behalf.
|
/coder-agents-review |
There was a problem hiding this comment.
All 14 prior findings resolved. The new commit (2236ecf) adds three pieces of genuinely original guidance: a lowest-maintenance-form pedagogy pattern, a series-navigation pattern, and a brittle-references anti-pattern. These are additive, do not restate canonical sources, and follow the established design principle. One Note below about the frontmatter description scope.
Hisoka: "Pulled every thread I could find across five rounds. Links resolve, anchors land, the partition between doc-check and write-docs is clean, the skill defers to canonical sources instead of restating them, and no instruction path produces a conflict. Nothing left to fight."
🤖 This review was automatically generated with Coder Agents.
Change the frontmatter description from "writing or editing" to "writing,
moving, or restructuring" so the skills registry indexes on a scope that
matches the AGENTS.md routing ("new, moved, or restructured docs/ pages,
or when unsure"). This avoids signaling capability for prose-only edits
that AGENTS.md deliberately routes to the simpler prose style guide.
Refs: DOCS-364
Filed via Coder Agents on Nick's behalf.
There was a problem hiding this comment.
All 15 findings resolved across 6 rounds. CRF-15 (description scope mismatch) addressed in a51ea02: frontmatter now says "writing, moving, or restructuring," matching the AGENTS.md routing. No new findings from Netero or the panel.
The skill is clean and ready to merge. Six rounds, 15 findings, all addressed. The design principle held throughout: link to canonical sources, add only genuinely new workflow and pedagogy content.
🤖 This review was automatically generated with Coder Agents.
Add a "Keep PRs reviewable" guardrail and a pre-handoff checklist item to the write-docs skill: keep each docs PR focused, ideally under ~1,000 lines changed, and split a multi-page series into one-page-per-PR changes. Large diffs get rubber-stamped or bounced, and both cost more review cycles than splitting up front. Refs: DOCS-364 Filed via Coder Agents on Nick's behalf.
1 participant
Adds
.claude/skills/write-docs/SKILL.md, the authoring counterpart to the existingdoc-checkskill. Wheredoc-checkdecides whether a change needs docs,write-docsguides writing them: it points atdocs/.style/content-guidelines.md(canonical scope and routing) and the prose style guide, then walks a short authoring workflow and the "what not to write" guardrails, so the rules are a default-loaded asset instead of something an agent has to rediscover.It also cross-links the skill from both
AGENTS.mdnavigation locations.What the skill covers
docs/manifest.jsonslot.coder/coder.com:redirects.json).It defers prose-style detail to
docs/.style/style-guide/rather than restating it.Verification and follow-up
make lint/emdash, markdownlint, and Vale pass on the skill andAGENTS.md.doc-check/SKILL.md(nameplusdescription).write-docsend to end on a small docs change. The skills registry indexes at startup, so this is best verified after merge.