doc-writer
/doc-writer
Pisze i przebudowuje dokumenty, które ludzie czytają, np. specyfikacje, poradniki, plany i raporty, zaczynając od najważniejszego, i mierzy czytelność tekstu.
- Autor
- steveclarke ↗
- Repozytorium
- dotfiles ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 13.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 4
- Skrypty
- 3
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
- 3 skrypty w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
Skrypty: scripts/flesch_kincaid.rb, scripts/markdown_prose.rb, scripts/vocabulary_profiler.rb
Co robi i kiedy
Pisze i przebudowuje dokumenty, które ludzie czytają, np. specyfikacje, poradniki, plany i raporty, zaczynając od najważniejszego, i mierzy czytelność tekstu.
Oryginalny opis (EN)
Writes and restructures documents people read (specs, guides, plans, READMEs, reports, runbooks, briefs) answer first, with progressive disclosure, and measures reading level with bundled Flesch-Kincaid and common-word scorers. Use when writing, revising or reviewing such a document, or when asked how readable a text is. Not for chat replies, email replies or code comments.
Jak działa
- Name the reader
- Answer first
- Progressive disclosure
- By kind
- Voice
- Measure every draft
- Before handing it over
Podgląd SKILL.md
---
name: doc-writer
license: MIT
description: Writes and restructures documents people read (specs, guides, plans, READMEs, reports, runbooks, briefs) answer first, with progressive disclosure, and measures reading level with bundled Flesch-Kincaid and common-word scorers. Use when writing, revising or reviewing such a document, or when asked how readable a text is. Not for chat replies, email replies or code comments.
---
# Doc writer
A document is read by someone who wants to act: build the feature, set up the
machine, approve the plan, fix the outage. Agents tend to write the opposite:
background first, every detail at the same depth, one long page, prose scored
by feel. This skill holds what goes wrong and how to check it.
## Name the reader
Choose before writing. A Brief for Steve asks for decisions in one or two
pages; Hugo's `docs/feature-briefs.md` sets its shape. A team explainer opens
each section with what it is and why it matters, then gives the detail. A
design document is for builders: code references and technical depth belong
there. It is never handed to Steve as his reading.
Write for someone with none of the writer's context. Explain each idea where
it first appears. Each section gives enough context to make sense on its own.
## Answer first
The first two lines say what this is and what the reader does with it. A spec
opens with what the feature does and for whom; a guide with what the reader
will have when done and how long it takes; a plan with the decision or approval
it needs. A reader who stops after two lines still knows what to do. Steve's
`docs/bluf.md` in Hugo gives the shape and its sources.
Background, history and how the work got here come last or go to the
discussion record. No opening that restates the request, describes the
document ("This document outlines…") or narrates the process.
## Progressive disclosure
Write in layers: summary, then detail, then reference.
- Summary: the answer and the few facts that change what the reader does.
- Detail: what the reader needs to act, in the order they act on it.
- Reference: what they look up later (field lists, edge cases, error codes,
full command options), at the end, in an appendix or on its own page.
Justify each section by asking whether the reader needs it to act or only to
look something up. The first kind stays in the flow, the second moves to
reference, and anything that serves neither comes out. Headings read top to
bottom should tell the story on their own.
A document past about two screens of action content splits into an index page
with linked pages, one level deep. The index carries the answer and one line
per linked page saying when to open it. Steve often reads on a phone, so long
tables and wide code blocks belong on reference pages.
## By kind
The usual structure of each kind is assumed; these are the places agents most
often go wrong.
- Spec: behaviour stated as what a person sees and does, with acceptance
checks a reviewer can run. Decisions made are stated as facts; open
questions are a short numbered list near the top, each with a recommended
answer. No implementation diary.
- Guide or runbook: numbered steps, one action each, commands ready to copy,
and the expected result after any step that can fail. Prerequisites come
before step 1, not at step 6.
- Plan: the decision or go it needs, then steps sized in agent time, then
risks only where they would change the decision.
- README: what it does and the quickest working start; the rest links to docs.
- Report: the finding and what it means for the reader, then the evidence,
with the scope and filters behind any search.
## Voice
Docs are in reference voice (Steve's global `AGENTS.md`, "Documents"). One
term per concept, acronyms defined on first use, and prose a reader with
English as a second language follows: short sentences, active voice, no idioms.
Real technical names stay: database, API, webhook, DNS record, Durable
Object. No coined phrases, buzzwords or clever labels. Describe what happens.
- "Immutable intake evidence" becomes "The form keeps the details first sent."
- "Operation receipts" becomes "A saved record shows whether the change worked."
- "Sealed approval snapshots" becomes "Approval applies to this saved version."
- "Each fact has one writer" becomes "Outport alone changes customer details."
## Measure every draft
Reading level is measured, never estimated. The scorers are in this skill's
`scripts/` folder, installed at `~/.agents/skills/doc-writer/scripts/`. Both
read standard input. Pass `--markdown` for a markdown file, so code blocks,
tables, headings and link targets are not scored as prose; plain text such as
an email goes in without it.
```bash
S=~/.agents/skills/doc-writer/scripts
ruby $S/flesch_kincaid.rb --markdown < doc.md
ruby $S/vocabulary_profiler.rb --markdown < doc.md
```
- Grade level: 9 or below for anything Steve or the team reads. A builder
design document may use a higher target set by its brief. Technical
terms raise the score and stay; the score comes down by splitting sentences
and using plain connectors, not by renaming technical things.
- Common-word coverage: the share of words among the 1000 most common English
words. It has no fixed target; it rises when the non-technical words are
kept simple.
Run both on the first draft and the final one, and report both pairs of
numbers with the document: "grade 13.2 → 8.8, common words 41% → 49%".
## Before handing it over
1. Read only the first two lines: they give the answer and the reader's action.
2. Read only the headings: they tell the story in order.
3. Check each section earns its place under "Progressive disclosure".
4. Run the scorers and record the numbers.
5. Run the explain-back test: three fresh readers each get only the page text
and the reader profile. They share no answers. For each section, they say
what it means in plain words
and list each phrase they cannot explain or that is a coined label.
Any listed phrase fails. Revise and repeat before handoff. In Hugo,
`coordinators/bin/readable <file-or-folder>` runs both checks; use
`--kind team` for an explainer or `--kind design` for builder reference.
The default is a Brief for Steve. The coordinator still reads it in full.
Pliki w paczce (4)
- SKILL.md 6 KB
- scripts/flesch_kincaid.rb 1 KB
- scripts/markdown_prose.rb 1 KB
- scripts/vocabulary_profiler.rb 7 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · steveclarke/dotfiles | 100 | MIT |
| microsoft/vscode-docs | 100 | MIT |
| claude-world/director-mode-lite | 100 | MIT |
| bannff/python-software-factory | 90 | Apache-2.0 |
Migawka bazy z 13.11.2026 · wersja paczki af7746171e4b (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100technical-writer
Pisze i restrukturyzuje dokumentację techniczną: README, tutoriale, poradniki, dokumenty architektury, onboarding, runbooki, noty wydania, na podstawie faktycznego kodu lub produktu ze sprawdzonymi poleceniami. - 100simplify-prose
Pisze i przepisuje techniczne teksty dla czytelników (dokumentacja, README, runbooki, komunikaty błędów, notatki wydania, raporty incydentów, prompty) według zasad STE i sprawdza je pod kątem naruszeń jasności. - 100document-writing
Tworzy, aktualizuje, przepisuje, recenzuje i weryfikuje trwałe dokumenty dla ludzi: README, przeglądy, przewodniki, specyfikacje, propozycje, raporty, polityki, runbooki, notatki i Feature Design Docs. - 100technical-writing
Pisze wewnętrzne dokumenty techniczne: specyfikacje, ADR, runbooki i plany migracji dla zespołów budujących i utrzymujących system. - 100word-read-write
Tworzy i czyta dokumenty Microsoft Word (.docx): generuje raporty, listy i szablony oraz wyciąga czytelny tekst z istniejących plików. - 95gvm-doc-write
Pisze i poprawia dokumenty: prezentacje, strategie, biuletyny, materiały szkoleniowe, raporty i dokumentację techniczną.