Communitygithub.com

EliasOulkadi/shokunin

Sincroniza automáticamente los repositorios de GitHub con tu sitio web de portafolio. Escanea repos, captura capturas de pantalla con Playwright, genera entradas de proyecto y actualiza projects-data.js o Supabase DB.

¿Qué es shokunin?

Esta habilidad automatiza la sincronización de tus repositorios de GitHub con tu sitio web de portafolio personal. Es especialmente útil para desarrolladores que mantienen un portafolio actualizado y desean reflejar automáticamente sus proyectos públicos de GitHub. El flujo de trabajo comienza recopilando la configuración del usuario, como el nombre de usuario de GitHub, el tipo de portafolio (estático con projects-data.js o dinámico con Supabase), el directorio del portafolio y filtros para excluir forks o repositorios archivados. Luego, la habilidad obtiene los repositorios mediante la API de GitHub, detecta cambios comparando con un archivo de estado local, captura capturas de pantalla de los repositorios que tienen una URL de despliegue (usando Playwright), y actualiza la fuente de datos del portafolio (ya sea el archivo projects-data.js o la base de datos Supabase). Finalmente, guarda el estado de la sincronización e informa los resultados. La habilidad incluye un manejo detallado de errores para casos como límites de tasa de la API, fallos de Playwright, o entradas corruptas.

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

Preguntar en tu IA favorita

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

Documentación

Nota: El archivo de estado last-sync.json se crea automáticamente en la primera sincronización exitosa. Ignora las advertencias de "archivo faltante" en la primera ejecución.

Sincronización Automática de Portafolio

Sincroniza automáticamente tus repositorios de GitHub con tu sitio web de portafolio.

Flujo de trabajo

Paso 1: Recopilar configuración

Pregunta al usuario:

  • Nombre de usuario de GitHub: (por defecto desde la configuración de git)
  • Tipo de portafolio: static (projects-data.js) o supabase (API)
  • Directorio del portafolio: Ruta al proyecto del portafolio
  • Filtros: Excluir repositorios (archivados, forks, nombres específicos)

Paso 2: Obtener repositorios mediante la API de GitHub

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

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

Filtrar:

  • Forks (a menos que el usuario los incluya)
  • Repositorios de perfil ({username}/{username})
  • Repositorios archivados

Paso 3: Detectar cambios

Compara con last-sync.json (almacenado en el directorio de la habilidad).

  • Nuevos repositorios: No estaban en la última sincronización → proceso completo
  • Repositorios actualizados: updated_at cambió → volver a capturar captura de pantalla
  • Repositorios sin cambios: Omitir

Paso 4: Capturar capturas de pantalla

Para repositorios con homepage o URL de despliegue:

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();

Guardar en el directorio de capturas de pantalla del portafolio.

Paso 5: Actualizar los datos del portafolio

Estático (projects-data.js)

{
  title: '{repo.name}',
  description: 'Auto-generado: {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)
});

Paso 6: Guardar estado de sincronización

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

Paso 7: Reportar resultados

Sincronización completada:
+ 2 nuevos (Cyberian, Image Enhancer)
+ 1 captura de pantalla capturada
+ 1 actualizado (Portfolio)
- 0 errores

Notas

  • Las capturas de pantalla requieren Playwright y una URL válida. Omitir si no hay homepage.
  • Nunca cambiar featured: true en proyectos existentes — solo el usuario puede promocionar.
  • Programar mediante cron/GitHub Actions para una sincronización semanal.

Manejo de errores

CausaSolución
La API de GitHub devuelve 401 No autorizadoNo hay token o el token ha expirado. Establece la variable de entorno GITHUB_TOKEN. Genera un nuevo token de acceso personal en github.com/settings/tokens con el ámbito public_repo.
Límite de tasa de la API de GitHub excedido (403)Las solicitudes no autenticadas están limitadas a 60/hora. Autenticadas: 5000/hora. Agrega un token. Si ya estás autenticado, espera el reinicio (comprueba el encabezado X-RateLimit-Reset).
El repositorio no tiene campo homepage ni URL de despliegueNo se puede capturar una captura de pantalla. Marca el repositorio como "sin vista previa en vivo" en la salida. Usa la URL de GitHub como enlace de respaldo.
El navegador Playwright no se iniciaChromium no está instalado. Ejecuta npx playwright install chromium. En un servidor sin interfaz gráfica, agrega la bandera --no-sandbox: chromium.launch({ headless: true, args: ['--no-sandbox'] }).
La URL de la captura de pantalla devuelve 404 o expira después de 15sLa URL de despliegue está desactualizada o el sitio está caído. Omite la captura de pantalla para este repositorio. Registra la URL y el error en un archivo failed-screenshots.json para revisión manual.
projects-data.js tiene formato personalizado que la generación automática romperíaUna inserción basada en expresiones regulares podría dañar el código escrito a mano. Lee primero el archivo para detectar una estructura no estándar. Si se detecta, agrega un bloque de comentarios con las nuevas entradas y pide al usuario que fusione manualmente.
La inserción de la API de Supabase falla con una restricción de clave externa o esquemaEl esquema del portafolio podría diferir de la forma de la carga útil generada automáticamente. Lee primero el esquema de la tabla de Supabase. Asigna los campos explícitamente (no con el operador spread). Valida con una POST de prueba que devuelva 200 antes de confirmar.
last-sync.json está corrupto o editado manualmenteAnaliza como JSON en un bloque try-catch. En caso de fallo, renombra a last-sync.json.bak e inicia una sincronización completa desde cero. Advierte al usuario de que se ha perdido la detección incremental.

Patrones de la API de GitHub

Descubrimiento de repositorios

import requests, os

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

# Obtener todos los repositorios (paginados)
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: solo no forks, no archivados, con descripción
candidates = [r for r in repos if not r["fork"] and not r["archived"] and r["description"]]

Límite de tasa

  • API de GitHub: 5,000 solicitudes/hora (autenticadas). Comprueba el encabezado X-RateLimit-Remaining.
  • Para repositorios con 500+ repos: usar solicitudes condicionales (If-None-Match con ETag)
  • Esperar 1s entre capturas de pantalla (evitar el límite de tasa de GitHub en los activos)

Patrón de captura de pantalla con 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()

Recuperación de errores

  • Tiempo de espera en carga de página -> reintentar una vez, omitir si aún falla (marcar en la salida)
  • Repositorio privado -> omitir (no se puede capturar sin autenticación)
  • La página se bloquea -> capturar el estado de error como captura de pantalla
  • Fallo de DNS -> omitir con mensaje de registro

Estrategia de caché

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  # Omitir: sin cambios desde la última sincronización
    # ... capturar captura de pantalla, actualizar entrada ...
    cache[repo['full_name']] = key

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

Lista de verificación

  • El token de GitHub tiene los ámbitos correctos (repo, read:user) antes de obtener repositorios
  • La captura de pantalla solo se ejecuta para repositorios con URLs de homepage válidas (primero una comprobación HEAD)
  • El navegador Playwright se cierra en un bloque finally para evitar procesos huérfanos
  • Las personalizaciones existentes del portafolio se preservan antes de insertar nuevas entradas
  • Modo de prueba disponible para previsualizar cambios sin ejecutarlos

Fuentes

  • Documentación de la API REST de GitHub v3 (docs.github.com/en/rest/repos/repos) — listado, filtrado y paginación de repositorios
  • Documentación de Playwright (playwright.dev/docs/api/class-playwright) — lanzamiento del navegador sin interfaz gráfica, captura de pantalla y configuración del viewport
  • Documentación del cliente JavaScript de Supabase (supabase.com/docs/reference/javascript) — inserción, upsert y patrones de autenticación de la API
  • Documentación del módulo fs de Node.js (nodejs.org/api/fs.html) — lectura/escritura de archivos con renombrado atómico para la seguridad del estado de sincronización
  • Mejores prácticas para tokens de acceso personal (docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) — ámbitos, caducidad y almacenamiento seguro
  • Programación cron de GitHub Actions (docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule) — patrón de sincronización semanal automatizada
  • "Automate the Boring Stuff with Python" de Al Sweigart (No Starch Press, 2ª Edición, 2019) — patrones de confiabilidad de automatización aplicables a tareas de automatización en JavaScript

Anti-patrones

PatrónProblemaSolución
Sincronizar sin verificar personalizaciones existentesLas entradas generadas automáticamente pueden sobrescribir descripciones de proyectos hechas a mano, banderas destacadas o el orden personalizado establecido por el usuario.Leer primero el archivo de destino. Detectar una estructura no estándar. Para las entradas con featured: true, preservar todos los campos. Solo agregar o actualizar repositorios nuevos o modificados.
Capturar capturas de pantalla para todos los repositorios indiscriminadamenteLos repositorios sin demostraciones en vivo desperdician tiempo de lanzamiento de Playwright (~3s cada uno). Los repositorios con URLs rotas producen capturas de pantalla de error inútiles.Prefiltrar: solo capturar repositorios donde el campo homepage no esté vacío y devuelva 200 en una solicitud HEAD.
Ejecutar la sincronización en una conexión medida o lentaClonar o capturar docenas de repositorios puede consumir ancho de banda y tiempo significativos.Ejecutar en lotes de 10. Agregar una bandera --dry-run que liste lo que cambiaría sin ejecutarlo.
Usar la clave anón de Supabase en lugar de la clave service_role para escriturasLa clave anón tiene restricciones de seguridad a nivel de fila que bloquean los upserts.Usar la clave service_role con precaución. Almacenarla en una variable de entorno, nunca en el código. Agregar políticas RLS a nivel de tabla para la función de sincronización.
No limpiar los procesos del navegador Playwright después de la sincronizaciónCada chromium.launch() genera un proceso. Los procesos huérfanos acumulan memoria y pueden agotar los recursos del sistema.Siempre llamar a browser.close() en un bloque finally. Rastrear los navegadores lanzados en un array y forzar el cierre en SIGINT/SIGTERM.
Codificar la ruta de datos del portafolio en lugar de leerla desde la configuraciónLas rutas cambian entre proyectos. Una ruta codificada falla en el primer uso en una máquina diferente.Preguntar por el directorio del portafolio en el Paso 1. Derivar la ruta de projects-data.js desde esa base. Almacenar en el estado de sincronización para su reutilización.

Individual skills in this repo

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

Skills relacionados