From 07341a266c4c0e543f34f1e705f829ffa2369566 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 04:26:40 +0000 Subject: [PATCH 1/5] =?UTF-8?q?feat(docs-hygiene):=20write-for-agents=20?= =?UTF-8?q?=E2=80=94=20authoring-time=20skill=20for=20agent-consumed=20mar?= =?UTF-8?q?kdown?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The write-side complement to the audit siblings, per the lane 7 design contract (docs/specs/write-for-agents-brief.md): model-invoked at the writing moment for CLAUDE.md/AGENTS.md content, rules files, agent-loaded reference docs, pointer lines, and doc-plus-pointer extractions. Inlines the adapted doctrine (two loads, branch-covering pointers, steps vs reference with co-location, observable completion criteria, split-by-sequence, positive-form prompting) and points at the audit siblings, the invocation-mode rubric, claude-memory's pointer remediation, and curate-language instead of restating them. Ships the docs-verified surface reference and a 9-case trigger/behavior eval suite. PLUGIN-PHILOSOPHY gains the cognitive-load cross-reference; the SSOT decomposition flips gaps 1-2 to ADOPTED and retires the leading-words tracked strand. docs-hygiene 0.17.0. Closes #2962. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01QbfCrj3X9FfGL7VRZYmrn4 --- docs/PLUGIN-PHILOSOPHY.md | 4 +- docs/upstream/mattpocock-skills.md | 22 ++-- .../docs-hygiene/.claude-plugin/plugin.json | 4 +- plugins/docs-hygiene/CHANGELOG.md | 21 ++++ plugins/docs-hygiene/README.md | 5 +- .../skills/write-for-agents/SKILL.md | 114 ++++++++++++++++++ .../skills/write-for-agents/evals/evals.json | 98 +++++++++++++++ .../evals/fixtures/draft-rule.md | 11 ++ .../reference/agent-doc-surfaces.md | 64 ++++++++++ 9 files changed, 327 insertions(+), 16 deletions(-) create mode 100644 plugins/docs-hygiene/skills/write-for-agents/SKILL.md create mode 100644 plugins/docs-hygiene/skills/write-for-agents/evals/evals.json create mode 100644 plugins/docs-hygiene/skills/write-for-agents/evals/fixtures/draft-rule.md create mode 100644 plugins/docs-hygiene/skills/write-for-agents/reference/agent-doc-surfaces.md diff --git a/docs/PLUGIN-PHILOSOPHY.md b/docs/PLUGIN-PHILOSOPHY.md index f18db0d4b..ab4330863 100644 --- a/docs/PLUGIN-PHILOSOPHY.md +++ b/docs/PLUGIN-PHILOSOPHY.md @@ -567,7 +567,9 @@ without the instruction, delete it or convert it to a hook" applied the same doctrine to Claude Code itself, removing over 80% of its system prompt for the Opus 5 / Fable 5 generation with no measurable loss on its coding evaluations ([The new rules of context engineering for Claude 5 generation models](https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models), -verified 2026-08-08). Four rules follow: +verified 2026-08-08). Context load is not the only budget: the human maintainer's cognitive load +is its sibling constraint, and the write-time doctrine budgeting both lives in +`docs-hygiene:write-for-agents`. Four rules follow: - **Evidence-gated additions.** A new standing instruction requires observed, repeated stumble evidence against the current model — the same failure seen more than once — never anticipation diff --git a/docs/upstream/mattpocock-skills.md b/docs/upstream/mattpocock-skills.md index e93b30757..34493fc89 100644 --- a/docs/upstream/mattpocock-skills.md +++ b/docs/upstream/mattpocock-skills.md @@ -86,8 +86,8 @@ design-locked as `docs-hygiene:write-for-agents` (contract: `docs/specs/write-for-agents-brief.md`; build: [#2962](https://github.com/melodic-software/claude-code-plugins/issues/2962) + [#2963](https://github.com/melodic-software/claude-code-plugins/issues/2963), the audit-side -completion-criteria criterion). The GAP/PARTIAL verdict cells below flip to ADOPTED when #2962 -merges. +completion-criteria criterion). **#2962 built (docs-hygiene 0.17.0)**: the gap-1/2 verdict +cells below are ADOPTED; #2963's audit-side criterion remains the one open follow-on. **Lane 8 closed 2026-08-17**: gap 3 (invocation) is decided — invocation-mode rubric homed at `docs/conventions/invocation-mode/README.md` (model-invoked default + three exception classes; @@ -97,12 +97,12 @@ flip as [#2969](https://github.com/melodic-software/claude-code-plugins/issues/2 | Upstream section | Our surface | Verdict | |---|---|---| -| Context pointers (wording-as-trigger, branches, front-loaded leading word) | `docs-hygiene:audit-progressive-disclosure` (blind-pointer finding + six pointer-quality criteria in its tier model) — audit-time; `playbooks:skill-authoring` description-as-trigger — skills only | PARTIAL — no authoring-time home for non-skill agent docs (gap 1 → #2909) | -| The two loads (context load / cognitive load) | PLUGIN-PHILOSOPHY Instruction economy (context load only) | GAP — cognitive-load-as-budget doctrine absent (→ #2909) | -| Information hierarchy (steps vs reference, ladder, co-location, sprawl) | three-tier load-cost model ≈ the ladder | PARTIAL — co-location and steps-vs-reference distinction absent (→ #2909) | -| Steps and completion criteria (clarity, demand, premature completion, post-completion steps, legwork) | none — the prior mapping was silent on this section (oversight, not a decision) | GAP (gap 2 → #2909) | -| When to split (by sequence / by invocation) | tier-model split triggers are size/concern-based only; invocation axis now owned by the rubric | PARTIAL — sequence half rides #2962; invocation half ADOPTED (lane 8: `docs/conventions/invocation-mode/`) | -| Leading words + negation | tracked strand (below) | TRACKED — disposition path #2909 | +| Context pointers (wording-as-trigger, branches, front-loaded leading word) | `docs-hygiene:write-for-agents` (authoring-time, branch-covering front-loaded pointer doctrine) + `audit-progressive-disclosure` (audit-time criteria) + `playbooks:skill-authoring` (skills) | ADOPTED (adapted; #2962, docs-hygiene 0.17.0) | +| The two loads (context load / cognitive load) | `write-for-agents` "Budget both loads" + PLUGIN-PHILOSOPHY Instruction-economy cross-reference | ADOPTED (adapted; #2962) | +| Information hierarchy (steps vs reference, ladder, co-location, sprawl) | `write-for-agents` steps-vs-reference + co-location doctrine; three-tier load-cost model carries the ladder | ADOPTED (adapted; #2962) | +| Steps and completion criteria (clarity, demand, premature completion, post-completion steps, legwork) | `write-for-agents` "Give every step a completion criterion" (write-side); audit-side criterion rides #2963 | ADOPTED (adapted; #2962 — audit-side pending #2963) | +| When to split (by sequence / by invocation) | `write-for-agents` split-by-sequence; invocation axis owned by the rubric (`docs/conventions/invocation-mode/`), pointed at, never restated | ADOPTED (both halves; #2962 + lane 8) | +| Leading words + negation | `write-for-agents` "Prompt the positive" | ADOPTED (adapted; #2962 — tracked strand retired below) | | Pruning: single source of truth | `docs-hygiene:extract-ssot` + the topic-docs single-home rule | PARITY+ | | Pruning: environment-as-truth ("cache") | `docs-hygiene:audit-derivability` (keep-as-derivation-cache verdict + drift control) | PARITY+ (stronger — cache without drift control is not a cache) | | Pruning: relevance / sediment | `claude-config:audit-instructions`, `session-flow:reanchor`, `docs-hygiene:rename-references`, `review` doc-drift-detector | PARITY | @@ -126,9 +126,9 @@ triggers stand until the owning lane records the disposition: negation/negative-space port deferred from that session's gap scan) — this record cross-links that deferral rather than opening a second ledger entry. Trigger: a mattpocock/skills release whose changeset names `writing-for-agents`. - **Disposition (lane 7, 2026-08-17): adopted into the `docs-hygiene:write-for-agents` design - (#2962) — this row retires when that implementation merges; the release trigger stands until - then.** + **RETIRED (2026-08-18): adopted as `write-for-agents` "Prompt the positive" + (docs-hygiene 0.17.0, #2962). The release-named recheck trigger now applies only as an + ordinary attribution-table row concern, not an open strand.** - **Invocation-reach invariant** (upstream `SKILL-MECHANICS.md:10`: a user-invoked skill — `disable-model-invocation: true` — can be invoked by no other skill). **Disposition (lane 8, 2026-08-17): CONFIRMED against current official docs** diff --git a/plugins/docs-hygiene/.claude-plugin/plugin.json b/plugins/docs-hygiene/.claude-plugin/plugin.json index e0322c223..f080c51bd 100644 --- a/plugins/docs-hygiene/.claude-plugin/plugin.json +++ b/plugins/docs-hygiene/.claude-plugin/plugin.json @@ -1,8 +1,8 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "docs-hygiene", - "version": "0.16.1", - "description": "Documentation-hygiene toolkit: compress (flavor-trim markdown with a semantic-diff safety net), audit-noise (classify markdown noise), extract-ssot (deduplicate repeated content into a single source of truth), audit-encapsulation (detect citations into skill-private surfaces), rename-references (sweep stale references after renames), audit-derivability (classify whether a whole document earns its existence \u2014 could a fresh agent re-derive it from the code?), and audit-progressive-disclosure (grade instruction files against a load-tier model for split opportunities and hub/spoke disclosure defects).", + "version": "0.17.0", + "description": "Documentation-hygiene toolkit: compress (flavor-trim markdown with a semantic-diff safety net), audit-noise (classify markdown noise), extract-ssot (deduplicate repeated content into a single source of truth), audit-encapsulation (detect citations into skill-private surfaces), rename-references (sweep stale references after renames), audit-derivability (classify whether a whole document earns its existence \u2014 could a fresh agent re-derive it from the code?), audit-progressive-disclosure (grade instruction files against a load-tier model for split opportunities and hub/spoke disclosure defects), and write-for-agents (authoring-time doctrine that fires while agent-consumed markdown is being written).", "author": { "name": "Melodic Software", "email": "info@melodicsoftware.com" diff --git a/plugins/docs-hygiene/CHANGELOG.md b/plugins/docs-hygiene/CHANGELOG.md index 3f2a53834..8d9afabf8 100644 --- a/plugins/docs-hygiene/CHANGELOG.md +++ b/plugins/docs-hygiene/CHANGELOG.md @@ -1,5 +1,26 @@ # Changelog — docs-hygiene plugin +## [0.17.0] + +### Added + +- New skill `write-for-agents`: the write-side complement to the audit skills — + authoring-time doctrine firing while agent-consumed markdown is written + (CLAUDE.md/AGENTS.md content, `.claude/rules` files, agent-loaded reference/context + docs, navigation-pointer lines, doc-plus-pointer extractions). Inlines the adapted + doctrine (two-loads budgeting, branch-covering front-loaded pointers, + steps-vs-reference separation with co-location, observable completion criteria with + premature-completion/post-completion/legwork guards, split-by-sequence, + positive-form prompting) and points at the audit siblings, the invocation-mode + rubric, `claude-memory:audit`'s navigation-pointer remediation, and + `curate-language` rather than restating them. Ships `reference/agent-doc-surfaces.md` + (docs-verified auto-read surface table, Claude Code v2.1.233 baseline, plus + other-ecosystem analogues) and a 9-case eval suite gating trigger reliability + (5 positive writing-moment cases, 3 negative route-away controls, 1 doctrine + behavior case). Route-away fence: SKILL.md authoring, audit requests, and + human-facing docs stay with their incumbent owners. Design contract: + `docs/specs/write-for-agents-brief.md` (course lane 7, #2909); build issue #2962. + ## [0.16.1] ### Changed diff --git a/plugins/docs-hygiene/README.md b/plugins/docs-hygiene/README.md index 1076fb3fb..015a206ec 100644 --- a/plugins/docs-hygiene/README.md +++ b/plugins/docs-hygiene/README.md @@ -3,8 +3,8 @@ A Claude Code plugin bundling documentation-hygiene skills — one cohesive capability: keeping a repository's tracked markdown lean, deduplicated, and free of decayed references. Each skill is invocable on its own; together they -cover the flavor, noise, duplication, boundary, rename, worth, and loading -axes of doc upkeep. +cover the flavor, noise, duplication, boundary, rename, worth, loading, +and authoring axes of doc upkeep. ## The skills @@ -17,6 +17,7 @@ axes of doc upkeep. | `/docs-hygiene:rename-references` | Sweeps stale references after renames — the forms plain token grep misses: slash-command tokens, relative paths from moved files, frontmatter chains and globs — via a 12-form pattern library with audit, half-rename detection, and apply modes. | | `/docs-hygiene:audit-derivability` | Read-only, document-level worth classifier: could a fresh agent re-derive this whole document from the code, config, and structure? Weighs derivability, re-derivation cost, drift risk, and fact ownership into a verdict (delete, convert-to-pointer, keep-as-derivation-cache, keep-owns-facts), splits it by audience, and confirms load-bearing deletions with a fresh-context spot-test. Where the other five trim *inside* a doc, this decides whether the doc should exist. | | `/docs-hygiene:audit-progressive-disclosure` | Read-only progressive-disclosure classifier: grades agent-facing instruction markdown against a three-tier load-cost model (always-loaded / invocation-loaded / on-demand) and emits seven finding shapes in two lanes — split opportunities (oversize, mixed-concerns, tier-mismatch) and hub/spoke structure defects (blind-pointer, orphan-spoke, deep-nesting, missing-toc) — with tiered treatment guidance. Thresholds are advisory and Anthropic-prescribed; a deterministic `detect.sh` emits the facts, the judgment layer adjudicates. | +| `/docs-hygiene:write-for-agents` | The write-side complement to the audit skills: authoring-time doctrine that fires while agent-consumed markdown is being written (CLAUDE.md/AGENTS.md content, rules files, agent-loaded reference docs, pointer lines, doc-plus-pointer extractions) — two-loads budgeting, branch-covering pointers, steps-vs-reference separation, observable completion criteria, split-by-sequence, positive-form prompting — with a verified auto-read surface reference and a trigger-reliability eval suite. | ## Requirements diff --git a/plugins/docs-hygiene/skills/write-for-agents/SKILL.md b/plugins/docs-hygiene/skills/write-for-agents/SKILL.md new file mode 100644 index 000000000..b8191b640 --- /dev/null +++ b/plugins/docs-hygiene/skills/write-for-agents/SKILL.md @@ -0,0 +1,114 @@ +--- +description: "Write agent-consumed markdown well at the moment of writing — CLAUDE.md or AGENTS.md content, .claude/rules files, agent-loaded reference/context docs, navigation-pointer lines, and doc-plus-pointer extractions. Use when: 'add this to CLAUDE.md', 'write a rule for X', 'write this up for the agent', 'add a pointer to the docs', 'move this section into its own doc', 'draft an AGENTS.md section', or any drafting or editing of a markdown file an agent will load. NOT for: creating or editing a SKILL.md (playbooks:skill-authoring and skill-quality:check own that), auditing existing docs (the docs-hygiene audit skills own that), or human-facing docs such as end-user READMEs and changelogs." +argument-hint: "[]" +user-invocable: true +disable-model-invocation: false +metadata: + workflow-stage: anytime + summary: Authoring-time doctrine for agent-consumed markdown +--- + +# Write For Agents + +## Why this skill exists + +The docs-hygiene siblings are audit-shaped: they find problems in docs that already exist. This +skill is the write-side complement — it fires while the doc is being written, so the problems the +audits catch are not created in the first place. Its scope is any markdown an agent will consume; +the auto-read surfaces (CLAUDE.md scopes, `.claude/rules`, auto-memory, and their kin) are the +high-value core because their cost recurs every session. Read +[`reference/agent-doc-surfaces.md`](reference/agent-doc-surfaces.md) when you need to know +whether, when, and how much of a target file the harness actually loads — write differently for +an always-loaded surface than for an on-demand one. + +## Budget both loads + +Every line you write spends two budgets, and cutting one can overspend the other: + +- **Context load** — tokens the agent pays, every session for always-loaded surfaces. Governed + marketplace-wide by PLUGIN-PHILOSOPHY's Instruction economy: an instruction earns its place + with observed-stumble evidence, or it goes. +- **Cognitive load** — attention the human maintainer pays. The human is the index of the doc + set: they must be able to hold where things live. Ten tiny fragment files can be cheaper for + the agent and ruinous for the human; one 500-line file the reverse. When the two budgets + conflict, say which one you spent and why. + +## Write pointers that cover their branches + +A pointer is a routing instruction; the reader decides whether to follow it from the pointer +text alone, without opening the target. + +- **Front-load the leading word.** Open with the term the reader is matching on ("Deploys: + see…", never "See the following doc for information about deploys"). +- **Cover the branches.** State when to follow it AND what the reader gets ("for tracked-changes + output specifically, read X"), so both the follow and the skip are informed decisions. +- A pointer that exists only because changes must be mirrored across distant folders can mask a + cohesion problem — `claude-memory:audit`'s navigation-pointer remediation guidance (if that + plugin is installed) owns the restructure-before-pointer call; consider it before adding the + pointer. + +The full pointer-quality criteria live in `audit-progressive-disclosure`'s tier model +([`../audit-progressive-disclosure/context/tier-model.md`](../audit-progressive-disclosure/context/tier-model.md)) +— write to them now rather than failing them at audit time. + +## Separate steps from reference, and co-locate what runs together + +Steps are read in order and executed; reference is jumped into and queried. Mixing them makes +both worse — a procedure interrupted by lookup tables loses its thread, and reference buried in +a procedure is unfindable. + +- Put the procedure in one contiguous block; move lookup material below it or into a spoke file + with a conditioned pointer. +- Co-locate what is consumed together: the fact a step depends on belongs beside the step, not + three sections away. Distance a reader must jump during execution is a defect. +- Sprawl is the failure of both: when a file serves several audiences or moments, split it along + who-reads-when lines, not topic lines. + +## Give every step a completion criterion + +A step is done when its criterion says so — not when text resembling the step has been produced. + +- **Clarity and demand.** State what "done" observably is, and demand it: "run X; the step is + complete when Y appears" beats "run X". +- **Premature completion** is the shape to design against: a step satisfiable before its + goal-state is reached will be marked complete at first plausible output. Make the criterion + the goal-state, never the attempt. +- **Post-completion steps.** When finishing creates an obligation (regenerate, notify, clean + up), state it in the step — an obligation after "done" is otherwise dropped. +- **The agent does the legwork.** Write steps that resolve their own facts from the environment; + a step that sends the human to look something up the agent could read is a defect. + +## Split by sequence; choose invocation by the rubric + +When one doc serves two moments in time, split it at the moment boundary — the reader at step +one should not scroll past material for step nine. Splitting an instruction surface into skills +with different invocation modes is a different axis with its own decision rubric: follow the +[invocation-mode rubric](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/invocation-mode/README.md) +(§ Splitting by invocation) rather than deciding it ad hoc. + +## Prompt the positive + +Write what to do, not what to avoid: a prohibition drags the banned behavior into context, and +pretrained leading words are the compact anchors that steer ("Prefer X" over "Never do Y unless"). +Keep a negation only when the positive form genuinely loses the constraint — then pair it with +the positive alternative in the same sentence. + +## After writing + +- Repeated the same prose a third time? Route to `extract-ssot`. +- Resolved or coined a domain term? Route to `domain-driven-design:curate-language` (if + installed) — never hand-write a glossary entry. +- Editing exposed pre-existing problems in the surrounding doc? Route to the audit siblings + (`audit-noise`, `audit-derivability`, `audit-progressive-disclosure`) rather than expanding + this write into an audit. + +## What this skill does NOT do + +- **Does not author skills** — a SKILL.md is `playbooks:skill-authoring` + `skill-quality:check` + territory; this skill's doctrine reaches skill authors through those surfaces. +- **Does not audit existing docs** — the audit siblings own read-only findings; this skill fires + at the writing moment only. +- **Does not write human-facing docs** — end-user READMEs, changelogs, and marketing prose have + a different reader and different rules. +- **Does not enforce via hooks** — trigger reliability is carried by this skill's description + and its eval suite, deliberately not by a forcing hook. diff --git a/plugins/docs-hygiene/skills/write-for-agents/evals/evals.json b/plugins/docs-hygiene/skills/write-for-agents/evals/evals.json new file mode 100644 index 000000000..068d4207d --- /dev/null +++ b/plugins/docs-hygiene/skills/write-for-agents/evals/evals.json @@ -0,0 +1,98 @@ +{ + "skill_name": "write-for-agents", + "evals": [ + { + "id": 1, + "name": "trigger-claude-md-section", + "prompt": "Add a section to our CLAUDE.md that tells the agent how to run the test suite.", + "expected_output": "The write-for-agents skill is invoked before or while drafting. The produced section follows its doctrine: positive-form instructions, steps carrying observable completion criteria (e.g. the command plus what output means done), no blind pointers.", + "expectations": [ + "The write-for-agents skill is invoked (its doctrine is applied at the writing moment)", + "Steps in the drafted section carry observable completion criteria, not bare commands", + "Instructions are phrased positively (what to do), with at most justified paired negations" + ] + }, + { + "id": 2, + "name": "trigger-rules-file", + "prompt": "Write a .claude/rules file capturing our API error-handling conventions.", + "expected_output": "The write-for-agents skill is invoked. The rule file is written for its load tier (session-start unless paths-scoped), separates any procedure from reference material, and phrases conventions positively.", + "expectations": [ + "The write-for-agents skill is invoked", + "The draft accounts for the rules-file load semantics (always-loaded vs paths:-gated) when scoping content" + ] + }, + { + "id": 3, + "name": "trigger-pointer-line", + "prompt": "Add a navigation pointer in CLAUDE.md to our deploy runbook.", + "expected_output": "The write-for-agents skill is invoked. The pointer front-loads the leading word (e.g. 'Deploys: ...'), states when to follow it and what the reader gets — not a bare 'See docs/deploy.md'.", + "expectations": [ + "The write-for-agents skill is invoked", + "The produced pointer front-loads its leading word and carries a when-to-follow condition (no blind pointer)" + ] + }, + { + "id": 4, + "name": "trigger-doc-plus-pointer-extraction", + "prompt": "This CLAUDE.md section on database migrations is getting long — move it into a doc the agent can load when it needs it, and leave something behind so it can find it.", + "expected_output": "The write-for-agents skill is invoked. The extraction produces a spoke doc plus a conditioned pointer in CLAUDE.md (leading word front-loaded, when-to-read stated); the always-loaded surface sheds the moved lines.", + "expectations": [ + "The write-for-agents skill is invoked", + "The extraction leaves a conditioned pointer, not a bare reference", + "The response accounts for the load-tier change (always-loaded line count drops; spoke loads on demand)" + ] + }, + { + "id": 5, + "name": "trigger-agent-context-doc", + "prompt": "Write up the auth-flow context doc that our subagents will read before touching the login code.", + "expected_output": "The write-for-agents skill is invoked; the doc separates steps from reference, co-locates facts beside the steps that need them, and states completion criteria for any procedure it contains.", + "expectations": [ + "The write-for-agents skill is invoked", + "Steps and reference material are structurally separated in the produced doc" + ] + }, + { + "id": 6, + "name": "negative-audit-request", + "prompt": "Audit our CLAUDE.md for stale instructions and noise.", + "expected_output": "The write-for-agents skill is NOT invoked. The request routes to audit-shaped surfaces (docs-hygiene audit skills or claude-memory/claude-config audits) — this is a read-only findings request, not a writing moment.", + "expectations": [ + "The write-for-agents skill is NOT invoked", + "An audit-shaped skill or workflow handles the request" + ] + }, + { + "id": 7, + "name": "negative-skill-authoring", + "prompt": "Create a skill that formats SQL files on save.", + "expected_output": "The write-for-agents skill is NOT invoked. Skill authoring routes to playbooks:skill-authoring / skill-quality:check territory per the route-away fence.", + "expectations": [ + "The write-for-agents skill is NOT invoked", + "The skill-authoring surfaces are engaged or named instead" + ] + }, + { + "id": 8, + "name": "negative-human-readme", + "prompt": "Write a quickstart README for end users installing our CLI from npm.", + "expected_output": "The write-for-agents skill is NOT invoked — human-facing docs are out of its scope; the README is written for people without the agent-doc doctrine's machinery.", + "expectations": [ + "The write-for-agents skill is NOT invoked" + ] + }, + { + "id": 9, + "name": "behavior-doctrine-applied-to-draft", + "prompt": "Improve evals/fixtures/draft-rule.md (relative to the skill directory) as an agent-consumed rule file, applying the write-for-agents doctrine.", + "expected_output": "The rewrite: flips the two bare prohibitions into positive-form instructions (keeping at most a justified paired negation), replaces 'See the migrations doc' with a conditioned front-loaded pointer or removes it, and rewrites the three steps with observable completion criteria — in particular step 3's 'Done when it works' becomes a goal-state test, and any post-completion obligation is stated on its step.", + "files": ["evals/fixtures/draft-rule.md"], + "expectations": [ + "Prohibitions are rewritten in positive form", + "The blind pointer gains a when-to-follow condition and front-loaded leading word, or is removed as unroutable", + "Each step carries an observable completion criterion; 'works' is replaced by a goal-state test" + ] + } + ] +} diff --git a/plugins/docs-hygiene/skills/write-for-agents/evals/fixtures/draft-rule.md b/plugins/docs-hygiene/skills/write-for-agents/evals/fixtures/draft-rule.md new file mode 100644 index 000000000..286d952a9 --- /dev/null +++ b/plugins/docs-hygiene/skills/write-for-agents/evals/fixtures/draft-rule.md @@ -0,0 +1,11 @@ +# Database migrations + +Don't use raw SQL in migrations. Don't forget about the tenant partition key. + +See the migrations doc. + +Steps: + +1. Make a migration. +2. Check it. +3. Done when it works. diff --git a/plugins/docs-hygiene/skills/write-for-agents/reference/agent-doc-surfaces.md b/plugins/docs-hygiene/skills/write-for-agents/reference/agent-doc-surfaces.md new file mode 100644 index 000000000..12c937a59 --- /dev/null +++ b/plugins/docs-hygiene/skills/write-for-agents/reference/agent-doc-surfaces.md @@ -0,0 +1,64 @@ +# Agent-consumed surfaces — what loads, when, and how much + +Read this when deciding how a file you are writing will actually reach an agent: whether it +auto-loads, at what moment, and under what size behavior. Write differently for an always-loaded +surface (every line is a per-session tax) than for an on-demand one (cost only when the trigger +fires). + +Claude Code rows verified against official docs current at v2.1.233 (2026-08-17). The harness +releases frequently — when a load-timing detail is load-bearing for your write, re-verify it +against before relying on it. + +## Claude Code surfaces + +| Surface | Path pattern | When it loads | +|---------|-------------|---------------| +| Managed-policy CLAUDE.md / `claudeMd` key | OS-specific managed dirs | Session start, before all other scopes; cannot be excluded | +| User CLAUDE.md | `~/.claude/CLAUDE.md` | Session start, full | +| Project CLAUDE.md | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Session start; re-injected after `/compact` | +| CLAUDE.local.md | `./CLAUDE.local.md` (also beside ancestor CLAUDE.md) | Session start, after same-level CLAUDE.md | +| Ancestor CLAUDE.md | every dir from filesystem root down to cwd | Session start, root→cwd; excludable via `claudeMdExcludes` | +| Nested/subdirectory CLAUDE.md | `/CLAUDE.md` below cwd | ON-DEMAND when the agent reads files there; NOT re-injected after `/compact` until the next matching read | +| Project rules | `.claude/rules/**/*.md` | No `paths:` frontmatter → session start; with `paths:` globs → on-demand on matching file read | +| User rules | `~/.claude/rules/*.md` | Session start, before project rules (lower priority) | +| `@` imports | `@path` inside CLAUDE.md/rules; max 4 hops; skipped in code spans/fences | Expanded at launch with the importing file — an import does NOT reduce context vs inlining | +| AGENTS.md | not read natively | Only via `@AGENTS.md` import, symlink, `/init`, or `/import` | +| Auto-memory index | `~/.claude/projects//memory/MEMORY.md` | Session start: first 200 lines or 25KB, whichever first | +| Auto-memory topic files | same dir, `*.md` | On-demand only | +| Skills | `.claude/skills/`, `~/.claude/skills/`, plugin `skills/` | Listing metadata (description) in context every turn; body on invocation or model trigger | +| Commands (legacy) | `.claude/commands/`, `~/.claude/commands/` | On invocation; merged into the skills mechanism | +| Subagent definitions | `.claude/agents/`, `~/.claude/agents/`, plugin `agents/` | Body becomes the subagent's system prompt at spawn; description read at delegation time | +| Subagent persistent memory | `agent-memory//` | First 200 lines/25KB of that agent's MEMORY.md at its spawn | +| Output styles | `output-styles/` (user/project/managed/plugin) | Session start when selected; modifies the system prompt | +| Workflows | `.claude/workflows/`, plugin `workflows/` | Startup; each file becomes a command | +| Hook-carried instruction text | hooks in settings/plugins/frontmatter | On lifecycle events; `additionalContext` capped at 10,000 chars | + +Load-semantics facts that change how you write: + +- Scope order is managed → user → project → local; the more specific scope lands later in + context. +- Nested CLAUDE.md and `paths:`-gated rules do NOT survive `/compact` re-injection — a + constraint that must hold post-compaction belongs on a surface that does. +- Block-level HTML comments in CLAUDE.md are stripped before injection — free maintainer notes. +- MEMORY.md hard-truncates (200 lines / 25KB); CLAUDE.md never truncates — official guidance is + <200 lines per CLAUDE.md anyway. +- These surfaces are context, not enforcement — a rule that must be mechanically guaranteed + belongs in a hook or permission policy, not prose. + +## Other-ecosystem analogues + +For repos whose docs serve multiple agent harnesses. Names and auto-read semantics only; +verify a vendor's current behavior before relying on details. + +| Convention | File(s) | Auto-read | +|---|---|---| +| AGENTS.md open standard | `AGENTS.md` root + nested (nearest wins) | Native in Codex, Cursor, Copilot agent, Gemini CLI (config), Windsurf, Zed, Roo — not Claude Code | +| Agent Skills standard (agentskills.io) | `/SKILL.md` folders | Metadata-first progressive disclosure; discovery dirs per agent — `.agents/skills/` + `~/.agents/skills/` is the shared cross-tool convention (Codex CLI, Cursor, Gemini CLI, VS Code Copilot, Zed); Claude Code uses its own `.claude/skills/` paths | +| Cursor rules | `.cursor/rules/*.mdc`; legacy `.cursorrules` | Per-rule types: Always / Auto Attached (globs) / Agent Requested / Manual | +| GitHub Copilot | `.github/copilot-instructions.md`; `.github/instructions/**.instructions.md` (`applyTo:` globs) | Auto-added to matching requests | +| Gemini CLI | `GEMINI.md` hierarchy + `~/.gemini/GEMINI.md` | Concatenated into every prompt | +| Windsurf | `.windsurf/rules/` (or `.devin/`); `global_rules.md` | Per-rule trigger modes | +| Cline / Roo | `.clinerules` file-or-folder / `.roo/rules/` | Appended to system prompt; workspace wins | +| Aider | `CONVENTIONS.md` | NOT auto-read — explicit `/read` / config only | +| JetBrains Junie | `.junie/guidelines.md` | Auto-read during generation | +| Amazon Q | `.amazonq/rules/*.md` | Auto-loaded on first interaction | From 71e44ca95c61812263aff69d0d5abeec7d84dec0 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 04:32:23 +0000 Subject: [PATCH 2/5] =?UTF-8?q?fix(docs-hygiene):=20write-for-agents=20rev?= =?UTF-8?q?iew=20round=20=E2=80=94=20real=20pointer=20targets,=20contract-?= =?UTF-8?q?clean=20links,=20add-dir=20row?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses the automated review findings on #3003: the restructure-before-pointer caveat is stated inline (its claude-memory home is #2987's unbuilt deliverable — a pointer to nothing, caught by review; #2987 may convert this to a pointer when it lands); the sibling tier-model link is replaced with the slash-only public-surface form per the encapsulation contract; operative handoffs use the explicit Skill-tool invocation phrasing the invocation-mode convention binds new skill text to; the reference table regains the conditional --add-dir load row dropped in trimming. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01QbfCrj3X9FfGL7VRZYmrn4 --- .../skills/write-for-agents/SKILL.md | 24 +++++++++---------- .../reference/agent-doc-surfaces.md | 1 + 2 files changed, 13 insertions(+), 12 deletions(-) diff --git a/plugins/docs-hygiene/skills/write-for-agents/SKILL.md b/plugins/docs-hygiene/skills/write-for-agents/SKILL.md index b8191b640..5be9de034 100644 --- a/plugins/docs-hygiene/skills/write-for-agents/SKILL.md +++ b/plugins/docs-hygiene/skills/write-for-agents/SKILL.md @@ -43,13 +43,13 @@ text alone, without opening the target. - **Cover the branches.** State when to follow it AND what the reader gets ("for tracked-changes output specifically, read X"), so both the follow and the skip are informed decisions. - A pointer that exists only because changes must be mirrored across distant folders can mask a - cohesion problem — `claude-memory:audit`'s navigation-pointer remediation guidance (if that - plugin is installed) owns the restructure-before-pointer call; consider it before adding the - pointer. + cohesion problem. Before adding it, consider restructuring so the things that change together + live together — a pointer papering over low cohesion outlives the reorganization that would + have removed it. -The full pointer-quality criteria live in `audit-progressive-disclosure`'s tier model -([`../audit-progressive-disclosure/context/tier-model.md`](../audit-progressive-disclosure/context/tier-model.md)) -— write to them now rather than failing them at audit time. +The full pointer-quality criteria are owned by the sibling audit skill — invoke +`/docs-hygiene:audit-progressive-disclosure` via the Skill tool to grade a draft against them, +rather than failing them at audit time. ## Separate steps from reference, and co-locate what runs together @@ -95,12 +95,12 @@ the positive alternative in the same sentence. ## After writing -- Repeated the same prose a third time? Route to `extract-ssot`. -- Resolved or coined a domain term? Route to `domain-driven-design:curate-language` (if - installed) — never hand-write a glossary entry. -- Editing exposed pre-existing problems in the surrounding doc? Route to the audit siblings - (`audit-noise`, `audit-derivability`, `audit-progressive-disclosure`) rather than expanding - this write into an audit. +- Repeated the same prose a third time? Invoke `/docs-hygiene:extract-ssot` via the Skill tool. +- Resolved or coined a domain term? Invoke `/domain-driven-design:curate-language` via the + Skill tool (if that plugin is installed) — never hand-write a glossary entry. +- Editing exposed pre-existing problems in the surrounding doc? Invoke the fitting audit + sibling via the Skill tool (`/docs-hygiene:audit-noise`, `/docs-hygiene:audit-derivability`, + `/docs-hygiene:audit-progressive-disclosure`) rather than expanding this write into an audit. ## What this skill does NOT do diff --git a/plugins/docs-hygiene/skills/write-for-agents/reference/agent-doc-surfaces.md b/plugins/docs-hygiene/skills/write-for-agents/reference/agent-doc-surfaces.md index 12c937a59..8d013a9ac 100644 --- a/plugins/docs-hygiene/skills/write-for-agents/reference/agent-doc-surfaces.md +++ b/plugins/docs-hygiene/skills/write-for-agents/reference/agent-doc-surfaces.md @@ -21,6 +21,7 @@ against before relying on it. | Nested/subdirectory CLAUDE.md | `/CLAUDE.md` below cwd | ON-DEMAND when the agent reads files there; NOT re-injected after `/compact` until the next matching read | | Project rules | `.claude/rules/**/*.md` | No `paths:` frontmatter → session start; with `paths:` globs → on-demand on matching file read | | User rules | `~/.claude/rules/*.md` | Session start, before project rules (lower priority) | +| `--add-dir` CLAUDE.md/rules | `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md`, `CLAUDE.local.md` in each added directory | Session start, ONLY when `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`; off by default — otherwise these files do not load at all | | `@` imports | `@path` inside CLAUDE.md/rules; max 4 hops; skipped in code spans/fences | Expanded at launch with the importing file — an import does NOT reduce context vs inlining | | AGENTS.md | not read natively | Only via `@AGENTS.md` import, symlink, `/init`, or `/import` | | Auto-memory index | `~/.claude/projects//memory/MEMORY.md` | Session start: first 200 lines or 25KB, whichever first | From 30e233dd3e5befca33ee8a4d7b22f72d3a88f03e Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 04:35:31 +0000 Subject: [PATCH 3/5] docs(docs-hygiene): align 0.17.0 changelog with the review-round skill body The entry still described the removed claude-memory:audit pointer; it now matches the shipped skill (caveat stated inline pending #2987). Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01QbfCrj3X9FfGL7VRZYmrn4 --- plugins/docs-hygiene/CHANGELOG.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/plugins/docs-hygiene/CHANGELOG.md b/plugins/docs-hygiene/CHANGELOG.md index 8d9afabf8..1898aedc9 100644 --- a/plugins/docs-hygiene/CHANGELOG.md +++ b/plugins/docs-hygiene/CHANGELOG.md @@ -12,8 +12,9 @@ steps-vs-reference separation with co-location, observable completion criteria with premature-completion/post-completion/legwork guards, split-by-sequence, positive-form prompting) and points at the audit siblings, the invocation-mode - rubric, `claude-memory:audit`'s navigation-pointer remediation, and - `curate-language` rather than restating them. Ships `reference/agent-doc-surfaces.md` + rubric, and `curate-language` rather than restating them; the + restructure-before-pointer caveat is stated inline pending its audit-side home + (#2987). Ships `reference/agent-doc-surfaces.md` (docs-verified auto-read surface table, Claude Code v2.1.233 baseline, plus other-ecosystem analogues) and a 9-case eval suite gating trigger reliability (5 positive writing-moment cases, 3 negative route-away controls, 1 doctrine From 19b1dd22b1b806849e21fda00005c2d5c453a395 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 04:43:46 +0000 Subject: [PATCH 4/5] docs: regenerate CATALOG.md for the docs-hygiene 0.17.0 description plugin-gate caught the stale generated catalog block after the write-for-agents manifest description change; regenerated via scripts/generate-catalog.mjs. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01QbfCrj3X9FfGL7VRZYmrn4 --- docs/CATALOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/CATALOG.md b/docs/CATALOG.md index ddc8455ac..2eaee9099 100644 --- a/docs/CATALOG.md +++ b/docs/CATALOG.md @@ -67,7 +67,7 @@ plugin manifests and kept in sync by CI — never hand-edit it; the category voc - [`bug-report`](../plugins/bug-report) — Produces a structured five-field bug report — title, steps to reproduce, expected vs actual, severity with justification, and suggested fix location — from an informal defect description. Read-only by default: it emits the report and never edits code, opens a PR, or files an issue on its own. - [`debugging`](../plugins/debugging) — Debug observed failures via a disciplined six-phase loop: build a fast deterministic reproduction signal, reproduce, rank falsifiable hypotheses, instrument, fix with a regression test, then clean up and post-mortem. -- [`docs-hygiene`](../plugins/docs-hygiene) — Documentation-hygiene toolkit: compress (flavor-trim markdown with a semantic-diff safety net), audit-noise (classify markdown noise), extract-ssot (deduplicate repeated content into a single source of truth), audit-encapsulation (detect citations into skill-private surfaces), rename-references (sweep stale references after renames), audit-derivability (classify whether a whole document earns its existence — could a fresh agent re-derive it from the code?), and audit-progressive-disclosure (grade instruction files against a load-tier model for split opportunities and hub/spoke disclosure defects). +- [`docs-hygiene`](../plugins/docs-hygiene) — Documentation-hygiene toolkit: compress (flavor-trim markdown with a semantic-diff safety net), audit-noise (classify markdown noise), extract-ssot (deduplicate repeated content into a single source of truth), audit-encapsulation (detect citations into skill-private surfaces), rename-references (sweep stale references after renames), audit-derivability (classify whether a whole document earns its existence — could a fresh agent re-derive it from the code?), audit-progressive-disclosure (grade instruction files against a load-tier model for split opportunities and hub/spoke disclosure defects), and write-for-agents (authoring-time doctrine that fires while agent-consumed markdown is being written). - [`code-tidying`](../plugins/code-tidying) — Code tidying and comment hygiene: /code-tidying:tidy proactively hunts a rotated, glob-scoped lane for Beck-style tidyings under a research-backed scope budget and ships one tight PR; /code-tidying:batch-simplify sweeps recently changed files through grouped, dependency-ordered simplification waves with a never-drop deferred-items contract; /code-tidying:dissolve-comments enforces self-describing expressive code over a diff — deletes zero-information comments, dissolves code-expressible ones into names and structure behind a tests gate (safe mode restricts applied edits to removals), and keeps only terse load-bearing comments code cannot express; /code-tidying:audit-comment-residue is a read-only classifier that flags history, plan, conversational, and ticket/PR residue in code comments for author-applied deletion. Project-specific tidy lanes are scaffolded into a tracked .claude/tidy-lanes/ config folder by a re-runnable setup skill. - [`coupling`](../plugins/coupling) — Iteratively reduces coupling in any repository at any altitude — documents, code modules, applications, or repositories: scans for change-transmitting dependencies typed against a coupling model (strength ladder, connascence, volatility weighting), verifies every finding, applies a budgeted batch of safe behavior-preserving reductions, and keeps a durable ledger so structural candidates route to design lanes and repeated runs continue where the last stopped. - [`repo-hygiene`](../plugins/repo-hygiene) — Repo hygiene action-router: /repo-hygiene:clean sweeps reclaimable caches, build artifacts, and stale git metadata, and can realign the working tree to a fresh-pull state — dry-run-first, with destructive tiers gated behind explicit confirmation and a session-scoped destructive-command guard. Ecosystem targets are detected at runtime; secrets, runtime dependencies, and skill data are preserved by default. From e0d767fe6ac0b3183251b5597c869c2c2f1cb4b7 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 04:51:46 +0000 Subject: [PATCH 5/5] docs: regenerate SKILL-CHEAT-SHEET.md for write-for-agents Second generated surface behind plugin-gate; the third (identity-prerequisites) verified in sync, and validate-plugins.sh now passes locally end to end. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01QbfCrj3X9FfGL7VRZYmrn4 --- docs/SKILL-CHEAT-SHEET.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/SKILL-CHEAT-SHEET.md b/docs/SKILL-CHEAT-SHEET.md index 21ee7d02b..a34da91fe 100644 --- a/docs/SKILL-CHEAT-SHEET.md +++ b/docs/SKILL-CHEAT-SHEET.md @@ -184,6 +184,7 @@ owned by [docs/CATALOG-TAXONOMY.md](CATALOG-TAXONOMY.md). | [`/docs-hygiene:compress`](../plugins/docs-hygiene/skills/compress/SKILL.md) | `docs-hygiene` | Tighten markdown by dropping flavor while preserving every directive | | [`/docs-hygiene:extract-ssot`](../plugins/docs-hygiene/skills/extract-ssot/SKILL.md) | `docs-hygiene` | Deduplicate repeated prose into one named source of truth | | [`/docs-hygiene:rename-references`](../plugins/docs-hygiene/skills/rename-references/SKILL.md) | `docs-hygiene` | Sweep stale references after renames, including forms grep misses | +| [`/docs-hygiene:write-for-agents`](../plugins/docs-hygiene/skills/write-for-agents/SKILL.md) | `docs-hygiene` | Authoring-time doctrine for agent-consumed markdown | | [`/education:explain`](../plugins/education/skills/explain/SKILL.md) | `education` | Explain any concept or the last response in genuinely plain words | | [`/education:quiz-me`](../plugins/education/skills/quiz-me/SKILL.md) | `education` | Generate a post-change report with a quiz verifying you absorbed the work | | [`/education:teach`](../plugins/education/skills/teach/SKILL.md) | `education` | Multi-session learning coach for general topics or repo-grounded concepts |