Communitygithub.com

readme-writer — Human-Facing README Skill

Claude Code Skill: Schreibt und verbessert menschenlesbare READMEs – den einzigen kanonischen Einstiegspunkt für Menschen, Suche und AI Overviews. Das menschenorientierte Gegenstück zu llms-txt-writer. Deterministisches strukturelles Linting + ganzheitliches LLM-Review ohne Bewertung (AKC ADR-0008 Code-LLM-Layering).

Was ist readme-writer — Human-Facing README Skill?

Dieses Skill, `readme-writer`, ist spezialisiert auf das Schreiben und Verbessern von menschenlesbaren READMEs. Es behandelt README als den einzigen kanonischen Einstiegspunkt für Menschen und gleichzeitig als die zuverlässigste Fläche für LLMs beim Grounding (z.B. durch Einfügen einer Repo-URL in KI-Suche/Chat). Der Kern des Skills liegt im Ausbalancieren von kurzer, visueller Aufmerksamkeit für Menschen mit ausreichender Information für LLMs, die das Projekt allein aus dem README rekonstruieren können. Das Skill nutzt einen zweistufigen Prozess: Zunächst ein deterministischer, struktureller Lint (`readme_lint.py`), der Fehler wie fehlende Alt-Texte oder falsche Überschriftsebenen erkennt. Danach folgt ein ganzheitliches LLM-Review, das ohne numerische Bewertung konkrete Verbesserungsvorschläge liefert, z.B. zur Auffindbarkeit der Identität des Projekts, zum Wertversprechen oder zur Frage, ob die Informationen auch ohne die mechanischen Ebenen (llms.txt, graph.jsonld) verständlich sind. Es arbeitet auf Claude Code und folgt dem Code-LLM-Layering-Prinzip, bei dem Code für strukturelle Prüfungen und das LLM für semantische Bewertungen zuständig ist.

Funktioniert mit✓Claude Code~Codex CLI✓Cursor✓Antigravity
npx skills add shimo4228/readme-writer

In Ihrer bevorzugten KI fragen

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

Dokumentation

Was macht readme-writer — Human-Facing README Skill?

Skill zum Schreiben und Verbessern von menschenlesbaren READMEs. Während llms-txt-writer die KI-spezifische Oberfläche übernimmt, ist dieses Skill für die einzige kanonische Einstiegsfläche für Menschen zuständig.

Zusätzlich wichtige Tatsache: Das README ist die einzige Fläche, die LLMs beim Grounding (KI-Suche/Chat mit Repo-URL) zuverlässig als gegeben voraussetzen können. Daher muss das README sowohl „kurz und visuell für Menschen“ sein als auch „eine kleine Informationsbasis hinterlassen, mit der ein LLM das Projekt allein aus dem README rekonstruieren kann“ – diese Vereinbarkeit ist die Kernherausforderung dieses Skills.

Wann verwenden

  • README.md / README.ja.md neu erstellen oder verbessern
  • Die „erste Landeseite für Menschen“ eines Repos/Projekts aufräumen
  • Vorhandene READMEs korrigieren, die „zu maschinenorientiert und für Menschen unvollständig“ / „zu dünn für Menschen, sodass das LLM es nicht erfasst“ sind
  • README kurz und visuell priorisiert halten, ohne die Informationsbasis zu verlieren

Nicht verwenden:

  • llms.txt / llms-full.txt / FAQ etc., die nur für KI bestimmt sind (→ llms-txt-writer)
  • Artikel, Essays, Blogs etc. mit Langtextprosa (→ writing-ecosystem)
  • Design von graph.jsonld (→ jsonld-knowledge-graph)

Die Achse lautet: „AUFMERKSAMKEIT des Menschen × INFORMATION des LLM“

Die eigentlich Optimierungsachse des READMEs ist nicht „Information für Menschen vs. Information für LLMs“. Es ist die Aufmerksamkeit des Menschen (kurz, packend, überfliegbar) × die Information des LLMs (allein aus dem README rekonstruierbar). Beide konvergieren in denselben Maßnahmen (siehe unten), also kein Trade-off, sondern beides durch Design erreichen.

README ist die einzige Fläche, die garantiert gelesen wird (aber nicht die „einzige“)

  • KI-Suche/Zitier-Crawler lesen llms.txt praktisch nicht (mehrere Log-Analysen von 2026 zeigen, dass die Mehrheit null Requests hat; wichtige Suchanbieter lehnen es offiziell ab).
  • graph.jsonld wird beim direkten Fetch als Plaintext behandelt und ersetzt nicht die Fakten des READMEs (Kontrollexperiment).
  • Daher darf man Informationen im README nicht unter der Annahme verdünnen, dass die mechanische Ebene sie „backstoppt“.

Wichtige Kalibrierung: „Das LLM liest nur das README“ ist zu stark. Richtig ist: „Beim generischen Paste-URL/Such-Grounding ist das README die einzige Fläche, die zuverlässig als gegeben vorausgesetzt werden kann“. Es gibt andere Pfade (Suchindex chunkt andere Dateien bereits / Link-Tracking ab README / GitHub-Connector/API legt Dateibaum offen / Wissen aus dem Pretraining). Das stärkste Ergebnis liefert anonymer Live-Web-Grounding und direkter Landing-Fetch. Umgekehrt: Geroutete Coding-Agents (Claude Code, Cursor etc.) lesen llms.txt on-demand, also bleibt llms.txt als Versicherung für den agentischen Kanal gültig – aber nicht als Einstieg für die KI-Suche.


Warum „strukturelles Lint“ und „ganzheitliches Review“ getrennt werden

README-Qualität hat zwei Arten von Eigenschaften. Nach dem Code-LLM-Layering (Struktur gehört zu 100% präzise zum Code, Bedeutung zum LLM) werden die Besitzer getrennt. Das Entscheidungskriterium ist when-code-when-llm: „Kann dieselbe Bytesequenz je nach Kontext unterschiedliche Bedeutung haben?“

EigenschaftBeispielTypBesitzer
StrukturellAnzahl H1 / Überschriftsebene / Vorhandensein von Alt-Text / Auflösung lokaler Links / Raster-Dateinamen / Anzahl Badges / DOI in <details> / Prosa-Zeilen direkt nach H1structuralCode (readme_lint.py)
SemantischPackt der Lead den Leser? / Klarheit des Wertversprechens / Kann das LLM allein aus dem README rekonstruieren? / Erzählfluss / Sind Badges nutzlos?semanticGanzheitliches LLM-Review

Es werden keine numerischen Bewertungen für READMEs erstellt. Abschnittsverhältnisse bei llms.txt (ski-ramp etc.) sind deterministische Signale, die durch KI-Zitierforschung validiert wurden, aber ob ein README ein „guter Einstieg“ ist, ist eine semantische Entscheidung ohne gleichwertige deterministische Erkenntnisse. KI-Oberflächenmetriken wie Entity-Dichte in menschliche READMEs zu übernehmen, ist ein Anti-Pattern.

Aber „strukturelle KI-Lesbarkeit“ wird aktiv übernommen (Zwei-Seiten-Regel)

„KI-Oberflächenmetriken nicht übernehmen“ gilt nur zur Hälfte. Das Prinzip ist: „Wie die Idee vermittelt wird, darf optimiert werden (keine Obergrenze). Was die Idee ist, darf niemals verbogen werden.“

  • Übernommen (unbegrenzte Stärke): Überschriftshierarchie, Informationsdesign, Entity-Anchoring (Autorenname / ORCID / DOI / kanonische Identifikatoren im Fließtext), Anchoring eigener/fachspezifischer Begriffe, Answer-First Lead, At-a-Glance-Tabellen. Diese wirken sowohl für Menschen als auch für LLMs auf dem Grounding-Pfad – Konvergenzzone.
  • Verboten: Keyword-Stuffing, Aufblähen von Attributen, Farming von Fragenüberschriften, Glossary-Dumping, Verzerrung von Behauptungen zugunsten einer Retrieval-Reward-Funktion. Zitate und Sterne sind keine Erfolgsmetriken, also gibt es gar kein Ziel, dem eine Verzerrung dienen könnte.

Minimale LLM-Read-Floor (klein, nicht verhandelbar, nicht aufblähen)

Regel: Wenn das LLM nur das README liest (weder llms.txt noch graph), muss es das Projekt allein aus dem Text rekonstruieren können.

Floor-Elemente (in Prosa / Markdown / Mermaid. Nicht nur in Bildern, nur in <details>, nur hinter Links):

  1. Identitäts-Aussage (erste 1-2 Sätze, für sich allein verständlich): „X ist ein {Kategorie}, der {Zielgruppe} {was tut}“
  2. Gelöstes Problem / Zielgruppe / Differenzierungsmerkmale
  3. Kanonische Fakten: Echter Name / Sprache/Stack/Status. Forschungs-/DOI-Repos zusätzlich: DOI + Zitierhinweis (BibTeX / CITATION) + 3-6 Core-Concept-Definitionen, die die Fachbegriffe stützen
  4. Genau ein konkretes Beispiel: Bei Code: Funktionssignatur + minimales ausführbares Stück (keine vollständige Implementierung – aufblähend + Halluzination auslösend) / Bei Forschung: Kernaussage + 2-3 Schlüsselzahlen
  5. Link-Map zu tieferen Docs: nur Pointer. Keine tragenden Fakten nur in Links / llms.txt / graph ablegen

Wichtigste Falle: Der Floor ist ein kleiner, nicht verhandelbarer Kern. Wenn man „nicht kürzen, sondern umstrukturieren“ zu stark anwendet, wird das README durch in Mermaid / Details / Floor-Abschnitten gehortete Informationen zu einem getarnten llms-full.txt aufgebläht. Das menschliche Ziel war kurz. Alles außer dem Floor wird gnadenlos gekürzt oder ausgelagert (→ Length Budget).

Wenn graph.jsonld / llms.txt aus dem README erstellt werden, die README-Prosa nicht als strukturelle Quelle verwenden. Identifikatoren und Graph-Kanten werden aus CITATION.cff / .zenodo.json / einem kleinen Manifest im Frontmatter abgeleitet (manuelle parallele Kopien driften).

Auch die Metadaten von GitHub (Repo-Beschreibung / Topics / Social-Preview / CITATION-Datei / Release / Package-Metadaten) sind Teil des Floor, der beim Grounding wirkt. Sie werden nicht im README-Text gesetzt (erfolgt durch gh repo edit / release-doi), aber als Checkliste prüfen, ob sie vorhanden sind.


Visual-First (Mermaid zuerst, Raster zuletzt)

Die korrekte Interpretation von „kurz und visuell“ ist „Prosa-Wände in überfliegbare Strukturen komprimieren“, nicht Prosa in Bilder umwandeln. Und „Mermaid zuerst“ ≠ „alles in Mermaid“ – zuerst prüfen, ob überhaupt eine Grafik nötig ist. Ein Format wählen, das auf Mobilgeräten (schmaler Bildschirm) nicht zerbricht und das LLM aufnehmen kann.

Formatwahl

InhaltOptimales FormatGrund
3-Schritte linear / einfache AufzählungProsa / Liste / kleine TabelleAuf allen Geräten (insb. Mobil) lesbar. Lohnt keine Grafik.
Wirklich Graph-förmig (Beziehungen, viele Verzweigungen, Matrix)Mermaid (TD vertikal)Quelle ist Text, auch vom LLM lesbar. Vertikales Scrollen ist auf Smartphones natürlich, horizontal (LR) zerbricht.
Große / komplexe GrafikenCommitted SVG (Zoom + Pan möglich) / Subsystem-AufteilungRiesige Mermaid-Diagramme stoßen auch auf dem Desktop an Grenzen und zerbrechen auf Mobilgeräten.
Echte UI / Ausführungsergebnisse / FotosRaster (PNG/JPG/WebP/GIF)Nur das, was Mermaid nicht darstellen kann.

Zu jeder Grafik muss zwingend ein Satz textuelles Äquivalent hinzugefügt werden (harte Regel). Dies garantiert, dass es sowohl bei Menschen als auch bei LLMs ankommt: Es rettet gleichzeitig den Menschen, bei dem die Grafik auf dem Handy zerbricht, den LLM-Extraktor, der den Mermaid-Fence als opaken Code überspringt, und den Screenreader. Die Grafik ist der visuelle Bonus obendrauf, nicht der alleinige Informationsträger.

Mermaid-Grundlagen

  • GitHub rendert nativ als theme-aware SVG. Die Quelle ist Text (diff-fähig, ~10 Token/Kante) und wird auch von text-only-Crawlern gelesen, die keine Pixel sehen können. Strukturen, die in Prosa/Grafiken versteckt sind (Concept-Matrix, Phasenbindung, Pipeline-Stufen), werden durch Mermaid kürzer und informationsdichter.
  • Priorität Mobilgeräte: TD (vertikal). Breite LR bricht auf schmalen Bildschirmen leicht.
  • Die Rendergrenze liegt bei Zeichen (Standard maxTextSize 50.000) + Kanten, nicht bei der Knotenzahl („50-100 Knoten sind die Grenze“ ist ein Gerücht). Bei Überschreitung in Subsysteme aufteilen. In speziellen Projekt-READMEs wird nicht gerendert.
  • Da Extraktoren Mermaid möglicherweise fallen lassen, die Bedeutung stets separat durch das textuelle Äquivalent (siehe oben) absichern.

Raster / Sonstiges

  • Raster dürfen keine tragenden Informationen enthalten. Alt-Text ist Pflicht (harter Floor: Der Text-Pfad liest nur den Alt = Bilder ohne Alt sind für LLMs unsichtbar – das betrifft nicht nur die Barrierefreiheit).
  • Dark/Light mit <picture><source media="(prefers-color-scheme: …)"><img alt="…"></picture>. <img alt> ist doppelt tragend.
  • Bild-Assets werden im Repo committed und relativ referenziert. Externe Hotlinks (Camo bricht) und inline/animated <svg>/<embed>/<object> (GitHub sanitized) vermeiden.
  • Badges: nur 2-4 hochsignifikante (CI / Version / Lizenz / bei Forschungs-Repos DOI). Vanity-Badges vermeiden. Anzahl begrenzen, damit die Badge-Zeile auf schmalen Bildschirmen nicht überquillt.
  • CLI-Repo: asciinema→agg-GIF + ein Satz Caption. UI-Repo: Screenshot/GIF + Alt-Text.

Seltene, maßgeschneiderte Grafiken: Claude Artifacts / Claude Code SVG- oder Diagram-Skill verwenden, um committable SVGs zu generieren und in assets/ abzulegen.


Length Budget (keine Wortzahlziele)

Es werden keine Wortzahlziele gesetzt („500-1500 Wörter Sweet Spot“, „visuelles README bringt mehr Sterne (GitHub-Studie)“ – beides als erfunden/quellenlos verworfen). Stattdessen:

  • Above the fold (erster Bildschirm = 30 Sekunden, um zu entscheiden, ob es für einen selbst ist): Beliebiges Hero → H1 → einzeiliger Tagline (Wertversprechen = die Zeile, die das LLM am zuverlässigsten extrahiert) → ≤4 funktionale Badges → Floor-Fakten → Copy-Paste Quick Start. Tiefe Begründung danach.
  • Reihenfolge variiert nach Repo-Typ: „Quickstart → Rationale“ gilt für Software. Bei Paper / Dataset / Concept / DOI-Essay-Repos nicht anwendbar. Keine feste Reihenfolge erzwingen, nur „Identität + kanonische Fakten vor tiefer Begründung“ einhalten. Der Lint identity_lead prüft strukturell nur die Existenz des Lead-Satzes und erzwingt keine Reihenfolge.
  • Die Gesamtmenge wird durch eine Variable bestimmt: Absorbiert die kanonische Doc-Site / die ADRs die Tiefe? Tiefes „Warum“/Design-Rationale wird in ADR / docs/ / llms-full.txt / hinterlegtes Paper verschoben, das README enthält nur einen Einzeiler-Pointer (Diátaxis' Explanation-Displacement). Das ist die direkte Behandlung eines „450-Zeilen-Forschungs-READMEs“.
  • <details> nur für sekundäre Mengen (Options-Tabelle / FAQ / Troubleshooting / vollständiges Glossar). Organisiert die menschliche Sicht, ist aber für das LLM sichtbar. Aber keinen Floor hineinlegen (Verlust der Primacy + Ctrl+F nicht möglich. Raw-Markdown-Pfad liest es zwar, aber Summarizer auf gerenderten Seiten könnten eingeklappte Bereiche de-priorisieren).

Workflow (Code-Filter → LLM-Review → menschliches Gate)

1. Code-Filter — readme_lint.py (deterministisch, nur strukturell)

uv run --directory ~/.claude/skills/readme-writer python -m scripts.readme_lint "$ARGUMENTS"

Argument ist der absolute Pfad zum README. --json für maschinenlesbare Ausgabe. Exit-Code ist das Code-eigene Gate (0=clean oder nur Warnings / 1=Fehler-Schweregrad vorhanden / 2=nicht gefunden/zu groß).

Prüfungen (keine Bewertung, sondern konkrete Issues. 2 Schweregrade):

Error (fällt durch das Gate, harte Struktur)

  • single_h1 — Genau 1 H1
  • heading_levels — Überschriftsebenen nicht überspringen
  • alt_text — Alle Bilder haben Alt-Text (harter Floor: kein Alt = für LLM unsichtbar)
  • local_link — Lokale relative Links / Bild-Quellen existieren

Warning (Hinweis, fällt nicht durch das Gate) — Strukturell erkennbar, aber ob es wirklich ein Problem ist, ist eine semantische Entscheidung; daher nur die Oberfläche prüfen. Semantische Entscheidung dem LLM-Review überlassen:

  • raster_diagram_hint — Bildname, der auf Diagramm hindeutet (architecture/flow/diagram/pipeline etc. als .png/.jpg/.webp/.gif) → Mermaid-Konvertierung vorschlagen. SVG, Screenshots, Logos ausgenommen
  • badge_budget — Zu viele Badges (Standard >6). Nur die Anzahl prüfen (ob Vanity oder nicht, entscheidet das LLM)
  • details_floor_leak — <details> enthält DOI / BibTeX / CITATION-Token (Anzeichen für Floor-Leck. „Ob wirklich Floor“ entscheidet das LLM)
  • identity_lead — Kein Prosa-Lead-Satz zwischen H1 und erstem Abschnitt (erzwingt keine Reihenfolge. Fehlender H1 wird von single_h1 abgedeckt)
  • doi_citation_pairing — DOI vorhanden, aber kein Zitierhinweis (Citation-Abschnitt / BibTeX / CITATION.cff) (erzwingt DOI nicht bei Nicht-Forschungs-Repos – feuert nur, wenn DOI vorhanden ist)

2. LLM Ganzheitliches Review (Rubric-as-Lens, keine Bewertung, Signal-First)

Wenn der Lint bestanden ist, liest Claude das README ganzheitlich und gibt mit folgenden Linsen konkrete Befunde + konkreten Diff aus:

  • 🚀 README-only Recovery (Flaggschiff, höchster Hebel) — Nur den Text des READMEs lesen und prüfen, ob (Identität / Zielgruppe / Problem / Differenzierung / ggf. DOI + Zitierhinweis / 3-6 Core Concepts / 1 Beispiel / Link zur nächsten Stufe) rekonstruiert werden kann. Fehlendes konkret auflisten („Zielgruppe nicht genannt“ etc.). Keine Bewertung. Dies ist die operative Umsetzung des „Minimalen LLM-Read-Floors“.
  • Lead: Was / Wer / Warum — Vermittelt der erste Bildschirm: „Was, für wen, warum sollte ich mich darum kümmern?“
  • Menschlicher Haken / Wertversprechen — Wird der Wert konkret und nicht in abstrakten Worten vermittelt?
  • Erzählung / Scannability — Sind Absätze, Überschriften, Listen, Mermaid für Menschen nachvollziehbar?
  • Kürzeprüfung (wichtigste Rückwärtskontrolle) — Wurde alles außer dem Floor ausgelagert? Wurde das README durch in Mermaid / Details / Floor gehortete Informationen zu einem getarnten llms-full.txt aufgebläht?
  • Angemessenheit der Visuals — Ist die Grafik in Mermaid (wenn Raster: Mermaid-Konvertierung oder Textäquivalent vorhanden?). Sind Badges hochsignifikant (keine Vanity)?
  • Faktenkonsistenz — Widersprechen Behauptungen der mechanischen Ebene (llms.txt / graph.jsonld)? → an context-sync delegieren

Grund für keine Bewertung (Signal-First + Scaffold-Dissolution): Nur Informationen ausgeben, „die das nächste Handeln ändern“. Lead: 6/10 ändert das Handeln nicht. „Lead sagt nicht, für wen es ist“ ändert das Handeln. Ausgabe im Diff-Format, aufgeteilt in y/n-genehmigbare Granularität. Für Author-Reviewer-Separation sollte das Review idealerweise in einem separaten Agentenprozess (analog zu editor / essay-reviewer) laufen.

3. Faktenkonsistenz prüfen → context-sync

Ob die Fakten des READMEs mit llms.txt / llms-full.txt / graph.jsonld übereinstimmen (Cloaking vermeiden), ist die Aufgabe von context-sync. Dieses Skill implementiert keine eigene Prüfung.

4. Menschliches Gate

Der Diff wird vom Menschen genehmigt und angewendet.


Was dieses Skill NICHT tut (Abgrenzung)

  • Schreibt kein llms.txt / llms-full.txt (→ llms-txt-writer)
  • Designt kein graph.jsonld (→ jsonld-knowledge-graph)
  • Erkennt/synchronisiert keine oberflächenübergreifenden Abweichungen (→ context-sync / release-doi)
  • Editiert keine Artikel / Essays (→ writing-ecosystem)
  • Setzt keine Repo-Beschreibung / Topics / Social-Preview (Aufgabe von gh repo edit / release-doi. Dieses Skill präsentiert sie nur als Checkliste)
  • Gibt keine Qualitätsbewertung / Note / Punktzahl aus

Anti-Patterns

  • Nur numerische Bewertung ohne konkrete Vorschläge liefern (Recommender-Falle)
  • Semantische Entscheidungen durch das LLM treffen lassen, die strukturell durch Code gelöst werden könnten / Semantische Entscheidungen durch Regex ersetzen (siehe when-code-when-llm)
  • KI-Oberflächenmetriken (ski-ramp / Entity-Dichte / Farming von Fragenüberschriften) auf menschliche READMEs anwenden (Lesbarkeitseinbuße)
  • „Visuell priorisiert“ als Umwandlung von Prosa in Bilder interpretieren (Raster-Grafiken sind für text-only-LLMs unsichtbar = Information vor dem Agenten versteckt. Mermaid verwenden)
  • „Nicht kürzen, sondern umstrukturieren“ zu stark anwenden, sodass das README zu einem getarnten llms-full.txt wird (Floor klein halten, alles andere gnadenlos kürzen/auslagern)
  • README-Floor unter der Annahme verdünnen, dass die mechanische Ebene (llms.txt/graph) sie backstoppt (wird auf dem Grounding-Pfad nicht gelesen)
  • llms.txt/graph aus der README-Prosa ableiten (Drift. Aus Manifest ableiten)
  • Fakten für Menschen aufblähen / Monetarisierungsappelle hinzufügen (Authentizitätsschaden + Widerspruch zur mechanischen Ebene = Cloaking. Verpackung ändern, Behauptung nicht)

Verifikation

cd ~/.claude/skills/readme-writer
uv sync --dev
uv run pytest tests/ --cov=scripts --cov-report=term-missing

fixtures/sample_clean.md (0 Issues, Best-Practice-Beispiel mit Mermaid) und fixtures/sample_issues.md (Beispiel, das alle 9 Prüfungen auslöst) zeigen das grundlegende Verhalten.


Verwandte

  • llms-txt-writer — Das Gegenstück für die KI-Oberfläche (hat geo_check.py mit forschungsbasierten Metriken). Dieses Skill ist für die menschliche Oberfläche.
  • when-code-when-llm — Entscheidungsachse für strukturell/semantisch
  • context-sync — Faktenkonsistenz README ↔ mechanische Ebene / Abweichungen (Faktenprüfung ist dorthin delegiert)
  • jsonld-knowledge-graph — Design von graph.jsonld
  • writing-ecosystem — Orchestrator für menschenlesbare Langtext-Prosa
  • inspiration.md — Herkunft des Designs, Provenienz der Primärforschung, Quellen externer Evidenz (ausgelagert aus SKILL.md für Portabilität)

Verwandte Skills