README-Schreiber

Schreibt oder überarbeitet ein Projekt-README, das Besucher in Nutzer und Mitwirkende verwandelt – mit einzeiligem Pitch, Badges, einem 60-Sekunden-Schnellstart, echten Beispielen, Funktionen, FAQ, Mitwirkungs- und Lizenzabschnitten – und prüft es auf fehlende Abschnitte, defekte relative Links, nicht existierende Anker im Inhaltsverzeichnis, fehlenden Alternativtext und einen späten ersten Codeblock. Verwende es, wenn der Nutzer bittet, ein README zu schreiben, zu verbessern, zu überprüfen oder umzustrukturieren, sagt, dass niemand das Projekt versteht oder mit Sternchen versieht, oder wenn eine Open-Source-Veröffentlichung vorbereitet wird.

Was ist README-Schreiber?

Dieses Skill für KI-Agenten (wie Claude Code, Cursor oder Codex) schreibt oder überarbeitet README-Dateien mit dem Ziel, Besucher in Nutzer und Mitwirkende zu verwandeln. Es stellt sicher, dass das README in weniger als einer Minute vom ersten Eindruck zum funktionierenden ersten Befehl führt. Der Skill sammelt zuerst Fakten aus dem Projektmanifest, der CLI-Hilfe und vorhandenen Dokumenten und fragt den Nutzer nur nach Dingen, die der Code nicht verraten kann. Dann lintet es das bestehende README nach definierten Regeln (fehlende Abschnitte, defekte Links, späte Codeblöcke) und schreibt oder überarbeitet es nach einer festgelegten Struktur mit Titeln, Badges, Pitch, Schnellstart, Beispielen, FAQ, Mitwirkungs- und Lizenzabschnitten. Abschließend wird das README erneut gelintet und die Links werden überprüft. Der Skill eignet sich für neue Projekte, dünne oder weitschweifige READMEs, vor Veröffentlichungen oder wenn ein Projekt zwar Besuche, aber kaum Sterne, Installationen oder Mitwirkende erhält. Er vermeidet API-Referenzen, lange Tutorials oder Architekturdokumente, die besser in separaten Dokumenten und verlinkt werden sollten.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/saizul/oss-maintainer-skills/tree/HEAD/skills/readme-writer

Installed? Explore more Produktivität & Zusammenarbeit skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht README-Schreiber?

Ein README hat eine Aufgabe: einen Besucher von „Was ist das?“ zu einem funktionierenden ersten Befehl in unter einer Minute zu bringen und ihm dann zu zeigen, wie er weitermachen und wie er helfen kann.

Verwendungszweck

  • Ein README für ein neues Projekt schreiben oder ein dünnes oder weitschweifiges umschreiben
  • Ein README vor einer Veröffentlichung oder einem 1.0-Release überprüfen
  • Der Nutzer sagt, das Projekt wird besucht, bekommt aber keine Sterne, Installationen oder Mitwirkende

Wann nicht verwenden

  • API-Referenzdokumentation (aus dem Code generieren; vom README aus verlinken)
  • Lange Tutorials oder Architekturdokumente: in docs/ ablegen und verlinken

Arbeitsablauf

  1. Fakten vor dem Schreiben sammeln. Das Manifest (pyproject.toml, package.json, composer.json, Cargo.toml...), die CLI --help oder den Haupteinstiegspunkt, vorhandene Dokumente und die Lizenz lesen. Den echten Installationsbefehl und ein echtes Beispiel finden. Niemals Flags, Ausgaben, Benchmarks oder Funktionen erfinden.

  2. Den Nutzer nur fragen, was der Code nicht verraten kann: für wen das Projekt ist, das eine Problem, das es löst, und warum es besser ist als die offensichtliche Alternative. Wenn sie nicht verfügbar sind, einen neutralen Pitch aus dem Code schreiben und zur Überprüfung markieren.

  3. Das aktuelle README linten (falls vorhanden). scripts/ ist relativ zu diesem Skill:

    python3 scripts/readme_lint.py README.md
    python3 scripts/readme_lint.py README.md --json --strict
    
  4. Mit der Struktur aus structure.md schreiben, beginnend mit der Vorlage. Die Reihenfolge ist wichtig: Titel + Badges, Pitch, (Demo-Bild), Schnellstart, Funktionen, Nutzung/Beispiele, Konfiguration, FAQ, Roadmap, Mitwirkende, Lizenz.

  5. Die Schreibregeln anwenden:

    • Pitch: ein Satz, unter 200 Zeichen, keine Übertreibungen. Muster: „<name> ist ein(e) <Kategorie>, die <macht X> für <Zielgruppe>, <Hauptunterscheidungsmerkmal>.“
    • Erster Codeblock vor Zeile 60. Jeder Befehl muss kopierbar und echt sein.
    • Ausgabe nach Befehlen zeigen, wo es hilft (# => ... oder ein separater Block).
    • Tabellen für Optionen und Vergleiche verwenden, Listen für Funktionen (zuerst den Nutzen nennen).
    • Verlinken, nicht einfügen: lange Dokumente, Änderungsprotokolle und API-Referenzen gehören woanders hin.
    • Jedes Bild erhält Alternativtext; SVG oder kurzes GIF des Hauptablaufs bevorzugen.
  6. Badges. Nur Badges verwenden, die wahr und gepflegt sind, in dieser Reihenfolge: CI-Status, aktuelle Version (PyPI/npm/Packagist/Release), Downloads (optional), Lizenz. Beispiele in structure.md.

  7. Erneut linten, bis keine Fehler mehr vorhanden sind. Warnungen beheben oder dem Nutzer erklären, warum nicht.

  8. Die Links überprüfen, die der Linter nicht prüft: absolute URLs und Anker. Klicktest oder erklären, welche nicht verifiziert wurden.

Ausgabe

  • Die neue oder aktualisierte README.md (bei Umschreibungen eine Diff-Zusammenfassung zeigen).
  • Das endgültige Lint-Ergebnis.
  • Eine kurze Liste von Fakten, die nicht verifiziert werden konnten, und Platzhaltern, die der Nutzer ausfüllen muss (Demo-GIF, Screenshots, Benchmark-Zahlen).

Lint-Regeln

RegelStufeBedeutung
titleFehler/Warnunggenau eine H1
pitchFehler/Warnungein kurzer erster Absatz unter dem Titel
badgesWarnungkein Badge gefunden
installFehler/WarnungAbschnitt zur Installation (oder Schnellstart), mit einem Codeblock
quickstartFehler/WarnungAbschnitt zur Nutzung, Schnellstart oder Beispiel, mit Code
codeFehlerüberhaupt kein Codeblock
scrollWarnungerster Codeblock nach --max-scroll Zeilen (Standard 60)
contributing, licenseWarnungfehlender Abschnitt
faq, tocInfoempfohlen
alt-textWarnungBild ohne Alternativtext
broken-linkFehlerrelativer Link zu einer fehlenden Datei oder ein leerer Link
broken-anchorFehler#anker-Link (Inhaltsverzeichnis), der auf keine Überschrift oder kein id/name-Attribut im HTML verweist, unter Verwendung der GitHub-Slug-Regeln
placeholderWarnungTODO, TBD oder Lorem Ipsum hinterlassen

Exit 1 bei Fehlern (und bei Warnungen mit --strict).

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Verwandte Skills