CommunityRédaction et éditiongithub.com

tzwkb/repo-maintainer

Compétence d'agent — nettoyage, consolidation et maintenance de dépôts GitHub.

Qu'est-ce que repo-maintainer ?

Cette compétence d'agent (skill) fournit un flux de travail systématique en six phases pour transformer des profils GitHub fragmentés en dépôts professionnels, propres et maintenables. Elle est conçue pour les agents IA comme Claude Code, Cursor ou Codex qui interagissent avec l'API GitHub. L'agent commence par analyser et diagnostiquer l'ensemble des dépôts, à la recherche de fichiers manquants (LICENSE, README, .gitignore), de descriptions vides et d'incohérences de nommage. Ensuite, il standardise ces fichiers fondamentaux pour chaque dépôt actif, puis gère les dépôts obsolètes en les archivant ou en les supprimant. La phase de fusion permet de consolider des dépôts similaires en un monorepo, avec des sous-modules ou des liens croisés, tout en gérant les problèmes de sécurité comme les fuites de secrets. Le skill comprend également des phases de renommage et de refactoring au niveau du code, avec des stratégies de commit précises pour préserver l'historique Git. Une section importante est dédiée au push de refactorisations locales volumineuses, avec une vérification de sécurité obligatoire avant push (scan de tokens et mots de passe en clair) et un arbre de décision complet pour différents scénarios (clone, zip, réécriture massive). Le skill est multi-plateforme (fonctionne avec tout agent capable d'appeler l'API GitHub) et fournit des scripts Python utilitaires pour l'analyse et la mise à jour en masse.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add tzwkb/repo-maintainer

Installed? Explore more Rédaction et édition skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Repository Maintainer

Flux de travail systématique pour transformer des profils GitHub fragmentés en dépôts propres, maintenables et professionnels.

Aperçu

Exécutez le nettoyage en 6 phases. Ignorez les phases non pertinentes. Obtenez toujours la confirmation de l'utilisateur pour les actions destructrices (suppression, renommage, fusion).

Principes fondamentaux (non négociables)

Chaque dépôt — nouveau ou ancien, actif ou archivé — doit posséder ces quatre documents de base. Ne considérez pas un nettoyage comme terminé tant que les quatre ne sont pas vérifiés.

DocumentRèglePourquoi
LICENSEChaque dépôt public obtient une LICENSE. Par défaut MIT sauf indication contraire de l'utilisateur.Sans licence, le code est « tous droits réservés » par défaut. Personne ne peut légalement l'utiliser.
README.mdDoit exister avec au moins : nom du projet, description en une phrase, et instructions d'utilisation/installation si applicable.La première chose que chaque visiteur voit. Un README vide ou manquant signale un abandon.
.gitignoreDoit correspondre au langage principal (Python/PHP/Node/etc.). Ne commitez jamais les artefacts de build, le cache, les fichiers d'environnement ou les configurations IDE.Empêche la fuite accidentelle de secrets et maintient la lisibilité des diffs.
Description GitHubLe champ description ne doit jamais être vide. Une phrase, en anglais simple (ou dans la langue du dépôt).Apparaît dans les résultats de recherche, les épingles de profil et les cartes sociales.

Si un dépôt manque de l'un des quatre, sa correction a priorité sur la fusion, le renommage ou le refactoring.

Phase 1 : Analyse et diagnostic

Récupérez la liste complète des dépôts via l'API GitHub :

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

Vérifiez pour chaque dépôt :

  • Absence de LICENSE, .gitignore, README.md
  • Champ description vide
  • Incohérences de nommage (majuscules/minuscules mélangées, noms trop longs)
  • Doublons ou séries évidents (ex. project, project-v2, project-mineru)
  • Noms contenant outdated, deprecated, old, test

Phase 2 : Standardiser les fichiers fondamentaux

Pour chaque dépôt actif, assurez-vous que l'ensemble de fichiers minimum existe :

FichierRègle
LICENSEPar défaut MIT sauf indication contraire de l'utilisateur
.gitignoreCorrespond au langage principal (Python/PHP/Node)
README.mdDoit exister ; réécrire s'il n'est qu'un espace réservé
Description GitHubRésumé en une phrase via l'API

Mise à jour groupée via l'API GitHub Contents (PUT /repos/{owner}/{repo}/contents/{path}).

Critique : les here-strings PowerShell corrompent les blocs de code à triple backtick en Markdown. Utilisez des scripts Python pour la génération groupée de README afin d'éviter les échecs d'échappement ` → ```.

Phase 3 : Gérer les dépôts obsolètes

Arbre de décision :

ConditionAction
Le nom contient outdated / deprecated / oldArchiver ou supprimer
Remplacé par un dépôt plus récentArchiver + lien vers le successeur dans le README
L'historique du dépôt public contient des secrets divulgués (clés API)Supprimer (l'archive laisse l'historique intact)
Le dépôt privé contient des clés, mots de passe, configuration privée ou données personnellesL'utilisateur peut ignorer les règles de fuite ; traiter comme un état privé acceptable sauf s'il demande un assainissement
Utile comme référence mais non maintenuArchiver

Les dépôts archivés sont en lecture seule. Pour modifier un dépôt archivé (renommer, mettre à jour le README), désarchivez d'abord (PATCH {"archived": false}), effectuez les modifications, puis réarchivez.

Phase 4 : Fusionner les dépôts connexes

Lorsque 2+ dépôts sont des variantes du même système (backends, moteurs, adaptateurs différents) :

Option A — Monorepo (recommandé) Créez un nouveau dépôt propre (sans historique). Placez chaque variante dans un sous-répertoire engines/{nom}/.

project-suite/
├── main.py              # moteur par défaut
├── engines/
│   ├── babeldoc/
│   └── mineru/
└── README.md

Préservez le point d'entrée et la configuration de chaque moteur. Mettez à jour le README racine pour expliquer le changement.

Option B — Sous-module Git Gardez les dépôts indépendants. Ajoutez des sous-modules dans le dépôt parent. À utiliser lorsque la préservation de l'historique est plus importante que la simplicité.

Option C — Garder indépendant + Lien Ne fusionnez pas. Ajoutez des liens croisés dans les README. À utiliser lorsque les variantes ont considérablement divergé.

Si l'historique contient des secrets : Créez toujours un nouveau dépôt propre et copiez l'instantané actuel (via téléchargement zip + re-commit). N'utilisez pas git merge ou git submodule car les fuites d'historique persisteraient.

Phase 5 : Renommer les dépôts

API PATCH : PATCH /repos/{owner}/{repo} avec {"name": "new-name"}.

Directives :

  • Tout en minuscules, tirets uniquement
  • 3-4 mots maximum
  • Supprimez les mots redondants (based-on, design-and-development)
  • Ajoutez le suffixe outdated aux dépôts archivés s'il n'est pas déjà présent

GitHub redirige automatiquement les anciennes URL pendant une période, mais les signets et les scripts peuvent se casser. Confirmez avec l'utilisateur avant de renommer les dépôts avec des étoiles ou des forks.

Phase 6 : Refactoring au niveau du code

Une fois la structure distante propre, refactorez le code dans les dépôts :

  1. Terminologie unifiée — Remplacez les noms de marque codés en dur par des termes génériques (GPTProcessor → LLMProcessor) tout en préservant les ID de modèle API réels (gpt-4, gpt-5).
  2. Renommage de fichiers — L'API GitHub Contents n'a pas de renommage ; créez un nouveau fichier avec le contenu mis à jour, supprimez l'ancien fichier.
  3. Réorganisation des répertoires — Utilisez les modèles engines/, variants/, ou core/ + adapters/ pour les projets multi-variantes.

Pousser les refactorisations locales volumineuses vers le dépôt distant

Lorsque l'utilisateur télécharge du code localement, effectue des modifications importantes (renommages de fichiers, renommages de variables, réécritures structurelles) et doit pousser vers le dépôt distant.

Analyse de sécurité pré-push (OBLIGATOIRE)

Avant de pousser, vous devez d'abord analyser les fuites de secrets. Signalez immédiatement toute découverte et interrompez le push.

Exception pour les dépôts privés : Si le dépôt cible est confirmé privé, vous pouvez ignorer les règles de fuite de clés, mots de passe, configuration privée, données personnelles et autres informations sensibles. L'analyse peut servir d'avertissement, mais les correspondances ne bloquent pas le push, ne nécessitent pas la suppression et la reconstruction du dépôt, ni le remplacement par des variables d'environnement, sauf si l'utilisateur demande explicitement un nettoyage ou prévoit de rendre le dépôt public.

Mode d'analyse (les deux doivent être exécutés — exécuter uniquement l'expression régulière de token peut manquer les mots de passe en clair) :

① Token à haute entropie / clé API :

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" .

② Mot de passe en clair / auxiliaire d'authentification (que l'expression régulière de token ne peut pas attraper ; en pratique, une ligne echo "<mot_de_passe_sudo>" dans askpass.sh a déjà été oubliée et poussée sur GitHub avec le commit init) :

git ls-files -z | xargs -0 grep -nIE "password|passwd|mot de passe|SUDO_ASKPASS|sshpass|^[[:space:]]*echo[[:space:]]+[\"'][^\"']{6,}[\"']" 2>/dev/null \
  | grep -vE "\.md:|getenv|getpass|placeholder|example"
# Et vérifiez manuellement les fichiers isolés askpass.sh / *_secret* / .pgpass / .npmrc — ces fichiers entiers sont des identifiants.

Pour un dépôt public, toute correspondance dans l'une ou l'autre analyse déclenche le processus obligatoire ci-dessous. Pour un dépôt privé, les correspondances ne font qu'avertir l'utilisateur et ne constituent pas un blocage. Notez que l'analyse porte sur git ls-files (fichiers suivis) ; ce qui est ignoré par .gitignore n'est pas considéré comme une fuite, mais les fichiers déjà commités, même s'ils sont maintenant dans .gitignore, sont toujours dans l'historique.

Format du rapport :

[LEAK] scripts/eval.py:15 — sk-xxxx (valeur de repli codée en dur)
[LEAK] ui/ui_backend.py:33 — sk-xxxx (valeur par défaut codée en dur)

Processus obligatoire après une fuite détectée :

  1. Informez immédiatement l'utilisateur du fichier et de la ligne concernés
  2. Remplacez par une variable d'environnement (os.getenv("API_KEY") sans valeur par défaut)
  3. Si déjà poussé vers le dépôt distant : informez l'utilisateur et, après confirmation explicite, supprimez et recréez le dépôt (l'historique Git ne peut pas être complètement effacé par un force push)
  4. L'utilisateur révoque la clé auprès du fournisseur de services correspondant

Liste de vérification pré-push

À exécuter avant chaque push :

git status

Confirmez l'absence de :

  • Fichiers non suivis (untracked files) — nouveaux fichiers non suivis (oublis courants : docs/, scripts/, modèles de config)
  • Modifications non indexées (changes not staged) — modifications non ajoutées
  • Modifications à commiter (changes to be committed) contenant des fichiers qui ne devraient pas être téléchargés (clés, données personnelles, scripts temporaires)

Avant confirmation, le push direct est interdit.

Arbre de décision

SituationAction recommandée
Le dépôt local n'a pas de dossier .git (zip téléchargé / fichiers copiés)Voir Scénario A ci-dessous
Le dépôt local est un git clone avec historique, dépôt distant inchangégit add → commit → push normal
Le dépôt local est un git clone, le dépôt distant a de nouveaux commitsgit pull --rebase ou merge, résoudre les conflits, push
Le dépôt local est un git clone, les modifications sont des renommages + réécritures massivesVoir Scénario B ci-dessous
Vous voulez préserver l'historique distant mais remplacer tout le codeVoir Scénario C ci-dessous

Scénario A : Le dépôt local n'a pas d'historique Git

Cas le plus courant : l'utilisateur télécharge un zip, édite abondamment, puis veut synchroniser.

Option A1 — Force Push (Projets personnels / solo)

# Dans le dossier du projet local
git init
git add .
git commit -m "refactor: réécriture majeure"
git remote add origin https://github.com/OWNER/REPO.git
git branch -M main
git push -u origin main --force

⚠️ Détruit l'historique distant. À utiliser uniquement si l'utilisateur confirme que l'historique distant est jetable.

Option A2 — Préserver l'historique distant (recommandé pour les dépôts de valeur)

git clone https://github.com/OWNER/REPO.git temp-repo
cp -r temp-repo/.git ./your-local-project/
cd your-local-project
git add .
git commit -m "refactor: réécriture majeure"
git push

Cela conserve tous les commits précédents et ajoute le refactoring comme un seul nouveau commit.

Option A3 — Nouveau dépôt propre Si la réécriture est si radicale qu'il s'agit essentiellement d'un nouveau projet :

  1. Créez un nouveau dépôt sur GitHub (incluez description dans le corps de la création ou utilisez PATCH immédiatement après)
  2. Poussez le code local vers ce nouveau dépôt
  3. Archivez l'ancien dépôt avec un lien vers le successeur dans le README

Scénario B : Renommages massifs + réécritures dans un dépôt cloné

Règle critique : ne mélangez jamais les renommages de fichiers et les modifications de contenu dans le même commit. Git traitera cela comme « supprimer l'ancien fichier + créer un nouveau fichier » et perdra le lien d'historique.

Stratégie de commit par étapes :

# Étape 1 : Renommer uniquement
git mv old_module.py new_module.py
git mv old_utils/ new_utils/
git commit -m "refactor: renommer les modules"

# Étape 2 : Renommages de variables/classes
git add .
git commit -m "refactor: renommer les variables et classes"

# Étape 3 : Modifications logiques
git add .
git commit -m "feat: mettre à jour la logique principale"

Si l'utilisateur a déjà tout mélangé dans l'arbre de travail :

# Stasher les modifications actuelles, rejouer par étapes
git stash push -m "refactoring mixte"

# Restaurer les renommages uniquement (utiliser git mv ou mv manuel + git add)
git mv old_file new_file
git commit -m "refactor: renommer les fichiers"

# Restaurer les modifications de contenu
git stash pop
# Résoudre les conflits si nécessaire, puis commit

Scénario C : Remplacer tout le code tout en conservant l'historique

Utile lorsque l'utilisateur veut repartir d'un code propre mais conserver les étoiles, les issues et l'URL.

git checkout --orphan fresh-start
git rm -rf .
# Copier le nouveau code local ici
git add .
git commit -m "init: réécriture propre"
git branch -D main
git branch -m main
git push -u origin main --force

Vérification de la détection de renommage

Après le push, vérifiez que Git a correctement suivi les renommages :

git log --follow -- new_file.py

Si l'historique est cassé (montre le fichier comme tout nouveau), le renommage et la modification de contenu ont été commités ensemble.

Sécurité et conformité

  • Token GitHub : Si un PAT est nécessaire, cherchez dans la mémoire de l'agent (n'écrivez pas de chemin/compte/valeur spécifique ici). N'écrivez JAMAIS la valeur du token dans un fichier qui sera poussé (y compris ce skill, README, configuration) — tout contenu contenant un token sera révoqué par le secret-scanning de GitHub dès qu'il sera poussé.
  • Hygiène du token : Après les opérations groupées, demandez à l'utilisateur de révoquer immédiatement le PAT sur https://github.com/settings/tokens.
  • Exception pour les dépôts privés : Si un dépôt est privé, l'agent peut ignorer les règles de fuite de clés, mots de passe, configuration privée, données personnelles et autres informations sensibles. Ne bloquez pas le push, n'exigez pas d'assainissement et ne recommandez pas la suppression uniquement parce que l'historique privé contient des secrets, sauf si l'utilisateur le demande ou si le dépôt pourrait devenir public.
  • Historique public contenant des secrets : Si un dépôt public a déjà commité des clés API, la suppression du dépôt est le seul moyen de purger l'historique de GitHub. Un force push avec un historique assaini ne garantit pas la suppression des systèmes de sauvegarde de GitHub.
  • Dépôts publics archivés avec secrets : Si la suppression est inacceptable, au minimum retirez le dépôt de la visibilité publique (rendez-le privé) ou supprimez-le et recréez-le vide avec un code propre.

Référence technique

Pièges d'encodage (Windows)

PowerShell utilise par défaut CP1252 pour stdout, ce qui détruit les caractères chinois et les blocs de code Markdown. Reconfigurez toujours :

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

Lorsque vous utilisez Invoke-RestMethod dans PowerShell avec des corps JSON contenant des backticks ou des triples backticks, privilégiez les scripts Python pour la génération de contenu afin d'éviter que la sérialisation JSON ne transforme ``` en `.

Modèles d'API GitHub

Créer un dépôt (n'omettez jamais description) :

api_call("POST", "/user/repos", {
    "name": "repo-name",
    "private": True,
    "description": "Résumé en une phrase."
})

Créer/mettre à jour un fichier :

import base64, json, urllib.request

payload = {
    "message": "message du commit",
    "content": base64.b64encode(content.encode('utf-8')).decode(),
    "sha": existing_sha  # requis pour les mises à jour
}
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}", ...}
)

Archiver/désarchiver :

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

Renommer un dépôt :

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

Supprimer un dépôt :

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

Téléchargement groupé sans clone

Téléchargez un instantané du dépôt sous forme de zip pour éviter un git clone lent sur des réseaux instables :

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

Ressources fournies

  • scripts/repo_analyzer.py — Analyse les dépôts GitHub de l'utilisateur et génère des recommandations de nettoyage
  • scripts/bulk_file_updater.py — Crée/met à jour en masse LICENSE, .gitignore, README via l'API GitHub

Skills associés