CommunitySchreiben & Editierengithub.com

tzwkb/repo-maintainer

Agent Skill – Aufräumen, Konsolidieren und Pflegen von GitHub-Repositories.

Was ist repo-maintainer?

Diese Skill-Anleitung befähigt KI-Agenten wie Claude Code, Cursor oder Codex, ein systematisches sechsphasiges Bereinigungs-Workflow für GitHub-Profile durchzuführen. Sie ist darauf ausgelegt, fragmentierte, ungepflegte Profile in saubere, professionelle und wartbare Repositories zu verwandeln. Der Prozess beginnt mit einer Diagnosephase, in der das gesamte Repository über die GitHub-API gescannt wird, um fehlende Fundamentaldokumente (LICENSE, README.md, .gitignore, Beschreibung) sowie Inkonsistenzen in der Namensgebung und veraltete Einträge zu identifizieren. Darauf folgen die Standardisierung der Basisdokumente, die Handhabung veralteter Repos (archivieren/löschen), das Zusammenführen verwandter Projekte (Monorepo/Submodul) und das Umbenennen nach einem einheitlichen Schema. Die letzte Phase behandelt Code-Refactoring und das Zurückschieben großer lokaler Änderungen unter strenger Einhaltung von Sicherheits- und Compliance-Regeln. Ein besonderer Schwerpunkt liegt auf der Erkennung von Secret-Leaks vor jedem Push; öffentliche Repos mit geleakten Secrets müssen zwangsweise gelöscht werden. Die Anleitung enthält detaillierte Python-/Bash-Skripte und klare Entscheidungsbäume für verschiedene Szenarien wie das Fehlen einer Git-Historie oder massive Umbenennungen. Sie ist für Entwickler konzipiert, die ihre GitHub-Präsenz professionalisieren und gleichzeitig Sicherheitsrisiken minimieren möchten.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add tzwkb/repo-maintainer

Installed? Explore more Schreiben & Editieren skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

In Ihrer bevorzugten KI fragen

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

Dokumentation

Repository Maintainer

Systematischer Workflow zur Umwandlung fragmentierter GitHub-Profile in saubere, wartbare und professionelle Repositories.

Überblick

Führen Sie die Bereinigung in 6 Phasen durch. Überspringen Sie nicht zutreffende Phasen. Holen Sie bei zerstörerischen Aktionen (Löschen, Umbenennen, Zusammenführen) immer die Bestätigung des Benutzers ein.

Kernprinzipien (Nicht verhandelbar)

Jedes Repository – neu oder alt, aktiv oder archiviert – muss diese vier grundlegenden Dokumente besitzen. Betrachten Sie eine Bereinigung erst dann als abgeschlossen, wenn alle vier überprüft wurden.

DokumentRegelWarum
LICENSEJedes öffentliche Repository erhält eine LICENSE. Standard ist MIT, sofern der Benutzer nichts anderes angibt.Ohne Lizenz ist der Code standardmäßig „Alle Rechte vorbehalten". Niemand kann ihn legal nutzen.
README.mdMuss mindestens enthalten: Projektname, ein Satz Beschreibung und ggf. Installations-/Verwendungsanweisungen.Das erste, was jeder Besucher sieht. Ein leeres oder fehlendes README signalisiert Aufgabe.
.gitignoreMuss zur primären Sprache passen (Python/PHP/Node/usw.). Keine Build-Artefakte, Caches, Env-Dateien oder IDE-Konfigurationen committen.Verhindert versehentliches Durchsickern von Geheimnissen und hält Diffs lesbar.
GitHub BeschreibungDas Feld description darf niemals leer sein. Ein Satz in klarem Deutsch (oder passend zur Sprache des Repos).Erscheint in Suchergebnissen, Profil-Pins und Social Cards.

Wenn einem Repository eines der vier Dokumente fehlt, hat die Behebung Priorität vor Zusammenführen, Umbenennen oder Refactoring.

Phase 1: Scannen und Diagnose

Komplette Repo-Liste über die GitHub-API abrufen:

curl -sH "Authorization: Bearer TOKEN" \
  "https://api.github.com/user/repos?per_page=100&affiliation=owner"

Für jedes Repository prüfen:

  • Fehlende LICENSE, .gitignore, README.md
  • Leeres description-Feld
  • Inkonsistenzen in der Benennung (gemischte Groß-/Kleinschreibung, übermäßig lange Namen)
  • Offensichtliche Duplikate oder Serien (z. B. projekt, projekt-v2, projekt-mineru)
  • Namen mit outdated, deprecated, old, test

Phase 2: Fundamentaldokumente standardisieren

Für jedes aktive Repository sicherstellen, dass der minimale Dateisatz vorhanden ist:

DateiRegel
LICENSEStandard ist MIT, sofern der Benutzer nichts anderes angibt
.gitignoreMuss zur primären Sprache passen (Python/PHP/Node)
README.mdMuss vorhanden sein; bei Platzhaltern neu schreiben
GitHub BeschreibungEin-Satz-Zusammenfassung über die API

Massenaktualisierung über die GitHub Contents API (PUT /repos/{owner}/{repo}/contents/{path}).

Wichtig: PowerShell Here-Strings beschädigen Codeblöcke mit drei Backticks in Markdown. Verwenden Sie Python-Skripte für die README-Massenerstellung, um Probleme mit der Maskierung von ` zu vermeiden.

Phase 3: Umgang mit veralteten Repositories

Entscheidungsbaum:

BedingungAktion
Name enthält outdated / deprecated / oldArchivieren oder löschen
Durch neueres Repository ersetztArchivieren + README-Nachfolgelink
Öffentliches Repo enthält durchgesickerte Secrets (API-Keys) in der HistorieLöschen (Archivieren behält die Historie bei)
Privates Repo enthält Keys, Passwörter, private Konfiguration oder personenbezogene DatenBenutzer darf Leck-Regeln ignorieren; als akzeptablen privaten Zustand behandeln, es sei denn, er bittet um Bereinigung
Als Referenz nützlich, aber ungepflegtArchivieren

Archivierte Repositories sind schreibgeschützt. Um ein archiviertes Repository zu ändern (umbenennen, README aktualisieren), zuerst dearchivieren (PATCH {"archived": false}), Änderungen vornehmen, dann erneut archivieren.

Phase 4: Zusammenhängende Repositories zusammenführen

Wenn 2+ Repos Varianten desselben Systems sind (verschiedene Backends, Engines, Adapter):

Option A – Monorepo (Empfohlen) Ein neues, sauberes Repository (ohne Historie) erstellen. Jede Variante in eigenem engines/{name}/-Unterverzeichnis platzieren.

projekt-suite/
├── main.py              # Standard-Engine
├── engines/
│   ├── babeldoc/
│   └── mineru/
└── README.md

Einstiegspunkt und Konfiguration jeder Engine beibehalten. Root-README aktualisieren, um den Wechsel zu erklären.

Option B – Git-Submodul Repos unabhängig lassen. Submodule im übergeordneten Projekt hinzufügen. Verwenden, wenn die Historie wichtiger ist als Einfachheit.

Option C – Unabhängig lassen + verlinken Nicht zusammenführen. Cross-Links in READMEs hinzufügen. Verwenden, wenn sich die Varianten erheblich unterschieden haben.

Wenn die Historie Secrets enthält: Immer ein neues, sauberes Repository erstellen und den aktuellen Snapshot kopieren (per Zip-Download + Neu-Commit). git merge oder git submodule nicht verwenden, da die Historie-Leaks bestehen bleiben.

Phase 5: Repositories umbenennen

API-Patch: PATCH /repos/{owner}/{repo} mit {"name": "neuer-name"}.

Richtlinien:

  • Nur Kleinbuchstaben, Bindestriche erlaubt
  • Maximal 3-4 Wörter
  • Überflüssige Wörter entfernen (based-on, design-and-development)
  • Bei archivierten Repos ggf. -outdated anhängen, wenn nicht bereits vorhanden

GitHub leitet alte URLs für eine gewisse Zeit automatisch weiter, aber Lesezeichen und Skripte könnten brechen. Vor dem Umbenennen von gestarnten oder geforkten Repos die Bestätigung des Benutzers einholen.

Phase 6: Refactoring auf Code-Ebene

Nachdem die Remote-Struktur bereinigt ist, den Code in den Repos refactorn:

  1. Einheitliche Terminologie – Hartcodierte Markennamen durch generische Begriffe ersetzen (GPTProcessor → LLMProcessor), während die tatsächlichen API-Modell-IDs (gpt-4, gpt-5) erhalten bleiben.
  2. Dateien umbenennen – Die GitHub Contents API hat keine Umbenennungsfunktion; neue Datei mit aktualisiertem Inhalt erstellen, alte Datei löschen.
  3. Verzeichnisstruktur überarbeiten – Muster wie engines/, variants/ oder core/ + adapters/ für Projekte mit mehreren Varianten verwenden.

Große lokale Refactorings an Remote pushen

Wenn der Benutzer Code lokal herunterlädt, umfangreiche Änderungen vornimmt (Datei-Umbenennungen, Variablen-Umbenennungen, strukturelle Umschreibungen) und zurück ins Remote-Repository pushen muss.

Pre-Push-Scanner auf Secrets (VERPFLICHTEND)

Vor dem Push muss ein Scan auf Secret-Leaks durchgeführt werden. Bei Fund sofort melden und den Push stoppen.

Ausnahme für private Repos: Wenn das Ziel-Repository nachweislich privat ist, können Leaks von Keys, Passwörtern, privaten Konfigurationen, personenbezogenen Daten und anderen sensiblen Informationen ignoriert werden. Der Scan dient als Hinweis, blockiert aber nicht den Push und erfordert keine Löschung/Neuerstellung des Repos oder Austausch gegen Umgebungsvariablen, es sei denn, der Benutzer fordert eine Bereinigung oder plant, das Repo öffentlich zu machen.

Scan-Modus (beide Läufe sind erforderlich – nur den Token-Regex zu laufen lässt Klartext-Passwörter aus):

① Token/API-Key mit hoher Entropie:

grep -rn "sk-[A-Za-z0-9]\{20,\}\|ghp_[A-Za-z0-9]\{36\}\|ghu_\|github_pat_\|Bearer [A-Za-z0-9+/=]\{40,\}" \
  --include="*.py" --include="*.js" --include="*.ts" --include="*.yaml" \
  --include="*.env" --include="*.json" --include="*.bat" --include="*.sh" \
  --exclude-dir=".git" .

② Klartext-Passwörter / Credential-Helper (vom Token-Regex nicht erfasst; in der Praxis wurde askpass.sh mit echo "<sudo password>" übersehen und landete per Init-Commit auf GitHub):

git ls-files -z | xargs -0 grep -nIE "password|passwd|SUDO_ASKPASS|sshpass|^[[:space:]]*echo[[:space:]]+[\"'][^\"']{6,}[\"']" 2>/dev/null \
  | grep -vE "\.md:|getenv|getpass|placeholder|example"
# Und isolierte askpass.sh / *_secret* / .pgpass / .npmrc-Dateien manuell prüfen – diese Dateien sind selbst die Credentials

Bei öffentlichen Repos führt jeder Treffer sofort zur unten beschriebenen Zwangsverarbeitung. Bei privaten Repos wird der Benutzer nur gewarnt, es gibt keine Blockade. Beachten Sie: Gescannt wird git ls-files (bereits getrackte Dateien); durch .gitignore ausgeschlossene Dateien zählen nicht als Leak, aber bereits committete Dateien bleiben auch dann in der Historie, wenn sie jetzt in .gitignore sind.

Meldeformat:

[LEAK] scripts/eval.py:15 — sk-xxxx (hartcodierter Fallback)
[LEAK] ui/ui_backend.py:33 — sk-xxxx (hartcodierter Standardwert)

Zwangsverarbeitung bei Leak-Fund:

  1. Benutzer sofort informieren, in welcher Datei in welcher Zeile
  2. Durch Umgebungsvariable ersetzen (os.getenv("API_KEY") ohne Standardwert)
  3. Bereits nach Remote gepusht: Benutzer informieren, nach Bestätigung Repo löschen und neu erstellen (Git-Historie lässt sich durch Force-Push nicht vollständig entfernen)
  4. Benutzer muss den Key beim entsprechenden Dienst widerrufen

Pre-Push-Checkliste

Vor dem Push muss Folgendes ausgeführt werden:

git status

Sicherstellen, dass Folgendes nicht vorliegt:

  • Untracked files – Neue, nicht verfolgte Dateien (häufig vergessen: docs/, scripts/, config-Vorlagen)
  • Changes not staged – Änderungen, die nicht hinzugefügt wurden
  • Changes to be committed enthält Dateien, die nicht hochgeladen werden sollten (Schlüssel, persönliche Daten, temporäre Skripte)

Bevor dies bestätigt ist, ist ein direkter Push verboten.

Entscheidungsbaum

SituationEmpfohlene Aktion
Lokales Repo hat kein .git (heruntergeladene Zip / kopierte Dateien)Siehe Szenario A unten
Lokal ist git clone mit Historie, Remote unverändertNormal git add → commit → push
Lokal ist git clone, Remote hat neue Commitsgit pull --rebase oder merge, Konflikte lösen, pushen
Lokal ist git clone, Änderungen sind massive Umbenennungen + UmschreibungenSiehe Szenario B unten
Remote-Historie erhalten, aber gesamten Code ersetzenSiehe Szenario C unten

Szenario A: Lokal hat keine Git-Historie

Tritt am häufigsten auf, wenn der Benutzer eine Zip herunterlädt, umfangreich bearbeitet und dann zurück synchronisieren möchte.

Option A1 – Force Push (Persönliche / Solo-Projekte)

# Im lokalen Projektordner
git init
git add .
git commit -m "refactor: major rewrite"
git remote add origin https://github.com/BESITZER/REPO.git
git branch -M main
git push -u origin main --force

⚠️ Zerstört die Remote-Historie. Nur verwenden, wenn der Benutzer bestätigt, dass die Remote-Historie entbehrlich ist.

Option A2 – Remote-Historie erhalten (Empfohlen für wertvolle Repos)

git clone https://github.com/BESITZER/REPO.git temp-repo
cp -r temp-repo/.git ./ihr-lokales-projekt/
cd ihr-lokales-projekt
git add .
git commit -m "refactor: major rewrite"
git push

Dies behält alle vorherigen Commits und hängt den Refactor als einzelnen neuen Commit an.

Option A3 – Neues sauberes Repository Wenn die Umschreibung so radikal ist, dass es sich im Wesentlichen um ein neues Projekt handelt:

  1. Neues Repo auf GitHub erstellen (muss description enthalten oder sofort per PATCH setzen)
  2. Lokalen Code dorthin pushen
  3. Altes Repo mit Nachfolgelink im README archivieren

Szenario B: Massive Umbenennungen + Umschreibungen in einem geklonten Repo

Wichtige Regel: Niemals Dateiumbenennungen und Inhaltsänderungen im selben Commit mischen. Git behandelt dies als „Alte Datei löschen + Neue Datei erstellen" und verliert die Historie.

Schrittweise Commit-Strategie:

# Schritt 1: Nur umbenennen
git mv altes_module.py neues_module.py
git mv alte_utils/ neue_utils/
git commit -m "refactor: Module umbenennen"

# Schritt 2: Variablen-/Klassen umbenennen
git add .
git commit -m "refactor: Variablen und Klassen umbenennen"

# Schritt 3: Logik-Änderungen
git add .
git commit -m "feat: Kernlogik aktualisieren"

Wenn der Benutzer bereits alles im Arbeitsverzeichnis vermischt hat:

# Aktuelle Änderungen stashen, in Schritten wiedereinspielen
git stash push -m "gemischter Refactor"

# Nur Umbenennungen wiederherstellen (git mv oder manuelles mv + git add verwenden)
git mv alte_datei neue_datei
git commit -m "refactor: Dateien umbenennen"

# Inhaltsänderungen wiederherstellen
git stash pop
# Ggf. Konflikte lösen, dann committen

Szenario C: Gesamten Code ersetzen, aber Historie behalten

Nützlich, wenn der Benutzer einen Neuanfang machen möchte, aber Stars/Issues/URL behalten will.

git checkout --orphan fresh-start
git rm -rf .
# Neuen lokalen Code hier einfügen
git add .
git commit -m "init: clean rewrite"
git branch -D main
git branch -m main
git push -u origin main --force

Erkennung von Umbenennungen prüfen

Nach dem Push überprüfen, ob Git die Umbenennungen korrekt verfolgt:

git log --follow -- neue_datei.py

Wenn die Historie unterbrochen ist (Datei als brandneu angezeigt wird), wurden Umbenennung und Inhaltsänderung zusammen committet.

Sicherheit und Compliance

  • GitHub-Token: Wenn ein PAT benötigt wird, im Agenten-Gedächtnis suchen (kein konkreter Pfad/Konto/Wert hier). Den Token-Wert niemals in eine Datei schreiben, die gepusht wird (einschließlich dieser Skill, README, Konfiguration) – sobald ein Token-haltiger Inhalt gepusht wird, wird er durch GitHub-Secret-Scanning widerrufen.
  • Token-Hygiene: Nach Bulk-Operationen den Benutzer anweisen, das PAT sofort unter https://github.com/settings/tokens zu widerrufen.
  • Ausnahme für private Repos: Wenn ein Repo privat ist, kann der Agent Leaks von Keys, Passwörtern, privater Konfiguration, personenbezogenen Daten und anderen sensiblen Informationen ignorieren. Push nicht blockieren, keine Zwangsbereinigung durchführen oder Löschung empfehlen, nur weil die private Historie Secrets enthält, es sei denn, der Benutzer verlangt es oder das Repo könnte öffentlich werden.
  • Öffentliche Secret-Historie: Wenn ein öffentliches Repository jemals API-Keys committet hat, ist das Löschen des Repos der einzige Weg, die Historie von GitHub zu entfernen. Force-Push einer bereinigten Historie garantiert keine Entfernung aus den Backup-Systemen von GitHub.
  • Archivierte öffentliche Repos mit Secrets: Wenn Löschung inakzeptabel ist, das Repo mindestens aus der öffentlichen Sichtbarkeit entfernen (privat machen) oder löschen und mit sauberem Code neu erstellen.

Technische Referenz

Encoding-Fallen (Windows)

PowerShell verwendet standardmäßig CP1252 für die Standardausgabe, was chinesische Zeichen und Markdown-Codeblöcke zerstört. Immer neu konfigurieren:

import sys
sys.stdout.reconfigure(encoding='utf-8')

Bei Verwendung von Invoke-RestMethod in PowerShell mit JSON-Bodies, die Backticks oder drei Backticks enthalten, Python-Skripte für die Inhaltsgenerierung bevorzugen, um zu vermeiden, dass ``` in ` umgewandelt wird.

GitHub-API-Muster

Repository erstellen (niemals description weglassen):

api_call("POST", "/user/repos", {
    "name": "repo-name",
    "private": True,
    "description": "Ein-Satz-Zusammenfassung."
})

Datei erstellen/aktualisieren:

import base64, json, urllib.request

payload = {
    "message": "Commit-Nachricht",
    "content": base64.b64encode(content.encode('utf-8')).decode(),
    "sha": existing_sha  # für Aktualisierungen erforderlich
}
req = urllib.request.Request(
    f"https://api.github.com/repos/{owner}/{repo}/contents/{path}",
    method="PUT",
    data=json.dumps(payload).encode(),
    headers={"Authorization": f"Bearer {token}", ...}
)

Archivieren/Dearchivieren:

api_call("PATCH", f"/repos/{owner}/{repo}", {"archived": True})

Repository umbenennen:

api_call("PATCH", f"/repos/{owner}/{repo}", {"name": "neuer-name"})

Repository löschen:

api_call("DELETE", f"/repos/{owner}/{repo}")

Massen-Download ohne Clone

Repo-Snapshot als Zip herunterladen, um langsames git clone über instabile Netzwerke zu vermeiden:

curl -sL "https://github.com/{owner}/{repo}/archive/refs/heads/main.zip" -o {repo}.zip

Mitgelieferte Ressourcen

  • scripts/repo_analyzer.py – GitHub-Repos des Benutzers scannen und Bereinigungsempfehlungen generieren
  • scripts/bulk_file_updater.py – LICENSE, .gitignore, README per GitHub-API in Batches erstellen/aktualisieren

Verwandte Skills