mcpField
W
write-docs

write-docs

github.com/wilbeibiDevelopment238 installsUpdated 2d ago
Repository

About write-docs

write-docs is a documentation-writing skill for developers and maintainers. It helps select the right conventions for a specific artifact, then draft and check it against the intended reader and source facts.

Key features

  1. 01Selects guidance by document type
  2. 02Tailors writing to the intended reader
  3. 03Provides strict and natural clarity modes
  4. 04Checks drafts against source facts
  5. 05Includes review and rewrite guidance

Use cases

  1. 01Writing a public library README
  2. 02Preparing a developer guide or runbook
  3. 03Documenting CLI flags and output
  4. 04Reviewing or revising existing documentation

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/wilbeibi/wilbeibi-skills --skill write-docs

After installing, type/write-docsin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

AGENTSMD-REFERENCE.md
AGENTSMD.md
CLARITY-REFERENCE.md
CLI.md
COMMENTS.md
GUIDES.md
PR.md
READMES-REFERENCE.md
READMES.md
scripts/
prose_lint.py
test_prose_lint.py

Details

From the project README

write-docs

Pick the artifact, read that file, then write. Do not load more than one — the conventions differ and mixing them produces documents that serve nobody.

Writing…ReadReader you are serving
A README for a public lib, CLI, or agent toolREADMES.mdsomeone deciding in 30 seconds whether to use this
A developer guide, tutorial, runbook, migration, or deprecationGUIDES.mdsomeone trying to complete a task without guessing
CLI flags, subcommands, --help, error text, output contractsCLI.mdsomeone typing at a prompt, and the script that wraps them
Code comments, docstrings, inline rationaleCOMMENTS.mdthe maintainer reading this during an outage
AGENTS.md / CLAUDE.md operating guidesAGENTSMD.mdan agent with no memory of your project
Commit messages, PR descriptions, changelog entriesPR.mda maintainer running git log in two years

Not this skill: blog posts and essays (use blog-review), design docs, ADRs (use grill-me), internal service wikis, or authoring a skill (use write-skill).

Workflow

  1. Read the implementation, schema, tests, --help, or diff that establishes the facts.
  2. Name the reader and the action this document must enable.
  3. Choose one canonical term for each repeated concept. Preserve exact API names and identifiers.
  4. Draft through the selected artifact lens.
  5. Check that every claim, command, caveat, and boundary still matches the source.
  6. Apply the clarity mode below, then run the checker. Treat heuristic findings as questions, not automatic edits.

Clarity modes

  • Strict — procedures, safety rules, agent workflows, CLI help, and recovery instructions. Also any text whose reader cannot ask a follow-up question: tool and function descriptions, error messages, and output another agent or script parses. Put conditions before commands. Use imperative steps, one action per step, direct verbs, simple tenses, and sentences of at most 20 words.
  • Natural — README narrative, explanations, comments, and PR rationale. Keep terminology and actors clear, but allow contractions, semicolons, sentence rhythm, and passive voice when the actor is unknown or irrelevant.

Apply modes by content block. A README quickstart can be strict while its motivation remains natural.

Shared rules

  • Lead with the reader's goal and shortest path. Put provenance and history later or omit them.
  • Be genuine. Write as a maintainer helping a reader, not as a product sheet imitating confidence.
  • Use evidence instead of quality adjectives. Give the measurement, example, or boundary behind the claim.
  • Use one name for one thing. Do not rotate synonyms unless they identify different concepts.
  • Name the doer and the action within the first eight words of a sentence. An abstract noun as subject (the configuration of, the handling of) hides them: make the doer the subject and the action the verb.
  • One idea per sentence. Open on what the reader already holds and end on the new name or value; this outranks active voice. A condition longer than ten words becomes its own step.
  • Break noun stacks of four or more words: “calibration of the connection resistance,” not “connection resistance calibration procedure.”
  • Say each fact once. Omit template sections that do not change the reader's next action.
  • Cut words that announce or reassure: This document describes, simply, obviously. Readers assume the opposite of an intensifier, and simply blames them when the step fails.
  • A hedge in a procedure is a missing condition: write if X, do Y, not you may need to do Y. In explanation, one hedge states uncertainty and two in a sentence hide it.
  • State unsupported cases and tradeoffs. Simpler wording must not erase precise technical meaning.

Check the draft

python3 scripts/prose_lint.py --mode strict <path>
python3 scripts/prose_lint.py --mode natural <path>

Use - for stdin and --json for structured findings. Exit 1 means strict errors; review-only findings return 0. Add <!-- prose-lint-ignore --> to ignore one line. The checker cannot detect synonym rotation without project context, so check terminology manually. This is not an STE certification or a substitute for factual review. See CLARITY-REFERENCE.md for rationale and sources.

Rewriting an existing document

  • Grep tests and CI for strings pinned from the document before you restructure it. If a test pins wording, make it assert the requirement (order, a link's presence) instead of the exact text. Name the changed assertion in the PR.
  • Find copies derived from it: package README, docs site, translations. Update them or state that they are out of scope.

Reviewing rather than writing

Same lens, inverted: verify the artifact against its source, then report what the target reader cannot do, cannot trust, or must read twice. Lead with the defect and its location, not with praise.

Comments

Markdown supported