README Screenshots
Verwandle ein funktionierendes Projekt in ein dokumentiertes, visuelles: Starte die App, erstelle echte Screenshots ihrer Oberflächen und setze daraus eine lebendige, saubere README.md zusammen. Das Ergebnis sollte wie die Landingpage eines beliebten Open-Source-Projekts wirken.
Nicht verhandelbar, unabhängig von der Plattform:
- Screenshots sind ECHTE Aufnahmen der laufenden App. Niemals zeichnen, mocken oder Bilder fälschen.
- Sie befinden sich im Repository (
docs/screenshots/) und die README verweist mit relativen Pfaden darauf, damit sie auf GitHub dargestellt werden. - Nichts Zerstörerisches: Ändere niemals den Quellcode des Projekts, um einen Screenshot zu ermöglichen – injiziere bei Bedarf Demozustand zur Laufzeit und weise darauf hin.
Arbeitsablauf
Phase 1 – Plattform erkennen
Suche im Projektstamm nach diesen Signalen und lade dann EIN Runbook aus references/:
| Signale | → Runbook |
|---|---|
package.json mit einem dev/start-Skript, oder index.html, oder ein reines Web-Frontend in einem src/public-Ordner | references/web.md |
manifest.json (WebExtension/MV3/V2) | references/web.md (Bereich Erweiterungen) |
Android: build.gradle(.kts), AndroidManifest.xml, settings.gradle, Kotlin/Java-App-Quellen | references/android.md |
iOS: *.xcodeproj, *.xcworkspace, Info.plist, App-Code in Swift | references/ios.md |
Flutter: pubspec.yaml mit flutter: und lib/main.dart | references/flutter.md |
| Mehrere Plattformen (z. B. Flutter + nativ oder ein Monorepo) | Dokumentiere zuerst die Plattform des Haupt-UIs; erwähne die anderen in der README |
Wenn die Plattform wirklich nicht eindeutig ist, frage den Benutzer einmal mit deiner besten Analyse des Repositorys. Wenn das Projekt KEINE benutzersichtbare Oberfläche hat (reine Bibliothek/CLI), erstelle keine gefälschten UI-Aufnahmen – falle auf eine Terminal-Demo, ein verfeinertes Diagramm oder ein generiertes Banner zurück und erstelle trotzdem eine großartige README.
Phase 2 – App gemäß Runbook starten
Jedes Runbook gibt vor:
- Was auf diesem Rechner bereits vorhanden sein muss (Toolchain-Prüfung, wiederholbarer Einzeiler).
- Wie die App gestartet wird, damit ihre Benutzeroberfläche dargestellt wird.
- Wie tatsächlich Pixel erfasst werden (gebündeltes Skript in
scripts/oder ein nativer Capture-Befehl). - Wie vorgegangen wird, wenn etwas leer ist („Auf Rendern warten" ist besser als „blind wiederholen").
Phase 3 – Erfassen
Konventionen, die für jede Plattform gelten:
- Speichere in
<repo>/docs/screenshots/, mit kebab-case-Namen, die den Moment beschreiben (hero-dashboard.png,settings-screen.png), niemals das Werkzeug (screenshot-2026-01-04-14-22.png). - Erfasse jede Oberfläche in ihrer natürlichen Form: Dialoge/Popups in ihrer nativen Größe, Seiten mit 1280×800 oder als vollständige Seite. Bei Handys erfasse den Gerätebildschirm wie er ist (seine eigene Auflösung ist Teil der Geschichte).
- Bevorzuge den Dark Mode für das Hero-Bild, wenn die App einen hat – dunkle UIs heben sich in READMEs ab – aber nur, wenn es ein echtes dunkles Theme gibt; erzwinge keines.
- Inszenierter Demozustand ist erlaubt (leere Zähler, „Laden…"-Platzhalter sehen in Marketing-Aufnahmen fehlerhaft aus), muss aber zur Laufzeit injiziert werden, nicht in den Projektcode geschrieben, und du musst dies dem Benutzer in deiner Zusammenfassung mitteilen.
- Ein leeres oder flackerndes Bild ist ein Timing-Fehler, nicht die Schuld der App: Warte auf das Laden + einen Moment für Schriftarten/Icons/Übergänge, wiederhole es einmal mit längerer Wartezeit.
Phase 4 – README erstellen
Schreibe (oder überschreibe) README.md im Stammverzeichnis des Repositorys. Wenn bereits umfangreiche README-Inhalte vorhanden sind (git-readme.md, eine Prosa-Datei, Docs), extrahiere ALLE Fakten daraus – du verbesserst die Präsentation, löschst niemals Informationen.
Zielstruktur (frei anpassbar, aber überschaubar halten):
# <Projektname>
<p align="center"><img src="docs/screenshots/hero.png" width="…"></p>
> Ein-Satz-Argumentation mit Persönlichkeit.
Badges: Lizenz, Sprache, Installationslink
## Warum es existiert ← das Problem, 2–4 Zeilen, fette Zahlen falls real
## Was es tut ← ✨ kompakte Funktionsliste (+ Screenshots neben den Funktionen)
## Screenshot-Tour ← Galerie mit einzeiligen Bildunterschriften
## Wie es funktioniert ← Architektur in einfachen Worten; Tabellen statt Prosa
## Installation ← nummeriert, kopierbar
## Konfiguration ← Parametertabelle, falls die App Einstellungen hat
## Datenschutz / Sicherheit ← nur, wenn sinnvoll
## Lizenz
Stilregeln:
- Hero-Bild oberhalb des Seitenumbruchs, explizite Breite (
width="400"für Handy-Aufnahmen, unter ~728px für Desktop), damit es auf GitHub gut aussieht. - Eine Idee pro Abschnitt; kurze Absätze; Fettdruck nur als Lesehilfe.
- Tabellen für Kompatibilitätsmatrixen und Einstellungen – sie schlagen Prosa.
- Minimaler, geschmackvoller Emoji-Einsatz in Überschriften (⏱ 🎨 🚀) ist in Ordnung; würze nicht jede Zeile.
- Relative Bildpfade mit Alt-Text, immer.
- Beschreibe niemals den Screenshot-Prozess in der README; es wirkt, als hätte das Projekt selbst geschrieben.
Phase 5 – Überprüfen
- Jeder Bildpfad in der README verweist auf eine vorhandene Datei.
- Kein Screenshot größer als ~1,5 MB; komprimiere (PNG → WebP oder verkleinere), wenn größer.
- Teile dem Benutzer mit: Wo sich die README befindet, welche Aufnahmen existieren, welche demoinjizierte Werte enthalten, und biete an, die Hero-Auswahl, das Theme oder die Reihenfolge zu ändern.
Toolchain-Richtlinie (Umgang mit fehlenden Abhängigkeiten)
Das Skill verwendet die auf dem Rechner bereits vorhandene Toolchain und installiert NIEMALS heimlich Plattform-SDKs (Android SDK, Xcode, Android-Emulatoren – Multi-GB-Downloads, denen der Benutzer zustimmen muss). Wenn die Toolchain-Prüfung eines Runbooks fehlschlägt, stoppe sauber mit genau dieser Form:
[Plattform]-Screenshots benötigen [Tool], das nicht installiert ist. So aktivieren Sie es:
<exakter Installationsbefehl oder Schritt>. Installieren Sie es, sagen Sie dann „Wiederholen" und ich fahre fort – die bisher geleistete Arbeit (Erkennung, README-Gerüst) ist gespeichert.
iOS ist ein Sonderfall: Wenn der Host nicht macOS ist, teile dies in einem Satz mit und überspringe es – kein Wiederholen kann es unter Windows/Linux ermöglichen. Biete dem Benutzer die Möglichkeit, selbst erstellte Screenshots bereitzustellen.