Communitygithub.com

EliasOulkadi/shokunin

GitHub 리포지토리를 포트폴리오 웹사이트에 자동 동기화합니다. Playwright로 스크린샷을 캡처하고 프로젝트 항목을 생성하여 projects-data.js 또는 Supabase DB를 업데이트합니다.

shokunin란 무엇인가요?

이 스킬은 사용자의 GitHub 리포지토리를 자동으로 스캔하고 포트폴리오 웹사이트에 동기화하는 AI 에이전트 도구입니다. '포트폴리오 업데이트', '프로젝트 동기화', '리포지토리를 포트폴리오에 추가'와 같은 자연어 요청을 처리합니다. 주요 기능으로는 GitHub API를 통한 리포지토리 수집, Playwright를 사용한 라이브 데모 스크린샷 캡처, 정적(projects-data.js) 또는 Supabase 기반 포트폴리오 업데이트, 증분 동기화를 위한 변경 감지 등이 있습니다. Claude Code, Cursor, Codex와 같은 플랫폼에서 사용할 수 있으며, GitHub Personal Access Token과 Playwright 설치가 필요합니다. 배치 동기화에 특화되어 있어 한 번에 많은 프로젝트를 포트폴리오에 반영할 때 유용합니다.

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

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

참고: last-sync.json 상태 파일은 첫 번째 성공적인 동기화 시 자동 생성됩니다. 첫 실행 시 '파일 없음' 경고는 무시하세요.

포트폴리오 자동 동기화

GitHub 리포지토리를 포트폴리오 웹사이트에 자동으로 동기화합니다.

워크플로우

1단계: 설정 수집

사용자에게 다음을 질문합니다:

  • GitHub 사용자 이름: (git config 기본값)
  • 포트폴리오 유형: static (projects-data.js) 또는 supabase (API)
  • 포트폴리오 디렉토리: 포트폴리오 프로젝트 경로
  • 필터: 제외할 리포지토리 (보관됨, 포크, 특정 이름)

2단계: GitHub API를 통해 리포지토리 가져오기

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

추출: name, description, html_url, homepage, language, topics, updated_at

필터링:

  • 포크 (사용자가 허용하지 않은 경우)
  • 프로필 리포지토리 ({username}/{username})
  • 보관된 리포지토리

3단계: 변경 감지

last-sync.json (스킬 디렉토리에 저장)과 비교합니다.

  • 새 리포지토리: 마지막 동기화에 없음 → 전체 처리
  • 업데이트된 리포지토리: updated_at 변경됨 → 다시 스크린샷
  • 변경 없는 리포지토리: 건너뛰기

4단계: 스크린샷 캡처

homepage 또는 배포 URL이 있는 리포지토리:

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

포트폴리오의 스크린샷 디렉토리에 저장합니다.

5단계: 포트폴리오 데이터 업데이트

정적 (projects-data.js)

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

6단계: 동기화 상태 저장

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

7단계: 결과 보고

동기화 완료:
+ 2개 신규 (Cyberian, Image Enhancer)
+ 1개 스크린샷 캡처
+ 1개 업데이트 (Portfolio)
- 0개 오류

참고 사항

  • 스크린샷은 Playwright와 유효한 URL이 필요합니다. 홈페이지가 없으면 건너뜁니다.
  • 기존 프로젝트의 featured: true는 변경하지 마세요. 사용자만 승격할 수 있습니다.
  • 주간 동기화를 위해 cron/GitHub Actions로 예약하세요.

오류 처리

원인해결 방법
GitHub API가 401 Unauthorized 반환토큰이 없거나 만료됨. GITHUB_TOKEN 환경 변수를 설정하세요. github.com/settings/tokens에서 public_repo 범위의 새 Personal Access Token을 생성하세요.
GitHub API 속도 제한 초과 (403)인증되지 않은 요청은 시간당 60회로 제한됩니다. 인증된 요청: 시간당 5000회. 토큰을 추가하세요. 이미 인증된 경우 재설정을 기다리세요 (X-RateLimit-Reset 헤더 확인).
리포지토리에 homepage 필드와 배포 URL이 모두 없음스크린샷을 캡처할 수 없습니다. 출력에서 "라이브 미리보기 없음"으로 표시하세요. GitHub URL을 대체 링크로 사용하세요.
Playwright 브라우저 시작 실패Chromium이 설치되지 않음. npx playwright install chromium을 실행하세요. 헤드리스 서버에서는 --no-sandbox 플래그를 추가하세요: chromium.launch({ headless: true, args: ['--no-sandbox'] }).
스크린샷 URL이 15초 후 404 또는 타임아웃 반환배포 URL이 오래되었거나 사이트가 다운됨. 이 리포지토리의 스크린샷은 건너뜁니다. URL과 오류를 수동 검토를 위해 failed-screenshots.json 파일에 기록하세요.
projects-data.js에 자동 생성이 깨뜨릴 사용자 정의 포맷팅이 있음정규식 기반 삽입이 수동 코드를 손상시킬 수 있습니다. 먼저 파일을 읽어 비표준 구조를 감지하세요. 감지되면 새 항목이 포함된 주석 블록을 추가하고 사용자에게 수동 병합을 요청하세요.
Supabase API 삽입이 외래 키 또는 스키마 제약 조건으로 실패포트폴리오 스키마가 자동 생성된 페이로드 모양과 다를 수 있습니다. 먼저 Supabase 테이블 스키마를 읽으세요. 필드를 명시적으로 매핑하세요 (확산 연산자 사용하지 않음). 커밋 전에 200을 반환하는 dry-run POST로 유효성을 검증하세요.
last-sync.json이 손상되었거나 수동으로 편집됨try-catch에서 JSON으로 파싱하세요. 실패 시 last-sync.json.bak으로 이름을 바꾸고 처음부터 새로 동기화를 시작하세요. 증분 감지가 손실되었음을 사용자에게 경고하세요.

GitHub API 패턴

리포지토리 검색

import requests, os

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

# 모든 리포지토리 가져오기 (페이지네이션)
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

# 필터: 포크가 아니고, 보관되지 않았으며, 설명이 있는 리포지토리만
candidates = [r for r in repos if not r["fork"] and not r["archived"] and r["description"]]

속도 제한

  • GitHub API: 시간당 5000개 요청 (인증됨). X-RateLimit-Remaining 헤더를 확인하세요.
  • 500개 이상의 리포지토리가 있는 경우 조건부 요청 (If-None-Match와 ETag) 사용
  • 스크린샷 캡처 사이에 1초 대기 (GitHub 자산 속도 제한 방지)

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

오류 복구

  • 페이지 로드 타임아웃 -> 한 번 재시도, 여전히 실패하면 건너뛰기 (출력에 표시)
  • 비공개 리포지토리 -> 건너뛰기 (인증 없이 스크린샷 불가)
  • 페이지 충돌 -> 오류 상태를 스크린샷으로 캡처
  • DNS 실패 -> 로그 메시지와 함께 건너뛰기

캐싱 전략

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  # 건너뛰기: 마지막 동기화 이후 변경 없음
    # ... 스크린샷 캡처, 항목 업데이트 ...
    cache[repo['full_name']] = key

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

체크리스트

  • 리포지토리를 가져오기 전에 GitHub 토큰에 올바른 범위(repo, read:user)가 있는지 확인
  • 유효한 홈페이지 URL(HEAD 확인 먼저)이 있는 리포지토리에 대해서만 스크린샷 실행
  • 고아 프로세스를 방지하기 위해 finally 블록에서 Playwright 브라우저 종료
  • 새 항목을 upsert하기 전에 기존 포트폴리오 사용자 정의 유지
  • 변경 사항을 미리 보기 위해 dry-run 모드 사용 가능

출처

  • GitHub REST API v3 문서 (docs.github.com/en/rest/repos/repos) — 리포지토리 목록, 필터링 및 페이지네이션
  • Playwright 문서 (playwright.dev/docs/api/class-playwright) — 헤드리스 브라우저 실행, 스크린샷 및 뷰포트 구성
  • Supabase JavaScript 클라이언트 문서 (supabase.com/docs/reference/javascript) — API 삽입, upsert 및 인증 패턴
  • Node.js fs 모듈 문서 (nodejs.org/api/fs.html) — 동기화 상태 안전을 위한 원자적 이름 변경을 포함한 파일 읽기/쓰기
  • Personal Access Token 모범 사례 (docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) — 범위, 만료 및 안전한 저장
  • GitHub Actions cron 스케줄링 (docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule) — 주간 동기화 자동화 패턴
  • Al Sweigart 저 "Automate the Boring Stuff with Python" (No Starch Press, 2판, 2019) — JavaScript 자동화 작업에 적용 가능한 자동화 안정성 패턴

안티패턴

패턴문제해결 방법
기존 사용자 정의 확인 없이 동기화자동 생성된 항목이 사용자가 설정한 수작업 프로젝트 설명, featured 플래그 또는 사용자 정의 순서를 덮어쓸 수 있습니다.대상 파일을 먼저 읽으세요. 비표준 구조를 감지하세요. featured: true 항목의 경우 모든 필드를 유지하세요. 새롭거나 변경된 리포지토리만 upsert하세요.
모든 리포지토리에 대해 무차별적으로 스크린샷 캡처라이브 데모가 없는 리포지토리는 Playwright 실행 시간(각 약 3초)을 낭비합니다. URL이 깨진 리포지토리는 쓸모없는 오류 스크린샷을 생성합니다.사전 필터링: homepage 필드가 비어 있지 않고 HEAD 요청에 200을 반환하는 리포지토리만 스크린샷을 캡처합니다.
제한된 또는 느린 연결에서 동기화 실행수십 개의 리포지토리를 클론하거나 스크린샷을 캡처하면 상당한 대역폭과 시간이 소모될 수 있습니다.10개씩 배치로 실행하세요. 변경 사항을 실행하지 않고 나열하는 --dry-run 플래그를 추가하세요.
쓰기에 Supabase anon 키 대신 service_role 키 사용anon 키는 upsert를 차단하는 행 수준 보안 제한이 있습니다.service_role 키를 주의해서 사용하세요. 환경 변수에 저장하고 코드에 절대 저장하지 마세요. 동기화 함수에 대한 테이블 수준 RLS 정책을 추가하세요.
동기화 후 Playwright 브라우저 프로세스 정리하지 않음각 chromium.launch()는 프로세스를 생성합니다. 고아 프로세스는 메모리를 축적하고 시스템 리소스를 고갈시킬 수 있습니다.finally 블록에서 항상 browser.close()를 호출하세요. 실행된 브라우저를 배열에 추적하고 SIGINT/SIGTERM에서 강제 종료하세요.
포트폴리오 데이터 경로를 구성에서 읽지 않고 하드코딩경로는 프로젝트 간에 변경됩니다. 하드코딩된 경로는 다른 머신에서 처음 사용 시 깨집니다.1단계에서 포트폴리오 디렉토리를 질문하세요. 해당 기본 경로에서 projects-data.js 경로를 파생하세요. 재사용을 위해 동기화 상태에 저장하세요.

Individual skills in this repo

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

관련 스킬