feat(docs-hygiene): write-for-agents — authoring-time skill for agent-consumed markdown

[kyle-sexton]

Closes #2962

Summary

Adds docs-hygiene:write-for-agents — the write-side complement to the plugin's seven audit/transform skills: authoring-time doctrine that fires while agent-consumed markdown is being written, closing the writing-for-agents re-evaluation's gaps 1–2 (no authoring-time home for non-skill agent docs; completion-criteria doctrine homeless) plus the two-loads budget. docs-hygiene 0.16.1 → 0.17.0.

Fix

• New skill plugins/docs-hygiene/skills/write-for-agents/ (model-invoked): inlines the adapted doctrine — budget both loads (context + cognitive), branch-covering front-loaded pointers, steps-vs-reference separation with co-location, observable completion criteria (premature-completion / post-completion / legwork guards), split-by-sequence, positive-form prompting — and points at audit-progressive-disclosure's tier model, the invocation-mode rubric (§ Splitting by invocation, per the lane 8 coordination note), claude-memory:audit's navigation-pointer remediation (per the lane 9 coordination note), and curate-language instead of restating any of them. Route-away fence keeps SKILL.md authoring, audit requests, and human-facing docs with their incumbent owners.
• reference/agent-doc-surfaces.md: shipped adaptation of the docs-verified auto-read surface enumeration (Claude Code v2.1.233 baseline, re-verify note) plus other-ecosystem analogues.
• evals/: 9-case suite gating trigger reliability — 5 positive writing-moment cases, 3 negative route-away controls, 1 doctrine-behavior case over a planted-flaw fixture.
• docs/PLUGIN-PHILOSOPHY.md: one-line cognitive-load cross-reference in Instruction economy.
• docs/upstream/mattpocock-skills.md: decomposition-table gap-1/2 verdicts flipped to ADOPTED; leading-words tracked strand retired (both per the Brief's on-merge criteria).

Verification

• markdownlint-cli2 over all touched markdown: 0 issues in 7 files.
• jq empty on plugin.json and evals.json: both parse.
• scripts/check-changelog-parity.sh --check and --check-bump origin/main: both exit 0 (0.17.0 entry present and matching).
• Description length is well inside the 1,536-char listing cap; the eval suite is the standing regression gate for the trigger families (CI's plugin-gate/skill-quality lanes run their checks on this PR).

Related

• Design contract: docs/specs/write-for-agents-brief.md (course lane 7, playbooks/docs-hygiene: aihero course lane 7: authoring-time steering doctrine (writing-for-agents re-decision) #2909; user-confirmed 2026-08-17)
• Refs skill-quality: add completion-criteria check criterion + pointer to write-for-agents doctrine #2963 (audit-side completion-criteria criterion — sequenced with-or-after this PR, next in the roadmap queue)
• Refs playbooks/docs-hygiene: aihero course lane 7: authoring-time steering doctrine (writing-for-agents re-decision) #2909, docs(upstream): AI Hero course journey roadmap — remaining lanes and filed follow-ons, in order #2994 (journey provenance); coordination notes honored from skill-quality/plugin-philosophy: aihero course lane 8: invocation-mode doctrine and evidence-driven fleet re-grade #2910 (lane 8) and claude-memory: aihero course lane 9: steering-surface validations (navigation pointers, harness claims, auto-memory, /init-then-prune eval) #2911 (lane 9)

🤖 Generated with Claude Code

https://claude.ai/code/session_01QbfCrj3X9FfGL7VRZYmrn4

---

Generated by Claude Code

[claude]

Claude finished @kyle-sexton's task in 3m 26s —— View job

---

Claude finished the code review

Todo list

• Gather context (PR diff, changed files)
• Understand the request (invoke /review:code-review)
• Run code-review skill/process over the PR diff
• Post inline comments for findings anchored to changed lines
• Post final summary review

Summary

Reviewed all 9 changed files (git diff origin/main...HEAD) against the /review:code-review criteria (correctness, CLAUDE.md/AGENTS.md alignment, high-signal bar). This is doc-only content (new skill, reference table, evals, changelog/README/plugin.json bumps), so the review focused on factual/cross-reference accuracy of the claims the new skill makes about itself and sibling plugins, rather than code logic.

1 finding, posted inline:

• plugins/docs-hygiene/skills/write-for-agents/SKILL.md:46 — claims claude-memory:audit owns "navigation-pointer remediation guidance" / "the restructure-before-pointer call." I checked plugins/claude-memory/skills/audit/ in full (all of reference/criteria.md's checks C1–C9/R1–R4/RD1/M1–M4, plus every context/*.md and SKILL.md) and the string "pointer" does not appear anywhere in that skill — no check addresses restructuring vs. pointing across distant folders. An agent following this pointer will find nothing there.

Verified as correct (no findings):

• Cross-references that do resolve: ../audit-progressive-disclosure/context/tier-model.md, docs/conventions/invocation-mode/README.md § Splitting by invocation, docs/specs/write-for-agents-brief.md.
• domain-driven-design:curate-language and the "(if installed)" cross-plugin attribution pattern — both plugins exist in-repo and the phrasing matches existing repo convention (planning:design, architecture:improve use the same pattern).
• The absolute GitHub-blob link to docs/conventions/invocation-mode/README.md (rather than a relative path) matches existing convention for plugin skills linking outside their own plugin root (claude-config:audit, claude-memory:audit, discipline:sweep-all all do the same, since a plugin installed standalone wouldn't carry the monorepo's docs/ tree).
• reference/agent-doc-surfaces.md's claims about CLAUDE.md/rules/skills compaction and re-injection behavior are consistent with the existing, independently-sourced compaction table in plugins/claude-memory/skills/audit/reference/official-guidance.md.
• plugin.json and evals.json parse (jq empty); plugin.json version bump (0.16.1 → 0.17.0) matches the new CHANGELOG.md entry; the eval-suite composition (5 positive / 3 negative / 1 behavior = 9 cases) matches the PR description's claim, and the draft-rule.md fixture actually contains the two prohibitions, blind pointer, and premature-completion step ("Done when it works") that eval case 9 expects it to.
• docs/upstream/mattpocock-skills.md table edits are internally consistent (gap 1/2 rows flip to ADOPTED, the leading-words tracked strand is marked RETIRED, and skill-quality: add completion-criteria check criterion + pointer to write-for-agents doctrine #2963 is correctly still called out as the one open follow-on for the audit-side completion-criteria half).

Everything else — markdownlint, check-changelog-parity.sh, the description-length cap — is the PR author's claimed verification; I did not have markdownlint-cli2/gh available in this environment to independently re-run those, so I'm not counting them as confirmed either way.
· branch

[claude]

Claude finished @kyle-sexton's task in 41s —— View job

---

Security review — PR #3003

Skip gate: stop early — the full diff (git diff origin/main...HEAD) touches only markdown/doc content, a plugin manifest version bump, a changelog, and a new skill's SKILL.md + evals/*.json + reference/*.md files. No code, no GitHub Actions workflow changes, no auth/authz logic, no injection surfaces (command/SQL/path/template), no secret/token/credential handling, and no permission or dependency-pin changes. There is no security-relevant surface in this change.

• Gather context (PR diff, custom instructions)
• Invoke /review:security-review skill and follow its instructions
• Post findings / summary

No security issues found. This PR is a documentation-only addition (a new authoring-time skill plus its supporting reference/eval fixtures) with no security-relevant surface — skip gate condition 2 applies.

[github-actions]

Last security-reviewed head: 71e44ca95c61812263aff69d0d5abeec7d84dec0. On the next push, the relevance gate compares only the commits since this SHA; delete this comment to force a full re-review.

[github-actions]

Claude has reviewed this PR 5 times. The lane skips further automatic reviews after 5; deleting this comment resets the count.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 07341a266c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[kyle-sexton]

Review round addressed in 71e44ca9 — all four findings verified against the tree before fixing, all valid:

• claude[bot] inline (SKILL.md:46): confirmed — plugins/claude-memory/skills/audit/ contains no pointer guidance today; that home is claude-memory: patch audit criteria for navigation pointers — C5 carve-out, C7 stale-highway note, C3 nested CLAUDE.md + @-mention rows, design-smell remediation #2987's unbuilt deliverable, so the sentence pointed at nothing. The restructure-before-pointer caveat is now stated inline (one sentence); noted on claude-memory: patch audit criteria for navigation pointers — C5 carve-out, C7 stale-highway note, C3 nested CLAUDE.md + @-mention rows, design-smell remediation #2987 that its implementing PR may convert the inline form back to a pointer once the real home exists.
• Codex P2 (SKILL.md:51): confirmed against the public-surface contract — the sibling context/tier-model.md relative link was a private-surface citation; replaced with the slash-only form (/docs-hygiene:audit-progressive-disclosure).
• Codex P2 (SKILL.md:98): confirmed against docs/conventions/invocation-mode/README.md § Cross-skill invocation phrasing (binds new skill text) — the three operative "After writing" handoffs now use explicit invoke-via-the-Skill-tool phrasing.
• Codex P2 (reference table): confirmed omission vs docs/specs/agent-doc-surfaces.md — the conditional --add-dir load row is restored so add-dir CLAUDE.md/rules aren't mis-budgeted as on-demand.

markdownlint clean after the round.

---

Generated by Claude Code

[claude]

Claude finished @kyle-sexton's task in 2m 16s —— View job

---

Code review — /review:code-review

• Gather context (PR diff, changed files)
• Invoke /review:code-review and follow its instructions
• Post inline findings anchored to changed lines
• Post final summary review

Summary

Skip-gate checks: PR is open, not a draft, and while HEAD (71e44ca) has an existing successful review on this lane, that review targeted the prior commit (07341a2) and this new commit (71e44ca) specifically addresses that review's findings plus two P2s from chatgpt-codex-connector — so it doesn't fully "still apply" and a fresh pass over the delta is warranted.

Re-verified the four prior findings against 71e44ca — all four are correctly fixed:

1. The claude-memory:audit "navigation-pointer remediation" attribution (my prior finding) is gone; SKILL.md:45-48 now states the restructure-before-pointer caveat inline instead of citing an unimplemented sibling capability.
2. The sibling-private-context link into ../audit-progressive-disclosure/context/tier-model.md (Codex P2) is replaced with SKILL.md:50-52's slash-invocation form (invoke /docs-hygiene:audit-progressive-disclosure via the Skill tool) — contract-clean per audit-encapsulation/context/public-surface-contract.md.
3. The bare "Route to X" handoffs (Codex P2) are now explicit Invoke ... via the Skill tool phrasing throughout the "After writing" section, matching docs/conventions/invocation-mode/README.md's Cross-skill invocation phrasing convention.
4. The dropped --add-dir load row (Codex P2) is restored at reference/agent-doc-surfaces.md:24, matching docs/specs/agent-doc-surfaces.md:22's source enumeration.

I also confirmed the invocation-reach invariant holds for every skill write-for-agents now chains to via the Skill tool (docs-hygiene:audit-progressive-disclosure, extract-ssot, audit-noise, audit-derivability, domain-driven-design:curate-language) — all five carry disable-model-invocation: false, so none is an invalid chain target.

1 new finding, posted inline (introduced by the fix commit, not present before):

• plugins/docs-hygiene/CHANGELOG.md:15 — the 0.17.0 entry still claims the skill "points at ... claude-memory:audit's navigation-pointer remediation," but that's exactly the pointer the fix commit removed from SKILL.md (because the target doesn't exist). The changelog now documents a cross-reference the shipped skill no longer makes.

Also checked, no issues:

• docs/upstream/mattpocock-skills.md table edits are internally consistent with the fix (still correctly attributes gap-1/2 doctrine to write-for-agents, doesn't reference claude-memory:audit).
• evals/evals.json and evals/fixtures/draft-rule.md are untouched by the fix commit and remain consistent with the current SKILL.md doctrine.
• plugin.json version bump (0.16.1 → 0.17.0) and description update are consistent with CHANGELOG.md's version header; README.md's new skill row is accurate.

Per this lane's rules, I did not independently re-run markdownlint-cli2 or check-changelog-parity.sh (no tool access in this environment) — treating those as author-claimed and unverified, not confirmed.
· branch

[claude]

Claude finished @kyle-sexton's task in 50s —— View job

---

Security review — PR #3003

Skip gate: stop early — this run reviews only the commits since the last security-reviewed head (07341a266c5 → 71e44ca95c6, per the bot's relevance-gate comment). That diff touches exactly two files, both markdown, both doc-text edits addressing the prior review round's findings:

• plugins/docs-hygiene/skills/write-for-agents/SKILL.md — replaces the inaccurate claude-memory:audit pointer-remediation attribution with inline doctrine text, and switches three "Route to <skill>" phrasings to explicit "Invoke /plugin:skill via the Skill tool" invocation-mode language.
• plugins/docs-hygiene/skills/write-for-agents/reference/agent-doc-surfaces.md — adds one table row documenting the conditional --add-dir CLAUDE.md/rules load path (gated on CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1).

No code, no GitHub Actions workflow changes, no auth/authz logic, no injection surfaces (command/SQL/path/template), no secret/token/credential handling, and no permission or dependency-pin changes. There is no security-relevant surface in this change — skip gate condition 2 applies.

• Gather context (diff since last-reviewed SHA, custom instructions)
• Invoke /review:security-review skill and follow its instructions
• Post findings / summary

No security issues found.
· branch

[claude]

Claude finished @kyle-sexton's task in 52s —— View job

---

Code review — /review:code-review

• Gather context (PR diff, changed files, prior review rounds)
• Invoke /review:code-review and follow its instructions
• Verify the new commit (30e233d) against the prior finding it addresses
• Post inline findings anchored to changed lines
• Post final summary review

Summary

This lane's last pass (on 71e44ca) found one new issue: CHANGELOG.md's 0.17.0 entry still credited claude-memory:audit with "navigation-pointer remediation," even though the same commit had just removed that (nonexistent) pointer from SKILL.md. Commit 30e233d — the only change since — fixes exactly that.

Re-verified the fix against the tree at 30e233d:

• plugins/docs-hygiene/CHANGELOG.md — the claude-memory:audit clause is gone; the entry now reads "...points at the audit siblings, the invocation-mode rubric, and curate-language rather than restating them; the restructure-before-pointer caveat is stated inline pending its audit-side home (claude-memory: patch audit criteria for navigation pointers — C5 carve-out, C7 stale-highway note, C3 nested CLAUDE.md + @-mention rows, design-smell remediation #2987)."
• Confirmed SKILL.md has no claude-memory:audit reference anywhere in the file (grep -c claude-memory → 0) — the changelog and skill body now agree, and neither cites the unbuilt claude-memory: patch audit criteria for navigation pointers — C5 carve-out, C7 stale-highway note, C3 nested CLAUDE.md + @-mention rows, design-smell remediation #2987 capability as if it exists today.
• The other three fixes from the prior round (slash-invocation link instead of a private sibling context/ path at SKILL.md:50-52, explicit "Invoke ... via the Skill tool" phrasing in the "After writing" section, and the restored --add-dir load row in reference/agent-doc-surfaces.md:21) are all still intact — this commit didn't touch those files.

No new findings. This commit only edits plugins/docs-hygiene/CHANGELOG.md (+3/-2 lines), and the edit is a straightforward doc-accuracy correction with no other observable effect.
· branch

[claude]

Claude finished @kyle-sexton's task in 1m 29s —— View job

---

Code review — /review:code-review

• Gather context (PR diff, prior review rounds, latest commit)
• Invoke /review:code-review and follow its instructions
• Verify latest commit (19b1dd2) since last-reviewed head (30e233d)
• Post inline findings anchored to changed lines
• Post final summary review

Summary

The only change since the last reviewed commit (30e233d) is 19b1dd2, which touches a single file: docs/CATALOG.md (+1/-1) — regenerating the docs-hygiene entry's description line to include write-for-agents.

Verified: the new CATALOG.md line is byte-for-byte consistent with plugins/docs-hygiene/.claude-plugin/plugin.json's description field (confirmed via jq -r .description), so this is a correct, mechanical regeneration with no drift.

I also re-walked the full PR diff (git diff origin/main...HEAD, all 10 files) end to end rather than trusting the prior rounds' conclusions blindly:

• SKILL.md — re-read in full. All three prior finding classes are fixed and stayed fixed: no claude-memory:audit reference anywhere in the file; the pointer-quality cross-reference at lines 50-52 uses the slash-invocation form (/docs-hygiene:audit-progressive-disclosure via the Skill tool) rather than a private sibling context/ path; all "After writing" handoffs (lines 98-103) use explicit "Invoke /plugin:skill via the Skill tool" phrasing.
• reference/agent-doc-surfaces.md — the --add-dir conditional-load row (line 24) is present and matches the source enumeration's semantics.
• CHANGELOG.md — the 0.17.0 entry's "points at the audit siblings, the invocation-mode rubric, and curate-language... restructure-before-pointer caveat is stated inline pending its audit-side home (claude-memory: patch audit criteria for navigation pointers — C5 carve-out, C7 stale-highway note, C3 nested CLAUDE.md + @-mention rows, design-smell remediation #2987)" phrasing matches what SKILL.md actually does — no more claiming a claude-memory:audit capability that doesn't exist.
• docs/upstream/mattpocock-skills.md, docs/PLUGIN-PHILOSOPHY.md, plugins/docs-hygiene/README.md — table/prose edits are internally consistent with each other and with the shipped skill (gap-1/2 rows ADOPTED, leading-words strand RETIRED, README's new skill row and axis list match, PLUGIN-PHILOSOPHY's cognitive-load cross-reference points at the right skill).
• evals/evals.json — 9 cases (5 positive / 3 negative / 1 behavior) match the PR's claimed composition; case 9's expectations line up with evals/fixtures/draft-rule.md's actual content (two prohibitions, a blind pointer, and a "Done when it works" premature-completion step).
• plugin.json and evals.json both parse (jq empty); version bump (0.16.1 → 0.17.0) matches CHANGELOG.md's header.

No new findings. All findings from earlier review rounds on this PR (the claude-memory:audit misattribution, the two Codex P2s on sibling-private linking and bare "Route to" phrasing, the missing --add-dir row, and the stale changelog clause) were fixed in 71e44ca/30e233d and remain fixed in the current head (19b1dd2). This round's only change (CATALOG.md) is a correct, verified regeneration with nothing to flag.

Per this lane's constraints, I did not have markdownlint-cli2 available to independently re-run in this environment (attempted npx markdownlint-cli2; sandboxed out) — treating markdownlint-clean as author-claimed, consistent with prior rounds.
· branch

[claude]

Claude finished @kyle-sexton's task in 44s —— View job

---

Code review — /review:code-review

• Gather context (PR diff, prior review rounds, latest commit)
• Invoke /review:code-review and follow its instructions
• Verify latest commit (e0d767f) since last-reviewed head (19b1dd2)
• Post inline findings anchored to changed lines
• Post final summary review

Summary

The only change since the last reviewed commit (19b1dd2) is e0d767f, which touches a single file: docs/SKILL-CHEAT-SHEET.md (+1/-0) — adding the write-for-agents row to the "Anytime / cross-cutting" table.

Verified: the new row is correct and consistent —

• docs/SKILL-CHEAT-SHEET.md:187 — link path ../plugins/docs-hygiene/skills/write-for-agents/SKILL.md resolves correctly, and the summary text "Authoring-time doctrine for agent-consumed markdown" is a byte-for-byte match of SKILL.md's own metadata.summary frontmatter field (SKILL.md:6).
• Row placement is alphabetically correct (write-for-agents sorts after rename-references among docs-hygiene: entries) and the "Anytime / cross-cutting" section is the right home for an authoring-time (not audit-triggered) skill.

I also re-walked the full PR diff (git diff origin/main...HEAD, all 11 files) to confirm nothing regressed:

• No claude-memory reference anywhere in SKILL.md or CHANGELOG.md (the misattributed pointer stays removed).
• No bare Route to phrasing remains in SKILL.md (the Skill-tool invocation phrasing from the earlier fix round is intact).
• The --add-dir conditional-load row is present in reference/agent-doc-surfaces.md:24.
• File count/diff shape (11 files, +331/-17) matches the PR's reported stats exactly.

No new findings. All findings from earlier review rounds on this PR (the claude-memory:audit misattribution, the two Codex P2s on sibling-private linking and bare "Route to" phrasing, the missing --add-dir row, and the stale changelog clause) were fixed in 71e44ca/30e233d and remain fixed in the current head (e0d767f). This round's only change (SKILL-CHEAT-SHEET.md) is a correct, verified mechanical regeneration with nothing to flag.

Per this lane's constraints, I did not have markdownlint-cli2 available to independently re-run in this environment — treating markdownlint-clean as author-claimed, consistent with prior rounds.
· branch