Context
Build deliverable of course lane 7 (#2909; design locked 2026-08-17, register gate clean, user-confirmed). The design contract is docs/specs/write-for-agents-brief.md (Brief; graduated from the chain branch's contract slice at chain close per the topic-docs convention) — this issue executes it; do not relitigate the locked decisions. Supporting artifacts: the verified agent-doc surface enumeration at docs/specs/agent-doc-surfaces.md, decision rows in docs/upstream/aihero-steering-lanes.md, provenance in docs/upstream/mattpocock-skills.md (decomposition table).
Proposed work
- New skill
plugins/docs-hygiene/skills/write-for-agents/ — model-invoked, write-side; body inlines the adapted doctrine: context-pointer wording (cover the branches, front-load the leading word), information hierarchy (steps vs reference, co-location, sprawl), completion criteria (clarity vs demand, premature completion, post-completion steps, legwork), when-to-split by sequence, leading words + negation (prompt the positive), two loads (context + cognitive)
- Points at (never restates):
audit-progressive-disclosure (tier model, pointer quality), extract-ssot, audit-derivability, domain-driven-design:curate-language; route-away fence: SKILL.md authoring → playbooks:skill-authoring + skill-quality:check; audit requests → audit siblings; human-facing docs out of scope
- Description trigger families (per Brief): CLAUDE.md/AGENTS.md content edits,
.claude/rules writing, agent-consumed reference/context docs, pointer-line adds, doc-plus-pointer extraction; passes skill-quality:check listing-budget
- Shipped
claude plugin eval suite (~6–10 cases): every positive trigger scenario fires the skill, every negative control (audit phrasing, "create a skill", human-README writing) does not — suite passing gates this PR
- Reference file adapting the surface enumeration (re-verify Claude-side rows against current docs at build time — enumeration was current at v2.1.233, 2026-08-17; optionally re-fetch the four egress-blocked vendor pages for Part 2 semantics)
- One-line cognitive-load cross-reference added to PLUGIN-PHILOSOPHY's Instruction economy section
- SSOT updates on merge: decomposition-table gap verdicts → adopted; leading-words tracked strand retires (disposition already annotated)
- docs-hygiene version bump + CHANGELOG entry; lane 7 status update in
docs/upstream/aihero-steering-lanes.md
Acceptance criteria
Mirror the Brief's (docs/specs/write-for-agents-brief.md § Acceptance criteria) — they are the contract; each is settled by the named diff or the eval suite run.
Metadata
| Field |
Value |
| Category |
unspecified |
| Area |
docs-hygiene, docs (philosophy, upstream) |
| Ecosystem |
unspecified |
Context
Build deliverable of course lane 7 (#2909; design locked 2026-08-17, register gate clean, user-confirmed). The design contract is
docs/specs/write-for-agents-brief.md(Brief; graduated from the chain branch's contract slice at chain close per the topic-docs convention) — this issue executes it; do not relitigate the locked decisions. Supporting artifacts: the verified agent-doc surface enumeration atdocs/specs/agent-doc-surfaces.md, decision rows indocs/upstream/aihero-steering-lanes.md, provenance indocs/upstream/mattpocock-skills.md(decomposition table).Proposed work
plugins/docs-hygiene/skills/write-for-agents/— model-invoked, write-side; body inlines the adapted doctrine: context-pointer wording (cover the branches, front-load the leading word), information hierarchy (steps vs reference, co-location, sprawl), completion criteria (clarity vs demand, premature completion, post-completion steps, legwork), when-to-split by sequence, leading words + negation (prompt the positive), two loads (context + cognitive)audit-progressive-disclosure(tier model, pointer quality),extract-ssot,audit-derivability,domain-driven-design:curate-language; route-away fence: SKILL.md authoring →playbooks:skill-authoring+skill-quality:check; audit requests → audit siblings; human-facing docs out of scope.claude/ruleswriting, agent-consumed reference/context docs, pointer-line adds, doc-plus-pointer extraction; passesskill-quality:check listing-budgetclaude plugin evalsuite (~6–10 cases): every positive trigger scenario fires the skill, every negative control (audit phrasing, "create a skill", human-README writing) does not — suite passing gates this PRdocs/upstream/aihero-steering-lanes.mdAcceptance criteria
Mirror the Brief's (
docs/specs/write-for-agents-brief.md§ Acceptance criteria) — they are the contract; each is settled by the named diff or the eval suite run.Metadata