Communitygithub.com

EliasOulkadi/shokunin

GitHubリポジトリをポートフォリオサイトに自動同期。スクリーンショットをキャプチャし、プロジェクトエントリを生成してprojects-data.jsまたはSupabase DBを更新します。

shokunin とは?

このスキルは、ユーザーのGitHubリポジトリを自動的にスキャンし、Playwrightを使用してスクリーンショットをキャプチャし、ポートフォリオサイトのプロジェクトデータ(静的ファイルまたはSupabaseデータベース)を一括同期するためのツールです。「ポートフォリオを更新」「プロジェクトを同期」「リポジトリを追加」などの指示に応じて動作します。まずユーザーにGitHubユーザー名やポートフォリオの種類(静的/Supabase)、ディレクトリ、フィルタ条件を確認し、GitHub APIでリポジトリ一覧を取得。前回の同期状態と比較して新規・更新リポジトリを検出し、deploy URLが存在するもののみスクリーンショットを撮影します。その後、静的ファイルのprojects-data.jsまたはSupabaseのAPIエンドポイントにデータを書き込み、last-sync.jsonに同期状態を保存します。エラーハンドリングも充実しており、レート制限、認証エラー、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: '自動生成: {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が必要です。homepageがない場合はスキップします。
  • 既存プロジェクトの featured: true は絶対に変更しないでください。プロモートはユーザーのみが行えます。
  • cron / GitHub Actionsを使用して週次同期をスケジュールできます。

エラーハンドリング

原因修正方法
GitHub APIが401 Unauthorizedを返すトークンがないか期限切れ。GITHUB_TOKEN 環境変数を設定してください。github.com/settings/tokens でスコープ public_repo の新しいパーソナルアクセストークンを生成します。
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が404または15秒のタイムアウトデプロイURLが古いかサイトがダウンしています。このリポジトリのスクリーンショットをスキップします。URLとエラーを failed-screenshots.json ファイルに記録し、手動確認を促します。
projects-data.js のカスタム書式が自動生成により壊れる可能性がある正規表現ベースの挿入で手書きコードが破損する可能性があります。まずファイルを読み込み、非標準構造を検出します。検出された場合は、新しいエントリを含むコメントブロックを追加し、ユーザーに手動マージを依頼します。
Supabase API insertが外部キーまたはスキーマ制約で失敗するポートフォリオスキーマが自動生成ペイロードの形状と異なる可能性があります。まずSupabaseテーブルスキーマを読み取ります。フィールドを明示的にマッピングします(スプレッド演算子は使用しない)。コミットする前に、200を返すドライラン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: 5,000リクエスト/時間(認証済み)。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()

エラーリカバリ

  • ページロードのタイムアウト -> 1回リトライ、それでも失敗した場合はスキップ(出力にマーク)
  • プライベートリポジトリ -> スキップ(認証なしではスクリーンショット不可)
  • ページクラッシュ -> エラー状態をスクリーンショットとしてキャプチャ
  • 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)があることをリポジトリ取得前に確認
  • スクリーンショットは有効なhomepage URLを持つリポジトリに対してのみ実行(最初にHEADチェック)
  • Playwrightブラウザはfinallyブロックで閉じ、ゾンビプロセスを防止
  • 既存のポートフォリオカスタマイズを新しいエントリのアップサート前に保持
  • ドライランモードで変更をプレビュー可能(実行せずに)

参照ソース

  • 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 insert、upsert、認証パターン
  • Node.js fs モジュール ドキュメント (nodejs.org/api/fs.html) — 同期状態の安全なファイル読み書き(アトミックリネーム)
  • パーソナルアクセストークンのベストプラクティス (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) — 週次同期自動化パターン
  • 「退屈なことはPythonにやらせよう」Al Sweigart 著(No Starch Press、第2版、2019年) — JavaScript自動化タスクに適用可能な自動化信頼性パターン

アンチパターン

パターン問題修正方法
既存のカスタマイズを確認せずに同期自動生成エントリがユーザーの手書きプロジェクト説明、featuredフラグ、カスタム順序を上書きする可能性があります。まず対象ファイルを読み込む。非標準構造を検出する。featured: true エントリについては全フィールドを保持する。新規または変更されたリポジトリのみアップサートする。
すべてのリポジトリに対して無差別にスクリーンショットをキャプチャライブデモのないリポジトリで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.

関連スキル