Claude Codeのスキル自動起動とは｜インフラ構成ショーケースを実機検証で解説

Claude Codeのスキル自動起動を、実在するショーケースで丸ごと実装したのが Claude Code Infrastructure Showcase（diet103/claude-code-infrastructure-showcase・GitHubスター9,883・MIT）です。Claude Code を使っていて、こんな経験はないでしょうか。せっかく frontend-dev-guidelines のようなスキル（プロジェクト規約をまとめたガイド）を用意したのに、Claude はそれを読まずにコンポーネントを書き始め、MUI の非推奨APIやチームで禁止したパターンが混ざる——。原因はシンプルで、Claude Code のスキルは「置いてあるだけ」では自動で発火しないからです。このリポジトリは、スキル・フック・エージェント・コマンドという運用インフラを一式束ねた参照ライブラリとして、その「Claude Code スキル 発火しない」問題に真正面から答えます。

このリポジトリの主題は、まさにその「スキルが自動で発火しない」問題を、UserPromptSubmit フックという仕組みで解くことにあります。あなたが送るプロンプトをフックが解析し、skill-rules.json に定義したトリガーに一致したら、該当スキルを自動で提案・強制する。しかも既定は正規表現ベースでAPIキー不要・完全オフライン・無料。この記事では、編集部が本物のフックを実機で動かした結果をもとに、仕組み・カタログ・導入手順、そして「個人のショーケースである」という限界までを正確に整理します。

まずは、実際にフックを走らせて「create a React component」というプロンプトがスキルの自動起動を引き起こした様子から。

なお、Claude Code そのもののインストール・設定・CLAUDE.md・フック・本番運用の全体像は Claude Code｜2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引き にまとめています。本記事はその中の「スキルとフックを自動化する運用」を、実在するショーケースを題材に深掘りする位置づけです。

1. Claude Codeのスキル自動起動とは — Infrastructure Showcaseが束ねる運用インフラ

このリポジトリは、Claude Code を長期プロジェクトで実運用するための「土台一式」を集めたものです。作者いわく、複雑な TypeScript マイクロサービス（6サービス・5万行超）を Claude Code で6か月回すなかで、「スキルが自動で発火しない」問題を解決し、エンタープライズ開発にスケールさせるために育てた仕組みを、そのまま公開しています。

重要なのは、README が冒頭で 「これは動くアプリケーションではない（NOT a working application）。参照ライブラリだ」 と明言している点です。つまり、git clone して起動するプロダクトではなく、必要な部品を自分のプロジェクトに cp して使うタイプのリポジトリです。この性質は評価軸を大きく変えるので、最初に押さえておきます。

中身を大まかに数えると、スキル4種・フック9種・エージェント8種・スラッシュコマンド4種、加えてセットアップウィザード（setup.ts）、Codex 連携用の .agents/ と .codex/、Claude のプロンプト編集向け NeoVim 設定まで含まれます。単なる「便利スニペット集」ではなく、プロンプト送信 → スキル起動 → 編集の検証 → セッションをまたぐ文脈保存という一連のライフサイクルを、フックで自動化しているのが特徴です。

なぜスキルは「置くだけ」では発火しないのか

Claude Code のスキルは、便利な反面「受け身」です。.claude/skills/ にどれだけ良いガイドを置いても、Claude がその存在に気づいて自分で読み込むか、ユーザーが Skill ツールで明示的に呼ばない限り、参照されません。結果として「規約はスキルに書いてあるのに、Claude はそれを読まずにコードを書く」という取りこぼしが日常的に起きます。

README はこの問題を一文でこう要約します。「Claude Code のスキルはただそこに座っているだけ。使うのを覚えておかなければならない」。そして解決策は、プロンプトが送られた瞬間に走る UserPromptSubmit フックで、プロンプトを分析し、文脈をチェックし、関連スキルを自動で提案すること。結果として、スキルは「あなたが思い出したとき」ではなく「必要なとき」に立ち上がる——これがこのショーケースの核心的な価値提案です。

言い換えると、このリポジトリが代替するのは「毎回 Skill を手で呼ぶ運用」や「CLAUDE.md に『必ずスキルを使え』と書いて祈る運用」です。前者は手間がかかって続かず、後者は Claude が指示を守るとは限らない。機械的なフックで確実に発火させることで、その両方の弱点を埋めます。

2. Claude Codeのスキル自動起動はどう動くのか — フック・skill-rules.json・検証ガード

仕組みの中心は、5つのライフサイクルフックと、その振る舞いを決める skill-rules.json です。この Claude Code フック スキル 連携が、本ショーケース最大の差別化点だと言えます。プロンプト送信から編集完了までの流れを図にすると、こうなります。

skill-rules.json がトリガーを決める

skill-rules.json は、どのプロンプト・どのファイルが、どのスキルを起動するかを定義する設定ファイルです。各スキルに promptTriggers（キーワードと正規表現の intentPatterns）と fileTriggers（パスパターンと中身のパターン）を持たせられます。例えば frontend-dev-guidelines は「component」「MUI」「React」などのキーワードや、\b(create|add|make|build)...\b.*?\b(component|UI|modal)...\b のような意図パターンにマッチします。

さらに各スキルには enforcement が付きます。suggest（提案するだけ）か block（起動するまで編集を止める＝ガードレール）か。実際の skill-rules.json では frontend-dev-guidelines が block、backend-dev-guidelines が suggest に設定されています。この違いは、編集部の実機テストではっきり出ました。

トリガーは「プロンプトの言葉」だけではありません。fileTriggers を使えば、触っているファイルの種類でもスキルを起動できます。例えば backend-dev-guidelines は backend/**/*.ts や services/**/*.ts といったパスパターンに加え、ファイルの中身が router. や app.get/post/put/delete を含むか（contentPatterns）まで見ます。テストファイル（*.test.ts / *.spec.ts）は pathExclusions で除外。つまり「バックエンドのルーティングを触っている」という文脈そのものを検知して、規約スキルを差し込めるわけです。加えて conservativeness（strict / balanced / aggressive）で提案の積極性を調整でき、strict は誤検知を最小化、aggressive は取りこぼしを嫌って広めに提案します。既定は balanced です。

実機で確かめた3つの挙動

編集部がリポジトリを clone し、.claude/hooks で npm install した後、実際のフック（skill_activation_mode: disabled＝regexモード）に3種類のプロンプトを食わせた結果です。入力も出力も本物です。

① 「create a React component for the settings dashboard」→ 強制（MANDATORY）

frontend-dev-guidelines（enforcement=block）が発火し、「⛔ MANDATORY SKILL ACTIVATION REQUIRED」「EDITS WILL BE BLOCKED until mandatory skills are activated」が返りました（記事冒頭のFV画像がこの出力）。

② 「add an Express API endpoint with Prisma for user profiles」→ 提案（RECOMMENDED）

こちらは backend-dev-guidelines（enforcement=suggest）に一致し、扱いが変わります。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎯 SKILL ACTIVATION CHECK
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📚 RECOMMENDED SKILLS:
  → backend-dev-guidelines

ACTION: Use Skill tool BEFORE responding
[via regex]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

③ 「what time is it in Tokyo」→ 何も出さない（沈黙）

無関係なプロンプトにはスキル提案を一切出さず、開発文書のリマインダーだけを表示しました。過剰発火しないことも実機で確認できます。[via regex] の表記は、AIではなく正規表現で判定したことを示しています。

この「MANDATORY / RECOMMENDED / 沈黙」の3段が、enforcement 設定と conservativeness（strict / balanced / aggressive）で調整できる、というのが仕組みの要点です。

検証ガードが「無視」を封じる（v2.0）

提案だけでは Claude が無視できてしまう——その穴を埋めるのが skill-verification-guard（PreToolUse フック）です。settings.json を見ると、Edit|MultiEdit|Write にマッチする PreToolUse として登録されており、コードを書こうとした瞬間に「必須スキルがまだ起動していない」と判断したら、その編集を止める。README はこれを two-try（2回まで）ブロックモデルと説明しています。1スキルにつき最大1回の助言的ブロックでコストを抑えつつ、起動を促す設計です。起動が済むと skill-activation-tracker（PostToolUse の Skill フック）が「起動済み」フラグを立て、ブロックが解除されます。

3. 何が入っているのか — スキル4・フック9・エージェント8・コマンド4

ここからは「結局どんな部品が入っているのか」を、実際のカタログに沿って見ていきます。目を引くのは、大きなスキルを500行ルールで分割し、必要な分だけ読み込ませるprogressive disclosure（段階的開示）の設計です。

スキル（4種）

各スキルは SKILL.md（入口）＋ resources/*.md（詳細）というモジュラー構成です。

backend-dev-guidelines が11本の資料ファイル（ルーティング・コントローラ・サービス・リポジトリ・テスト等）に割れているのが、500行ルールの実例です。

フック（9種）と登録の仕組み

フックは .claude/settings.json に登録します。実際の登録内容を整理すると、Claude Code の主要なライフサイクルイベントをほぼ網羅しています。

「必須」の4つはそのまま入れれば動くとされ、任意の Stop フック群はモノレポ前提など重めのカスタマイズが要ります。まず必須4つで自動起動を体験し、後から任意フックを足すのが定石です。

エージェント（8種）とコマンド（4種）

エージェントは Markdown 1枚で定義されたサブエージェントで、code-architecture-reviewer（アーキ整合レビュー）、refactor-planner（リファクタ計画）、auto-error-resolver（TypeScriptエラー自動修正）、documentation-architect（文書生成）、web-research-specialist（技術調査）など8種。README は「コピーするだけで使える」としています。スラッシュコマンドは /dev-docs・/dev-docs-update・/verify-setup・/route-research-for-testing の4種です。

4. context resetを越える dev-docs と Codex 対応

長い作業では、Claude の文脈（コンテキスト）がリセットされて、それまでの決定や作業中のタスクが失われます。このショーケースが用意する回答が dev-docs パターンです。

/dev-docs コマンドを使うと、作業ごとに [task]-plan.md（戦略）・[task]-context.md（決定と対象ファイル）・[task]-tasks.md（チェックリスト）の3ファイルを生成します。context がリセットされても、この3ファイルを読み直せば作業を再開できる、という発想です。session-doc-updater（Stop フック）が、応答が終わるたびにこれらを更新する役目を担います。

Codex でも同じ仕組みが動く

見落とされがちですが、このショーケースは OpenAI Codex CLI にも対応しています。Codex のフックは Claude Code と同じイベント・stdin スキーマ・終了コードの意味を採用しており、スキルは横断標準の Agent Skills 標準 に従うため、1つのコードベースでフォークなしに両対応できます。具体的には、.agents/skills/（.claude/skills/ の同期ミラー）と .codex/hooks.json、そして Codex 固有の差分だけを吸収する薄いアダプタ（_codex-adapter.sh）で実現しています。編集部の verify-setup では「cross-agent mirror: .agents/skills matches .claude/skills」も合格していました。ただし Codex には Skill ツールイベントが無いため、起動済みフラグを早期に消すトラッカーだけは発火しない、という既知の差はあります。

5. 導入と実機検証 — 15〜30分で自分の環境へ移植する

導入は3通りです。①ウィザード（推奨）、②手動コピー、③Claude 自身にやらせる。いずれも「危険な自動実行」ではなく、あなたのプロジェクトに .claude/ を足すだけの操作です。

必須要件は Node.js 18+（20+推奨）、macOS / Linux / WSL2（フックが bash スクリプトのため、素の Windows cmd/PowerShell では動かない）、そして任意で jq。ウィザードは次の1行です。

# 1. リポジトリを clone
git clone https://github.com/diet103/claude-code-infrastructure-showcase.git

# 2. あなたのプロジェクトを指してウィザードを実行
cd claude-code-infrastructure-showcase
npx tsx setup.ts ~/my-project

ウィザードは .claude/（フック・スキル・エージェント・コマンド）をコピーし、技術スタックを検出し、Classic（regexのみ）か AI-Enhanced かを尋ね、依存をインストールし、最後に8項目のヘルスチェックで自分の作業を検証します。手で入れるなら cp -r claude-code-infrastructure-showcase/.claude ~/my-project/.claude と cd .claude/hooks && npm install && chmod +x *.sh の実質3コマンドです。

セルフ検証を実機で走らせる

導入後（またはいつでも）、bash .claude/scripts/verify-setup.sh を実行すると、Node バージョン・フック登録・実行権限・依存・設定の妥当性、さらにテストプロンプトを本物の起動フックに通す E2E チェックまでを一気に検証します。編集部が macOS / Node v22.13.1 で実行した実際の結果がこれです。

regex か AI 分類か — 使い分けの目安

既定の disabled（regexのみ）は無料・オフラインで、まずはこれで十分です。タイポや言い換え（「作って」ではなく「実装したい」など）まで拾いたくなったら、AI 分類を有効化します。

AI プロバイダは Gemini（無料枠が広い）・OpenAI・Anthropic・Ollama（ローカル）から選べ、fallback はキーが無くても regex に落ちるため壊れません。なお編集部の計測では、regex モードのフック1回あたりの所要は約0.35秒（Node の起動時間込み・Apple Silicon）でした。プロンプトごとに毎回走る前提でも、体感できる遅延はほぼありません。

6. 使えるか？ — ライセンス・活性度・バス係数を正直に見る

最後に、当サイトが最も大事にする「使えるかどうか」を、盛らずに評価します。結論から言うと、”仕組みを学んで移植する手本” としては極めて優秀。ただし “メンテされ続けるプロダクト” ではない、という二面性が本質です。

もう一つの正直な注意点は、スキル本体が作者のスタックに強く依存していることです。frontend-dev-guidelines は React / MUI v7 前提、backend-dev-guidelines は Express / Prisma 前提で、そのまま使えるかはあなたの技術スタック次第。移植して普遍的に効くのは「自動起動の仕組み」＝フックと skill-rules.json の設計であって、スキルの中身は自分のプロジェクト用に書き換える前提で見るのが正解です。ライセンスは素直な MIT（dcg のような反AIベンダー条項は無し）なので、改変・再配布は自由です。

代替や近接する選択肢と並べると、位置づけがはっきりします。

つまりこのショーケースは、Claude Skillsとは｜「スキル=フォルダ」の仕組みと作り方・使い方を徹底解説 が説明する「スキルとは何か・どう作るか」の次の一手——「作ったスキルを、忘れず確実に発火させる運用」——を実装で示したものです。安全側のフック運用に興味があれば Destructive Command Guard（dcg）とは｜AIエージェントの危険コマンドを実行前ブロック が、CLAUDE.md 側からエージェントを制御する発想は Karpathy流CLAUDE.md徹底解説｜LLMコーディング暴走を止める4原則と30kスターの理由 が、それぞれ補完になります。

おすすめできる人：Claude Code を長期プロジェクトで使い、「スキルを作ったのに使われない」問題に困っている人。フックと skill-rules.json の設計を学び、自分のスタック用に作り替える前提の人。慎重になるべき人：メンテされ続ける公式サポート付きの仕組みを求める人、または React/Express 以外のスタックで「そのまま動く」ことを期待する人。手本として読み、必要な部品だけを自分の手で移植する——この距離感で付き合うのが、このショーケースの正しい使い方です。

まとめ — 「自動起動の設計図」として読む

Claude Code Infrastructure Showcase は、「スキルが自動で発火しない」という Claude Code の弱点に、UserPromptSubmit フック＋ skill-rules.json ＋ 検証ガードという具体的な実装で答えた参照ライブラリです。既定は無料・オフラインの regex モードで動き、必要なら AI 分類にも拡張でき、セットアップは自分自身を8項目で検証する。編集部の実機でも「MANDATORY / RECOMMENDED / 沈黙」の3段と、8合格・0失敗のヘルスチェックを確認できました。

一方で、コミット14件・contributor実質2名・リリース0本という「個人のショーケース」である事実と、スキル本体が作者スタックに依存している点は正直に押さえるべきです。プロダクトとしてではなく、”自動起動の設計図” として読み、フックと設定の考え方を自分のプロジェクトへ移植する——それが、このリポジトリから最大の価値を引き出す道です。

参照ソース

・diet103/claude-code-infrastructure-showcase（公式リポジトリ）
・README.md（自動起動・モード・パターン一覧）
・CLAUDE_INTEGRATION_GUIDE.md（AI支援での移植手順）
・Claude Code Hooks 公式ドキュメント（UserPromptSubmit / PreToolUse）
・Agent Skills 標準（agentskills.io）