今回の変更を先に理解する
先に答えると、上限を気にし始めたら、まずhookを増やす前にsourceとsessionの境界を確認します。1,024と16,384は設計を無制限にする数字ではなく、登録された構成を観測し、重複や広すぎる条件を見つけるための公開仕様です。到達していない場合でも、機密データの外部送信や危険commandの実行を許可してよい理由にはなりません。
Claude Code公式changelogの2.1.304（2026年10月19日）は、同じsource（repo、自分のfolder、pluginなど）のSkillが、1 sessionあたり最大1,024 hooksと16,384 matcher charactersを登録できるよう変更したと説明しています。hookが多いほど便利になるという話ではなく、Skillを大量に重ねた環境で、実効範囲と発火を測るための上限です。
既存のSkillsの同期・優先順位・出所確認が、どのSkillを信頼して配布するかを扱うのに対し、本稿はhookの件数・matcher・source分割へ意図を限定します。上限を理由に未確認のpluginを追加したり、matcherを広げて発火漏れを隠したりしないでください。
hook・Skill・sourceを分けて数える
| 対象 | 今回の確認 | 混同しないもの |
|---|---|---|
| hook | イベントに応じて実行される処理 | Skill本文そのもの |
| matcher | hookが対象を選ぶ条件の文字数 | 出力文字数やcontext上限 |
| source | repo・自分のfolder・pluginなどの出所 | 一つの組織全体の合算 |
| session | 実際に読み込まれた作業単位 | ディスク上の全ファイル |
公式SkillsガイドはSkillの作成・管理・共有を説明し、公式Hooksガイドはイベント、matcher、commandなどの定義とテストを説明しています。上限を判定するときはこの3つのレイヤーを同時に数えず、実行sessionで何がロードされたかを確認します。
上限に近づく典型的な原因
原因は、各Skillが個別に小さいことではなく、同じsourceへ多くのイベント用hookを積み重ねることです。似たmatcherを複数のSkillに書く、全ファイル変更へ広いmatcherを付ける、pluginとrepoの責任範囲を分けない、といった構成では、登録数と条件文字数が増えます。
特に通知、整形、secret scan、テスト、記録をそれぞれ別hookにすると、同じイベントで多重実行する可能性があります。安全のため、件数を減らすことだけを目的に一つの巨大commandへまとめるのではなく、失敗時の停止、権限、タイムアウト、ログ、rollbackを比較して決めます。
棚卸しの8手順
claude --versionとsessionの接続先を記録する。- repo、user folder、pluginごとにSkillのsource台帳を作る。
- 各Skillからhook名、イベント、matcher、実行command、責任者を抜き出す。
- sourceごとにhook件数とmatcher文字数を数え、1,024・16,384との差を出す。
- 同じイベントとmatcherで重複するhookを候補化する。
- 広すぎるmatcherを、対象ファイルや操作へ絞れるか検証する。
- 低頻度の処理を手動commandやCIへ移し、必須hookだけ残す。
- fixtureで発火順、拒否、失敗、ログ、所要時間を確認し、台帳を更新する。
公式に記載された上限と、自社で観測した実効値は分けて保存します。上限に達していないことは、hookが期待通り発火した証拠ではありません。イベントが発火したか、commandのexit codeがどう扱われたか、同じ操作が二重に走っていないかをログで確認します。
分割・統合の判断基準
sourceを分けると責任境界は明確になりますが、同じ目的のhookが重複するおそれがあります。repo Skillはプロジェクト固有の検査、user folderは個人の通知、pluginは配布可能な共通処理というように、目的と所有者を一文で定義します。sourceを分けただけで安全性や発火順が保証されるわけではありません。
統合する場合は、処理の失敗を一つのexit codeで隠さないことが重要です。secret scanが失敗したのに整形処理の成功で全体を成功扱いにするなら、監査上の意味が変わります。hookごとに「止める」「警告だけ」「記録だけ」を決め、変更前後をテストします。
既存のClaude Code Hooksの基本ガイドやplugin hookの審査記事とも接続し、件数の削減と権限審査を別のチェックにします。
公開前に確認する運用記録
正式名称はSkillsとHooks、対象versionはClaude Code 2.1.304、上限はsource単位・session単位のhook数とmatcher文字数として記録します。実機で観測したロード結果、発火順、commandのexit code、失敗時の扱いは公式仕様と別欄にし、将来の更新で挙動が変わっても比較できるようにします。pluginの出所、更新者、レビュー日も残してください。
数字を減らすことだけを成功条件にせず、低リスクfixtureで変更前後を比較します。hookが一度も発火しない場合、二重に実行される場合、失敗を成功に見せる場合をそれぞれ不合格にし、手動commandやCIへ戻すfallbackを明記します。
チーム導入チェックリスト
- 2.1.304以降と接続先を記録した
- repo・user folder・pluginのsource台帳がある
- sourceごとのhook件数を数えた
- matcher文字数をsource・session単位で集計した
- 同一イベントの重複と広すぎる条件を確認した
- hookの失敗時動作と停止条件を定義した
- command、権限、外部送信、ログ保持を確認した
- fixtureで発火・失敗・rollbackを検証した
よくある質問
1,024件はプロジェクト全体の上限ですか？
公式changelogは、repo・自分のフォルダ・pluginなど一つのsourceのskillsが、1 sessionで登録できる上限として説明しています。全環境の合算値だと決めつけず、sourceとsessionを分けて測ります。
16,384文字はSkill本文の上限ですか？
この更新で示されているのはhook matcher charactersの上限です。Skill本文、指示文、tool実行結果の容量とは別に扱います。
上限を超えたら自動で安全に分割されますか？
公式情報だけから自動分割や発火保証は断定できません。sourceを整理し、必要なhookを減らして実環境で発火とログを確認してください。
hook設計をチームで見直せますか？
無料診断でsource、matcher、イベント、権限、副作用、監査ログを棚卸しし、分割と承認の方針を整理できます。無料診断（60秒）からご相談ください。
まとめ
Claude Code 2.1.304のSkill hook上限は、sourceとsessionごとの実効構成を見直すきっかけです。1,024 hooksと16,384 matcher charactersを全体の無制限枠やSkill本文の上限と誤解せず、source、イベント、matcher、副作用、失敗時の扱いを台帳化してください。Miraigentでは、SkillsとHooksを企業の権限・監査・引き継ぎまで含めて無料で診断します。無料診断（60秒）からご相談ください。