/brag-more
Du hast es gebaut. Jetzt soll auch das Repo damit prahlen. Die README ist das Erste, was jeder auf GitHub sieht; mach daraus eine Startseite, die das Projekt in fünf Sekunden verkauft und einen Fremden in einer Minute vom Nullpunkt zum Laufen bringt.
Egal, um welches Projekt es sich handelt – das Ergebnis soll sich anfühlen wie eine README aus einem beliebten Open-Source-Projekt: selbstbewusst, überfliegbar, visuell und wahr. Nichts auf der Seite, was seinen Platz nicht verdient hat.
Verwendung: /brag-more [Optionen]. Optionen (Flags oder Klartext):
| Option | Standard |
|---|---|
| `--style clean | bold |
--preview | aus: überschreibt README.md direkt. Mit Option: schreibt nur in brag-output/repo/ und lässt README.md in Ruhe |
--no-banner | Banner an |
--no-video | aus: wenn das Projekt kein Brag-Video hat, erstelle zuerst eines (sieh Das Video) |
--no-demo | Demo an, wenn es etwas zu zeigen gibt |
Arbeitsdateien kommen in brag-output/repo/ (zeitgestempelt brag-output-YYYY-MM-DD-HHmmss/repo/, wenn brag-output/ bereits existiert und nicht von diesem Durchlauf stammt). Assets, auf die die README verweist, liegen im Repo in .github/readme/, damit sie mit ausgeliefert werden.
1. Untersuche
Lies das Projekt, nicht nur die alte README:
- Die vorhandene README, jede Zeile. Es ist der Text des Benutzers. Behalte, was wahr und nützlich ist (Installationsschritte, Konfigurationstabellen, Credits, Lizenzhinweise, Sponsorenlinks, Danksagungen); gestalte es um, wirf es nicht weg.
- Identität: exakte Markenfarben und Schriftarten aus Stylesheets oder der Theme-Konfiguration, das Logo oder Favicon, ein vorhandenes Hero-Bild oder OG-Bild.
- Was es ist: Paketmanifeste (
package.json,pyproject.toml,Cargo.toml,go.mod, …) für Name, Beschreibung, Version, Lizenz, Binärdateien und Skripte; der Einstiegspunkt und die Hauptrouten oder Befehle für die echten Features. - Wie man es ausführt: die tatsächlichen Installations- und Startbefehle aus den Manifest-Skripten,
Makefile,justfile, Dockerfile oder CI-Workflow. Notiere die Laufzeitversionen, die das Projekt festlegt. - Signale für Badges:
LICENSE,.github/workflows/*, ob das Paket veröffentlicht ist (npm, PyPI, crates.io – prüfe den Namen im Manifest und dasprivate-Flag), die Git-Remote-URL (git remote get-url origin) fürowner/repo. - Vorhandene Brag-Ausgabe: wenn
brag-output*/brag.mp4undbrag.jpgexistieren, sind sie das beste Demo-Material auf dem Rechner. Verwende das neueste. Wenn es keins gibt, erstelle es im nächsten Schritt.
Überspringe Build-Ausgabe, Lock-Dateien, .git/, Umgebungs- und Geheimnisdateien (.env, .env.*), Schlüssel- und Anmeldedaten und alles, was .gitignore aus diesen Gründen ausschließt.
Beantworte vor dem Schreiben: Was ist es (ein Satz, den ein Fremder versteht)? Für wen ist es? Was ist das eine, was es besser macht als die Alternative? Was ist der visuelle Haken – der Screenshot, das GIF oder das Banner, das jemanden vom Scrollen abhält? Was sind die 3–5 echten Features? Was ist der kürzeste Weg vom Klonen zum Laufen?
Die README ist öffentlich. Übernimm niemals Geheimnisse, Tokens, interne Hostnamen, echte Kunden- oder Benutzernamen, E-Mail-Adressen oder andere persönliche Daten in sie oder ihre Bilder. Wenn ein Screenshot solche Daten zeigt, ersetze sie durch plausible fiktive Platzhalter.
Das Video (vor dem Plan, wenn noch keins vorhanden ist)
Das beste Demo der README ist das Launch-Video des Projekts, also erstellt brag-more eines, wenn es fehlt. Überspringe diesen Schritt, wenn --no-demo oder --no-video gesetzt ist oder wenn bereits eine brag-output*/brag.mp4 existiert.
- Wenn der
/brag-Skill installiert ist (prüfe die Skill-Liste), führe ihn für dieses Projekt mit dem Skill-Tool aus und gib alle--tone- oder Formatwünsche weiter. Teile dem Benutzer in einer Zeile mit: „Noch kein Launch-Video, also erstelle ich zuerst eines mit /brag.“ - Ansonsten lies
<skill-dir>/video.md(der schlanke Video-Workflow, der hier gebündelt ist, von brag-slim) und folge ihm. Es benötigt nur die bereits auf dem Rechner vorhandenen Werkzeuge. - Wenn es fertig ist, sind das Video, das Poster und die Freigabe-Kopie in
brag-output/. Fahre mit der README fort und verwende sie als Demo.
Wenn das Erstellen des Videos fehlschlägt oder der Benutzer nicht warten möchte, fahre ohne es fort und verwende die Fallbacks unter Demo.
2. Plane
Schreibe brag-output/repo/readme-plan.md: den Einzeiler, den gewählten Stil, die Reihenfolge der Abschnitte, welche Visuals du erstellst und was jedes zeigt, welche Badges gerechtfertigt sind (und die Belege für jedes) und was du aus der alten README behältst.
Form: eine Startform, keine Vorlage. Lasse jeden Abschnitt weg, der leer oder nur Füllmaterial wäre.
- Heldenbereich – der animierte SVG-Held (siehe Bauen), dann zentriert: der Einzeiler, eine kurze Badges-Zeile und eine Navigationszeile mit Links (Demo · Install · Docs · …).
- Demo – das Produkt in Aktion, direkt unter dem Helden, eingerahmt: der Brag-Video-Loop, ein GIF der echten Benutzeroberfläche oder eine Terminalaufzeichnung. Ein visuelles Element, groß.
- Warum – 2–4 Sätze: was es für den Benutzer tut und was es auszeichnet, in den eigenen Worten des Projekts. Für ein Entwicklerwerkzeug schlägt ein 3–5-zeiliger Codeblock, der den Pitch darstellt, einen Absatz (
bun run index.tsx # TS und JSX out of the box). - Feature-Schau – 3–6 echte Features, jedes mit einem eigenen kleinen visuellen Element: ein zugeschnittener Screenshot der echten Benutzeroberfläche, ein Terminal-GIF pro Befehl oder ein Code-Snippet mit seiner Ausgabe. Lege visuelle Elemente als nebeneinanderliegende Karten aus (siehe Bauen). Text-only-Features erhalten eine fette Einleitung und eine Zeile.
- Quickstart – kopierbar, in Reihenfolge, jeder Befehl gegen das Projekt verifiziert. Voraussetzungen zuerst.
- Verwendung – ein oder zwei echte Beispiele: ein Befehl und seine Ausgabe, ein Code-Snippet oder ein Konfigurationsblock.
- Wie es funktioniert – optional. Ein kurzer Absatz oder ein Mermaid-Diagramm, wenn die Architektur der interessante Teil ist.
- Alles andere aus der alten README – Konfiguration, FAQ, Roadmap, Mitwirkung, Credits – aufgeräumt, falls lang in
<details>gefaltet. - Fußzeile – Lizenzzeile plus den abschließenden Kunststreifen (siehe Bauen).
README-Gesetze
- Wahr. Jede Behauptung, Zahl, jedes Feature und jeder Badge muss durch das Projekt belegt sein. Keine erfundenen Sterne, Downloads, Benchmarks, Testimonials oder „verwendet von“-Logos. Ein Badge erscheint nur, wenn das, worauf er verweist, existiert (ein veröffentlichtes Paket, ein echter Workflow, eine Lizenzdatei).
- Läuft. Jeder Befehl in Quickstart und Verwendung existiert im Projekt wie geschrieben. Wenn du ihn sicher ausführen kannst (Installieren, Bauen,
--help, Tests), tu es. Wenn ein Schritt Geheimnisse oder einen kostenpflichtigen Dienst benötigt, sage es klar, anstatt es zu verstecken. - Fünf-Sekunden-Test. Jemand, der vom Tweet auf das Repo kommt, weiß, was es ist, sieht es in Aktion und findet den Installationsbefehl, ohne über den ersten Bildschirm hinauszuscrollen.
- Zeige das Ding. Die Demo zeigt das echte Produkt in Aktion, keine Logo-Animation oder abstrakte Kunst. Verwende die echte Benutzeroberfläche, echtes CSS, echten Text.
- Sage, was das Repo ist. Wenn das Repo die Website, die Landing Page oder die Demo für ein Produkt ist, sage das im Einzeiler; suggeriere nicht, dass Leute eine App herunterladen oder ein Paket installieren können, das das Repo nicht ausliefert.
- Spezifisch. Es muss sich anfühlen, als sei es für dieses genaue Projekt geschrieben. „Blitzschnell“, „nahtlos“, „nächste Generation“, „optimieren Sie Ihren Workflow“ sind verboten, es sei denn, das Projekt verdient sie messbar.
- Überfliegbar. Kurze Absätze, Überschriften, die etwas aussagen, eine Idee pro Aufzählungspunkt. Emoji in Überschriften nur, wenn die eigene Stimme des Projekts sie verwendet, und dann sparsam (der
showcase-Stil ist die Ausnahme: ein Emoji pro Abschnittsüberschrift, absichtlich). - Beide Themes. GitHub-Leser verwenden den hellen und den dunklen Modus. Jedes Bild sieht auf
#ffffffund auf#0d1117gut aus: transparente PNGs mit einer sichtbaren Kante oder<picture>mit einerprefers-color-scheme-Quelle pro Theme. - Passt in die Spalte. Die README-Spalte ist auf dem Desktop etwa 830px breit und auf dem Handy viel schmaler. Bannertext bleibt lesbar, wenn er auf Handybreite skaliert wird; Tabellen haben wenige Spalten; keine breiten rohen HTML-Layouts, die auf Mobilgeräten brechen.
- Jeder Link löst auf. Relative Links verweisen auf Dateien, die existieren; Anker entsprechen echten Überschriften.
Stile
| Stil | Gefühl | Verwende, wenn |
|---|---|---|
clean | Animierter Held mit zurückhaltender Bewegung, eingerahmte Demo, ordentliche Karten | Die meisten Projekte; der Standard |
bold | Vollflächiger Held in Markenfarben mit größerem animierten Moment, knackiger Einzeiler, Demo im Zentrum | Verbraucher-Apps, verspielte Projekte, Launches |
minimal | Kleines animiertes Logo-Lockup + Name + Einzeiler, schlichte Abschnitte | Bibliotheken, CLIs, Infrastruktur, seriöse Werkzeuge |
showcase | Die dichte, mit Emoji strukturierte technische README (denk an ein preisgekröntes Hackathon- oder Forschungsprojekt): ein echter Screenshot des Produkts oben, eine Auszeichnungs- oder Statuszeile, dann ein emoji-geführter Abschnitt pro Thema | Hackathon, Forschung, ML, Daten oder wissenschaftliche Projekte; alles mit echter Tiefe, um es zu zeigen. Wähle es, wenn der Benutzer nach „so etwas wie Find My Shark“ oder einer detaillierten, dokumentationsartigen README fragt |
Das showcase-Rezept
Modelliert nach der Find-My-Shark-README des Eigentümers. Behalte, was funktioniert, und behebe, was nicht:
- Titel mit einem Emoji und der Auszeichnungszeile darunter („NASA Space Apps 2025, Galactic Impact Winner“), nur wenn das Projekt es wirklich verdient hat. Frage nach oder lies es aus der alten README; erfinde nie eine.
- Ein echter Screenshot oder das Demo-GIF direkt unter dem Titel, eingerahmt (siehe Demo, eingerahmt). Behalte den animierten Helden nur, wenn er etwas hinzufügt; hier ist das echte Produkt der Star.
- Eine 2–3-zeilige Beschreibung und die „Warum es wichtig ist“-Zeile, dann Abschnitte, jeder von einem Emoji angeführt: Features, Region/Umfang oder Eingaben, Datenquellen (Tabelle), Wie es funktioniert oder Mathematisches Modell, Quick Start (Installation, grundlegende Verwendung, API-Verwendung), Projektstruktur (annotierter Baum), Konfiguration (die echte Konfiguration), Ausgabedateien, Befehlszeilenoptionen, Hintergrund, Zukünftige Erweiterungen, Tests, Protokollierung, abschließender Slogan.
- Füge nur Abschnitte ein, für die das Projekt echten Inhalt hat. Hackathon-Tiefe ist der Punkt, also behalte die Details: Parameter, Formeln, Schwellenwerte, Datensatznamen und den Projektbaum.
- Behebe die üblichen Fehler: verwende die echte Klon-URL (niemals
your-username), ersetze veraltete Einträge im Projektbaum-Codeblock durch das, was existiert, füge ein Inhaltsverzeichnis oder eine Schnellverknüpfungszeile hinzu, sobald es mehr als sechs Abschnitte gibt, verpacke lange Referenzabschnitte (CLI-Optionen, vollständige Konfiguration, wissenschaftlicher Hintergrund) in<details>, füge Badges für den echten Stack hinzu (Python-Version, Lizenz, Schlüsselbibliotheken) und ein<picture>oder eingerahmten Screenshot für beide Themes, und setze die Repo-Beschreibung und Themen bei der Auslieferung. - Anker mit Emoji: GitHub entfernt das Emoji aus dem Slug einer Überschrift, behält aber den Bindestrich, also ist
## 🚀 Quick Start#-quick-start, nicht#quick-start. Schreibe jeden Navigationslink und jeden Badge-Link auf diese Weise und überprüfe jeden gegen seine Überschrift. Die<details>-Zusammenfassung ist keine Überschrift und hat keinen Anker. - Befolge trotzdem jedes README-Gesetz (Wahr, Läuft, Beide Themes) und den Prüfschritt.
3. Baue
Die besten READMEs auf GitHub (Excalidraw, Scalar, Supabase, Charm, Rich, Bun) teilen einige Tricks. Verwende sie alle; das macht diese zu einem Scroll-Stopper.
Der Held: ein animiertes SVG
Das ist das Markenzeichen. Ein statisches Banner wirkt wie eine Vorlage; ein Held, der sich bewegt – in den eigenen Farben, Schriftarten und der eigenen Benutzeroberfläche des Projekts – wirkt wie für dieses Projekt gemacht. GitHub rendert ein SVG in einem <img>-Tag mit seinen CSS @keyframes, die laufen, sodass sich der Held ohne die Banden oder das Gewicht eines GIFs animieren kann.
Baue .github/readme/hero.svg (viewBox etwa 1600×800, gerendert mit width="100%"):
- Die Szene ist das Produkt. Erstelle den echten Helden oder den wichtigsten Bildschirm des Projekts als SVG-Formen: sein Hintergrundbild, seine Schlagzeile in seiner eigenen Schriftart und ein echtes UI-Element, das seine Aufgabe erfüllt (eine Karte, die wischt, ein Befehl, der getippt wird, ein Diagramm, das gezeichnet wird, ein Toast, der landet). Eine Idee, ein Loop.
- Bewegung: CSS
@keyframesin einem<style>-Block innerhalb des SVGs, nur auftransformundopacity, mittransform-box: fill-box; transform-origin: centerauf allem, was skaliert oder rotiert. Ein 6–10 s Loop, der nahtlos zum Startframe zurückkehrt, gestaffelte Eintritte, jede Textzeile lange genug gesetzt, um gelesen zu werden. Füge eine leichte Drift im Hintergrund hinzu (eine 1.0 → 1.05 Skalierung über den Loop), damit sich der Frame nie eingefroren anfühlt. Ein CSStransformersetzt das SVGtransform-Attribut eines Elements, also positioniere Dinge mit einem äußeren<g transform=…>und animiere ein inneres Element. - Reduzierte Bewegung: verpacke die Keyframes in
@media (prefers-reduced-motion: no-preference), damit Leser, die sich dagegen entscheiden, den fertigen, stabilen Frame sehen. Der stabile Frame muss für sich alleinstehend postbar sein und das Produkt zeigen, also beginne alles, was nur mitten im Loop erscheint (ein Match-Overlay, ein Toast), versteckt mit einemopacity="0"-Attribut und wird nur durch seine Keyframes enthüllt. - In sich geschlossen. Ein SVG, das über
<img>geladen wird, kann nichts abrufen: keine Webfonts per URL, keine externen Bilder, keine Skripte. Einbettung von Schriftarten als base64@font-face(dielatin-Dateien von Google Fonts sind bereits ~20 KB und können vollständig eingebettet werden; unterteile andere Schriftarten mitpyftsubset … --text="…" --flavor=woff2, was eine aktuelle fontTools erfordert) oder konvertiere den Text in Pfade. Bette Fotos als base64 JPEG ein, in der Größe, die der Held benötigt. Vermeide<foreignObject>(Safari rendert es nicht innerhalb von<img>). Halte die Datei unter ~1,5 MB. - Beide Themes. Wenn der Held vollflächig und undurchsichtig ist, funktioniert er auf beiden; ansonsten erstelle auch
hero-dark.svgund wechsle mit<picture>oder#gh-dark-mode-only/#gh-light-mode-onlyURL-Fragmenten. - Text: der Projektname und der Einzeiler, groß (der Held schrumpft auf ~40% auf Handys). Nichts anderes.
<p align="center">
<a href="<Site- oder Demo-Link>"><img src=".github/readme/hero.svg" alt="<Projekt> — <Einzeiler>" width="100%"></a>
</p>
Erfasse auch den stabilen Frame bei 1280×640 als .github/readme/social-preview.png (undurchsichtig) für die Social Card des Repos; rendere das SVG in einem Headless-Browser mit aktivierter reduzierter Bewegung.
Wenn das Projekt keine visuelle Identität hat, die eine Animation lohnt (eine Bibliothek ohne UI), erstelle stattdessen ein animiertes Wortmarke: der Name in einer passenden Schriftart, eine Bewegung, die sagt, was es tut (ein Wert, der durch eine Pipe fließt, Text, der formatiert wird, ein Test, der grün wird).
Demo, eingerahmt
In der Reihenfolge der Präferenz:
- Das Brag-Video. Das in Untersuche gefundene oder im Schritt Das Video erstellte. Wenn eine
brag.mp4existiert, erstelle einen Loop-Vorschau-GIF oder animierten WebP aus den stärksten 4–8 Sekunden