Skip to content
Skills Library
Programming · Writing

write-docs

/write-docs

Write or revise developer docs (a README, guide, how-to, reference or design explanation) by gathering context, agreeing on an outline, writing section by section and testing it on a newcomer. Use it when asked for docs, when a change alters what users must know, or when docs are stale.

Repository
yaap ↗
Licence
MIT
Last repository change
13.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Write or revise developer docs (a README, guide, how-to, reference or design explanation) by gathering context, agreeing on an outline, writing section by section and testing it on a newcomer. Use it when asked for docs, when a change alters what users must know, or when docs are stale.

Original author description

Write or revise developer docs (a README, guide, how-to, reference or design explanation) by gathering context, agreeing on an outline, writing section by section and testing it on a newcomer. Use it when asked for docs, when a change alters what users must know, or when docs are stale.

How it works

  1. 1. Pick the kind
  2. 2. Gather context
  3. 3. Outline first
  4. 4. Write section by section
  5. 5. Read it as a newcomer
  6. 6. Keep it true
  7. README outline
Original SKILL.md headings · 102 lines, 834 words
SKILL.md preview
---
name: write-docs
description: Write or revise developer docs (a README, guide, how-to, reference or design explanation) by gathering
  context, agreeing on an outline, writing section by section and testing it on a newcomer. Use it when asked for
  docs, when a change alters what users must know, or when docs are stale.
license: MIT
metadata:
  sources: agency-agents/engineering/engineering-technical-writer.md, own
---

# Write docs

Documentation fails in two ways: it is wrong, or it assumes what the reader does not know. Both come from writing
before understanding the reader and the code. Gather first, outline second, write third, and then test the result
on someone who knows nothing.

## 1. Pick the kind

Each document does one job. Mixing them makes all of them worse.

| Kind | The reader wants to | Shape |
|---|---|---|
| Tutorial | learn by doing, from zero | numbered steps to one working result |
| How-to guide | get one task done | goal, prerequisites, steps, how to check it worked |
| Reference | look up a fact | complete, consistent entries; no story |
| Explanation | understand why | prose about design, trade-offs and context |

A README is a front door: what this is, why it exists, the shortest way to start, and links to the rest.

## 2. Gather context

- **The reader.** Who reads it, what they already know, and what they want to do after reading. Ask the user when
  this is unclear; it decides every later choice.
- **The facts.** Read the code, the configuration, the existing docs and the tests. Run the commands the document
  will tell readers to run, in a clean state where you can. A step you did not run is a step that may be wrong.
- **The gaps.** Look at issues, questions and review comments about the topic: they show where readers get stuck.
- **The rules.** If the project has a documentation standard, load it with `load_standard` and follow it; follow the
  tone and layout of the docs next to the new one.

Ask the user a few short questions at once rather than one per reply, and say what you will assume if they skip
them.

## 3. Outline first

Write the headings and one line per heading on what it says. Show the outline for anything longer than a page and
agree on it; moving a heading is cheap, rewriting three sections is not. Check that each section has one purpose and
that the order follows what the reader does.

## 4. Write section by section

- The point first: the first sentence of a section says what it is for or what to do.
- Second person, present tense, active voice: "Run `make test`", not "The tests can be run".
- One concept per section; installation, configuration and usage are separate.
- Define each term at its first use, or link to where it is defined.
- Examples are short, complete and correct: commands with their expected output, code that runs as shown. Check
  each one.
- Say what can go wrong at the step where it happens, with the message the reader will see and what to do.
- Link instead of repeating. Two copies of a fact drift apart.

For a document the user wants to shape with you, open it beside the chat with `open_document` when it is available
(in a project conversation): they see each change and their edits reach you. Elsewhere, write the file and show the
changed sections in the reply.

## 5. Read it as a newcomer

Re-read the whole document as a reader who has only this page and the project. Better, when `delegate` is
available (in a project conversation): hand it to an exploring worker, give it only the document and the task it
describes, and ask where it got stuck, what it had to guess and which terms it did not know. Without `delegate`,
follow the document's steps yourself, literally and in order. Fix what you find, then check:

- Every command and example was run or checked against the code.
- No step depends on something only the author knows (a local path, a setting, an earlier conversation).
- The first screen of a README answers what it is, why it matters and how to start.
- Links work; names match the code exactly.

For a larger piece, when `delegate` is available, hand the writing to the `docs-writer` agent (`delegate` with
`agent: docs-writer`) and review its diff. That agent follows this skill itself and writes directly.

## 6. Keep it true

Docs go in the same change as the code they describe, so they cannot fall behind. When a change breaks how readers
use something, the docs say what to do instead (and the release notes do too, see the `release-notes` skill).

## README outline

```markdown
# <Name>

<One sentence: what it is and who it is for.>

## Why
<Two or three sentences: the problem it solves.>

## Quick start
<The shortest path to something working, with the expected result.>

## Install
<Prerequisites with versions, then the steps.>

## Use
<The most common task, fully worked; then the next most common.>

## Configure
<Settings that matter, with defaults; link to the full reference.>

## Develop
<Run, test and contribute, or a link to CONTRIBUTING.>

## License
```

Versions

RepositoryScoreLicence
This page · jelvodev/yaap100MIT
hassan-mohiddin/freeflow100MIT
alchemy-run/alchemy100Apache-2.0
Agenta-AI/agenta100MIT
comet-ml/opik100Apache-2.0
gosodax/sodax-sdks100MIT
gtriggiano/statica100MIT
browseros-ai/browseros100BSD-3-Clause
wilbeibi/claude-toolkit100MIT

Database snapshot: 13.11.2026 · package version d0ca2d045e2e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100absolute-docs
    Diátaxis-driven documentation for AI coding agents: write, improve, or audit tutorials, how-tos, reference, explanation, and developer docs (README, CONTRIBUTING, ADRs). Detects the docs stack; gates on the outline before writing prose; verifies every claim against the code…
  • 100docs
    Generates developer documentation (API reference, developer guide) and user-facing help docs organized by user journey. This skill should be used when the user asks to "generate documentation", "create API docs", "write developer guide", "generate help docs", "create onboarding…
  • 85write-the-docs
    Write or edit project documentation. Use when writing a README, design doc, or module doc.
  • 100documentation
    Write and maintain technical documentation. Trigger with "write docs for", "document this", "create a README", "write a runbook", "onboarding guide", or when the user needs help with any form of technical writing — API docs, architecture docs, or operational runbooks.
  • 90write-documentation
    Write software documentation structured by Diátaxis. Use when the user wants a tutorial, how-to guide, reference page, explanation doc, or user guide — "write docs", "document this", "we need a guide for X". Not for READMEs (write-readme) or docstrings (update-docstrings).
  • 100writing-developer-docs
    Use when writing or editing developer-facing documentation, guides, references, READMEs, or API docs. Triggers include requests to write docs, document a feature/API, simplify or clarify docs, or make writing plainer and more developer-friendly.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.