skill-hub CLAUDE.md

CLAUDE.md — Skill Hub セットアップ手順（Claude Code向け）

このリポジトリを渡されたら、以下の手順で自走してセットアップしてください。各ステップは冪等なので、途中で失敗しても最初からやり直して問題ありません。

前提確認

• Node.js 20以上が入っているか確認する（node --version）。無ければ利用者に案内する。
• このリポジトリの直下で作業する。

手順

1. 依存関係をインストールする。

   npm ci
   

2. Cloudflareへのログインを確認する。これは唯一の手作業（ブラウザでの認証）なので、必ず利用者に実行してもらう。

   npx wrangler whoami
   

   失敗したら、利用者に次を実行してもらってから再開する:

   npx wrangler login
   

   利用者が複数のCloudflareアカウントを持っている場合は、対象アカウントIDを聞いて CLOUDFLARE_ACCOUNT_ID 環境変数に設定してから進める。

3. 利用者に管理者の表示名（例: 「田中(情シス)」）を確認してから、セットアップスクリプトを実行する。

   node scripts/setup.mjs --seed --admin-name "<確認した表示名>"
   

   これが以下を自動で行う（すべて冪等・状態確認型）:

   • D1データベース skill-hub-db の作成/確認、wrangler.jsonc の database_id 書き換え
   • マイグレーション適用（未適用分のみ）
   • wrangler deploy によるデプロイ
   • 有効なadminトークンが0件の場合のみ、初期adminトークンを発行して1回だけ表示
   • skills-samples/ の3本のサンプルスキルを投入

   ※ --admin-name を省略すると対話環境では質問され、非対話環境では「管理者」になる。

4. 出力されたURLと初期adminトークンを利用者にそのまま伝える。adminトークンは二度と表示されないので、チャット上に貼るだけでなく「必ずご自身でも控えてください」と一言添える。

5. 動作確認として、次を実行して200が返ることを確認する。

   curl -s https://<deployされたURL>/api/health
   

6. 利用者に次のアクションを提示する:

   • 管理画面（https://<URL>/app）にadminトークンでログインし、自社のスキルを登録する
   • メンバーを招待リンク（管理画面 > トークン・招待）で招待する
   • 招待されたメンバーは /join?code=... を開き「トークンを発行する」ボタンを押して、表示された claude mcp add ... コマンドを自分のClaude Codeに貼る

トラブルシュート

• wrangler d1 list --json が空を返す/権限エラー: Cloudflareアカウントの権限（D1編集権限）を確認する。
• deployが失敗する: npx wrangler deploy を単体実行してエラーメッセージをそのまま利用者に見せる。Workers Paidプランへの加入が必要なケースがある。
• 初期adminトークンを紛失した: wrangler d1 execute skill-hub-db --remote --command "SELECT id,name,revoked_at,expires_at FROM tokens WHERE role='admin'" で既存adminの状態を確認する。全て失効/期限切れなら scripts/setup.mjs を再実行すると新しいadminが自動発行される（bootstrapは「有効なadminが0件の時だけ」動く設計）。

開発者向け（コード変更時）

• 型チェック: npm run typecheck（tsc --noEmit。0エラーが必須）
• ローカルsmoke（出荷ゲート）: npm run smoke（scripts/smoke.mjs。wrangler devを自前起動し12項目すべてPASSでexit 0）
• ローカル動作確認: npm run dev（wrangler dev）
• サンプル投入（ローカル）: node scripts/seed.mjs --local --base-url http://localhost:8787 --token <editor以上のトークン>