A second, optional skill for how to write the documents

Context¶

The packaged guide teaches an agent to drive docir — the commands, the schema, the read/write loop. Nothing taught it what to put in a document, so the corpus quality rested on whatever the agent already believed about documentation.

docir lint --deep does check two of the properties that matter: near-duplicate documents (cosine ≥ 0.9, unlinked) and oversized ones (8,000 characters). But a check is a verifier, not a teacher. An agent that never learned the rule produces the finding every time and learns it only by being corrected — which is the expensive order, and only works when a human reads the output.

Two more properties nothing measures at all: whether the corpus names one concept one way, and whether a document does one job. Both are cheap to follow while writing and expensive to repair afterwards, because repairing them means splitting documents and rewriting every reference.

Decision¶

Ship the rules as a second, opt-in skill: target claude-writing → .claude/skills/docir-writing/SKILL.md, from its own packaged template writing.md. TemplateProvider becomes a keyed catalogue (template(name)) and AgentTarget names its template, so a skill is a catalogue entry plus a file rather than a branch in the renderer.

Separate, not a section of the guide. The two are read at different moments — one when driving the CLI, one when composing prose — and a skill is loaded by its description, so merging them means every session that touches docir at all loads both. That is also the rule the new skill teaches, applied to itself.

Opt-in. It is absent from DEFAULT_AGENTS; both skills match the same work, so a repo that did not ask for the second one should not pay its context. The AGENTS.md index lists it once installed but never drags it in — which is why points_to stayed the pointer's floor rather than becoming its full contents.

The rules, and what backs them¶

Four rules, three of them well supported and one deliberately reshaped.

One name per concept and state each fact once are standard: style guides put terminology consistency first, and single-sourcing exists precisely because the second copy is the one that goes stale. docir's own answer to the second is a typed related edge, which is why the skill teaches linking rather than quoting.

One purpose per document is topic-based authoring's "one topic, one idea" and Diátaxis's "do not mix the four modes". docir already encodes it: a document's type declares its purpose, so the rule reads as write what the type says rather than as an abstraction.

Length is the reshaped one. A round "under 1,000 words" has no support — the topic-based standards say explicitly that a topic runs as long as its subject requires, and that chunking follows content rather than word counts. What docir does have is a measured number in the other direction: MAX_CHUNK_CHARS is 1,200 because the embedding model reads ~1,900 characters (adr-927aa43d9635), so a longer ## section is split mid-paragraph and retrieves worse. The rule is therefore a section limit, which is real, plus "bound the document by its purpose, not by counting", which is rule 2 doing the work.

Consequences¶

• The rules exist in two tiers on purpose: the skill prevents, docir check and docir lint --deep detect. The overlap with the existing lint checks is the design, not redundancy — a finding should be a rule the writer already knew.
• Chosen cost: a repo that installs both skills loads both descriptions in every session. That is the price of keeping each one single-purpose, and the reason the second is opt-in rather than default.
• The catalogue makes a third skill cheap — a template plus a target entry — so the pressure to grow one skill into a grab-bag is gone.
• Scoped out: making any of these machine-checked. Terminology drift and purpose-mixing are judgement calls, and a Tier 1 error on either would fail builds over prose (the argument the staleness and schema-drift rules already make). If they ever land, they land as Tier 2 advisories.