CommunityEscrita e Ediçãogithub.com

tzwkb/repo-maintainer

Habilidade de agente — Limpeza, consolidação e manutenção de repositórios GitHub.

O que é repo-maintainer?

O `repo-maintainer` é uma habilidade especializada para agentes de IA (como Claude Code, Cursor ou Codex) que automatiza a transformação de perfis GitHub fragmentados em repositórios limpos, profissionais e fáceis de manter. Ele executa a limpeza em seis fases: escaneamento e diagnóstico, padronização de arquivos fundamentais (LICENSE, README.md, .gitignore e descrição), tratamento de repositórios desatualizados (arquivamento ou exclusão), mesclagem de repositórios relacionados (monorepo, submódulo ou links), renomeação padronizada e refatoração em nível de código. A habilidade impõe princípios não negociáveis — todo repositório público deve ter LICENSE, README.md, .gitignore e descrição preenchida — e inclui uma varredura obrigatória de segredos antes de qualquer push, com tratamento especial para repositórios privados. Ela também oferece orientação detalhada para cenários complexos de push, como lidar com código baixado via zip sem histórico Git, renomeações massivas com preservação de histórico e substituição completa de código. É compatível com qualquer plataforma que execute agentes de IA com acesso ao shell e à API do GitHub.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add tzwkb/repo-maintainer

Installed? Explore more Escrita e Edição skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Repository Maintainer

Fluxo de trabalho sistemático para transformar perfis GitHub fragmentados em repositórios limpos, sustentáveis e profissionais.

Visão Geral

Execute a limpeza em 6 fases. Pule fases que não se aplicam. Sempre obtenha confirmação do usuário em ações destrutivas (exclusão, renomeação, mesclagem).

Princípios Essenciais (Innegociáveis)

Todo repositório — novo ou antigo, ativo ou arquivado — deve ter estes quatro documentos de base. Não considere uma limpeza concluída até que todos os quatro sejam verificados.

DocumentoRegraPorquê
LICENSETodo repositório público recebe uma LICENSE. Padrão MIT, a menos que o usuário especifique o contrário.Sem uma licença, o código é "todos os direitos reservados" por padrão. Ninguém pode usá-lo legalmente.
README.mdDeve existir com pelo menos: nome do projeto, descrição de uma frase e instruções de uso/instalação, se aplicável.A primeira coisa que todo visitante vê. Um README vazio ou ausente sinaliza abandono.
.gitignoreDeve corresponder à linguagem primária (Python/PHP/Node/etc.). Nunca faça commit de artefatos de build, cache, arquivos de ambiente ou configurações de IDE.Previne vazamento acidental de segredos e mantém diffs legíveis.
Descrição do GitHubO campo description nunca deve estar vazio. Uma frase, em português claro (ou no idioma do repositório).Aparece em resultados de busca, pins de perfil e cartões sociais.

Se um repositório estiver faltando qualquer um dos quatro, corrigir isso tem prioridade sobre mesclar, renomear ou refatorar.

Fase 1: Escanear e Diagnosticar

Buscar lista completa de repositórios via API do GitHub:

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

Verificar em cada repositório:

  • Faltando LICENSE, .gitignore, README.md
  • Campo description vazio
  • Inconsistências de nomenclatura (maiúsculas/minúsculas misturadas, nomes muito longos)
  • Duplicatas ou séries óbvias (ex.: projeto, projeto-v2, projeto-mineru)
  • Nomes contendo outdated, deprecated, old, test

Fase 2: Padronizar Arquivos de Base

Para cada repositório ativo, garantir que o conjunto mínimo de arquivos exista:

ArquivoRegra
LICENSEPadrão MIT, a menos que o usuário especifique o contrário
.gitignoreCorresponder à linguagem primária (Python/PHP/Node)
README.mdDeve existir; reescrever se for apenas um placeholder
Descrição do GitHubResumo de uma frase via API

Atualização em lote via GitHub Contents API (PUT /repos/{owner}/{repo}/contents/{path}).

Crítico: Here-strings do PowerShell corrompem blocos de código com três crases em Markdown. Use scripts Python para geração em massa de README para evitar falhas de escape de ` → ```.

Fase 3: Lidar com Repositórios Desatualizados

Árvore de decisão:

CondiçãoAção
Nome contém outdated / deprecated / oldArquivar ou excluir
Substituído por repositório mais novoArquivar + link no README para o sucessor
Histórico de repositório público contém segredos vazados (chaves de API)Excluir (arquivar deixa o histórico intacto)
Repositório privado contém chaves, senhas, configuração privada ou dados pessoaisUsuário pode ignorar regras de vazamento; tratar como estado privado aceitável, a menos que peça para sanitizar
Útil como referência, mas não mantidoArquivar

Repositórios arquivados são somente leitura. Para modificar um repositório arquivado (renomear, atualizar README), desarquive primeiro (PATCH {"archived": false}), faça as alterações e depois re-arquive.

Fase 4: Mesclar Repositórios Relacionados

Quando 2+ repositórios são variantes do mesmo sistema (diferentes backends, engines, adaptadores):

Opção A — Monorepo (Recomendado) Crie um novo repositório limpo (sem histórico). Coloque cada variante no subdiretório engines/{nome}/.

projeto-suite/
├── main.py              # engine padrão
├── engines/
│   ├── babeldoc/
│   └── mineru/
└── README.md

Preserve o ponto de entrada e a configuração de cada engine. Atualize o README raiz para explicar como alternar.

Opção B — Submódulo Git Mantenha repositórios independentes. Adicione submódulos no repositório pai. Use quando a preservação do histórico for mais importante que a simplicidade.

Opção C — Manter Independente + Link Não mescle. Adicione links cruzados nos READMEs. Use quando as variantes divergiram significativamente.

Se o histórico contém segredos: Crie sempre um novo repositório limpo e copie o snapshot atual (via download zip + novo commit). Não use git merge ou git submodule, pois o vazamento do histórico persistirá.

Fase 5: Renomear Repositórios

API Patch: PATCH /repos/{owner}/{repo} com {"name": "novo-nome"}.

Diretrizes:

  • Tudo minúsculo, apenas hífens
  • Máximo 3-4 palavras
  • Remover palavras redundantes (baseado-em, design-e-desenvolvimento)
  • Adicionar sufixo outdated a repositórios arquivados, se ainda não estiver presente

O GitHub redireciona URLs antigas automaticamente por um período, mas bookmarks e scripts podem quebrar. Confirme com o usuário antes de renomear repositórios estrelados ou bifurcados.

Fase 6: Refatoração em Nível de Código

Após a estrutura remota estar limpa, refatore o código dentro dos repositórios:

  1. Terminologia unificada — Substitua nomes de marca hardcoded por termos genéricos (GPTProcessor → LLMProcessor) preservando IDs de modelos de API reais (gpt-4, gpt-5).
  2. Renomeação de arquivos — GitHub Contents API não tem renomeação; crie novo arquivo com conteúdo atualizado, exclua o antigo.
  3. Reorganização de diretórios — Use padrões engines/, variants/ ou core/ + adapters/ para projetos com múltiplas variações.

Enviando Grandes Refatorações Locais para o Remoto

Quando o usuário baixa o código localmente, faz alterações pesadas (renomeações de arquivos, renomeações de variáveis, reescritas estruturais) e precisa enviar de volta para o repositório remoto.

Varredura de Segredos Pré-Push (OBRIGATÓRIA)

Antes de enviar, deve-se escanear vazamentos de segredos; qualquer descoberta deve ser imediatamente relatada, e o push não deve prosseguir.

Exceção para repositório privado: Se o repositório alvo for confirmadamente privado, pode-se ignorar regras de vazamento de chaves, senhas, configuração privada, dados pessoais e outras informações sensíveis. A varredura pode servir como aviso, mas acertos não bloqueiam o push, não exigem recriação do repositório, nem exigem substituição por variáveis de ambiente, a menos que o usuário peça explicitamente para limpar ou planeje tornar o repositório público.

Modos de varredura (ambos devem ser executados — executar apenas o regex de token pode perder senhas em texto claro):

① Token de alta entropia / chave de 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" .

② Senhas em texto claro / helpers de credenciais (regex de token não pega; na prática, já vazou uma linha echo "<senha_sudo>" em askpass.sh que foi enviada com o commit init no GitHub):

git ls-files -z | xargs -0 grep -nIE "password|passwd|senha|SUDO_ASKPASS|sshpass|^[[:space:]]*echo[[:space:]]+[\"'][^\"']{6,}[\"]'" 2>/dev/null \
  | grep -vE "\.md:|getenv|getpass|placeholder|example"
# E verifique manualmente arquivos isolados como askpass.sh / *_secret* / .pgpass / .npmrc — o arquivo inteiro é uma credencial

Em repositório público, qualquer acerto em qualquer modo aciona o fluxo obrigatório abaixo. Em repositório privado, apenas notifique o usuário, sem bloqueio. Observe que a varredura usa git ls-files (arquivos rastreados); o .gitignore exclui os que não são rastreados, mas arquivos já commitados, mesmo que agora no .gitignore, ainda estão no histórico.

Formato do relatório:

[LEAK] scripts/eval.py:15 — sk-xxxx (fallback hardcoded)
[LEAK] ui/ui_backend.py:33 — sk-xxxx (default hardcoded)

Fluxo obrigatório após descoberta de vazamento:

  1. Informe imediatamente ao usuário qual arquivo e linha
  2. Substitua por variável de ambiente (os.getenv("API_KEY") sem valor padrão)
  3. Se já tiver sido enviado para o remoto: informe o usuário e, após confirmação explícita, exclua e recrie o repositório (o histórico do git não pode ser completamente removido com force push)
  4. O usuário deve revogar a chave no serviço correspondente

Checklist Pré-Push

Antes de enviar, execute:

git status

Confirme que não há:

  • Untracked files — Novos arquivos não rastreados (omissão comum: docs/, scripts/, modelos de config)
  • Changes not staged — Modificações não adicionadas
  • Changes to be committed contendo arquivos que não deveriam ser enviados (chaves, dados pessoais, scripts temporários)

Antes de confirmar, não prossiga com o push.

Árvore de Decisão

SituaçãoAção Recomendada
Repositório local não tem .git (zip baixado / arquivos copiados)Veja Cenário A abaixo
Local é git clone com histórico, remoto inalteradogit add → commit → push normal
Local é git clone, remoto tem novos commitsgit pull --rebase ou merge, resolva conflitos, push
Local é git clone, alterações são renomeações massivas + reescritasVeja Cenário B abaixo
Quer preservar o histórico remoto, mas substituir todo o códigoVeja Cenário C abaixo

Cenário A: Local Não Tem Histórico Git

Mais comum quando o usuário baixa um zip, edita extensivamente e depois quer sincronizar de volta.

Opção A1 — Force Push (Projetos Pessoais / Solo)

# Na pasta do projeto local
git init
git add .
git commit -m "refactor: reescrita principal"
git remote add origin https://github.com/OWNER/REPO.git
git branch -M main
git push -u origin main --force

⚠️ Destrói o histórico remoto. Use apenas quando o usuário confirmar que o histórico remoto é descartável.

Opção A2 — Preservar Histórico Remoto (Recomendado para Repositórios Valiosos)

git clone https://github.com/OWNER/REPO.git temp-repo
cp -r temp-repo/.git ./seu-projeto-local/
cd seu-projeto-local
git add .
git commit -m "refactor: reescrita principal"
git push

Isso mantém todos os commits anteriores e anexa a refatoração como um único novo commit.

Opção A3 — Novo Repositório Limpo Se a reescrita for tão radical que é essencialmente um novo projeto:

  1. Crie novo repositório no GitHub (deve incluir description no corpo da criação ou fazer PATCH imediatamente após)
  2. Envie o código local para lá
  3. Arquive o repositório antigo com um link para o sucessor no README

Cenário B: Renomeações Massivas + Reescritas em um Repositório Clonado

Regra crítica: nunca misture renomeações de arquivos e alterações de conteúdo no mesmo commit. O Git tratará como "excluir arquivo antigo + criar novo arquivo" e perderá a ligação do histórico.

Estratégia de commit passo a passo:

# Passo 1: Apenas renomear
git mv modulo_antigo.py novo_modulo.py
git mv utilitarios_antigos/ novos_utilitarios/
git commit -m "refactor: renomear módulos"

# Passo 2: Renomeações de variáveis/classes
git add .
git commit -m "refactor: renomear variáveis e classes"

# Passo 3: Alterações de lógica
git add .
git commit -m "feat: atualizar lógica principal"

Se o usuário já misturou tudo na árvore de trabalho:

# Guarde as alterações atuais e reproduza em etapas
git stash push -m "refatoração misturada"

# Restaure apenas renomeações (use git mv ou mv manual + git add)
git mv arquivo_antigo arquivo_novo
git commit -m "refactor: renomear arquivos"

# Restaure alterações de conteúdo
git stash pop
# Resolva conflitos, se houver, e faça commit

Cenário C: Substituir Todo o Código, mas Manter o Histórico

Útil quando o usuário quer começar com código novo, mas manter estrelas/issues/URL.

git checkout --orphan novo-inicio
git rm -rf .
# Copie o novo código local aqui
git add .
git commit -m "init: reescrita limpa"
git branch -D main
git branch -m main
git push -u origin main --force

Verificando a Detecção de Renomeação

Após o push, verifique se o Git rastreou as renomeações corretamente:

git log --follow -- novo_arquivo.py

Se o histórico estiver quebrado (mostrar o arquivo como totalmente novo), a renomeação e a alteração de conteúdo foram commitadas juntas.

Segurança e Conformidade

  • Token do GitHub: Quando um PAT for necessário, procure na memória do agente (não escreva caminho/usuário/valor específico aqui). Nunca escreva o valor do token em nenhum arquivo que será enviado (incluindo esta skill, README, configurações) — conteúdo com token, uma vez enviado, será revogado pela varredura de segredos do GitHub.
  • Higiene de token: Após operações em lote, instrua o usuário a revogar o PAT imediatamente em https://github.com/settings/tokens.
  • Exceção para repositório privado: Se um repositório for privado, o agente pode ignorar regras de vazamento de chaves, senhas, configuração privada, dados pessoais e outras informações sensíveis. Não bloqueie push, não force sanitização, nem recomende exclusão apenas porque o histórico privado contém segredos, a menos que o usuário peça ou se o repositório puder se tornar público.
  • Histórico público com segredos: Se um repositório público já commitou chaves de API, excluir o repositório é a única maneira de purgar o histórico do GitHub. Force-push de histórico sanitizado não garante remoção dos sistemas de backup do GitHub.
  • Repositórios públicos arquivados com segredos: Se a exclusão for inaceitável, no mínimo remova o repositório da visibilidade pública (torne privado) ou exclua e recrie vazio com código limpo.

Referência Técnica

Armadilhas de Codificação (Windows)

O PowerShell usa CP1252 como padrão para stdout, destruindo caracteres chineses e blocos de código Markdown. Sempre reconfigurar:

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

Ao usar Invoke-RestMethod no PowerShell com corpos JSON contendo crases ou três crases, prefira scripts Python para geração de conteúdo para evitar que a serialização JSON transforme ``` em `.

Padrões da API do GitHub

Criar repositório (nunca omita description):

api_call("POST", "/user/repos", {
    "name": "nome-do-repo",
    "private": True,
    "description": "Resumo em uma frase."
})

Criar/atualizar arquivo:

import base64, json, urllib.request

payload = {
    "message": "mensagem do commit",
    "content": base64.b64encode(content.encode('utf-8')).decode(),
    "sha": sha_existente  # necessário para atualizações
}
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}", ...}
)

Arquivar/desarquivar:

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

Renomear repositório:

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

Excluir repositório:

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

Download em Massa Sem Clone

Baixe o snapshot do repositório como zip para evitar git clone lento em redes instáveis:

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

Recursos Inclusos

  • scripts/repo_analyzer.py — Escaneia repositórios GitHub do usuário e gera recomendações de limpeza
  • scripts/bulk_file_updater.py — Cria/atualiza LICENSE, .gitignore, README em lote via API do GitHub

Como Usar

  1. Ative a habilidade no seu agente de IA (ex.: adicione ao arquivo de configuração do agente ou habilite via comando).
  2. Execute o fluxo solicitando ao agente: "Limpe meu perfil do GitHub" ou "Organize meus repositórios".
  3. Siga as confirmações — O agente solicitará aprovação antes de qualquer ação destrutiva.
  4. Revise as recomendações — O agente pode sugerir mesclagens, renomeações ou exclusões.

Dependências

  • Acesso a um terminal com curl, git e Python instalados.
  • Token de acesso pessoal (PAT) do GitHub com escopos repo e delete_repo.

Notas

  • Esta habilidade foi projetada para ser usada com agentes de IA que têm acesso ao sistema de arquivos e à API do GitHub.
  • Para perfis com muitos repositórios, execute a varredura inicial para identificar rapidamente quais repositórios precisam de atenção.

Habilidades Relacionadas