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.jsonldwird 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?“
| Eigenschaft | Beispiel | Typ | Besitzer |
|---|---|---|---|
| Strukturell | Anzahl H1 / Überschriftsebene / Vorhandensein von Alt-Text / Auflösung lokaler Links / Raster-Dateinamen / Anzahl Badges / DOI in <details> / Prosa-Zeilen direkt nach H1 | structural | Code (readme_lint.py) |
| Semantisch | Packt der Lead den Leser? / Klarheit des Wertversprechens / Kann das LLM allein aus dem README rekonstruieren? / Erzählfluss / Sind Badges nutzlos? | semantic | Ganzheitliches 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):
- Identitäts-Aussage (erste 1-2 Sätze, für sich allein verständlich): „X ist ein {Kategorie}, der {Zielgruppe} {was tut}“
- Gelöstes Problem / Zielgruppe / Differenzierungsmerkmale
- 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
- 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
- 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
| Inhalt | Optimales Format | Grund |
|---|---|---|
| 3-Schritte linear / einfache Aufzählung | Prosa / Liste / kleine Tabelle | Auf 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 Grafiken | Committed SVG (Zoom + Pan möglich) / Subsystem-Aufteilung | Riesige Mermaid-Diagramme stoßen auch auf dem Desktop an Grenzen und zerbrechen auf Mobilgeräten. |
| Echte UI / Ausführungsergebnisse / Fotos | Raster (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). BreiteLRbricht auf schmalen Bildschirmen leicht. - Die Rendergrenze liegt bei Zeichen (Standard
maxTextSize50.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_leadprü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 H1heading_levels— Überschriftsebenen nicht überspringenalt_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 ausgenommenbadge_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-syncdelegieren
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/graphaus 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 (hatgeo_check.pymit forschungsbasierten Metriken). Dieses Skill ist für die menschliche Oberfläche.when-code-when-llm— Entscheidungsachse für strukturell/semantischcontext-sync— Faktenkonsistenz README ↔ mechanische Ebene / Abweichungen (Faktenprüfung ist dorthin delegiert)jsonld-knowledge-graph— Design von graph.jsonldwriting-ecosystem— Orchestrator für menschenlesbare Langtext-Prosainspiration.md— Herkunft des Designs, Provenienz der Primärforschung, Quellen externer Evidenz (ausgelagert aus SKILL.md für Portabilität)