Writing docs

Skill aj604/toolshed/plugins/doc-lifecycle/skills/writing-docs

Reference docs as checkable claims — a Claude Code plugin for the documentation lifecycle: bootstrap → write → detect drift → fix.

Install

npx -y skills add aj604/toolshed --skill writing-docs

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use when writing or editing a documentation file whose job is to track the repo — README, runbook, CLAUDE.md/AGENTS.md, reference (including the claim-style docs/reference/architecture.md that bootstrapping-docs prescribes), or agent-facing context pack — including converting human or marketing docs into dense agent-facing form, or when tempted to add example output, install steps, or "why" prose. The one door for these repo-tracking docs, across human and agent readers (token bloat, context rot). Out of scope: tutorials, narrative architecture/conceptual overviews and design rationale, and decision records (ADRs) — narrative by design, not line-by-line claims about the repo (growing-docs creates those when demand justifies it). To create a baseline doc set from scratch for an undocumented repo, start with bootstrapping-docs; it routes here for each doc.

SKILL.md

7.5 KB, as published. Nobody here has run it

Writing Docs

Overview

A doc whose job is to track the repo is a set of claims that must be true of the repo. This is the spine: when any guideline conflicts with verifiability, verifiability wins. A smaller all-true doc beats a complete one with unverifiable parts.

Every line is one of two kinds of claim:

Verifiable claim — commands, paths, symbols, behavior (output included), structure, values. Must be mechanically checkable against the repo as it is now.
Rationale claim — the "why", tradeoffs, rejected alternatives. Allowed, but only in a marked section and anchored to a file:line, commit, or date.

If a line is neither, cut it.

Scope: as in the frontmatter above — README/runbook/CLAUDE.md/AGENTS.md/reference (incl. claim-style docs/reference/architecture.md); not a universal theory of documentation — tutorials/narrative-architecture/ADRs stay narrative (growing-docs), never claim-audited.

The rules (these address what agents get wrong)

Strong agents already read package.json and get commands and flags right. They fail on the subtler things below. Spend your discipline here.

1. Example output is a claim — run it or omit it

Never invent illustrative numbers, sample output, or "looks-right" results. Output you didn't produce is a fabricated claim, even when it's "just an example."

Run the command, paste the real output.
If output is environment-dependent (byte sizes, timestamps, hashes), say so instead of pinning a fragile exact value.
Can't run it? Don't show output.

2. Rationale must be marked and anchored

Do not weave the "why" into prose as timeless fact. Put it in a marked section and anchor it: > **Why (as of bin/cli.js:34):** reads the whole buffer because gzip ratio…. Unanchored rationale can't be audited for relevance and will rot silently.

3. No aspirational claims

Document the repo as it is, not as you assume it will be. No npm install <pkg> for an unpublished package, no "supports X" for unbuilt features. If a claim isn't true yet, omit it or mark it explicitly as not-yet-true.

4. Cut what the reader can already infer

Apply the test: would removing this line cause the reader to make a mistake? If not, cut it. Don't restate what the code, types, or git history plainly show. This bites hardest in agent docs (see agent-context.md).

5. Document-at-all counter-test

Before writing a doc, ask: does the code, a type signature, or git history already say this? If yes, link to it; don't duplicate it into a doc that will drift. The counter-test cuts duplication, not demand: a fact derived the hard way twice — by anyone, across sessions — has falsified "cheaply inferable"; that's a growth signal, see growing-docs.

Where a doc lives (reader + moment of need)

Reader, at this moment	Artifact	Guide
Newcomer evaluating / setting up	README	readme.md
On-call mid-incident, under pressure	runbook	runbooks.md
AI agent starting a session in the repo	CLAUDE.md / AGENTS.md	agent-context.md
Agent reading on demand in a multi-unit repo	`docs/reference/` tree (architecture.md, per-unit overview.md)	bootstrapping-docs' repo-shape.md (shape + routing)
Reader needing breadth/why — walkthrough, ADR, conceptual overview	durable narrative doc, also under `docs/reference/` (out of this skill's scope)	growing-docs (template + `> As of` anchor)

One bar, every reader — then route

The contract above governs every repo-tracking doc (see Scope); verifiability never bends. Audience and job size decide only how dense and who writes it — never whether it's true. This is the one door for repo-tracking doc writing: don't go looking for a second skill. Two questions, answered once:

1. Who reads it?

Human (README, runbook, guide): orient first, skimmable, some warmth OK.
Agent (CLAUDE.md/AGENTS.md, context pack): density is mandatory, not optional. Maximum signal-per-token, pointers over inline copies, no narrative. The reader can read the repo on demand — spend tokens only on what it can't reconstruct. This is Rule 4 at full strength: an agent doc that "reads fine" but restates inferable facts has failed, even if every line is true.

2. Can you verify it without leaving your current context?

Yes — a self-contained edit (a line or a short section whose claims you can check from what's already in front of you) → write it inline, applying the bar.
No — you'd have to read code or run commands to verify the claims, or it's more than a few lines → dispatch, so that exploration stays out of your context:
- human-facing → dispatch a general-purpose subagent whose prompt gives the path to this SKILL.md and instructs it to read and apply it, plus the same three inputs the llm-doc-writer branch passes: what to write from, the repo path, and the output path.
- agent-facing → the llm-doc-writer agent — it owns the densify+verify method and runs in its own context. Pass it: what to write from (source path, raw content, or topic + findings), the repo path (puts it in verify mode — anchors every claim to file:line, runs safe commands), and the output path. A one-line agent-doc tweak isn't worth a dispatch — apply the density rule inline.

Do not stop at the first thing that feels sufficient. If the reader is an agent, the density pass — inline or via llm-doc-writer — is part of this job, not a separate skill you may skip.

Red flags — STOP

About to type example output you didn't run → run it or delete it.
Writing "because…" / "the reason is…" in body prose → move to a marked, anchored section.
npm install <thing>, "just run X" you haven't confirmed exists → verify or cut.
A sentence the reader could get from reading one obvious file → cut it.
Reader is an agent and you wrote it like a human doc (narrative, restated-inferable facts) → the density pass is owed; it is not optional.
Agent doc that's a whole-doc or needs verification, and you didn't dispatch llm-doc-writer → you skipped the specialist that enforces density+anchoring in its own context.
"This skill covers it, I'll just start" on an agent doc → you still owe the density half.

Reference files

readme.md — README structure, coverage checklist, one verified example, failure modes.
runbooks.md — runbook structure for 3am usability; copy-pasteable steps, real output.
agent-context.md — CLAUDE.md/AGENTS.md; the cut-test, pointers-over-inline, when to dispatch the llm-doc-writer agent.