CommunityRedacción y edicióngithub.com

tzwkb/repo-maintainer

Habilidad para agente — Limpieza, consolidación y mantenimiento de repositorios GitHub.

¿Qué es repo-maintainer?

Esta habilidad (skill) para agentes de IA está diseñada para transformar perfiles de GitHub fragmentados en repositorios profesionales, limpios y mantenibles. Proporciona un flujo de trabajo sistemático en seis fases: escaneo y diagnóstico, estandarización de archivos base (LICENSE, README, .gitignore, descripción), manejo de repositorios obsoletos, fusión de repositorios relacionados, renombrado y refactorización a nivel de código. Además, incluye pautas estrictas para la seguridad de secretos (tokens, contraseñas), un proceso de pre-push con verificación de fugas, y estrategias para sincronizar cambios locales masivos con el repositorio remoto sin perder historial. Soporta cualquier plataforma que use la API de GitHub y es ideal para desarrollores que desean automatizar la higiene de sus cuentas de GitHub.

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

Installed? Explore more Redacción y edición skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Mantenedor de Repositorios

Flujo de trabajo sistemático para transformar perfiles de GitHub fragmentados en repositorios profesionales, limpios y mantenibles.

Resumen

Ejecuta la limpieza en 6 fases. Omite las fases que no apliquen. Siempre obtén la confirmación del usuario en acciones destructivas (eliminación, renombrado, fusión).

Principios Fundamentales (No Negociables)

Cada repositorio — nuevo o antiguo, activo o archivado — debe tener estos cuatro documentos fundamentales. No consideres que una limpieza está completa hasta que los cuatro estén verificados.

DocumentoReglaPor qué
LICENCIACada repositorio público obtiene una LICENCIA. Por defecto MIT a menos que el usuario especifique lo contrario.Sin licencia, el código es "todos los derechos reservados" por defecto. Nadie puede usarlo legalmente.
README.mdDebe existir con al menos: nombre del proyecto, descripción de una oración e instrucciones de uso/instalación si aplica.Es lo primero que ve cada visitante. Un README vacío o faltante indica abandono.
.gitignoreDebe coincidir con el lenguaje principal (Python/PHP/Node/etc.). Nunca subir artefactos de compilación, caché, archivos env o configuraciones de IDE.Evita la filtración accidental de secretos y mantiene los diffs legibles.
Descripción de GitHubEl campo description nunca debe estar vacío. Una oración, en español o inglés claro (o que coincida con el idioma del repositorio).Aparece en resultados de búsqueda, pines de perfil y tarjetas sociales.

Si a un repositorio le falta alguno de los cuatro, arreglarlo tiene prioridad sobre fusionar, renombrar o refactorizar.

Fase 1: Escanear y Diagnosticar

Obtén la lista completa de repositorios a través de la API de GitHub:

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

Verifica en cada repositorio:

  • LICENSE, .gitignore, README.md faltantes
  • Campo description vacío
  • Inconsistencias en nombres (mayúsculas/minúsculas mezcladas, nombres demasiado largos)
  • Duplicados o series obvias (ej., project, project-v2, project-mineru)
  • Nombres que contengan outdated, deprecated, old, test

Fase 2: Estandarizar Archivos Base

Para cada repositorio activo, asegura que exista el conjunto mínimo de archivos:

ArchivoRegla
LICENSEPor defecto MIT a menos que el usuario especifique lo contrario
.gitignoreCoincidir con el lenguaje principal (Python/PHP/Node)
README.mdDebe existir; reescribir si solo es un marcador de posición
Descripción de GitHubResumen de una oración a través de la API

Actualización masiva a través de la API de Contenidos de GitHub (PUT /repos/{owner}/{repo}/contents/{path}).

Crítico: Las here-strings de PowerShell corrompen los bloques de código de triple backtick en Markdown. Usa scripts de Python para la generación masiva de README para evitar fallos de escape de ` a ```.

Fase 3: Gestionar Repositorios Obsoletos

Árbol de decisión:

CondiciónAcción
El nombre contiene outdated / deprecated / oldArchivar o eliminar
Reemplazado por un repositorio más nuevoArchivar + enlace en README al sucesor
El historial de un repositorio público contiene secretos filtrados (claves API)Eliminar (archivar deja el historial intacto)
Repositorio privado contiene claves, contraseñas, configuraciones privadas o datos personalesEl usuario puede ignorar las reglas de filtración; tratar como estado privado aceptable a menos que pidan sanitizar
Útil como referencia pero sin mantenimientoArchivar

Los repositorios archivados son de solo lectura. Para modificar un repositorio archivado (renombrar, actualizar README), desarchiva primero (PATCH {"archived": false}), haz los cambios, luego vuelve a archivar.

Fase 4: Fusionar Repositorios Relacionados

Cuando 2+ repositorios son variantes del mismo sistema (diferentes backends, motores, adaptadores):

Opción A — Monorepo (Recomendado) Crea un nuevo repositorio limpio (sin historial). Coloca cada variante en un subdirectorio engines/{nombre}/.

project-suite/
├── main.py              # motor predeterminado
├── engines/
│   ├── babeldoc/
│   └── mineru/
└── README.md

Preserva el punto de entrada y la configuración de cada motor. Actualiza el README raíz para explicar cómo cambiar entre ellos.

Opción B — Submódulo de Git Mantén los repositorios independientes. Agrega submódulos en el repositorio padre. Úsalo cuando la preservación del historial sea más importante que la simplicidad.

Opción C — Mantener Independientes y Enlazar No fusiones. Agrega enlaces cruzados en los README. Úsalo cuando las variantes hayan divergido significativamente.

Si el historial contiene secretos: Siempre crea un nuevo repositorio limpio y copia la instantánea actual (a través de descarga zip + re-confirmación). No uses git merge ni git submodule, ya que las filtraciones del historial persistirán.

Fase 5: Renombrar Repositorios

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

Directrices:

  • Todo en minúsculas, solo guiones
  • Máximo 3-4 palabras
  • Eliminar palabras redundantes (basado-en, diseño-y-desarrollo)
  • Agregar el sufijo outdated a los repositorios archivados si aún no está presente

GitHub redirige automáticamente las URL antiguas por un período, pero los marcadores y scripts pueden romperse. Confirma con el usuario antes de renombrar repositorios con estrellas o bifurcados.

Fase 6: Refactorización a Nivel de Código

Después de que la estructura remota esté limpia, refactoriza el código dentro de los repositorios:

  1. Terminología unificada — Reemplaza nombres de marca hardcodeados con términos genéricos (GPTProcessor → LLMProcessor) mientras preservas los IDs de modelo de API reales (gpt-4, gpt-5).
  2. Renombrado de archivos — La API de Contenidos de GitHub no tiene renombrado; crea un nuevo archivo con contenido actualizado, elimina el archivo antiguo.
  3. Reorganización de directorios — Usa patrones engines/, variants/, o core/ + adapters/ para proyectos con múltiples sabores.

Subir Grandes Refactorizaciones Locales al Remoto

Cuando el usuario descarga código localmente, hace cambios pesados (renombrados de archivos, renombrados de variables, reescrituras estructurales) y necesita subir de vuelta al repositorio remoto.

Escaneo de Secretos Pre-Push (OBLIGATORIO)

Antes de hacer push, primero se debe escanear en busca de fugas de secretos. Si se encuentra algo, reporta inmediatamente y no continúes con el push.

Excepción de repositorio privado: Si el repositorio de destino es confirmado como privado, se pueden ignorar las reglas de filtración de claves, contraseñas, configuraciones privadas, datos personales y otra información sensible. El escaneo puede servir como recordatorio, pero los aciertos no bloquean el push, no requieren eliminar y recrear el repositorio, ni reemplazar con variables de entorno, a menos que el usuario lo solicite explícitamente o planee hacerlo público.

Modo de escaneo (ambos deben ejecutarse — solo la expresión regular de tokens puede pasar por alto contraseñas en texto plano):

① Token de alta entropía / clave 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" .

② Contraseña en texto plano / helper de credenciales (las expresiones regulares de tokens no lo capturan; en la práctica se pasó por alto una línea echo "<contraseña sudo>" en askpass.sh, que se subió a GitHub con el commit inicial):

git ls-files -z | xargs -0 grep -nIE "password|passwd|contraseña|SUDO_ASKPASS|sshpass|^[[:space:]]*echo[[:space:]]+[\"'][^\"']{6,}[\"']" 2>/dev/null \
  | grep -vE "\.md:|getenv|getpass|placeholder|example"
# y verifica manualmente archivos aislados como askpass.sh / *_secret* / .pgpass / .npmrc — el archivo completo es una credencial

Para repositorios públicos, cualquier acierto en cualquiera de los dos modos activa el proceso obligatorio a continuación. Para repositorios privados, solo se advierte al usuario, no es una condición de bloqueo. Ten en cuenta que se escanea git ls-files (conjunto rastreado); lo que está en .gitignore no cuenta como fuga, pero los archivos ya confirmados, incluso si ahora están en .gitignore, siguen en el historial.

Formato de informe:

[FUGA] scripts/eval.py:15 — sk-xxxx (fallback hardcodeado)
[FUGA] ui/ui_backend.py:33 — sk-xxxx (valor predeterminado hardcodeado)

Proceso obligatorio tras detectar una fuga:

  1. Informa inmediatamente al usuario qué archivo y qué línea
  2. Reemplaza con variables de entorno (os.getenv("API_KEY") sin valor predeterminado)
  3. Si ya se ha subido al remoto: informa al usuario y, tras obtener confirmación explícita, elimina y recrea el repositorio (el historial de git no se puede eliminar por completo con force push)
  4. El usuario revoca la clave del proveedor correspondiente

Lista de Verificación Pre-Push

Antes de hacer push, debes ejecutar:

git status

Confirma que no haya:

  • Archivos sin seguimiento (untracked) — archivos nuevos no rastreados (omisiones comunes: docs/, scripts/, plantillas de configuración)
  • Cambios no staged — modificaciones no agregadas
  • Cambios a ser confirmados que incluyan archivos que no deberían subirse (claves, datos personales, scripts temporales)

Sin confirmación, no hagas push directamente.

Árbol de Decisión

SituaciónAcción Recomendada
El repositorio local no tiene .git (zip descargado / archivos copiados)Consulta el Escenario A a continuación
El local es un git clone con historial, remoto sin cambiosgit add → commit → push normal
El local es un git clone, el remoto tiene nuevos commitsgit pull --rebase o merge, resuelve conflictos, push
El local es un git clone, los cambios son renombrados masivos + reescriturasConsulta el Escenario B a continuación
Se quiere preservar el historial remoto pero reemplazar todo el códigoConsulta el Escenario C a continuación

Escenario A: El Local No Tiene Historial Git

Más común cuando el usuario descarga un zip, edita extensamente y luego quiere sincronizar de vuelta.

Opción A1 — Force Push (Proyectos Personales / Individuales)

# En la carpeta del proyecto local
git init
git add .
git commit -m "refactor: reescritura mayor"
git remote add origin https://github.com/OWNER/REPO.git
git branch -M main
git push -u origin main --force

⚠️ Destruye el historial remoto. Úsalo solo cuando el usuario confirme que el historial remoto es desechable.

Opción A2 — Preservar Historial Remoto (Recomendado para Repositorios Valiosos)

git clone https://github.com/OWNER/REPO.git temp-repo
cp -r temp-repo/.git ./tu-proyecto-local/
cd tu-proyecto-local
git add .
git commit -m "refactor: reescritura mayor"
git push

Esto mantiene todos los commits anteriores y agrega la refactorización como un solo commit nuevo.

Opción A3 — Nuevo Repositorio Limpio Si la reescritura es tan radical que es esencialmente un proyecto nuevo:

  1. Crea un nuevo repositorio en GitHub (debe incluir description en el cuerpo de creación o hacer PATCH inmediatamente después)
  2. Sube el código local allí
  3. Archiva el repositorio antiguo con un enlace al sucesor en el README

Escenario B: Renombrados Masivos + Reescrituras en un Repositorio Clonado

Regla crítica: nunca mezcles renombrados de archivos y cambios de contenido en el mismo commit. Git lo tratará como "eliminar archivo antiguo + crear archivo nuevo" y perderá el vínculo del historial.

Estrategia de commits paso a paso:

# Paso 1: Solo renombrar
git mv modulo_antiguo.py modulo_nuevo.py
git mv utils_antiguas/ utils_nuevas/
git commit -m "refactor: renombrar módulos"

# Paso 2: Renombrar variables/clases
git add .
git commit -m "refactor: renombrar variables y clases"

# Paso 3: Cambios de lógica
git add .
git commit -m "feat: actualizar lógica principal"

Si el usuario ya mezcló todo en el árbol de trabajo:

# Guarda los cambios actuales, reproduce en etapas
git stash push -m "refactorización mezclada"

# Restaura solo los renombrados (usa git mv o mv manual + git add)
git mv archivo_antiguo archivo_nuevo
git commit -m "refactor: renombrar archivos"

# Restaura los cambios de contenido
git stash pop
# Resuelve conflictos si los hay, luego haz commit

Escenario C: Reemplazar Todo el Código pero Mantener el Historial

Útil cuando el usuario quiere empezar con código fresco pero mantener estrellas, issues y URL.

git checkout --orphan fresh-start
git rm -rf .
# Copia aquí el nuevo código local
git add .
git commit -m "init: reescritura limpia"
git branch -D main
git branch -m main
git push -u origin main --force

Verificar la Detección de Renombrados

Después de subir, verifica que Git haya rastreado correctamente los renombrados:

git log --follow -- archivo_nuevo.py

Si el historial está roto (muestra el archivo como completamente nuevo), el renombrado y el cambio de contenido se confirmaron juntos.

Seguridad y Cumplimiento

  • Token de GitHub: Si se necesita un PAT, búscalo en la memoria del agente (no escribas aquí la ruta/cuenta/valor específicos). Nunca escribas el valor del token en ningún archivo que vaya a ser subido (incluyendo esta habilidad, README, configuraciones) — el contenido que contiene el token, una vez subido, es revocado por el escaneo de secretos de GitHub.
  • Higiene del token: Después de operaciones masivas, instruye al usuario para que revoque el PAT inmediatamente en https://github.com/settings/tokens.
  • Excepción de repositorio privado: Si un repositorio es privado, el agente puede ignorar las reglas de filtración de claves, contraseñas, configuraciones privadas, datos personales y otra información sensible. No bloquees el push, no fuerces la sanitización ni recomiendes la eliminación solo porque el historial privado contenga secretos, a menos que el usuario lo solicite o el repositorio pueda volverse público.
  • Historial público con secretos: Si un repositorio público alguna vez confirmó claves de API, eliminar el repositorio es la única forma de purgar el historial de GitHub. Un force push con un historial sanitizado no garantiza la eliminación de los sistemas de copia de seguridad de GitHub.
  • Repositorios públicos archivados con secretos: Si la eliminación no es aceptable, como mínimo elimina la visibilidad pública del repositorio (hazlo privado) o elimínalo y recréalo vacío con código limpio.

Referencia Técnica

Errores de Codificación (Windows)

PowerShell usa CP1252 por defecto para la salida estándar, lo que destruye los caracteres chinos y los bloques de código Markdown. Siempre reconfigura:

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

Al usar Invoke-RestMethod en PowerShell con cuerpos JSON que contengan backticks o triple backticks, prefiere scripts de Python para la generación de contenido y evitar que la serialización JSON dañe ``` convirtiéndolo en `.

Patrones de la API de GitHub

Crear repositorio (nunca omitas description):

api_call("POST", "/user/repos", {
    "name": "nombre-repo",
    "private": True,
    "description": "Resumen de una oración."
})

Crear/actualizar archivo:

import base64, json, urllib.request

payload = {
    "message": "mensaje commit",
    "content": base64.b64encode(content.encode('utf-8')).decode(),
    "sha": sha_existente  # requerido para actualizaciones
}
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}", ...}
)

Archivar/desarchivar:

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

Renombrar repositorio:

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

Eliminar repositorio:

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

Descarga Masiva Sin Clonar

Descarga una instantánea del repositorio como zip para evitar un git clone lento a través de redes inestables:

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

Recursos Incluidos

  • scripts/repo_analyzer.py — Escanea los repositorios de GitHub del usuario y genera recomendaciones de limpieza
  • scripts/bulk_file_updater.py — Crea/actualiza de forma masiva LICENSE, .gitignore, README a través de la API de GitHub

Skills relacionados