Communitygithub.com

EliasOulkadi/shokunin

Sincroniza automaticamente repositórios do GitHub com seu site de portfólio. Faz scan de repositórios, captura screenshots com Playwright, gera entradas de projeto e atualiza projects-data.js ou banco Supabase. Use quando o usuário pedir 'atualizar portfólio', 'sincronizar projetos', 'adicionar meus repositórios ao portfólio' ou 'atualizar projetos do portfólio'. NÃO use para adições únicas de projeto — apenas sincronização em lote.

O que é shokunin?

O Shokunin é uma skill de agente IA projetada para automatizar a sincronização de repositórios do GitHub com um site de portfólio pessoal. Ele escaneia todos os repositórios públicos de um usuário, captura screenshots das páginas iniciais usando Playwright (apenas para repositórios com URL válida), e gera entradas de projeto no formato correto, seja para um arquivo estático `projects-data.js` ou para um banco Supabase via API. A skill é ideal para usuários que desejam manter seu portfólio sempre atualizado com seus projetos mais recentes do GitHub, sem precisar editar manualmente o código ou dados. Ela suporta filtragem (excluir forks, arquivados, repositórios específicos), detecção incremental de mudanças via um arquivo de estado `last-sync.json`, e tratamento robusto de erros, incluindo limites de taxa da API, falhas no Playwright e corrupção de cache. A skill opera como um comando em lote, não para adições únicas de projeto, e pode ser agendada via cron ou GitHub Actions para sincronização semanal.

Funciona com~Claude Code~Codex CLI~Cursor✓OpenCode
npx skills add https://github.com/EliasOulkadi/shokunin/tree/HEAD/.pack/skills/portfolio-auto

Perguntar na sua IA favorita

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

Documentação

Nota: O arquivo de estado last-sync.json é criado automaticamente na primeira sincronização bem-sucedida. Ignore avisos de "arquivo ausente" na primeira execução.

Sincronização Automática de Portfólio

Sincroniza automaticamente repositórios do GitHub para seu site de portfólio.

Fluxo de Trabalho

Passo 1: Coletar configuração

Pergunte ao usuário:

  • Nome de usuário do GitHub: (padrão do git config)
  • Tipo de portfólio: static (projects-data.js) ou supabase (API)
  • Diretório do portfólio: Caminho para o projeto do portfólio
  • Filtros: Excluir repositórios (arquivados, forks, nomes específicos)

Passo 2: Buscar repositórios via API do GitHub

GET /users/{username}/repos?per_page=100&sort=updated&direction=desc

Extrair: name, description, html_url, homepage, language, topics, updated_at

Filtrar:

  • Forks (a menos que o usuário opte por incluí-los)
  • Repositórios de perfil ({username}/{username})
  • Repositórios arquivados

Passo 3: Detectar alterações

Comparar com last-sync.json (armazenado no diretório da skill).

  • Novos repositórios: Não estão na última sincronização → processo completo
  • Repositórios atualizados: updated_at mudou → recapturar screenshot
  • Repositórios inalterados: Pular

Passo 4: Capturar screenshots

Para repositórios com homepage ou URL de implantação:

const { chromium } = require('playwright');
const browser = await chromium.launch({ headless: true });
const page = await browser.newPage();
await page.setViewportSize({ width: 1280, height: 800 });
await page.goto(process.env.URL, { waitUntil: 'networkidle', timeout: 15000 });
await page.screenshot({ path: `/tmp/portfolio-${name}.png`, fullPage: false });
await browser.close();

Salvar no diretório de screenshots do portfólio.

Passo 5: Atualizar dados do portfólio

Estático (projects-data.js)

{
  title: '{repo.name}',
  description: 'Gerado automaticamente: {description}',
  tech: '{language},{topics}',
  github_url: '{html_url}',
  live_url: '{homepage || ""}',
  featured: false
}

Supabase

const res = await fetch('https://your-site.com/api/projects', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer {token}' },
  body: JSON.stringify(projectData)
});

Passo 6: Salvar estado da sincronização

{
  "lastSync": "2026-05-12T18:30:00Z",
  "repos": {
    "example-repo": { "updated_at": "2026-04-20T10:00:00Z", "screenshot": true }
  }
}

Passo 7: Relatar resultados

Sincronização concluída:
+ 2 novos (Cyberian, Image Enhancer)
+ 1 screenshot capturado
+ 1 atualizado (Portfolio)
- 0 erros

Notas

  • Screenshots exigem Playwright + URL válida. Pular se não houver homepage.
  • Nunca altere featured: true em projetos existentes — apenas o usuário pode promover.
  • Agende via cron/GitHub Actions para sincronização semanal.

Tratamento de Erros

CausaCorreção
API do GitHub retorna 401 Não AutorizadoSem token ou token expirado. Defina a variável de ambiente GITHUB_TOKEN. Gere um novo Personal Access Token em github.com/settings/tokens com escopo public_repo.
Limite de taxa da API do GitHub excedido (403)Requisições não autenticadas são limitadas a 60/hora. Autenticadas: 5000/hora. Adicione token. Se já autenticado, aguarde a redefinição (verifique cabeçalho X-RateLimit-Reset).
Repositório não possui campo homepage nem URL de implantaçãoNão é possível capturar screenshot. Marque o repositório como "sem prévia ao vivo" na saída. Use a URL do GitHub como fallback.
Navegador Playwright não iniciaChromium não instalado. Execute npx playwright install chromium. Em servidor headless, adicione flag --no-sandbox: chromium.launch({ headless: true, args: ['--no-sandbox'] }).
URL do screenshot retorna 404 ou timeout após 15sURL de implantação está desatualizada ou site fora do ar. Pule screenshot para este repositório. Registre a URL e o erro em um arquivo failed-screenshots.json para revisão manual.
projects-data.js tem formatação personalizada que a geração automática pode quebrarUma inserção baseada em regex pode corromper código escrito à mão. Leia o arquivo primeiro para detectar estrutura não padrão. Se detectada, anexe um bloco de comentário com as novas entradas e peça ao usuário para mesclar manualmente.
Inserção na API do Supabase falha com restrição de chave estrangeira ou esquemaO esquema do portfólio pode diferir da forma do payload gerado automaticamente. Leia o esquema da tabela Supabase primeiro. Mapeie campos explicitamente (não use operador spread). Valide com um POST de teste que retorne 200 antes de confirmar.
last-sync.json está corrompido ou editado manualmenteAnalise como JSON em um try-catch. Em caso de falha, renomeie para last-sync.json.bak e inicie sincronização completa do zero. Avise o usuário que a detecção incremental foi perdida.

Padrões da API do GitHub

Descoberta de Repositórios

import requests, os

headers = {"Authorization": f"token {os.environ['GITHUB_TOKEN']}"}

# Buscar todos os repositórios (paginado)
repos = []
page = 1
while True:
    r = requests.get(f"https://api.github.com/user/repos?per_page=100&page={page}&sort=updated", headers=headers)
    batch = r.json()
    if not batch: break
    repos.extend(batch)
    page += 1

# Filtrar: apenas não-fork, não-arquivados, com descrição
candidates = [r for r in repos if not r["fork"] and not r["archived"] and r["description"]]

Limitação de Taxa

  • API do GitHub: 5.000 requisições/hora (autenticado). Verifique cabeçalho X-RateLimit-Remaining.
  • Para repositórios com 500+: use requisições condicionais (If-None-Match com ETag)
  • Durma 1s entre capturas de screenshot (evitar limite de taxa do GitHub em assets)

Padrão de Screenshot com Playwright

from playwright.sync_api import sync_playwright

def capture(url, output_path):
    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_page(viewport={"width": 1280, "height": 800})
        page.goto(url, timeout=15000, wait_until="networkidle")
        page.screenshot(path=output_path, full_page=False)
        browser.close()

Recuperação de Erros

  • Timeout no carregamento da página -> tente novamente uma vez, se ainda falhar, pule (marque na saída)
  • Repositório privado -> pule (não é possível capturar screenshot sem autenticação)
  • Página crasha -> capture estado de erro como screenshot
  • Falha de DNS -> pule com mensagem de log

Estratégia de Cache

import hashlib, json, os
cache_file = ".sync-cache.json"
cache = json.load(open(cache_file)) if os.path.exists(cache_file) else {}

for repo in repos:
    key = hashlib.md5(f"{repo['full_name']}:{repo['pushed_at']}".encode()).hexdigest()
    if cache.get(repo['full_name']) == key:
        continue  # Pular: sem alterações desde a última sincronização
    # ... capturar screenshot, atualizar entrada ...
    cache[repo['full_name']] = key

json.dump(cache, open(cache_file, 'w'))

Lista de Verificação

  • Token do GitHub tem escopos corretos (repo, read:user) antes de buscar repositórios
  • Screenshot executa apenas para repositórios com URLs homepage válidas (verificação HEAD primeiro)
  • Navegador Playwright fechado no bloco finally para evitar processos órfãos
  • Personalizações existentes do portfólio preservadas antes de upsertar novas entradas
  • Modo dry-run disponível para visualizar alterações sem executar

Fontes

  • Documentação da REST API v3 do GitHub (docs.github.com/en/rest/repos/repos) — listagem, filtragem e paginação de repositórios
  • Documentação do Playwright (playwright.dev/docs/api/class-playwright) — inicialização de navegador headless, screenshot e configuração de viewport
  • Documentação do cliente JavaScript do Supabase (supabase.com/docs/reference/javascript) — inserção via API, upsert e padrões de autenticação
  • Documentação do módulo fs do Node.js (nodejs.org/api/fs.html) — leitura/escrita de arquivos com rename atômico para segurança do estado de sincronização
  • Melhores práticas para Personal Access Tokens (docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) — escopos, expiração e armazenamento seguro
  • Agendamento cron do GitHub Actions (docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule) — padrão de automação de sincronização semanal
  • "Automate the Boring Stuff with Python" de Al Sweigart (No Starch Press, 2ª Edição, 2019) — padrões de confiabilidade de automação aplicáveis a tarefas de automação JavaScript

Anti-Padrões

PadrãoProblemaCorreção
Sincronizar sem verificar personalizações existentesEntradas geradas automaticamente podem sobrescrever descrições de projeto artesanais, flags de destaque ou ordenação personalizada definida pelo usuário.Leia o arquivo de destino primeiro. Detecte estrutura não padrão. Para entradas com featured: true, preserve todos os campos. Apenas faça upsert de repositórios novos ou alterados.
Capturar screenshots para todo repositório indiscriminadamenteRepositórios sem demonstrações ao vivo desperdiçam tempo de inicialização do Playwright (~3s cada). Repositórios com URLs quebradas produzem screenshots de erro inúteis.Pré-filtre: capture screenshots apenas de repositórios onde o campo homepage não está vazio e retorna 200 em uma requisição HEAD.
Executar sincronização em conexão medida ou lentaClonar ou capturar screenshots de dezenas de repositórios pode consumir largura de banda e tempo significativos.Execute em lotes de 10. Adicione uma flag --dry-run que liste o que mudaria sem executar.
Usar anon key do Supabase em vez de service_role key para escritasAnon key tem restrições de segurança em nível de linha que bloqueiam upserts.Use service_role key com cuidado. Armazene em variável de ambiente, nunca no código. Adicione políticas RLS no nível de tabela para a função de sincronização.
Não limpar processos do Playwright após a sincronizaçãoCada chromium.launch() inicia um processo. Processos órfãos acumulam memória e podem exaurir recursos do sistema.Sempre chame browser.close() em um bloco finally. Rastreie navegadores iniciados em um array e force fechamento em SIGINT/SIGTERM.
Hardcodar o caminho dos dados do portfólio em vez de ler da configuraçãoCaminhos mudam entre projetos. Um caminho hardcodado quebra no primeiro uso em uma máquina diferente.Pergunte pelo diretório do portfólio no Passo 1. Derive o caminho de projects-data.js a partir dessa base. Armazene no estado de sincronização para reutilização.

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Habilidades Relacionadas