Communitygithub.com

geekjourneyx/readme-generator

Generiert Portfolio-würdige README.md-Dateien für GitHub-Projekte – mit Fokus auf Storytelling, visuelle Qualität und Zurückhaltung.

Was ist readme-generator?

Diese Fähigkeit erstellt README-Dateien, die als professionelles Portfolio für GitHub-Projekte dienen. Sie folgt dem ersten Prinzip, dass READMEs Vertrauenseinstiege und Pfadeinstiege sind, keine vollständigen Handbücher oder Funktionslisten. Die Fähigkeit durchläuft sechs Phasen: Projektlesen und Mustererkennung, Destillation der Projektgeschichte, Auswahl der visuellen Generierungsmethode, Generierung von visuellen Assets in Portfolioqualität, Zusammenbau des READMEs und Vorschläge für GitHub-Metadaten. Sie unterstützt Plattformen wie Codex und Cursor und verwendet einen standardisierten Bewertungsrahmen (mindestens 90 von 100 Punkten), um sicherzustellen, dass jedes README klar, ästhetisch, zurückhaltend und glaubwürdig ist. Die Fähigkeit priorisiert Codex Image Gen für visuelle Assets, fällt aber auf HTML-zu-PNG-Screenshots zurück, wenn eine präzise Textdarstellung erforderlich ist. Sie generiert standardmäßig bis zu zwei Bilder (Banner und Features) im WebP-Format, um die Ladezeit zu optimieren, und vermeidet übermäßiges Design, Template-Overlays und aufgeblähte Abschnitte. Der Fokus liegt darauf, einem Projekt zu helfen, seine eigene Geschichte zu erzählen, die visuelle Intensität basierend auf dem Projekttyp anzupassen und nach dem Motto „Visuelles dient dem Verständnis, nicht dem Ersatz“ zu handeln.

Funktioniert mit✓Claude Code✓Codex CLI~Cursor
npx skills add geekjourneyx/readme-generator

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Vorschau

Aus dem Skill-README

License: MIT
readme-generator preview
readme-generator preview

Dokumentation

GitHub README Generator

README ist die erste Portfolio-Seite eines Projekts. Es ist kein Inhaltsverzeichnis einer Anleitung und kein Container für eine Funktionsliste. Es muss in kurzer Zeit drei Dinge beantworten:

  1. Was ist das.
  2. Warum ist es sehenswert.
  3. Wie fange ich an.

Ziel dieser Fähigkeit ist es, 100-Punkte-README-Werke zu generieren: klar, ästhetisch, zurückhaltend, glaubwürdig, die das Projekt wie ein vollständiges Werk erscheinen lassen.


Erste Prinzipien

README ist ein Vertrauenseinstieg und ein Pfadeinstieg, keine vollständige Dokumentation. Es sollte der Person, die das Repository zum ersten Mal öffnet, helfen, eine schnelle Einschätzung zu treffen:

  1. Welches Problem löst dieses Projekt.
  2. Passt es zu mir.
  3. Kann ich es sofort ausführen, installieren oder mich weiter informieren.

Open-Source-Projekte mit über 10.000 Sternen überzeugen in der Regel nicht durch die Menge an Informationen, sondern durch einen klaren ersten Bildschirm, einen direkten Einstiegspfad, einen glaubwürdigen Dokumentationseinstieg und zurückhaltende Community-Informationen. Bilder, Badges, Autoreninformationen und Designkonzepte sind nur Hilfsmittel; wenn sie das Verständnis verlangsamen, sind sie Rauschen.

Der Kern dieser Fähigkeit: README erklärt zuerst das Projekt, dann erfolgt die Verschönerung; Visuelles dient dem Verständnis, ersetzt es nicht.


Werkstandard

Verwende die folgende Bewertungstabelle für alle Ausgaben:

DimensionPunkteKriterium
15-Sekunden-Verständnis25Auf dem ersten Bildschirm sind Projektname, Wert und Zielgruppe erkennbar
Projektgeschichte20Nicht nur Funktionen auflisten, sondern Hintergrund, Motivation und Ergebnis erklären
Visueller Ausdruck20Bilder wirken wie Werke, nicht wie kleine Screenshots von Abläufen
Schnellstart15Installations- und Nutzungspfad ist kurz, klar und kopierbar
Glaubwürdiges Produkt10Zeigt echte Ergebnisse, Fähigkeitsgrenzen oder Resultate
Zurückhaltung/Rauschreduzierung10Entferne Wiederholungen, Slogans, übermäßige Erklärungen und Dekoration

READMEs mit weniger als 90 Punkten werden nicht ausgeliefert; zuerst Rauschen entfernen, Schwerpunkte vergrößern, Erzählung neu anordnen.

Basislinie für High-Star-Projekte

Standardmäßig von diesen Strukturen lernen:

  • Projektname + einzeiliges Wertversprechen.
  • Wenige notwendige Badges, keine Statusdekoration anhäufen.
  • Schnellstart oder Dokumentationseinstieg nach vorne.
  • Beispiele nur, wenn sie die Einstiegshürde senken.
  • Beitrag, Community, Sicherheit, Lizenz kurz und klar.
  • UI-/Produktprojekte können Screenshots haben; Bibliotheken, SDKs, Infrastrukturprojekte haben wenige oder keine Bilder.

Schreibe README nicht als Designmanifest, vollständiges Handbuch, Funktionswand, Social-Media-Visitenkarte oder internen Workflow-Bericht.


Designprinzipien

Unbedingt einhalten

  • H1 muss der offizielle Projektname sein, gefolgt von einem einzeiligen Wertversprechen.
  • README beginnt mit dem Projektwert, dann folgen Installationsdetails.
  • Bilder vermitteln nur einen Schwerpunkt, sollten aber als Projektvisitenkarte dienen: Der Leser sollte auf einen Blick Projektname und Positionierung sehen.
  • Standardmäßig maximal zwei Bilder: ein Banner und ein Bild für Kernfähigkeiten oder Ergebnisse.
  • GitHub verkleinert die Bilddarstellung; der Haupttext im Bild muss in Plakatgröße gestaltet sein.
  • Beschreibungen von Funktionen sind spezifisch, aber nicht übertrieben; verwende Ergebnisse zur Erklärung, anstatt dich selbst zu loben.
  • Halte Autor und Lizenz kurz, keine Anhäufung von Social-Media-Visitenkarten.

Unbedingt vermeiden

  • ASCII-Art-Titel.
  • Emoji-dekorierte Titel oder Autorentabellen.
  • Lange, leere Phrasen wie „Wir sind sehr professionell“.
  • Mehr als 6 kleine Karten in einem Bild.
  • Flussdiagramme voller Phasen, Befehle und kleiner Beschriftungen.
  • Das dritte Flussdiagramm als Standardprodukt; Funktionsweise wird meist im Fließtext klarer.
  • Image Gen als Tool für lange Textlayouts.
  • README als vollständiges Produkthandbuch; detaillierte Dokumentation gehört in docs/.

Gesamtablauf

Phase 0    Projektlesen und Mustererkennung
Phase 1    Destillation der Projektgeschichte
Phase 2    Auswahl der visuellen Generierungsmethode
Phase 3    Generierung von visuellen Assets in Portfolioqualität
Phase 4    README-Zusammenbau
Phase 5    Vorschläge für GitHub-Metadaten
Phase 6    Validierung und Auslieferung

Phase 0: Projektlesen und Mustererkennung

Zuerst das Projekt lesen, nicht direkt eine Vorlage schreiben.

Überprüfen:

ls
find . -maxdepth 2 -type f | sed 's#^\./##' | sort | head -80

Priorität beim Lesen:

  • README.md
  • package.json / pyproject.toml / go.mod / Cargo.toml
  • docs/
  • Haupt-Einstiegsdateien
  • Beispiele, Screenshots, Demo-Dateien

Szenario und visuelles Budget bestimmen:

SzenarioErkennungsmethodeStrategieBildobergrenze
README neu erstellenKein README oder sehr kurzVollständig generieren, aber kurzen Pfad halten1-2
README aktualisierenVorhandenes README mit gültigem InhaltEinzigartigen Inhalt behalten, Struktur und ersten Bildschirm neu schreiben0-2
Portfolio-StärkungBenutzer betont Ästhetik, Geschichte, PräsentationPriorität auf Erzählung und Bannerdarstellung2
Reiner DokumentationsmodusSDK, Bibliothek, Backend-Tool, InfrastrukturWenig Bilder, Fokus auf Installation, API, Dokumentationseinstieg0-1
UI / ProduktpräsentationHat Oberfläche, Screenshots, Demo, visuelle ErgebnisseEchte Ergebnisse oder Banner zur Verständnishilfe1-2

Beim Aktualisieren eines vorhandenen READMEs keine wichtigen bestehenden Inhalte des Benutzers löschen. Zuerst beibehaltbare Inhalte extrahieren, dann neu anordnen.

Rauschprüfung

Vor dem Schreiben des READMEs markieren, welche Inhalte ausgelagert oder gelöscht werden sollten:

InhaltStandardbehandlung
Design-Bewertungstabelle, Arbeitsprinzipien, interne MethodikIn SKILL.md oder docs/, nicht ins README
Generierte Dateibaumstruktur, Vorlagenvariablen, SkriptdetailsNur behalten, wenn der Benutzer Entwicklungsdokumentation benötigt
Drittes FlussdiagrammLöschen, durch 2-4 Zeilen Fließtext oder kurze Liste ersetzen
Zu viele Social-Media-LinksNur GitHub / Hauptseite als Kerneinstieg behalten
Zu allgemeine FunktionslisteZu 3 ergebnisorientierten Fähigkeiten zusammenfassen
Langer Hintergrund vor der InstallationKürzen, Schnellstart nach vorne ziehen

Phase 1: Destillation der Projektgeschichte

7 Felder sammeln oder ableiten:

FeldBeschreibung
project_nameOffizieller Projektname
taglineEinzeiliges Wertversprechen, kurz, mit Urteilskraft
originHintergrund des Projekts: Warum wurde es benötigt
audienceWer wird es nutzen
promiseWelches Ergebnis erhält der Benutzer dadurch
proofTatsächliche Fähigkeiten, Screenshots, Ausgaben, Beispiele, Metriken
startKürzester Einstiegspfad

Nicht zu viele Fragen stellen. Wenn es aus dem Projekt abgeleitet werden kann, direkt ableiten; nur bei Auswirkungen auf die Erzählgenauigkeit den Benutzer fragen.

Empfohlene Erzählstruktur

Projektname
Einzeiliges Wertversprechen
Visuelles Banner (je nach Projekttyp entscheiden, ob nötig)

Was ist das
Warum wird es benötigt
Was du bekommst
Schnellstart
Beispiel oder Ausgabe
Funktionsweise (Fließtext, standardmäßig kein Bild)
Installation
Lizenz
Autor

Wenn das Projekt eher ein Tool, eine Bibliothek oder Infrastruktur ist, „Schnellstart“ vor „Warum wird es benötigt“ setzen. Die Reihenfolge des READMEs dient der Handlung des Lesers, nicht der Vollständigkeit einer Vorlage.


Phase 2: Auswahl der visuellen Generierungsmethode

README-Bilder haben zwei Arten:

  1. Werk-Banner: Vermittelt Charakter, Thema, Erinnerungswert.
  2. Strukturelle Erklärungsgrafik: Vermittelt Schritte, Fähigkeiten, Vergleiche, Abläufe.

Modus basierend auf Benutzerabsicht wählen:

ModusAnwendungsszenarioBildstrategie
portfolioStandardempfehlung, geeignet für Projekte, die ein vollständiges Werkgefühl zeigen müssen1 Banner + 1 Kernfähigkeiten-Bild
clean-docSDK, Bibliothek, Backend-Tool, ernsthafte Infrastruktur0-1 Bilder, Priorität auf Schnellstart und Beispiele
visual-storyKI-Tools, Design-Tools, eigenständige Produkte, WerkpräsentationMaximal 2 Bilder, Codex Image Gen für Erinnerungswerte
structuredBenutzer wünscht explizit Infografiken, Vergleichsgrafiken, Flussdiagramme1-2 HTML/CSS-Plakate, um Textgenauigkeit zu gewährleisten

Standardmäßig zuerst den Projekttyp bestimmen, nicht portfolio erzwingen. Die Priorität der visuellen Asset-Generierung ist festgelegt:

  1. Codex Image Gen Skill: Priorisiere die integrierte Bildgenerierungsfähigkeit von Codex zur Erstellung visueller Assets.
  2. Leichtgewichtig: README-Anzeigebilder bevorzugt in WebP konvertieren, dann den Referenzpfad im README eintragen.
  3. HTML to PNG fallback: Nur wenn Image Gen nicht verfügbar ist, die Ausgabe nicht den Anforderungen entspricht oder der Benutzer explizit strukturierte, präzise Texte wünscht, auf HTML/CSS-Vorlagen-Screenshots zurückgreifen.

HTML-Screenshots nicht als Standardpfad betrachten. Sie sind eine zuverlässige Absicherung, nicht die bevorzugte visuelle Lösung.


Phase 3: Generierung von visuellen Assets in Portfolioqualität

Standardausgabe verwendet zwei stabile Dateinamen:

assets/banner.webp
assets/features.webp

Dadurch ist der README-Referenzpfad stabil, unabhängig davon, ob die Bilder von Codex Image Gen oder HTML-Screenshot-Absicherung stammen.

Bildaufgaben

BildZielEmpfohlene Methode
banner.webpProjektvisitenkarte, schafft Projektname, Positionierung und ErinnerungswertCodex Image Gen bevorzugt
features.webpVerbreitungsbild für Kernfähigkeiten, Ergebnisse oder notwendige AbläufeCodex Image Gen bevorzugt; HTML-Absicherung bei präzisem Text

Standardmäßig kein workflow.png oder workflow.webp generieren. Wenn der Benutzer explizit ein Flussdiagramm wünscht, die Flussinhalte in features.webp zusammenführen oder in den Fließtext setzen, kein drittes Bild hinzufügen.

Standardbildstil

Alle README-Visual-Assets verwenden standardmäßig denselben Stil:

Schwarzer Hintergrund, minimalistisch, filmische Beleuchtung, hoher Kontrast, große Leerräume, geringe Helligkeit, weiße/graue/warme goldene Dreifarbenpalette, hochwertiges Magazin-Cover-Gefühl.
Bildtextur: extrem tiefer schwarzer Hintergrund #050505, Papierkörnung, geringe Tiefenschärfe, volumetrischer Dunst, dünne Randbeleuchtung, selektive metallische Highlights.
Qualitätsziel: Designerniveau eines 10k-Star-Projekts.

Designbeschränkungen:

  • Hintergrund hauptsächlich tiefschwarz #050505.
  • Nur weiße, graue und warme goldene Farben verwenden; keine Regenbogenverläufe, lila-blaue Neon- oder hochgesättigte Dekorfarben einführen.
  • Große Leerräume und lokales Licht verwenden, anstatt Elemente zu stapeln.
  • Bilder sollten wenige hochwertige Textinformationen enthalten, die der Verbreitung und Positionierung dienen, keine langen Erklärungen.
  • Je weniger Text, desto besser: Jedes Bild behält nur die Informationen, an die sich der Leser erinnern sollte, nachdem er das README verlassen hat.
  • Keine Absätze, Befehle, Tabellen, gestapelte Versionsnummern oder dichte Beschreibungen einfügen.

Textstrategie für Projektvisitenkarten

Standardmäßig „Projektvisitenkarten-Bilder“ verwenden, keine reinen Atmosphärenbilder.

BildEmpfohlener TextObergrenze
banner.webpProjektname + einzeilige Positionierung + 1-3 kurze Tags18 englische Wörter oder 28 chinesische Schriftzeichen
features.webp2-3 Ergebnisphrasen, bei Bedarf einen kurzen Titel hinzufügenJede Phrase 2-5 Wörter

Guter Text sollte wie ein Cover-Titel wirken, nicht wie eine Bedienungsanleitung:

  • Projektname muss klar sein und bevorzugt auf banner.webp platziert werden.
  • Positionierungssatz beschreibt das Ergebnis, keinen Slogan, z. B. „Portfolio-grade README design for open source projects“.
  • Tags nur die Wörter mit dem höchsten Such- und Erinnerungswert verwenden, z. B. Story, Visual, Signal.
  • Chinesisch kann verwendet werden, aber sparsam; englische Projektnamen und kurze englische Tags sind in der Regel stabiler.
  • Wenn Image Gen Text falsch schreibt, einen erneuten Versuch starten; immer noch ungenau, dann das visuelle Hintergrundbild von Image Gen beibehalten und den präzisen Text mit HTML/CSS-Fallback bereitstellen.
  • Die Genauigkeit von Projektname und Positionierung nicht für eine „durchgehende KI-Generierung“ opfern.

Schriftgrößenuntergrenzen

Bei Design mit 1920×1080:

| Element | Minimale Schriftgröße | |---|---|---| | Haupttitel | 92px | | Chinesischer Haupttitel | 80px | | Großer Kartentitel | 48px | | Fließtextbeschreibung | 28px | | Hilfstags | 22px | | Fußzeile | 20px |

Keinen Text unter 18px verwenden. Nach der Skalierung durch GitHub ist er nicht mehr lesbar.

Codex Image Gen-Ergebnisse müssen nur im 16:9-Format und ausreichend scharf sein; nicht extra für 1920×1080 ein gutes Bild zwangsweise neu abtasten. README-Anzeigebilder bevorzugt als WebP speichern; 1920×1080 ist die Vorlagengröße für den HTML-to-PNG-Fallback.

HTML to PNG fallback

Nur verwenden, wenn Image Gen nicht verfügbar ist, der Benutzer präzise strukturierte Texte wünscht oder die Image Gen-Ausgabe die Prüfung nicht besteht:

node scripts/gen_infographic.mjs /tmp/readme-banner.html assets/banner.png 1920 1080
node scripts/gen_infographic.mjs /tmp/readme-features.html assets/features.png 1920 1080
node scripts/convert_webp_assets.mjs assets/banner.png assets/banner.webp assets/features.png assets/features.webp

Vorlagen stammen von:

templates/banner.html
templates/features.html

Vorlagenvariablen:

{{PROJECT_NAME}}
{{TAGLINE}}
{{PRIMARY_COLOR}}
{{CATEGORY}}
{{PLATFORM}}
{{LANGUAGE}}
{{VERSION_INFO}}
{{TECH_CARDS}}
{{FEATURE_CARDS}}
{{FEATURE_COUNT}}

Kartenstruktur:

  • {{TECH_CARDS}} wird auf der rechten Seite des Banners verwendet, empfohlen 2-3 Einträge, nur kurze Tags und eine Beschreibung.
  • {{FEATURE_CARDS}} nur 2-3 große Karten, die erste kann featured sein.
  • Wenn ein Arbeitsablauf dargestellt werden muss, die 3 Ergebnisphasen von features.webp verwenden, kein drittes Bild hinzufügen.

Codex Image Gen / gpt-image-2 Methode

Standardmäßig die integrierte Bildgenerierungsfähigkeit von Codex aufrufen und keine API-Skripte im Projekt fest codieren.

Für Image Gen geeignete Inhalte:

  • README-Banner.
  • Produktatmosphärenbilder.
  • Portfolio-Visuals.
  • Abstrakte Konzeptbilder.
  • Stilerweiterung mit vorhandenen Bildern.

Für Image Gen ungeeignete Inhalte:

  • Präzise Flussdiagramme.
  • Große Mengen chinesischen Texts oder mehrteilige Erklärungen.
  • Befehle, Versionen, Tabellen.
  • Wortwörtlich genauer langer Text oder UI-Bilder.

Empfohlene Prompt-Struktur:

Use case: productivity-visual
Asset type: GitHub README visual asset, 16:9
Project: <project_name>
Story: <origin + promise>
Visual direction: black background, minimalist, cinematic lighting, high contrast, large negative space, low brightness, premium magazine cover
Texture and lighting: #050505 deep black background, subtle paper grain, shallow depth of field, volumetric haze, thin rim light, selective metallic highlights
Palette: white, gray, warm gold only
Composition: one strong visual idea, restrained, spacious, no dense UI
Quality bar: 10k-star designer portfolio quality
Text policy: include only high-value name-card text. Use the exact project name, one short positioning line, and optional 1-3 short labels. No paragraphs, commands, tables, tiny captions, or decorative text.
Avoid: emoji, clutter, fake interface text, tiny labels, generic gradients, bright neon, overdesigned dashboards

Wenn Image Gen nicht unterstützt wird, nicht aufgerufen werden kann oder die Ausgabe falsche Texte/Stilabweichungen aufweist, zuerst mit einem kürzeren Text-Prompt einen erneuten Versuch starten; wenn immer noch ungenau, auf den HTML-to-PNG-Fallback-Prozess für präzisen Text zurückgreifen.

Bildoptimierung

README-Anzeigebilder standardmäßig als WebP verwenden. WebP ist in der Regel besser für das Laden von READMEs geeignet als PNG; PNG wird nur als Zwischenprodukt für HTML-Screenshot-Absicherung, transparente Bilder oder wenn verlustfreie Speicherung erforderlich ist, verwendet.

Standardbefehl:

npm run webp

Wenn das Projekt kein WebP-Konvertierungsskript hat, bevorzugt cwebp, sips oder ein verfügbares leichtgewichtiges Tool verwenden. Keine schweren Abhängigkeiten für die Konvertierung einführen. Wenn eine Konvertierung nicht möglich ist, PNG beibehalten und den Grund angeben.

Visuelle Prüfung

Nach der Generierung jedes Bildes überprüfen:

  • Auch nach Verkleinerung auf die README-Anzeigebreite von GitHub noch lesbar.
  • Ein Bild vermittelt nur einen Schwerpunkt.
  • Keine gestapelten kleinen Texte.
  • Projektname und Positionierungssatz auf einen Blick sichtbar.
  • Keine Rechtschreibfehler, verstümmelter Text oder Pseudotext im Bild.
  • Keine übermäßige Dekoration.
  • Visueller Stil stimmt mit der Projektgeschichte überein.
  • Image Gen-Bilder haben keine falschen Texte oder zusätzlichen Wasserzeichen.
  • Bilder sind nach der Komprimierung immer noch scharf, ohne sichtbare Farbbänder, Rauschartefakte oder unscharfe Textkanten.

Phase 4: README-Zusammenbau

Standardstruktur:

<div align="center">

# Projektname

**Einzeiliges Wertversprechen**

<img src="assets/banner.webp" alt="[Projektname] — [Wertversprechen]" width="100%">

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

</div>

---

## Was ist das

[2-3 Sätze zu Projekt, Hintergrund, Ergebnis.]

## Warum wird es benötigt

[Reale Probleme beschreiben, keine Anti-Pattern-Listen.]

## Was du bekommst

<img src="assets/features.webp" alt="[3 Kernfähigkeiten]" width="100%">

## Funktionsweise

[2-4 Zeilen zur Funktionsweise; standardmäßig kein drittes Bild hinzufügen.]

## Schnellstart

[Kürzester ausführbarer Pfad.]

## Installation

[Abhängigkeiten und Installationsbefehle.]

## Lizenz

[MIT](./LICENSE)

## Über den Autor

[Kurze Autoreninformationen.]

Regeln:

  • Nicht mehr als 3 Badges verwenden, es sei denn, das Projekt benötigt tatsächlich Statusindikatoren.
  • Nach Bildern keine identische Funktionsliste wiederholen.
  • „Designprinzipien“, „Projektstruktur“, „Generierte Inhalte“ nicht alle ins README packen; nur den für den Leser nützlichen Teil behalten.
  • Standardmäßig kein drittes Workflow-Bild einfügen; zwei Bilder reichen für das Werkgefühl und die Kerninformationen.
  • Wenn es detaillierte Erklärungen gibt, in docs/ ablegen, README dient nur als Einstieg.

Phase 5: Vorschläge für GitHub-Metadaten

Repository-Beschreibung und Topics sind Einstiegspunkte für die GitHub-Suche, Trending-Verknüpfungen, KI-Suchreferenzen und schnelle manuelle Bewertung. Sie sind kein README-Inhalt und sollten nicht in README.md geschrieben werden; sie werden nur in der endgültigen Antwort als eigenständiger Vorschlag ausgegeben.

First-Principle-Ziele

  • Description beantwortet: Für wen schafft dieses Projekt welches Ergebnis.
  • Topics beantworten: In welche Suchkategorien sollte dieses Projekt fallen.
  • Empfohlene Anzahl wird durch die Signalqualität bestimmt, nicht durch Quantität; hochwertige 7-9 sind in der Regel besser als 20 vollgestopfte.
  • Trending / SEO / GEO ausgleichen: Sowohl beliebte Suchbegriffe abdecken als auch die Projektfakten genau halten, um die KI-Referenzierung zu erleichtern.

Description-Erstellungsregeln

3 Kandidaten generieren und einzeln bewerten:

[Verb] [spezifisches Ergebnis] für [Zielgruppe] — [1-3 präzise Schlüsselwörter]

Harte Einschränkungen:

  • Bevorzugt Englisch, ≤ 160 Zeichen.
  • Mit Verb beginnen: Design / Generate / Build / Create / Convert / Automate.
  • Die 2-3 Kernschlüsselwörter des Projekts enthalten.
  • Kein Emoji, Ausrufezeichen, Marketing-Adjektive.
  • Keine Fähigkeiten schreiben, die nicht durch Projektfakten belegt werden können.

Bewertung:

DimensionPunkteKriterium
Genauigkeit40Entspricht den tatsächlichen Fähigkeiten des Projekts
Suchwert25Deckt häufig auf GitHub/Google gesuchte Begriffe ab
KI-Zitierbarkeit20Kann von ChatGPT / Claude / Perplexity direkt verstanden werden
Zurückhaltung15Keine Übertreibungen und kein Fülltext

Sternebewertung:

PunkteSterne
90-1005 Sterne, zur Verwendung empfohlen
80-894 Sterne, brauchbar, aber weiter kürzbar
70-793 Sterne, nur als Alternative geeignet
< 70Nicht empfohlen

Topics-Erstellungsregeln

Zunächst einen Kandidatenpool erstellen, dann die endgültige Empfehlung filtern.

Kandidatenquellen:

  • Projekttyp: agent-skill, cli-tool, developer-tools, documentation
  • Kerntechnologie: nodejs, playwright, codex, image-generation
  • Anwendungsbereich: readme, github-readme, open-source, portfolio
  • Aktuelle Trends: KI-Agenten, Bildgenerierung, Entwicklertools, Dokumentationsautomatisierung
  • Tatsächliche Projektdateien und Schlüsselwörter, die in der README-Erzählung vorkommen

Filterregeln:

  • 7-9 empfehlen, nicht mehr als 10, es sei denn, das Projekt erstreckt sich tatsächlich über mehrere klare Bereiche.
  • Topic muss klein geschrieben sein, nur Buchstaben, Zahlen und Bindestriche verwenden.
  • Zu allgemeine Wörter löschen: software, tool, app, github, project, ai.
  • Doppelte Wörter löschen: readme und github-readme können nebeneinander existieren; von open-source und opensource nur eines behalten.
  • Keine unrealistischen Topics hinzufügen, um Trends zu folgen.

Jedes Topic erhält eine Sternebewertung und einen Grund:

SterneBedeutung
5 SterneStark relevant, hoher Suchwert, sollte hinzugefügt werden
4 SterneRelevant und mit Entdeckungswert, kann hinzugefügt werden
3 SterneGewisser Zusammenhang, aber nicht kernrelevant
2 SterneSchwache Relevanz, normalerweise nicht empfohlen
1 SternRauschen, nicht hinzufügen

Ausgabeformat:

GitHub Description Empfehlung:

1.  ★★★★★ <description>
    Grund: ...

2.  ★★★★☆ <description>
    Grund: ...

Endgültige Empfehlung: <description>

GitHub Topics Empfehlung:

Hinzufügen:
- ★★★★★ github-readme — Beschreibt präzise den Projektzweck
- ★★★★★ agent-skill — Entspricht der Projektform
- ★★★★☆ image-generation — Hinzufügen, wenn das Projekt Image Gen unterstützt

Nicht empfohlen zum Hinzufügen:
- ★★☆☆☆ ai — Zu allgemein, Suchrauschen
- ★★☆☆☆ github — Zu allgemein, hilft nicht bei der Kategorisierung

Optionale gh CLI-Aktualisierung

Wenn der Benutzer gh installiert hat, das aktuelle Verzeichnis bereits ein Git-Repository ist und der GitHub-Remote aufgelöst werden kann, kann dem Benutzer vorgeschlagen werden, dass der Agent gh repo edit zur Aktualisierung verwendet. Nicht eigenmächtig aktualisieren; zuerst den auszuführenden Inhalt angeben und auf die Bestätigung des Benutzers warten.

Überprüfen:

gh --version
git remote -v

Empfohlenes Befehlsformat:

gh repo edit OWNER/REPO \
  --description "<final-description>" \
  --add-topic topic-one \
  --add-topic topic-two \
  --add-topic topic-three

Wenn alte Topics ersetzt werden müssen, zuerst die aktuellen Topics lesen, dann nur die explizit nicht empfohlenen entfernen:

gh repo view OWNER/REPO --json description,repositoryTopics
gh repo edit OWNER/REPO --remove-topic old-topic --add-topic new-topic

Hinweis: git kann keine Repository-Metadaten aktualisieren

Der git-Befehl kann weder die GitHub-Beschreibung noch die Topics ändern. Grund: Beschreibung und Topics sind Metadaten der GitHub-Plattform, keine Commits, Branches, Tags oder Remote-Konfigurationen im Git-Repository.

git remote -v kann nur zur Identifizierung von OWNER/REPO verwendet werden, nicht zur Aktualisierung von Metadaten.

Wenn gh nicht installiert ist, nur die empfohlenen Werte angeben, damit der Benutzer sie manuell auf der GitHub-Seite aktualisieren kann; keine komplexen Alternativbefehle bereitstellen.

Diese Empfehlungen nicht in der README-Datei speichern; sie gehören zu den Handlungsempfehlungen für den Benutzer bei der Auslieferung.


Phase 6: Validierung und Auslieferung

Vor der Auslieferung muss validiert werden:

node --version
npm run showcase
file assets/banner.webp assets/features.webp
git status --short

Wenn Vorlagen oder tatsächliche Bilder geändert wurden, WebP neu generieren und zur Überprüfung öffnen.

Der abschließende Bericht sollte nur Folgendes klarstellen:

  • Was wurde geändert.
  • Was ist das Ergebnis.
  • Welche Validierungen wurden durchgeführt.
  • Gibt es noch Punkte, über die der Benutzer entscheiden muss.

Dem Benutzer keine Implementierungsdetails und langwierigen Prozesse präsentieren.

Verwandte Skills