Przejdź do treści
Biblioteka skilli
Programowanie · Pisanie

write-docs

/write-docs

Pisze dokumenty, opisy pull requestów i commity dla zmian w dokumentacji, ADR oraz opisów zmian.

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

Brak sygnałów. Repozytorium zmienione 05.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 robi i kiedy

Pisze dokumenty, opisy pull requestów i commity dla zmian w dokumentacji, ADR oraz opisów zmian.

Argumenty

/write-docs [doc type or path]
Oryginalny opis (EN)

Write and place documents, PR bodies and commit messages. Use for documentation changes, ADRs and change descriptions.

Jak działa

  1. Write plainly
  2. Put each doc where readers look
  3. Change docs with the code
  4. Record decisions in ADRs
  5. Keep instruction files lean
  6. Write the PR body
  7. Write commit messages
Sekcje z nagłówków SKILL.md, w oryginale · 153 linii, 1 308 słów
Podgląd SKILL.md
---
name: write-docs
description: Write and place documents, PR bodies and commit messages. Use for documentation changes, ADRs and change descriptions.
argument-hint: "[doc type or path]"
---

# Write docs

Give each fact one home.
Code, types and tests define behavior.
Documents explain how to run the project, define its terms, explain decisions and describe operations.
The tracker records status and progress.
Commits and PRs record change history.

Follow the repo's PR template, ADR format and document layout when they exist.
Use this skill where the repo has no convention.

Read the reference for the document that you write, and no other document type:

- ADR, or a change that reverses a decision: `references/adr.md`.
- `AGENTS.md`, `CLAUDE.md` or another instruction file: `references/instruction-files.md`.
- Any prose: `references/technical-writing.md`, then `references/unslop.md`.
- PR bodies and commit messages: this file holds the rules, and `references/pr-and-commits.md` holds a worked example and the first-line rules.

## Write plainly

Use `references/technical-writing.md` for documents, PR bodies and commit messages.
Then apply `references/unslop.md`.
Their main rules are these:

- Use actual symbols, files and commands with ordinary developer vocabulary.
- State one thought per sentence. Use active voice, present tense and "you".
- Remove filler, hedges and adverbs. Exclude long dashes, bold-label lists, emoji and title-case headings.
- Verify each count at the landing commit. Otherwise link its source instead of copying the count.

## Put each doc where readers look

| Doc | Location | Content | Excluded content |
|---|---|---|---|
| README | `README.md` | Project purpose, local setup and document index | Status and unstable counts |
| Agent instructions | `AGENTS.md`, imported by `CLAUDE.md` | Commands, hard rules with pointers and measured traps | Status, dates, plans and delivery history |
| Glossary | Existing `CONTEXT.md` or `GLOSSARY.md`, otherwise `CONTEXT.md` | Bold domain terms with one or two definition sentences, `_Avoid_:` and optional `_Code_:` symbols | Ticket sections and implementation details |
| Context map | `CONTEXT-MAP.md` for several contexts | Links to one glossary per context | Duplicate glossary definitions |
| Decisions | `docs/adr/NNNN-<claim>.md`, indexed in `docs/adr/README.md` | One decision topic per file | Review logs, PR history and status |
| Runbooks | `docs/runbooks/<task>.md` | Steps to deploy, operate or recover one system | File names based on tickets or dates |
| Reference | `docs/reference/<system>.md` | Subsystem facts | Instructions and opinion |
| Plans | `docs/plans/<slug>.md`, written and checked by `/astack:plan` | Decisions, sessions, premises and open questions for current work | Status, checkboxes, dates and citations from code |
| Status and progress | The tracker or PR | Work ownership and completion | Copies in repo files |

Delete a plan after its last session ships.

## Change docs with the code

Update documents in the same PR as the behavior they describe:

| Change | Document |
|---|---|
| Add or rename a domain term | Glossary |
| Make a choice that passes the ADR test | New ADR |
| Reverse or replace a decision | New ADR that supersedes it |
| Leave an ADR's words stale or misleading | Note or Amended block in that ADR |
| Change an env var, deployment step or operations procedure | Runbook and env inventory |
| Change a command or hard rule | `AGENTS.md` |
| Change local setup | `README.md` |
| Change visible user behavior | User documentation |

Encode an enforceable constraint in a type or test.
If it also needs words, apply the three ADR tests below.
If it fails those tests, put the reason in the commit body.
A code comment can state a constraint only when a keep clause covers it, such as a vendor or protocol requirement.

## Record decisions in ADRs

Write an ADR only when all three conditions hold:

1. Reversal would require substantial work.
2. A future reader would find the code surprising without the reason.
3. The choice came from a real trade-off between alternatives.

When a condition fails, use another location.
Put enforceable constraints in types or tests, terms in the glossary, and history in commits or PRs.

During design discussions, `astack:domain-modeling` updates the glossary and proposes ADRs with the same tests.
This skill owns their file names and format.
Keep an existing `GLOSSARY.md` name.
Otherwise use `CONTEXT.md`.
Read `references/adr.md` for the title, the numbering, notes, amendments, supersession and the template.

## Keep instruction files lean

Make `CLAUDE.md` contain `@AGENTS.md` or link to it with a symlink.
Keep the shared source under about 300 lines or 6,000 tokens, because every session loads it.
Put status, dates, phases, session IDs and delivery history in the tracker.
Read `references/instruction-files.md` for the rules, the skeleton and the reduction process.

## Write the PR body

Write for a reviewer who has the diff open and less than one minute.
Explain the problem, behavior change, proof and failure risks.
Keep the body under about 40 lines, because it becomes the commit body on squash merge.

Use an existing repo template.
Look for `PULL_REQUEST_TEMPLATE.md` or `pull_request_template.md` in `.github/`, the root or `docs/`.
Also inspect `.github/PULL_REQUEST_TEMPLATE/` for multiple templates.
Copy the selected template's headings into the body file.
Never pass `--template` with `gh pr create`.
GitHub CLI refuses it beside `--body` or `--body-file`.
The astack hook checks the template headings.
With multiple templates, it checks only their shared headings.
Run `astack check-pr <file>` before creation.
Use `astack check-pr <file> --template <name>` to check all headings of one selected template.

Without a repo template, use this format with the headings unchanged:

```md
Part of ABC-123

## Why

## What changes

## Acceptance criteria and evidence

## Verification

## Risk and rollback

## Deploy notes

## Follow-ups
```

The hook requires `Why`, `What changes`, `Verification` and `Risk and rollback`.
`Acceptance criteria and evidence`, `Deploy notes` and `Follow-ups` are optional.
Delete empty optional sections instead of writing "n/a".

- Name the ticket on the first line as `Part of ABC-123`. Multiple tickets can share that line, as in `Part of ABC-123, ABC-124`. The line is mandatory when `.astack/profile.json` sets `tracker.requirePartOf`.
- Never put a ticket key or `#n` after a closing word such as `Closes`, `Fixes` or `Resolves`. That form triggers tracker completion at merge, so the astack hook refuses it. The reference explains GitHub issue and branch-name cases.
- Describe behavior. Call out schema, API and migration changes rather than listing files.
- Describe the final state. Keep review rounds, commit SHAs and owner rulings out of headings and body. Link logs and long tables.
- Explain internal code and abbreviations in plain words, or omit them.
- Always state rollback. Name the revert, flag or reversible migration that undoes the change.
- Keep Why to one to three short sentences covering the problem, impact and approach.
- Keep What changes to one to three behavior bullets, followed by excluded work. Add a small call tree or screenshot only when prose cannot explain the change.
- Keep Verification to one to three gates or run paths with counts or outcomes. For defects and review findings, show the failing run before the passing run.
- Keep Risk and rollback to one or two sentences. State reversibility, affected systems and the rollback step.

## Write commit messages

- Use `type(scope): imperative summary` with at most 72 characters and no final period. Types are `feat`, `fix`, `docs`, `refactor`, `test`, `perf`, `build`, `ci` and `chore`.
- Put the ticket key in a `Refs: ABC-123` trailer. Exclude it from the subject.
- Explain the reason, behavior change and rejected alternatives in the body. Do not repeat the subject. Put discovery history and earlier attempts here rather than in code comments.
- Keep agent-added trailers such as `Co-Authored-By` and session links.
- Apply the subject rules to PR titles, because a squash merge uses that title on the main branch.
- Small ordered branch commits are valid. Put a fix and its test or script together so every commit passes its checks.

Follow a repo's commitlint configuration or local commit rules when present.
Pliki w paczce (6)
  • SKILL.md 8 KB
  • references/adr.md 5 KB
  • references/instruction-files.md 3 KB
  • references/pr-and-commits.md 5 KB
  • references/technical-writing.md 8 KB
  • references/unslop.md 5 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · vahaah/astack100MIT
hassan-mohiddin/freeflow100MIT
alchemy-run/alchemy100Apache-2.0
Agenta-AI/agenta100MIT
comet-ml/opik100Apache-2.0
jelvodev/yaap100MIT
gosodax/sodax-sdks100MIT
gtriggiano/statica100MIT
browseros-ai/browseros100BSD-3-Clause

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

  • 100shipping
    Prowadzi przez wnoszenie zmian do monorepo FAST: tworzenie pull requestów, plików zmian i opisów PR oraz aktualizację dokumentacji.
  • 100write-architecture-docs
    Pisze i przegląda dokumenty architektury podsystemów oraz ADR-y dla zespołu inżynierskiego w katalogu docs.
  • 100pr-writing
    Pisze i poprawia tytuły oraz opisy PR-ów, commity, changesety, wpisy do changelogu i notki o wydaniach dla odbiorców.
  • 100pr
    Pisze opisy pull requestów i merge requestów.
  • 100pr-writing
    Pisze opisy pull requestów z prawdziwymi dowodami, że zmiana działa, zamiast samego opisu zmian.
  • 100engineering-change-descriptions
    Pisze i poprawia opisy pull requestów, commit messages i podsumowania zmian w kodzie, wyjaśniając, co się zmieniło i dlaczego.

Uwagi i zgłoszenia

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