rfdiosuao/AgentSkill

Craft Repository README

Verwandle ein Repository in eine klare, glaubwürdige Landing Page. Stütze jede Behauptung, jeden Befehl, jedes Badge und jeden Link auf das tatsächliche Projekt; visuelle Aufbereitung darf niemals die Genauigkeit übertreffen.

Wähle den Betriebsmodus

• Verwende den Audit-Modus, wenn der Nutzer nur Feedback wünscht. Untersuche und berichte; bearbeite oder veröffentliche nicht.
• Verwende den Build-Modus, wenn der Nutzer die README erstellen oder verbessern möchte. Bearbeite das Repository und validiere das Ergebnis.
• Verwende den Publish-Modus nur, wenn der Nutzer einen Commit, Push, Pull Request oder die Aktualisierung von Repository-Einstellungen wünscht. Folge dem normalen Git-Workflow des Repositorys.

1. Untersuche das reale Projekt

Bevor du einen Entwurf erstellst, untersuche:

• Vorhandene README*-, Beitrags-, Sicherheits-, Lizenz-, Changelog- und Bereitstellungsdokumente.
• Paketmanifeste, Einstiegspunkte, Beispiel-Umgebungsdateien, Testbefehle, Screenshots, Logos und öffentliche URLs.
• Git-Remote, Standardbranch, Release-Tags, CI-Workflows und Hosting-Konfiguration.
• Repository-spezifische Anweisungen wie AGENTS.md oder CONTRIBUTING.md.

Leite den Produktnamen, einen einleitenden Wertversprechen-Satz, die Zielgruppe, unterstützte Plattformen, Installationsbefehle, Ausführungsbefehle und die Bereitstellungsgeschichte aus den Nachweisen ab. Wenn eine wesentliche Tatsache nicht überprüft werden kann, lasse sie weg oder kennzeichne sie klar als geplant.

2. Führe eine öffentliche und sicherheitsrelevante Überprüfung durch

Behandle README-Arbeit als Freigabeprüfung. Bevor du Details preisgibst:

• Durchsuche nachverfolgte Dateien und bereitgestellte Änderungen nach API-Schlüsseln, privaten Schlüsseln, Tokens, Passwörtern, Cookies, internen Hostnamen, privaten IPs und persönlichen Pfaden.
• Gib niemals Geheimnisse aus der lokalen Konfiguration, dem Chatverlauf, der Shell-Historie oder Bereitstellungsdateien weiter.
• Verlinke auf .env.example; reproduziere niemals Werte aus .env.
• Bestätige, dass Screenshots, QR-Codes, Namen und Kontaktlinks absichtlich öffentlich sind.
• Bewahre Lizenz-, Marken-, Quellenangaben- und Drittanbieterrechte.

Stoppe und zeige ein konkretes Hindernis an, wenn die Veröffentlichung vertrauliches Material offenlegen würde.

3. Gestalte die Geschichte vor der Dekoration

Schreibe die README in dieser Reihenfolge:

1. Erkennen – Name, Logo, prägnantes Versprechen.
2. Vertrauen – eine kleine Anzahl wahrheitsgemäßer Badges und ein echtes Produktbild.
3. Verstehen – was es tut, für wen es ist und sein wesentlicher Unterschied.
4. Ausprobieren – kürzester überprüfter Weg vom Klonen zum funktionierenden Ergebnis.
5. Adoptieren – Konfiguration, Bereitstellung, Architektur, Einschränkungen und Support.
6. Teilnehmen – Beitragsrichtlinien, Sicherheit, Lizenz, Sponsoren und Community.

Lies references/readme-patterns.md, bevor du ein README-Layout neu erstellst oder Badges auswählst.

4. Erstelle einen kompakten markierten Header

Verwende diese Reihenfolge, wenn das Projekt die entsprechenden Ressourcen hat:

1. Verlinktes Logo mit beschreibendem Alt-Text und zurückhaltender Größe.
2. Projektname und einzeiliges Wertversprechen.
3. Vier bis acht aussagekräftige Badges.
4. Primäre Links wie Live-Demo, Dokumentation, Issue-Tracker oder Download.
5. Optionale Seitennavigation für eine lange README.
6. Ein starkes Heldenbild, Produktscreenshot oder kurze Demo.

Bevorzuge Repository-eigene Assets unter einem stabilen docs/, .github/ oder assets/-Pfad. Verwende ein vorhandenes Logo, bevor du ein neues generierst. Wenn der Nutzer ein neues Bild wünscht und eine Bilderzeugungsfähigkeit verfügbar ist, verwende diese und optimiere dann das Ergebnis für die Repository-Anzeige.

Verwende keine gefälschten Build-Badges, Platzhalter-Metriken, riesige Badge-Wände, dekorative Zähler oder verlinkte Assets, die nicht vom Projekt kontrolliert werden.

5. Wähle nur nützliche Abschnitte aus

Ein kompaktes Projekt benötigt normalerweise:

• Was es ist und warum es existiert.
• Höhepunkte der Funktionen, die auf implementiertem Verhalten basieren.
• Schnellstart mit kopierbaren, getesteten Befehlen.
• Konfiguration mit sicheren Platzhaltern.
• Screenshots oder Demo, wenn visuelle Beweise wesentlich helfen.
• Bereitstellungs- oder Produktionshinweise, wenn das Projekt bereitstellbar ist.
• Beitrags-, Sicherheits-, Lizenz- und Danksagungslinks, wenn diese Dateien vorhanden sind.

Füge Architektur, API-Referenz, Kompatibilität, Roadmap, FAQ oder Fehlerbehebung nur hinzu, wenn das Projekt dies rechtfertigt. Erstelle keine leeren Abschnitte mit Vorlagen.

Für chinesische Projekte: Schreibe zuerst natürliches Chinesisch und behalte technische Bezeichner in ihrer ursprünglichen Form bei. Füge eine englische Version nur auf Anfrage hinzu, oder wenn das Repository bereits eine unterhält.

6. Füge Sponsoring hinzu, ohne die Produktgeschichte zu stören

Wenn der Nutzer ein Sponsor-Bild oder einen QR-Code bereitstellt und autorisiert:

• Kopiere es in einen stabilen, vom Repository verwalteten Asset-Pfad.
• Verwende eine klare Überschrift wie Unterstützung oder Sponsor im unteren Teil der README.
• Füge Alt-Text, eine angemessene Breite und einen Satz hinzu, der erklärt, was durch die Unterstützung finanziert wird.
• Ändere, entschlüssele oder regeneriere niemals einen Zahlungs-QR-Code, es sei denn, es wird ausdrücklich darum gebeten.

Sponsoring darf niemals den Schnellstart, die Dokumentation oder die Sicherheitsinformationen überlagern.

7. Überprüfe die README als ausführbare Dokumentation

Führe nach Möglichkeit die relevanten Build-, Test-, Lint- oder Smoke-Befehle des Projekts aus. Führe dann den gebündelten Prüfer aus:

python3 craft-repository-readme/scripts/validate_readme.py \
  --repo-root . \
  --readme README.md

Füge strenge Flags hinzu, wenn die entsprechenden Elemente erforderlich sind:

python3 craft-repository-readme/scripts/validate_readme.py \
  --repo-root . \
  --readme README.md \
  --require-logo --require-badges --require-hero --require-sponsor

Überprüfe auch manuell:

• Jeder Installations- und Ausführungsbefehl stimmt mit dem Repository überein.
• Relative Bild- und Dokumentlinks werden mit den GitHub-spezifischen Pfaden aufgelöst (Groß-/Kleinschreibung).
• Externe Links verwenden die beabsichtigten kanonischen Domains.
• Überschriftenanker und Links zum Inhaltsverzeichnis funktionieren.
• Bilder haben beschreibenden Alt-Text und angemessene Abmessungen.
• Die README wird sowohl auf Desktop- als auch auf schmalen Bildschirmen gut dargestellt.
• Es sind kein Geheimnis, kein Platzhalter, kein lokaler absoluter Pfad und keine unbelegte Behauptung mehr vorhanden.

8. Veröffentliche bewusst

Wenn die Veröffentlichung im Umfang enthalten ist:

• Überprüfe git diff und halte nicht zusammenhängende Änderungen aus dem Commit heraus.
• Führe den Commit mit einer fokussierten Nachricht durch und pushe über den normalen Workflow des Repositorys.
• Bevorzuge einen Pull Request, wenn Branch-Schutz oder Zusammenarbeitspraktiken dies erfordern.
• Aktualisiere die GitHub-Beschreibung, Homepage, Themen und soziale Vorschau nur, wenn der Nutzer Änderungen an den Repository-Einstellungen angefordert hat und die Werte verifiziert sind.
• Öffne nach der Veröffentlichung die gerenderte README auf GitHub erneut und überprüfe Bilder, Badges, Links und das mobile Layout.

Abschlusskriterien

• Der erste Bildschirm vermittelt Name, Zweck, Vertrauenssignale und die primäre nächste Aktion.
• Alle hervorgehobenen Behauptungen und Befehle sind gegen das Repository verifiziert.
• Logo, Heldenbild, Badges und Sponsorinhalte sind beabsichtigt und nicht dekorativ.
• Links und lokale Assets werden aufgelöst.
• Keine geheimen oder privaten Umgebungsdetails sind offengelegt.
• Die Validierung ist bestanden und der angeforderte Veröffentlichungsschritt ist abgeschlossen.