Przejdź do treści
Biblioteka skilli
Programowanie · Pisanie

technical-writing

/technical-writing

Pisze lub naprawia dokumentację zgodną z opisywanym systemem (README, setup, how-to, referencje API, runbook), ustalając najpierw czytelnika i zadanie oraz opierając twierdzenia na przeczytanym kodzie.

Licencja
MIT
Ostatnia zmiana repozytorium
29.09.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 29.09.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 lub naprawia dokumentację zgodną z opisywanym systemem (README, setup, how-to, referencje API, runbook), ustalając najpierw czytelnika i zadanie oraz opierając twierdzenia na przeczytanym kodzie.

Oryginalny opis (EN)

Write or repair documentation that stays true to the system it describes — README, setup guide, how-to, API reference, architecture explanation, release notes, runbook — by fixing the reader and the task first, then grounding every factual claim in code you actually read. Use when documentation is being written, restructured or found to be stale, or when a reader cannot get from the docs to a working result. Not for interface strings inside a product, not for persuasive or marketing copy, and not itself proof that the documented commands work.

Jak działa

  1. When this fires
  2. Procedure
  3. Checklist
  4. Failure handling
  5. Evidence to report
Sekcje z nagłówków SKILL.md, w oryginale · 88 linii, 934 słów
Podgląd SKILL.md
---
name: technical-writing
description: Write or repair documentation that stays true to the system it describes — README, setup guide, how-to, API reference, architecture explanation, release notes, runbook — by fixing the reader and the task first, then grounding every factual claim in code you actually read. Use when documentation is being written, restructured or found to be stale, or when a reader cannot get from the docs to a working result. Not for interface strings inside a product, not for persuasive or marketing copy, and not itself proof that the documented commands work.
---

# Technical writing

Documentation drifts because it is written from what the author remembers rather than from what
the system does. The failure is not bad prose — it is a true-sounding sentence nobody checked.

Keep the verbs apart: **created** is the document written; **reviewed** is someone reading it;
**verified** is every command run and every link resolved. This skill gets you to created and
reviewed. It does not get you to verified — see `documentation-verification`.

## When this fires

Documentation is being authored, restructured, or updated after a change; a README no longer
matches the repository; a reader reports that the guide does not work. It does not fire for copy
inside the product's own interface, or for copy whose job is to persuade.

## Procedure

1. **Name the reader and the moment.** Who they are, what they already know, what they were doing
   one step before they opened this, and what state the system is in when they arrive. Write to
   that person. "Developers" is not a reader.
2. **Name the one task this document completes**, and what proves it completed — a running server,
   a passing request, a deployed change. A document with no finishable task becomes reference by
   accident and serves nobody.
3. **Choose the shape and keep it pure.** A tutorial gets a beginner to a first success; a how-to
   solves one problem for someone who already has the context; a reference is looked up, never
   read; an explanation covers why. Mixing two of these in one page is the most common structural
   defect — split instead, and link.
4. **Find the source of truth and pin the scope.** Read the code, the config, the schema, the
   route definitions, the CLI's own help output, the migrations. Record the version, platform and
   environment the document is true for. Where two sources disagree, resolve it before writing —
   an unresolved contradiction shipped as prose is a defect you authored.
5. **Draft the spine before the sentences:** prerequisites, the single main path in order, and
   what the reader should observe after each step. If a reader cannot tell whether step 4 worked,
   step 5 is where they will silently fail.
6. **Ground every factual claim in something you read.** Default flags, env var names, config
   keys, return shapes, error text, supported versions — each should be traceable to a file you
   can name. A claim you cannot trace is a hypothesis: check it, or mark it as unconfirmed. Never
   write plausible output you have not seen.
7. **Make examples literally runnable.** Copy-pasteable commands, complete code, and placeholders
   that are visibly placeholders (`<your-project-id>`), never a real-looking value a reader will
   paste. Never invent a flag, an endpoint or a sample response to make an example tidy.
8. **Document the failure the reader will actually hit** — the missing dependency, the wrong
   version, the permission error you met while checking. A troubleshooting section written from
   imagination is filler.
9. **Reconcile with what already exists.** Update the stale page rather than adding a second
   truth; fix cross-references, navigation and terminology so one name means one thing throughout.
   Delete what the code no longer supports instead of leaving it as history.
10. **Hand off honestly.** List the commands, examples and links you did not execute, and say the
    document is written but unverified. Publishing it — to a docs site, a wiki, a package
    registry, a public repository — is an outward-facing act: **stop and ask** rather than
    shipping it as part of the writing.

## Checklist

- [ ] Reader, prior knowledge and finishing condition are written down, not assumed
- [ ] One document shape, not two spliced together
- [ ] Version, platform and environment scope stated
- [ ] Every factual claim traceable to code, config or observed output
- [ ] Every command and example complete, runnable, with placeholders marked as such
- [ ] No invented flags, fields, options or sample output
- [ ] Each step tells the reader what they should now see
- [ ] Failure cases come from real ones encountered, not imagined
- [ ] Stale content updated or deleted; cross-references and terminology consistent
- [ ] Unexecuted commands, examples and links named; publication not performed unasked

## Failure handling

- **The code does not settle the question** — read the tests and the callers next. If it is still
  ambiguous, write what is true of every branch and raise the question; do not pick the version
  that reads better.
- **The existing document contradicts the implementation** — the implementation wins for what you
  describe, but say so in the report. A silent rewrite hides either a doc bug or a code bug, and
  you do not yet know which.
- **A behaviour only the maintainers know** — mark it unconfirmed and ask. An authoritative
  sentence sourced from inference is the exact failure this skill exists to prevent.
- **The feature is not built yet** — do not document it in the present tense. Documentation
  describing intent is indistinguishable from documentation describing the product.
- **A third-party library's current behaviour matters** — read its current documentation rather
  than recalling it, and cite what you read.

## Evidence to report

The reader and task the document targets; the files, commands and outputs each non-obvious claim
came from; the version and platform scope; the contradictions found between docs and code, and how
you resolved them; and the explicit list of what remains unverified. "Docs updated" with no source
named and no unverified list is not evidence — it is the claim this skill asks you to back.
Pliki w paczce (2)
  • SKILL.md 6 KB
  • manifest.json 1 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · nahid-sparktales/agent-dispatcher100MIT
ericrisco/rsc-harness100MIT
sma1lboy/rove100MIT
Calvin-LLC/skills100MIT
chmonitor/chmonitor100GPL-3.0
KyaniteHQ/threadsift100AGPL-3.0
asarelcastellanos/claude-workbench100MIT
guangshinhaha/shinstack100MIT
valsteen/pinboard100MIT

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

  • 100documentation
    Pisze i utrzymuje dokumentację techniczną: README, runbooki, przewodniki wdrożeniowe, dokumentację API, architektury i operacyjną.
  • 100technical-documentation
    Pomaga napisać README, dokumentację API w OpenAPI, runbook dla dyżurnych inżynierów i ADR oraz publikować dokumentację na GitHub Pages.
  • 100docs
    Pisze lub poprawia dokumentację techniczną pod jedno zadanie czytelnika: README, dokumentację API, instrukcje operacyjne, RFC, dokumenty projektowe, propozycje architektury i ADR.
  • 100maisongr-documentation
    Pisze dokumentację techniczną, która pozostaje zgodna z kodem: README, instrukcje instalacji, opisy API, runbooki i wpisy w changelogu.
  • 100technical-documentation
    Pomaga pisać dokumentację dla deweloperów: cztery typy dokumentacji i wybór między nimi, README, referencja API i działające tutoriale.
  • 100code-documentation
    Analizuje repozytorium i tworzy lub aktualizuje README, dokumentację API i architektury, a potem ją sprawdza.

Uwagi i zgłoszenia

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