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

writing

/writing

Pisze i poprawia dokumenty czytane przez ludzi: wymagania, projekt, plan testów, zadania i opisy PR, według zasad szkieletu dokumentu, diagramów i skracania.

Repozytorium
the-loop ↗
Licencja
MIT
Ostatnia zmiana repozytorium
27.10.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
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

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

Licencja

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

Co robi i kiedy

Pisze i poprawia dokumenty czytane przez ludzi: wymagania, projekt, plan testów, zadania i opisy PR, według zasad szkieletu dokumentu, diagramów i skracania.

Oryginalny opis (EN)

How the-loop writes for a human reader. Use when authoring or revising any artifact a person will read — requirements.md, design.md, testing-plan.md, tasks.md, a PR briefing or PR description, a decision record, a capability doc, a ticket or review comment, a README. Carries the document spine, the prefer-a-diagram rule, the formal-language carve-out that keeps EARS and API contracts intact, and a revise pass for cutting a draft down. Not for code, code comments, log messages or test names.

Jak działa

  1. Who is reading
  2. The spine
  3. Length follows the change
  4. Prefer a diagram
  5. Keep the formal register where it is a contract
  6. The revise pass
  7. Related
Sekcje z nagłówków SKILL.md, w oryginale · 83 linii, 641 słów
Podgląd SKILL.md
---
name: writing
description: How the-loop writes for a human reader. Use when authoring or revising any artifact a person will read — requirements.md, design.md, testing-plan.md, tasks.md, a PR briefing or PR description, a decision record, a capability doc, a ticket or review comment, a README. Carries the document spine, the prefer-a-diagram rule, the formal-language carve-out that keeps EARS and API contracts intact, and a revise pass for cutting a draft down. Not for code, code comments, log messages or test names.
---

# Writing for a human reader

A reviewer's job is to say yes or no. Every word between them and that decision is a cost
you are charging them. Write to be approved, not to be admired.

> **The rule:** say it once, to a named reader, in the fewest words that survive review.

## Who is reading

Name the reader before the first sentence. A reviewer of `design.md` knows the codebase
and wants the shape of the change. A `capability.md` reader wants current behaviour and
does not care how it arrived. A ticket comment is read on a phone. The same fact is a
paragraph for one and a table row for another.

## The spine

Every explanatory document answers four questions, in this order:

1. **What was broken** — the situation, and why it mattered enough to open a ticket.
2. **What we did about it** — the resolution, stated as a decision, not a tour.
3. **What it costs** — the trade-off taken, the thing given up, the risk carried.
4. **What to check** — where the reader should look first, and what would falsify it.

Front-load each one. A section's first sentence carries its conclusion; the rest is
support the reader may skip. Read only the first sentence of every section — if that alone
tells the story, the document is shaped right.

## Length follows the change

**There is no word limit, and there should not be.** A two-line bug fix and a new
subsystem are both `design.md`, and a number that fits one is wrong for the other. A cap
would only teach you to move prose into an appendix.

The test is not length, it is **density**: can any sentence come out without losing
information? While the answer is yes, the document is too long — at 200 words or 2000.
Three cuts nearly always find the slack: the sentence restating the heading, the sentence
restating the sentence before it, and the adjective a number would replace.

**Concision is about words, not coverage.** A gated section stays even when it is empty;
say so in one sentence, and why. Deleting `## Security considerations` to shorten a
document is fraud, not editing.

## Prefer a diagram

Describing a structure, a sequence or a state change with three or more named parts? Draw
it. Mermaid, always. Then let the prose say only what the
diagram cannot — why the arrow points that way, what happens when it fails. `design.md`
carries at least one.

## Keep the formal register where it is a contract

These are testable artifacts, not prose, and this skill does not touch them:

- EARS acceptance criteria and abuse cases (`WHEN … THEN the system SHALL …`)
- RFC-2119 keywords in a specification
- OpenAPI / GraphQL contracts and JSON-Schema `description` values
- Quoted material, third-party text, committed evidence and code

These are the formal registers of the writing contract (fixed since issue-352).
Explanation *around* them is ordinary prose and follows this skill.

## The revise pass

Draft first, cut second — never both at once.

1. Delete every opener that clears the throat before the point.
2. Delete every sentence the reader could reconstruct from the one before it.
3. Replace each evaluative adjective with the number or example behind it.
4. Convert any run of prose that is really a list, a table or a diagram.
5. Read the first sentence of each section in order. If that alone tells the story, stop.
   If it does not, the problem is the structure, not the wording.

For the catalogue of writing tells and what to do about each,
read [`reference/tells.md`](reference/tells.md).

## Related

The token-economy verbosity rule (`the-loop` skill, `reference/token-economy.md`)
compresses **chat narration** and preserves specs; this skill governs the
**artifacts**. Third-party skills covering neighbouring ground are implemented
natively, not vendored (decision-005, decision-062).
Pliki w paczce (2)
  • SKILL.md 4 KB
  • reference/tells.md 5 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · madarauchiha-314/the-loop100MIT
molveau/skills100MIT
iliaal/ai-skills100MIT
se-uhd/ai-slop-skill100CC-BY-4.0
getgithard/githard100MIT
builtnotboosted/built-not-boosted-skills100MIT
williampsmith/marketing-skills100MIT
solidvibes/solid-vibes100MIT
nhthai173/plainspoken100MIT

Migawka bazy z 13.11.2026 · wersja paczki 71769485c292 (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

  • 85write-the-docs
    Pisze lub edytuje dokumentację projektu: README, dokumenty projektowe i opisy modułów.
  • 90writing-artifacts
    Pisze trwałe dokumenty robocze, takie jak README, ADR, notatki wydania, runbook czy opisy błędów, z myślą o czytelniku.
  • 100technical-writing
    Pisze i przegląda dokumenty techniczne: RFC, design doc, PRD i opisy PR, wybierając najpierw typ dokumentu według Diátaxis.
  • 100write-docs
    Pisze i sprawdza dokumenty do działania: specyfikacje, PRD, kontrakty API, decyzje, plany wdrożeń i README, gdy zmiana kodu czyni stare dokumenty błędnymi.
  • 100writing-technical-documents
    Pisze i poprawia dokumenty techniczne, takie jak README, ADR, runbook czy opis PR, zaczynając od wniosku i sprawdzonych faktów.
  • 100no-stop-it-writing
    Podaje zasady pisania dla ludzi w czacie, commitach, PR, komentarzach i slajdach, z sygnałami, że czytelnik się zniechęci.

Uwagi i zgłoszenia

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