Przejdź do treści
Biblioteka skilli
Programowanie · Przegląd i audyt

writing-docstrings

/writing-docstrings

Pisze, przepisuje i audytuje docstringi Pythona, z których powstaje strona dokumentacji, tak aby czytelnik wygenerowanego odniesienia umiał się w nim odnaleźć.

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

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

Licencja

CC0-1.0, otwarta.

Co robi i kiedy

Pisze, przepisuje i audytuje docstringi Pythona, z których powstaje strona dokumentacji, tak aby czytelnik wygenerowanego odniesienia umiał się w nim odnaleźć.

Wyzwalacze z opisu

audit the docstringsdocstring slopdocstrings as documentationthe API reference reads badlyrewrite these docstrings
Oryginalny opis (EN)

Use when writing, rewriting, or auditing Python docstrings that a documentation site is generated from, or when docstrings are long, narrate the code, or leave a reader of the generated reference unable to find their way. Triggers - "audit the docstrings", "docstring slop", "docstrings as documentation", "the API reference reads badly", "rewrite these docstrings".

Jak działa

  1. When to Use
  2. When Not to Use
  3. Invocation Notice
  4. Workflow
  5. Output
  6. References
Sekcje z nagłówków SKILL.md, w oryginale · 58 linii, 496 słów
Podgląd SKILL.md
---
name: writing-docstrings
description: Use when writing, rewriting, or auditing Python docstrings that a documentation site is generated from, or when docstrings are long, narrate the code, or leave a reader of the generated reference unable to find their way. Triggers - "audit the docstrings", "docstring slop", "docstrings as documentation", "the API reference reads badly", "rewrite these docstrings".
---

# Writing Docstrings

Docstrings that a site is generated from are the product's documentation.
Each one states what a reader needs, in a fixed place, in plain language.

## When to Use

- A documentation site (great-docs, quartodoc, mkdocstrings, Sphinx autodoc) renders the package's docstrings.
- An audit of docstrings for length, body narration, rationale, history, or vague wording.
- A rewrite of docstrings after an API change, where the reference must stay accurate.
- A new public function, class, or module needs a docstring that matches the rest.

## When Not to Use

- Comments inside a body, or slop in code: use `simplify`.
- Narrative documentation pages, tutorials, or a docs site built from prose: use `scaffold-docs`.
- Commit messages: use `commit-message`.

## Invocation Notice

- Tell the user when this skill is running: `writing-docstrings`.
  Skip the notice when the user asked for the skill by name or slash command; spelling and spacing need not match.
  A phrase from this skill's own trigger list is not a name — naming the work is not naming the skill.

## Workflow

1. Find what the site renders.
   Read the docs configuration for the parser and for the objects that get pages.
   A docstring of an object without a page is a maintainer note, not documentation.
   When the configuration does not settle it, probe the renderer with a throwaway package (`references/renderer-probe.md`).
2. Classify each docstring by level: landing page, module page, class, function or method, or not rendered.
   The level sets the register and the shape (`references/shape.md`).
3. Calibrate with the user before any bulk edit.
   Bring three docstrings at a time, of different levels or kinds.
   For each, quote it, give a verdict, name what fails, and show the rewrite.
   Use length only as a first filter: a long docstring can be all contract, and a short one can be too dense to read.
   Continue until the user agrees with the verdicts.
4. Write or rewrite to the shape and the register (`references/register.md`).
   Verify every fact against the code before you state it; read the body, the tests, or run it.
   Add a missing contract fact, such as a default or an error, when a reader needs it.
5. For more than about 30 docstrings, run the work in parallel with separate review sweeps (`references/parallel-run.md`).
6. Rebuild the site, or the renderer probe, and check that sections, links, and examples render.

## Output

- Rewritten docstrings, each true against the code and placed in the shape for its level.
- Body comments for rationale that guards against a wrong fix; other rationale deleted.
- Documentation-site configuration changes, when module pages or sections need them.

## References

- `references/shape.md`: the labeled sections and the shape for each level.
- `references/register.md`: reference and explanation registers, plain language, and what to keep and cut.
- `references/examples.md`: calibrated before-and-after examples.
- `references/renderer-probe.md`: how to check what a renderer does with a docstring.
- `references/parallel-run.md`: writer brief, batching, and review sweeps.
Pliki w paczce (6)
  • SKILL.md 3 KB
  • references/examples.md 6 KB
  • references/parallel-run.md 2 KB
  • references/register.md 3 KB
  • references/renderer-probe.md 2 KB
  • references/shape.md 3 KB

Wersje

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

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

  • 100write-docstrings
    Pisze i sprawdza docstringi w repozytorium, gdy trzeba dodać nowe, przejrzeć istniejące albo je zmienić.
  • 95docstring
    Pisze docstringi dla funkcji i metod PyTorch zgodnie z konwencjami PyTorch, także przy ich aktualizacji.
  • 100documentation-generation
    Generuje dokumentację projektu: README, docstringi (JSDoc, JavaDoc, Python), opisy OpenAPI i potoki dokumentacji w CI/CD.
  • 95documenting-python-libraries
    Pisze dokumentację biblioteki Python: docstringi w stylu Google, konfigurację Sphinx, referencje API i poradniki.
  • 100numpy-docstrings
    Pisze i recenzuje docstringi w stylu NumPy dla publicznych API Pythona, z właściwą kolejnością sekcji, parametrami, wartościami zwracanymi, wyjątkami i przykładami.
  • 100document-code
    Stosuje standardy dokumentowania Google Style w kodzie Python, Go, TypeScript i Terraform: docstringi, komentarze, JSDoc oraz opisy zmiennych i wyjść Terraform.

Uwagi i zgłoszenia

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