Przejdź do treści
Biblioteka skilli
Programowanie · Pisanie

writing-readmes

/writing-readmes

Pisze, przepisuje lub przegląda README repozytorium, tak by pierwszy ekran mówił, czym jest projekt i dla kogo.

Repozytorium
agent-skills ↗
Licencja
MIT
Ostatnia zmiana repozytorium
13.11.2026

Ocena i bezpieczeństwo

90/ 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ść25 / 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
0
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 robi i kiedy

Pisze, przepisuje lub przegląda README repozytorium, tak by pierwszy ekran mówił, czym jest projekt i dla kogo.

Wyzwalacze z opisu

write the READMEfix the READMEreview the READMEthe readme isn
Oryginalny opis (EN)

Write, overhaul or review a repo's front-door README.md. The first screen says what the project is and who it is for, the quickstart is proven by a cold run, and reference material moves to docs. Use for "write the README", "fix the README", "review the README", "the readme isn't clear", or a README that has grown into a docs dump.

Jak działa

  1. Modes
  2. Steps
  3. Owner decisions
Sekcje z nagłówków SKILL.md, w oryginale · 41 linii, 841 słów
Podgląd SKILL.md
---
name: writing-readmes
description: Write, overhaul or review a repo's front-door README.md. The first screen says what the project is and who it is for, the quickstart is proven by a cold run, and reference material moves to docs. Use for "write the README", "fix the README", "review the README", "the readme isn't clear", or a README that has grown into a docs dump.
---

# writing-readmes

A README is the front door. On the first screen a newcomer learns what the project is, whether it is for them, and how to start. Everything deeper lives in the docs and is linked.

Work on the current repo unless you are given a path. In a monorepo, "the README" is the root README; write a package README only when asked for it. Follow `reference/style.md` for the prose.

In Write mode, when you are in the repo's main checkout (`git rev-parse --path-format=absolute --git-dir --git-common-dir` prints the same path twice), do not edit there: another session may be working in it. Do the whole run on a new branch in a worktree of your own (from the repo root, `git worktree add -b readme ../<repo>-readme`; if that branch or folder exists, pick another name, never reuse or delete it) and give its path and branch in the report. Work in place when the repo has no commits or the README has uncommitted changes.

## Modes

- **Write**: produce or overhaul the README. This is the default.
- **Review**: report only, change nothing. Use it when asked to review, check or audit a README. Run steps 1 and 4 against the existing file and list each finding with its line and the evidence.

## Steps

`<skill>` in a command is this skill's folder, the one that holds this file. Run those scripts by that path, with the target repo as the working directory.

1. Read the repo before the README: the package manifest, the entry points, the CI config, the docs folder, the licence file. Settle the repo type (library, CLI, service, application, framework, monorepo, skills bundle) and the reader. Then read the existing README and mark each claim true, stale or unverifiable against the code.
2. Choose the sections from `reference/anatomy.md` for that repo type. Leave out a section that has nothing true to say.
3. Write.
   - First screen: the name, one sentence that says what it is and who it is for, then three to six highlights. Each highlight is a fact a reader can check (a command, a supported platform, a limit, a measured number), not a claim about quality.
   - Quickstart: the shortest path from nothing to a visible result, in copyable blocks with the expected output. Keep the full install (other platforms, options, configuration) in its own section or in the docs.
   - Move reference material (the full configuration table, every command, deployment) to the docs and leave a two-line summary with a link. Move it; do not delete it. If no docs page exists for it, create one or keep the material and report it.
   - Contributing: link to `AGENTS.md` and `CONTRIBUTING.md` for the commands and rules. Do not repeat them.
   - For a project that agents consume (a CLI, an MCP server, a library, a skills bundle), add the **Use with agents** section from `reference/anatomy.md`.
4. Verify.
   - Quickstart: give a fresh subagent only the README and a clean checkout (`git clone` into a temporary folder, or `git worktree add`), and tell it to follow the quickstart exactly and report each command, its output, and where it had to guess. A guess is a defect in the README. Tell it also to stop before a step that would change what this machine already has in use (a global install, moving an image tag that exists, starting, stopping or reconfiguring a service the quickstart does not own, such as Docker) and to report that step instead; report it as not proven, and ask the owner before running it. Without a subagent, run the quickstart yourself in a clean checkout under the same limit and say that the cold run was not independent.
   - Every other command, flag, default and path: open the code that defines it.
   - Links and paths: run `<skill>/scripts/check-links README.md`. It must report 0 broken.
   - Badges: each badge points at something that exists. The workflow file named in a CI badge is in `.github/workflows/`, the package named in a version badge is published, and the licence badge matches the `LICENSE` file. Remove a badge that fails this.
   - Images: every image path resolves. Never link an image that is not in the repo; list it as something for the owner to supply.
5. Report: what the README now covers, what moved to which docs page, what you could not verify, and the owner decisions.

## Owner decisions

- Licence. For a public repo, or one about to become public, a missing `LICENSE` file is reported, and the README gets no licence section until the owner picks one. Never choose a licence. For a private repo, do not raise it.
- Screenshot or demo. Propose where one would help. Do not fabricate one.
- If the repo is public, check that its description and topics say the same thing as the first sentence. `publishing-a-repo` covers discovery in full.
- `llms.txt` belongs to a hosted docs site, not to a README. Do not add one to a repo without a site.
Pliki w paczce (4)
  • SKILL.md 5 KB
  • reference/anatomy.md 3 KB
  • reference/style.md 2 KB
  • scripts/check-links 9 KB

Wersje

W bazie nie ma innych skilli o nazwie writing-readmes.

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

  • 100readme
    Pisze lub przepisuje README repozytorium tak, by pierwszy ekran pokazywał projekt, a każde twierdzenie dało się sprawdzić.
  • 100readme-writing
    Pomaga pisać README, które dają wartość na pierwszym ekranie, z quickstartem przed referencją i łatwe w utrzymaniu.
  • 100write-readme
    Pisze lub poprawia pliki README, dobierając szablon do odbiorców i rodzaju projektu.
  • 100readme-writer
    Pisze, tworzy i poprawia dopracowane pliki README.md dla projektów, także na podstawie przekazanego repozytorium lub kodu.
  • 95readme
    Tworzy lub aktualizuje plik README.md projektu na podstawie jego kodu i dokumentacji.
  • 100readme
    Tworzy lub aktualizuje README projektu: co to jest, jak zainstalować, używać i zbudować, sprawdzone z repozytorium.

Uwagi i zgłoszenia

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