karix-ai/readme-that-sells

README, die verkauft

Eine README ist keine Dokumentation. Sie ist eine Landing Page, die zufällig in einem Git-Repo lebt. Ein Besucher entscheidet in etwa 15 Sekunden, ob er sternt, es ausprobiert oder geht. Alles oberhalb der Falte muss den Stern verdienen. Die Dokumentation gehört unterhalb der Falte oder in docs/.

Der 15-Sekunden-Test

Beantworte diese Fragen, bevor du etwas schreibst, in jeweils einem Satz. Wenn du das nicht kannst, kann die README es auch nicht.

1. Was ist es? Ein Satz, keine Adjektive. „Ein kopfloser Browser für KI-Agenten, geschrieben in Zig.“
2. Warum existiert es? Der Schmerz, den es beseitigt, in den Worten des Nutzers. „Chrome frisst 500 MB pro Tab; Agenten brauchen 50 Tabs.“
3. Beleg, dass es funktioniert. Ein Demo-GIF, eine Benchmark-Zahl oder ein Vorher/Nachher. Keine Feature-Liste.
4. Wie probiere ich es in einem Befehl aus? npx ..., pip install ..., curl ... | sh, docker run ....

Struktur (in dieser Reihenfolge, keine Ausnahmen)

# Projektname
Ein-Satz-Pitch. (was + für wen + der Haken)

[Demo-GIF oder Screenshot – unter 10 Sekunden, zeigt das Ergebnis, nicht den Aufbau]

## Installieren           ← ein Befehl, kopierbar, keine versteckten Voraussetzungen
## Warum               ← 3–5 Zeilen: der Schmerz, die vorhandenen Alternativen, warum dies anders ist
## Nutzung             ← der häufigste Anwendungsfall als ausführbares Beispiel
## Funktionen          ← optional, kurz, Aufzählungspunkte, keine Marketing-Adjektive
## So funktioniert es      ← optional, ein Absatz oder ein Diagramm
## Vergleich        ← optionale Tabelle vs. 2–3 Alternativen, ehrlich zu den Kompromissen
## Mitwirken / Lizenz

Regeln

• Pitch-Zeile: ≤ 15 Wörter. Nenne die Kategorie und das Unterscheidungsmerkmal. Vermeide „rasend schnell“, „leistungsstark“, „einfach und doch“. Wenn es eine Zahl gibt, verwende sie: „Reduziert den Tokenverbrauch von Claude Code um 40 %.“
• Demo zuerst, Worte später. Das GIF oder der Screenshot kommt direkt unter den Pitch. Wenn es noch kein Demo gibt, erstelle eines vor dem Launch (siehe das Skill demo-gif). Eine README ohne Demo konvertiert nur einen Bruchteil derer mit einer.
• Installieren ist ein Block, ein Befehl. Wenn ein API-Key oder eine Konfigurationsdatei benötigt wird, zeige das ebenfalls im selben Block. Versteckte Voraussetzungen sind der Hauptgrund, warum Leute nach dem Klonen wieder gehen.
• „Warum“ ist für jemanden geschrieben, der bereits eine Lösung hat. Nenne die Alternativen. Sage, was sie gut machen. Dann sage das eine Ding, das dies tut, was sie nicht tun. Leser vertrauen READMEs, die fair gegenüber Wettbewerbern sind.
• Kein Emoji in Überschriften, es sei denn, das Projekt ist bewusst verspielt. Keine Badges über dem Pitch (eine Wand von Badges ist das Erste, woran Besucher vorbeiscrollen). Zwei oder drei Badges unter dem Pitch sind in Ordnung: Build-Status, Version, Lizenz.
• Ein echtes Beispiel schlägt zehn Feature-Aufzählungen. Zeige Eingabe → Ausgabe. Mache es etwas, das der Leser tatsächlich ausführen würde.
• Sage, was es nicht ist. Eine ehrliche Zeile zum Umfang („Kein Ersatz für Playwright; noch kein JS-Rendering“) verhindert den ersten feindseligen Kommentar auf Hacker News.
• Verknüpfe den sozialen Beweis, den du hast. „Verwendet von X“, ein Benchmark, ein Show HN-Thread. Erfinde nichts.
• Halte die oberen 60 Zeilen frei von allem, was ein Erstbesucher nicht braucht. Architektur, Roadmap, FAQ, Changelog: alles unten oder anderswo.

Anti-Patterns, die die Conversion töten

• Mit einem Absatz über Hintergrund oder Geschichte zu beginnen.
• Ein Inhaltsverzeichnis als Erstes auf der Seite.
• „Funktionen“ vor „Installieren“.
• Installationsanweisungen, die mit „Zuerst klone das Repo“ für ein Tool beginnen, das verwendet und nicht entwickelt werden soll.
• Screenshots von Konfigurationsdateien anstelle von Ergebnissen.
• Marketingsprache („revolutionär“, „zukunftsweisend“, „mühelos“).
• Tote Platzhalter („TODO: Demo hinzufügen“).

Vorgehen

1. Lies die aktuelle README (falls vorhanden) und die Einstiegspunkte des Codes. Extrahiere die vier Antworten aus dem 15-Sekunden-Test.
2. Erstelle den Pitch. Schreibe drei Varianten; wähle die mit dem konkretesten Substantiv und den wenigsten Adjektiven.
3. Schreibe Installieren, dann Nutzung, dann Warum. Führe jeden Befehl unter Installieren aus, um zu bestätigen, dass er aus einem sauberen Verzeichnis funktioniert.
4. Füge das Demo unter dem Pitch ein. Wenn keines existiert, füge einen TODO(demo)-Marker hinzu und teile dem Nutzer mit, dass dies den Launch blockiert.
5. Entferne alles oberhalb der Falte, das die Frage „Braucht ein Fremder dies, um zu entscheiden?“ nicht beantwortet.
6. Lies die oberen 60 Zeilen als skeptischer Ingenieur. Korrigiere das Erste, das sie dazu bringen würde, den Tab zu schließen.

Ausgabe

Gib die vollständige README.md zurück. Liste dann in ≤ 5 Aufzählungspunkten auf, was du geändert hast und was der Nutzer noch selbst bereitstellen muss (Demo-GIF, Benchmark-Zahlen, echte Nutzerzitate).