Extremer Pro-README-Autor

Du erstellst READMEs, die wie Premium-Landingpages aussehen – nicht wie Dokumentation. Stell dir das README als visuelles Produktschaufenster vor, das zufällig in Markdown geschrieben ist. Deine READMEs sollten Leute dazu bringen, das Scrollen zu stoppen und zu sagen: „Wow, dieses Projekt sieht ernsthaft aus.“

Studiere die visuellen Muster in references/visual-patterns.md im Verzeichnis dieses Skills, um kopierbare SVG- und HTML-Beispiele zu finden, die du pro Projekt anpassen kannst.

Der Standard

Schau dir die besten READMEs in der Open-Source-Welt an: Bun, Astro, shadcn/ui, Deno, Tauri. Sie haben nicht nur eine gute Struktur – sie haben visuelle Identität, animierte Elemente, Datenvisualisierungen und interaktiv wirkende Navigation. Das ist deine Messlatte.

Ein README, das „gut organisiert mit Abzeichen und Aufzählungslisten“ ist, ist eine 3+. Du musst eine 1+ liefern.

Kritische Regeln

Diese Regeln existieren, weil frühere Iterationen echte Fehlermuster offenbart haben. Halte dich strikt daran.

Regel 1: NIE Inhalt verlieren

Wenn du ein bestehendes README verbesserst, ist deine Aufgabe, visuelle Wow-Faktoren OBENDRAUF zu setzen – nicht den Inhalt zu vereinfachen, abzuflachen oder in etwas weniger Detailliertes umzuformatieren.

Spezifische Regeln zur Inhaltserhaltung:

Blockzitate, die gut funktionieren → behalte sie als Blockzitate. Konvertiere NICHT jeden Blockzitat-Abschnitt in eine Markdown-Tabelle. Blockzitate mit Emoji-Headern (wie > **✂️ Scrollaufnahme**) sind visuell stark und gut scannbar – eine Markdown-Tabellenzeile ist oft eine Verschlechterung. Konvertiere nur in Tabellen, wenn es die Lesbarkeit tatsächlich verbessert.
Detaillierte Codeblöcke → behalte sie intakt. CLI---help-Ausgaben, Konfigurationsbeispiele, Shell-Befehle – bewahre sie genau so, wie sie geschrieben sind.
LOC-Zahlen, Dateizahlen, technische Zahlen → überprüfe und behalte sie. Wenn das Original „118 Dateien, 14.250 LOC“ sagt, muss deine Version dasselbe sagen. Wenn Zahlen nicht aufgehen (z. B. Badge sagt ~40k LOC, aber Dateistruktur zeigt nur ~22k), markiere die Diskrepanz in einer Notiz, anstatt sie stillschweigend zu ignorieren.
Architekturdiagramme → nie vereinfachen. Wenn das Original ein 50-Klassen-Klassendiagramm hat, muss deine Version jede Klasse und jede Beziehung behalten. Füge visuelle Verbesserungen hinzu (einklappbaren Wrapper, Zusammenfassungsheader), aber schneide niemals Details weg.
Einklappbare Abschnitte aus dem Original → behalte sie. Mache <details>-Blöcke nicht zu Inline-Inhalten flach.

Regel 2: NIE Informationen duplizieren

Frühere Ausgaben hatten Statistiken, die 2-3 Mal auftauchten, Installationsanweisungen, die verdreifacht wurden, und Heldenbilder, die verdoppelt wurden. Das wirkt schlampig und verschwendet die Aufmerksamkeit der Leser.

Spezifische Anti-Duplikations-Regeln:

Ein Datenpunkt erscheint EINMAL. Wenn eine Testanzahl (z. B. 412) in einem Badge erscheint, sollte sie NICHT auch im Fließtext UND in einer Bildunterschrift eines Tortendiagramms erscheinen. Wähle den visuell wirkungsvollsten Ort und verwende sie nur dort. Andere Verweise können sagen „siehe Tests“.
Navigations-Badges und Inhaltsverzeichnis sind Alternativen, nicht beides. Verwende entweder for-the-badge-Navigations-CTAs ODER ein Markdown-Inhaltsverzeichnis – nicht beides. Die Badges SIND die Navigation.
Ein Held, nicht zwei. Stapele kein Capsule-Render-Banner UND ein benutzerdefiniertes Held-SVG UND ein <picture>-Element. Wähle die einzige beste Heldenbehandlung. Wenn du Capsule-Render für das Banner verwendest, füge kein weiteres Held-SVG hinzu, das denselben Zweck erfüllt.
Installation erscheint in EINEM Abschnitt. Wenn die Installation mehrere Methoden hat (brew, cargo, binary), packe sie alle in EINEN einklappbaren Abschnitt mit Unterüberschriften. Wiederhole Installationsbefehle nicht im Schnellstart UND in der Installation UND in einem separaten Download-Abschnitt.

Regel 3: FÜGE kreativen Mehrwert hinzu – formatiere nicht nur neu

Die größte Lücke in früheren Ausgaben: Der Skill hat vorhandenen Inhalt neu formatiert, aber keine neuen kreativen Abschnitte hinzugefügt. Nur neu formatieren reicht nicht aus. Füge für jedes README, das du erstellst, mindestens 2-3 dieser Dinge hinzu:

Anwendungsfall-Walkthroughs – Konkrete, reale Szenarien, mit denen der Benutzer sich identifizieren kann. Keine abstrakten Feature-Beschreibungen, sondern „Du bist in dieser Situation, hier ist, wie das Tool sie löst“:

### 💡 Reale Szenarien

<details>
<summary><strong>🐞 Einen Bug melden</strong></summary>

1. Erfasse den fehlerhaften Bildschirm mit einer Verknüpfung
2. Verpixel den Namen des Kunden, kreise den Fehler ein
3. Füge den Link in das Ticket ein
4. Fertig, bevor die Seite neu geladen hat

</details>

Vorher/Nachher-Szenarien – Zeige das Problem ohne das Tool und die Lösung damit. Das ist extrem überzeugend und niemand macht es:

### Vorher vs. Nachher

| Ohne dieses Tool | Mit diesem Tool |
|:---|:---|
| ❌ Screenshots stapeln sich auf dem Desktop | ✅ Jede Aufnahme erhält in Sekunden einen Link |
| ❌ Editor öffnen, um einen Namen zu verpixeln | ✅ Verpixeln und Kommentieren direkt vor Ort |
| ❌ Dateien in jedes Ticket ziehen | ✅ Link einfügen |

Wettbewerbsvergleichsmatrix – Wenn das Projekt Alternativen hat, zeige einen visuellen Vergleich. Kein „Wir sind besser“-Fließtext – eine ehrliche, datengetriebene Tabelle:

### Wie es sich vergleicht

| Funktion | Dieses Projekt | Alternative A | Alternative B |
|:---|:---:|:---:|:---:|
| Scrollaufnahme | ✅ | ❌ | ✅ |
| Kommentieren vor Upload | ✅ | ❌ | ❌ |
| Open Source | ✅ | ✅ | ❌ |

Benutzerreisediagramm – Mermaid-Reise, die den tatsächlichen Benutzererfahrungsfluss mit Zufriedenheitsbewertungen zeigt:

journey
    title Benutzererfahrung
    section Onboarding
      Installieren: 5: Benutzer
      Berechtigungen erteilen: 3: Benutzer
      Menüleiste sehen: 5: Benutzer
    section Tägliche Nutzung
      Ein Fenster aufnehmen: 5: Benutzer
      Link teilen: 5: Benutzer

Fehlerbehebungs-Entscheidungsbaum – Mermaid-Flussdiagramm für häufige Probleme anstelle einer flachen Tabelle:

flowchart TD
    A[Problem?] --> B{Aufnahme ist schwarz?}
    B -->|Ja| C[Überprüfe Bildschirmaufnahme-Berechtigung]
    B -->|Nein| D{Verknüpfung funktioniert nicht?}
    D -->|Ja| E[Überprüfe auf eine konkurrierende Verknüpfung]

Regel 4: SVG-Dateien MÜSSEN IMMER generiert werden

Wenn das README auf eine SVG-Datei verweist (./hero.svg, ./gauge.svg usw.), MUSST du diese Datei tatsächlich erstellen und zusammen mit dem README speichern. Ein Verweis auf eine nicht existierende Datei erzeugt ein kaputtes Bild auf GitHub – was schlimmer ist, als gar kein Bild zu haben.

Wenn du in der README auf ./performance-gauge.svg verweist, erstelle die tatsächliche SVG-Datei mit funktionierendem animiertem Inhalt. Wenn du helle/dunkle Varianten erstellst (hero-dark.svg, hero-light.svg), erstelle BEIDE Dateien. Keine Ausnahmen.

Regel 5: Respektiere die visuellen Entscheidungen des Originals

Wenn das ursprüngliche README bereits ein starkes visuelles Muster verwendet (Blockzitat-Feature-Karten, HTML-Tabellenraster, Unicode-Fortschrittsbalken), ersetze es nicht durch ein anderes Muster, das denselben Zweck erfüllt, es sei denn, deins ist eindeutig besser. Verbessere, was da ist, anstatt es durch eine laterale Bewegung zu ersetzen.

Wenn das Original beispielsweise dieses Muster für Features verwendet:

> **✂️ Scrollaufnahme**
>
> Erfasse eine ganze Seite als ein Bild. Das Zusammenfügen erfolgt auf dem Gerät, nichts wird hochgeladen, bis du es sagst.

Behalte es. Konvertiere es nicht in eine Markdown-Tabellenzeile – die Blockzitat-Version ist visuell prominenter. Verbessere stattdessen den umgebenden Kontext: füge einen Capsule-Render-Abschnittstrenner darüber ein, füge eine visuelle Vergleichstabelle nach den Features hinzu, füge ein Benutzerreisediagramm darunter ein.

Wie du jede README-Aufgabe angehst

Verstehe die Eingabe

Vorhandene Codebasis / Repository – Erkunde die Projektstruktur, lies wichtige Dateien und leite Zweck, Tech-Stack, Architektur und Zielgruppe ab.

Vorhandenes README zur Verbesserung – Lies es gründlich durch. Identifiziere, was bereits stark ist (behalte es). Identifiziere, was veraltet oder fehlend ist (repariere es). Dein Mehrwert kommt von: animierten Bannern, SVG-Datenvisualisierungen, kreativen neuen Abschnitten (Anwendungsfälle, Vorher/Nachher, Vergleiche) und Mermaid-Diagrammvielfalt. Nicht von der Neuformatierung dessen, was bereits funktioniert.

Benutzerbeschreibung – Stelle bei Bedarf gezielte Fragen und generiere dann ein vollständiges README.

Bestimme den Projekttyp

Projekttyp	Visuelle Prioritäten
Mobile App	Screenshots, Geräte-Mockups, App-Store-Badges, Reisediagramm
Backend-Dienst	Architektur-Sequenzdiagramm, API-Fluss, Deployment-Badges, Leistungsmessgeräte
SDK / Bibliothek	Code-Snippet-Held, API-Tabelle, Paketmanager-Badges, Benchmark-SVG-Diagramme
KI/ML-Projekt	SVG-Messgeräte für Metriken, Benchmark-Balkendiagramme, Trainingspipeline-Diagramm
CLI-Tool	Terminal-SVG-Mockup, Befehlsreferenz, Installationsmatrix
Web-App	Live-Demo-Badge, Screenshot, Tech-Stack-Badges, Bundle-Tortendiagramm

Umgang mit großen / komplexen Projekten

Für Projekte mit großen Codebasen (10k+ LOC, mehrere Module, umfangreiche Testsuiten):

Überprüfe alle Zahlen. Summiere die Komponenten-LOC-Zahlen und überprüfe, ob sie mit der angegebenen Gesamtzahl übereinstimmen. Wenn nicht, füge eine Notiz hinzu, die die Lücke erklärt (z. B. „Verbleibende LOC umfassen generierten Code, Test-Fixtures und Konfigurationsdateien“).
Füge Zusammenfassungsstatistiken hinzu. Füge nach detaillierten Aufschlüsselungen eine hochrangige Zusammenfassung hinzu: „3 Ebenen, 11 Dienste, 5 Bildschirme.“
Verwende einklappbare Abschnitte großzügig. Große Projekte haben viele Details. Verpacke Deep-Dive-Inhalte (Klassendiagramme, Dateibäume, API-Referenzen) in <details>-Blöcken. Der Hauptfluss sollte in 30 Sekunden überfliegbar sein.
Erstelle ein visuelles Statistik-Dashboard. Für Projekte mit reichhaltigen Daten (Testanzahlen, Abdeckung, LOC) erstelle ein SVG mit animierten Messgeräten, die 2-3 Schlüsselmetriken anzeigen.

Das visuelle Toolset

Diese sind nicht verhandelbar. Jedes README muss sie verwenden.

1. Animierte Gradienten-Banner

Verwende Capsule-Render für den Header und Footer:

Header:

<img width="100%" src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=6,12,20&height=180&section=header&text=ProjectName&fontSize=42&fontColor=fff&animation=fadeIn&fontAlignY=36&desc=Your%20tagline&descAlignY=56&descSize=18" />

Footer:

<img width="100%" src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=6,12,20&height=120&section=footer" />

Passe customColorList an die Identität des Projekts an.

2. Benutzerdefinierte SVG-Assets

Erstelle mindestens eine .svg-Datei pro README. Wähle, was zum Projekt passt:

Leistungsmessgerät – Animierter Bogen, der eine Schlüsselmetrik anzeigt (Geschwindigkeit, Abdeckung, Genauigkeit)
Terminal-Mockup – Gestaltetes SVG, das einem Terminal-App-Fenster mit Befehlen + Ausgabe ähnelt
Benchmark-Balkendiagramm – Animierte wachsende Balken, die dieses Projekt mit Alternativen vergleichen
Held mit hellen/dunklen Varianten – Über <picture> für themenbewusste Darstellung

Siehe references/visual-patterns.md für vollständigen, kopierbaren SVG-Code.

Denke an Regel 4: Wenn du darauf verweist, MUSST du es erstellen.

3. Feature-Anzeige – Wähle das beste Format

Für 3-6 Features: Verwende ein HTML-Tabellenraster mit Emoji-Symbolen und kurzen Beschreibungen:

<table>
<tr>
<td align="center" width="33%">

### ⚡ Blitzschnell
Sub-Millisekunden-Start. Kein Laufzeit-Overhead.

</td>
<td align="center" width="33%">

### 🔄 Live Reload
Automatische Aktualisierung bei Dateiänderungen. Null Konfiguration.

</td>
<td align="center" width="33%">

### 🌐 CORS integriert
Cross-Origin bereit ab Werk.

</td>
</tr>
</table>

Für 8+ detaillierte Features: Verwende Blockzitat-Karten in einer 2-spaltigen HTML-Tabelle. Dies skaliert besser für umfangreiche Feature-Beschreibungen:

<table>
<tr>
<td width="50%" valign="top">

> **📸 Feature-Name**
>
> Detaillierte Beschreibung mit technischen Details. Nutzenorientiert – erklärt, warum dies wichtig ist, nicht nur, was es tut.

> **✂️ Ein weiteres Feature**
>
> Mehr Details hier.

</td>
<td width="50%" valign="top">

> **🔗 Drittes Feature**
>
> Beschreibung.

</td>
</tr>
</table>

Verwende niemals eine einfache Aufzählungsliste für Features. Das ist das #1-Zeichen eines faulen READMEs.

4. Mermaid-Diagramme – Mindestens 2 verschiedene Typen

Gehe über einfache Flussdiagramme hinaus. Wähle mindestens ZWEI aus: pie, gantt, journey, sequenceDiagram, stateDiagram, mindmap, timeline, classDiagram, gitGraph.

Wähle Diagrammtypen, die echte Einblicke bieten:

pie → Code-Zusammensetzung, Testverteilung, Budgetaufschlüsselung
gantt / timeline → Fahrplan (ersetzt langweilige Kontrollkästchenlisten)
journey → Benutzererfahrungsfluss mit Zufriedenheitsbewertungen
sequenceDiagram → API-Flüsse, Architekturinteraktionen
mindmap → Designentscheidungen, Tech-Stack-Übersicht
stateDiagram → Lebenszyklus, Zustandsmaschinen, Workflows

5. Unicode-Visuelle Elemente

Für Inline-Daten, die kein separates SVG rechtfertigen:

Abdeckung   ███████░░░  71%
Tests       ██████████  412 bestanden
Speicher    ████░░░░░░  24 MB

Verwende sie zusammen mit Tabellen, nicht anstelle von ihnen. Großartig für Abdeckungsaufschlüsselungen, Leistungsvergleiche und Sprachvollständigkeitsprozentsätze.

6. For-the-Badge-Navigations-CTAs

<p align="center">
  <a href="#-quick-start"><img src="https://img.shields.io/badge/⚡_Quick_Start-2ea44f?style=for-the-badge" /></a>&nbsp;
  <a href="#-features"><img src="https://img.shields.io/badge/✨_Features-6366f1?style=for-the-badge" /></a>&nbsp;
  <a href="#-benchmarks"><img src="https://img.shields.io/badge/📊_Benchmarks-f59e0b?style=for-the-badge" /></a>&nbsp;
</p>

Diese ersetzen ein traditionelles Inhaltsverzeichnis – verwende nicht beides.

7. Einklappbare Abschnitte

Verpacke sekundäre Inhalte in <details>-Blöcke: Installationsvarianten, erweiterte Konfiguration, vollständige API-Dokumentation, Projektstruktur-Bäume, Fehlerbehebung. Der Hauptfluss sollte in 30 Sekunden überfliegbar sein.

8. Datentabellen mit visuellen Indikatoren

| Funktion | Dieses Projekt | Alt A | Alt B |
|:---|:---:|:---:|:---:|
| Funktion X | ✅ | ❌ | ⚠️ |

README-Struktur

Passe sie je nach Projekt an. Nicht jeder Abschnitt ist anwendbar, aber visuelle Elemente sind nicht verhandelbar.

 1. ANIMIERTER HEADER-BANNER (capsule-render)

 2. ZENTRIERTER HELD
    - Titel mit Emoji
    - Slogan
    - For-the-badge-Navigations-CTAs (diese ersetzen ein Inhaltsverzeichnis)
    - Metadaten-Badges (Version, CI, Lizenz, Plattform)

 3. NUTZENVERSRPECHEN (2-3 Sätze – warum dies existiert)

 4. FEATURES (HTML-Raster oder Blockzitat-Karten – nie Aufzählungsliste)

 5. SCHNELLSTART (nummerierte Emoji-Schritte 1️⃣ 2️⃣ 3️⃣ mit erwarteter Ausgabe)

 6. REALE ANWENDUNGSFÄLLE (kreative Szenarien – siehe Regel 3)

 7. BENCHMARKS / DATEN (SVG-Messgeräte + Unicode-Balken + Vergleichstabelle ✅❌)

 8. VORHER / NACHHER (vergleichende Tabelle – siehe Regel 3)

 9. ARCHITEKTUR (Mermaid-Sequenzdiagramm + optionales Klassen-/Komponentendiagramm)

10. WIE ES SICH VERGLEICHT (Feature-Vergleichstabelle – siehe Regel 3)

11. INSTALLATION (einklappbar – alle Methoden an einem Ort, Regel 2)

12. NUTZERREISE (Mermaid-Reisediagramm)

13. RESSOURCEN / FAHRPLAN (Mermaid-Zeitleiste, falls zutreffend)

14. FEHLERBEHEBUNG (Mermaid-Entscheidungsbaum durch Regel 3 abgedeckt?)

15. MITWIRKEN / LIZENZ / CREDITS

16. FOOTER-BANNER (capsule-render)

Sa74/readme-writer

Was ist readme-writer?

In Ihrer bevorzugten KI fragen

Vorschau

Dokumentation