Przejdź do treści
Biblioteka skilli
Dokumenty i biuro · Pisanie

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.

Repozytorium
dotfiles ↗
Licencja
MIT
Ostatnia zmiana repozytorium
13.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
4
Skrypty
3
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • 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

  1. Name the reader
  2. Answer first
  3. Progressive disclosure
  4. By kind
  5. Voice
  6. Measure every draft
  7. Before handing it over
Sekcje z nagłówków SKILL.md, w oryginale · 122 linii, 993 słów
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

RepozytoriumWynikLicencja
Ta strona · steveclarke/dotfiles100MIT
microsoft/vscode-docs100MIT
claude-world/director-mode-lite100MIT
bannff/python-software-factory90Apache-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ą.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.