Descrição

Descubra e crie uma lista filtrada de repositórios GitHub que contenham um arquivo SKILL.md, ingerindo exportações CSV do SEART (listas de repositórios), escaneando cada repositório em busca de arquivos correspondentes e exportando os resultados para um único CSV de saída para processamento posterior.

Esta skill foi projetada para agentes de IA e scripts de automação executarem mineração repetível e somente leitura sobre grandes conjuntos de repositórios, com varredura consciente de limites de taxa e execução retomável.

Quando usar esta skill

Use esta skill quando você tiver:

Uma pasta de arquivos CSV gerados pelo SEART que incluam identificadores de repositórios GitHub.
A necessidade de encontrar repositórios que contenham SKILL.md (nome exato por padrão).
A necessidade de exportar um CSV filtrado para processamento posterior (download, análise, indexação).

Não use esta skill para extração de conteúdo, revisão de conformidade de licenças, varredura de vulnerabilidades ou modificação de repositórios.

Entradas

Obrigatórias

Pasta de CSVs do SEART
- Caminho para um diretório contendo um ou mais arquivos .csv.
- Cada CSV deve incluir informações suficientes para reconstruir um identificador de repositório GitHub no formato owner/repo.
Caminho do CSV de saída
- Caminho onde os resultados da varredura devem ser escritos.

Configuração opcional

match_name: padrão SKILL.md
case_sensitive: padrão true
search_paths: padrão ["/SKILL.md"]
- Você pode expandir esta lista para incluir locais comuns, se desejado.
include_negative_results: padrão true
- Se false, exporta apenas repositórios onde houve correspondência.
max_repos: padrão 0 (sem limite)
resume: padrão true
- Permite continuar a partir de um arquivo de saída anterior.
concurrency: padrão 8
min_stars: padrão 0
allow_forks: padrão true
allow_archived: padrão true

Esquema CSV esperado (SEART)

As exportações do SEART variam. Esta skill suporta vários padrões. Um repositório pode ser derivado de qualquer um destes:

Padrões de coluna preferidos

full_name (exemplo: psf/requests)
repo (exemplo: psf/requests)
repository (exemplo: psf/requests)

Padrões alternativos

owner e name (combinar em owner/name)
org e repo_name (combinar em org/repo_name)
repo_owner e repo_name (combinar em repo_owner/repo_name)
html_url ou url (extrair owner/repo de https://github.com/owner/repo)

Regras de análise

Remover espaços em branco.
Remover sufixo .git, se presente.
Normalizar https://github.com/owner/repo/... para owner/repo.
Deduplicar repositórios em todos os CSVs.

Se nenhuma coluna suportada for encontrada em um CSV, registrar um erro de nível de entrada e continuar com os arquivos restantes.

Saídas

CSV de saída: `skill_md_scan_results.csv`

Um único CSV com uma linha por repositório (a menos que você configure para emitir várias linhas por caminho de correspondência).

Colunas recomendadas

repo
Identificador canônico owner/repo.
source_csv
Nome do arquivo CSV SEART de origem (ou MULTIPLE se mesclado).
found
true|false.
match_name
A regra de nome de arquivo usada, geralmente SKILL.md.
match_path
O caminho correspondente (exemplo: /SKILL.md).
default_branch
Nome do branch padrão, se disponível.
ref_scanned
Referência do branch ou commit usada (exemplo: HEAD ou main).
match_url
URL canônica para o arquivo, se encontrado.
match_sha
SHA do blob Git, se disponível.
match_size_bytes
Tamanho, se disponível.
scan_method
contents_api | code_search | sparse_checkout | local_clone.
http_status
Código de status de chamadas de API, quando aplicável.
error_type
none | not_found | rate_limited | auth | network | invalid_repo | other.
error_message
Breve detalhe do erro, não incluir segredos.
scanned_at_utc
Carimbo de data/hora ISO.
stars (opcional)
fork (opcional)
archived (opcional)

CSV filtrado (opcional)

Se include_negative_results=false, a própria saída se torna a lista filtrada. Caso contrário, gere um segundo arquivo:

skill_md_shortlist.csv contendo apenas found=true.

Capacidades

1) Ingerir pasta de CSVs do SEART

Descobrir todos os arquivos .csv em um diretório (recursivo opcional).
Extrair identificadores de repositórios com detecção robusta de colunas.
Deduplicar e normalizar em uma lista canônica de repositórios.

2) Escanear repositórios em busca de `SKILL.md`

Esta skill usa uma estratégia em camadas, consciente de limites de taxa:

Camada A (preferida): API de Conteúdos do GitHub

A mais rápida e barata quando você conhece o caminho exato.

Verificar caminhos candidatos (padrão /SKILL.md) contra o branch padrão.
Registrar 200 como encontrado, 404 como não encontrado.

Camada B (opcional): Busca de código do GitHub (busca por nome de arquivo dentro do repositório)

Use apenas quando:

Você quiser encontrar SKILL.md em subdiretórios.
Você quiser correspondência insensível a maiúsculas/minúsculas.
Os caminhos da API de Conteúdos forem desconhecidos.

Forma de consulta recomendada:

repo:owner/repo filename:SKILL.md

Camada C (fallback): Clone superficial com sparse checkout

Use apenas quando as APIs estiverem indisponíveis, com limite de taxa, ou você precisar suportar GitHub Enterprise sem APIs de busca.

Realizar um clone filtrado que evita histórico completo e blobs grandes, quando possível.
Usar sparse checkout para buscar apenas caminhos candidatos.

3) Exportar resultados para CSV de saída

Escrever a saída incrementalmente (streaming) para evitar perda de trabalho.
Garantir colunas determinísticas.
Suportar modo de continuação (resume) pulando repositórios já escaneados.

Fluxo de trabalho

Etapa 0: Pré-condições

Operação somente leitura.
Garanta autenticação GitHub para limites de taxa mais altos, se escaneando muitos repositórios.

Opções de ambiente (resolvidas em ordem de prioridade):

--github-tokens ghp_tok1,ghp_tok2 flag CLI — lista separada por vírgulas para rotação de múltiplos tokens (5000 req/h por token)
--github-token ghp_tok flag CLI — substituição de token único
GH_TOKENS=ghp_tok1,ghp_tok2 — variável de ambiente, separada por vírgulas (nova variável para múltiplos tokens)
GH_TOKEN=ghp_tok — variável de ambiente, token único (retrocompatível)
GITHUB_TOKEN=ghp_tok — variável de ambiente, fallback token único
GitHub CLI gh auth login — para uso interativo
Não autenticado — apenas 60 req/h principais (não adequado para varreduras em massa)

Quando múltiplos tokens são fornecidos, o TokenPool em src/github_client/ automaticamente:

Seleciona o token com a maior cota restante em cada requisição.
Atualiza a cota por token a partir dos cabeçalhos de resposta X-RateLimit-*.
Rotaciona para o próximo token disponível quando o atual está esgotado.
Aguarda até o horário de redefinição mais cedo quando todos os tokens estão esgotados.
Levanta RateLimitExhaustedError se a espera exceder o máximo configurável.

Etapa 1: Construir a lista de repositórios a partir dos CSVs SEART

Enumerar CSVs de entrada.
Para cada CSV:
- Detectar colunas de repositório.
- Extrair e normalizar owner/repo.
- Rastrear source_csv.
Deduplicar em todos os arquivos.

Etapa 2: Verificações de pré-voo

Validar presença de token (avisar se não autenticado).
Opcionalmente consultar status do limite de taxa e definir concorrência conservadora.

Etapa 3: Escanear cada repositório

Para cada owner/repo:

(Opcional) Buscar metadados do repositório:
- Confirmar existência do repositório.
- Registrar branch padrão, arquivado, fork, estrelas.
- Aplicar filtros (estrelas, forks, arquivados).
Escanear por SKILL.md usando a Camada A.
Se habilitado e necessário, executar a Camada B para busca mais profunda.
Se habilitado e necessário, executar a Camada C como fallback.
Registrar a melhor correspondência única (ou todas, se configurado).
Escrever a linha de resultado imediatamente.

Etapa 4: Produzir lista filtrada

Filtrar onde found=true.
Exportar CSV da lista filtrada.

Etapa 5: Relatório de resumo

Ao final, relatar:

Total de repositórios escaneados.
Contagem e porcentagem de encontrados.
Detalhamento de erros por error_type.
Taxa de varredura efetiva e quaisquer limites de taxa encontrados.

Exemplos de uso

Exemplo A: Escanear apenas o caminho raiz exato (rápido)

Entradas:
- seart_dir = data/seart_csvs/
- search_paths = ["/SKILL.md"]
Saída:
- outputs/skill_md_scan_results.csv

Exemplo B: Encontrar `SKILL.md` em qualquer lugar do repositório

Entradas:
- Habilitar busca de código.
- case_sensitive=false
Saída:
- outputs/skill_md_scan_results.csv
- outputs/skill_md_shortlist.csv

Exemplo C: Retomar uma varredura parcial

Se outputs/skill_md_scan_results.csv já existir, pular repositórios já presentes e continuar.

Restrições operacionais e salvaguardas

Somente leitura

Não enviar commits, abrir PRs, criar issues ou modificar conteúdos de repositórios.
Não escrever em diretórios do usuário fora da pasta de saída escolhida.

Limites de taxa e varredura educada

Preferir verificações da API de Conteúdos em vez de clonagem.
Usar concorrência limitada e backoff exponencial em:
- 403 limites de taxa secundários
- 429 muitas requisições
Armazenar progresso parcial continuamente.

Minimização de dados

Não baixar repositórios completos, a menos que o fallback seja necessário.
Não armazenar tokens, cookies ou cabeçalhos de autenticação brutos em logs ou CSV de saída.

Reprodutibilidade

Registrar scanned_at_utc e ref_scanned.
Manter configuração (caminhos, sensibilidade a maiúsculas/minúsculas, camadas habilitadas) junto com as saídas.

Regras de tratamento de erros

Erros de análise de repositório

Se uma linha não puder ser analisada em owner/repo, descartá-la e registrar um resumo de erro de análise por CSV.

Repositórios ausentes ou privados

Se o repositório for 404 ou inacessível:
- error_type=invalid_repo ou error_type=auth
- found=false

Falhas temporárias

Timeouts de rede, respostas 5xx:
- tentar novamente com backoff
- se ainda falhar, marcar error_type=network e continuar

Limite de taxa

Se limitado por taxa:
- reduzir concorrência
- fazer backoff e tentar novamente
- se ainda bloqueado, registrar error_type=rate_limited

Configuração padrão sugerida

match_name = "SKILL.md"
case_sensitive = true
search_paths = ["/SKILL.md"]
include_negative_results = true
resume = true
concurrency = 8
Camadas habilitadas:
- Camada A: ativada
- Camada B: desativada (ativar apenas se necessário)
- Camada C: desativada (ativar apenas se necessário)

Definição de conclusão

CSV de saída existe e contém uma linha por repositório escaneado (ou apenas repositórios encontrados, se configurado).
Linhas com found=true incluem um match_url e match_path funcionais.
A varredura é retomável sem duplicar linhas.
Estatísticas de resumo são relatadas e o detalhamento de erros está disponível.

Notas para processamento downstream

A lista filtrada produzida por esta skill destina-se a ser entrada para um estágio posterior do pipeline, por exemplo:

baixar e analisar o conteúdo de SKILL.md
extrair seções estruturadas (Descrição, Capacidades, Fluxo de Trabalho, Restrições)
construir um conjunto de dados de skills detectáveis por agente por repositório

Estágios downstream devem tratar o conteúdo de SKILL.md como entrada não confiável e devem sanitizar qualquer texto extraído antes do uso.

Perguntar na sua IA favorita

Documentação