記事一覧スパルタClaude Code塾AI研修法人研修導入支援研修プランよくある質問
使い方ガイドClaude Code研究所 オリジナル解説

Claude Codeのhooks・スキルが動かない原因は?設定ミス16個を/statusと/doctorで実測

Claude Codeのhooksやスキルが動かない原因の一部は、v2.1.327の/statusで一覧になります。設定ミス16個で試すと/statusが示したのは11個。残る5個はClaudeに聞くと見つかりました。確認手順を解説します。

Claude Codeのhooks・スキルが動かない原因は?設定ミス16個を/statusと/doctorで実測

この記事の結論

  • Claude Code v2.1.327(2026年11月17日)で、/statusが壊れたスキル・サブエージェント・コマンド・出力スタイルのファイル、keybindingsの誤り、どのツールにも合わないhookのmatcherなどを一覧にするようになりました。
  • 当研究所が設定ミスを1つずつ仕込んだ16通りで試すと、v2.1.327の/statusが示したのは16個中11個でした。v2.1.326では5個で、増えた6個がこの更新の分です。
  • 残る5個(SKILL.mdのファイル名違い、skillsフォルダの綴り違い、matcherの小文字bash、存在しないhookスクリプト、CLAUDE.mdの読み込み先の欠落)は、起動時の表示・/status・/hooks・ターミナルのclaude doctorのどれにも出ませんでした(存在しないスクリプトは、hookが実際に動いた時点で会話に「hook failed」と出ます)。
  • この5個を1つのフォルダにまとめ、Claudeに「設定がうまく効いていない気がする」と聞くと、Haiku 5.5・Sonnet 5.5・Opus 5.5の9回すべてが5個とも見つけました。/doctorも Sonnet・Opusでは全回見つけましたが、Haiku 5.5では3回中2回がhooksの2つを見落としました。
  • hooksやスキルが効かないときは、起動時の警告と/statusを見て、何も出なければClaudeに設定を調べてもらう、の順が早道です。/doctorは利用状況の点検まで含むので、Opus 5.5では1回あたり中央値で約4.7分かかりました。

こんにちは、Claude Code研究所 技術ブログ担当です。hooksを書いたのに動かない、スキルを置いたのに呼ばれない。Claude Codeを使い込むほど、一度は通る道ですよね…。11月17日のv2.1.327で、/statusが「壊れた設定の一覧」を出すようになりました。そこで今回は設定ミスを1つずつ仕込んだ16通りのフォルダで/statusを開き、出なかったミスはClaude自身に探させてみました(/statusの記録36回、Claudeへの依頼27回)。動かないときにどこを見ればいいかを、結果から整理します。

目次

  1. Claude Codeのhooks・スキルが効かないとき、どこを見ればいい?
  2. v2.1.327の/statusは設定ミスをいくつ見つけた?
  3. 起動時にも/statusにも出なかった5つの設定ミスは?
  4. 出ないミスはClaudeに聞けば見つかる?
  5. 動かないときの確認手順
  6. 検証の方法と限界
  7. まとめ
  8. よくある質問
  9. 参考資料・出典

Claude Codeのhooks・スキルが効かないとき、どこを見ればいい?

まず起動時の表示と/statusを見て、何も出なければClaudeに設定を調べてもらいます。起動時と/statusは費用がかからずすぐ見られますが、今回の実測では拾えない設定ミスが5つありました。その5つは、Claudeに聞くとどのモデルでも見つかりました。

Claude Codeが設定の誤りを知らせる場所は、いくつかに分かれています。

  • 起動時の表示:settings.jsonが壊れている、イベント名や権限ルールの書き方が誤っている、などは起動直後に警告の画面や行が出ます
  • /status:設定画面の「Status」タブです。一番下の「System diagnostics」に設定の警告が出ます。v2.1.327で、壊れたスキルなどのファイルや合わないmatcherも出るようになりました
  • /hooks・/skills・/context:実際に読み込まれたhooksやスキル、CLAUDE.mdの一覧です。公式ドキュメントの「Debug your configuration」は、まず/contextで読み込まれたかを確かめるよう勧めています
  • /doctor:Claudeが手順に沿ってインストールや設定を点検し、直し方を提案する同梱のスキルです。シェルから打つ claude doctor は、インストールと設定を読み取るだけの簡易版です

コマンドの全体像はClaude Codeのコマンド一覧にまとめています。この記事では、それぞれが実際にどの設定ミスを拾うのかを測りました。

v2.1.327の/statusは設定ミスをいくつ見つけた?

v2.1.327の/statusが示したのは、16個中11個でした。1つ前のv2.1.326では5個で、増えた6個はスキル・コマンド・出力スタイル・サブエージェントのファイル、MCPのmatcher、keybindingsの誤りです。

よくある書き間違いを17通り作り、1つのフォルダに1つずつ仕込みました。何も仕込まない正常なフォルダも1つ用意して、余計な警告が出ないことを確かめています。17通りのうち1つ(YAMLが少し崩れたサブエージェント)は、崩れていても読み込まれたので数から外し、16個で集計しました。

仕込んだ設定ミス本当に効いていない?起動時の表示/status v2.1.326/status v2.1.327
settings.jsonのJSONが壊れている(末尾のカンマ)ファイル全体が読まれない警告画面表示表示
hookのイベント名の綴り違い(PreToolUSe)hookが動かない警告画面表示表示
権限ルールの括弧が閉じていないルールが無視される警告画面表示表示
拒否ルールのツール名の綴り違い(Bsh)ルールが効かない警告の行表示表示
Write(パス)の拒否ルールルールが効かない警告の行表示表示
スキルのYAMLが壊れているClaudeから呼べないなしなし表示
サブエージェントにdescriptionが無い読み込まれないなしなし表示
コマンドのYAMLが壊れているfrontmatterが読まれないなしなし表示
出力スタイルのYAMLが壊れているfrontmatterが読まれないなしなし表示
MCPのmatcherに .* が無い(mcp__memory)どのツールにも合わないなしなし表示
keybindings.jsonのJSONが壊れている読まれないなしなし表示
スキルのファイル名がSKILLS.md読み込まれないなしなしなし
スキルのフォルダが .claude/skill/(sが無い)読み込まれないなしなしなし
hookのmatcherが小文字の "bash"hookが一度も動かないなしなしなし
hookが存在しないスクリプトを呼ぶhookが動かないなしなしなし
CLAUDE.mdの @docs/rules.md が存在しないルールが読み込まれないなし未測定なし

※macOS、対話モード。各フォルダで1回ずつ起動して記録。「本当に効いていない?」は、読み込まれたスキルの一覧・Bashを1回動かしたときのhookの実行・/contextのCLAUDE.md一覧で確かめた(権限ルール・MCPのmatcher・出力スタイル・keybindingsは画面の文言と公式ドキュメントで判断)

v2.1.326の/statusに出ていた5個は、もともと起動時にも警告が出るものでした。つまり、起動時に見逃すと気づけなかったミスのうち6個を、新しい/statusが拾ってくれるようになったわけです! たとえばdescriptionの無いサブエージェントには「.claude/agents/reviewer.md not loaded: Missing required "description" field in frontmatter」のように、ファイル名と理由がそのまま出ました。

スキルのYAMLが壊れたケースは、少しややこしい動きでした。/reportはスラッシュコマンドの一覧に残っているのに、Claudeが自分から呼べるスキルの一覧からは消えていたんです。「コマンドとしては見えるのに、頼んでも使ってくれない」という症状になりそうです。こういう中途半端な壊れ方こそ、一覧に出してもらえるのは助かります。

起動時にも/statusにも出なかった5つの設定ミスは?

SKILL.mdのファイル名違い、skillsフォルダの綴り違い、matcherの小文字bash、存在しないhookスクリプト、CLAUDE.mdの読み込み先の欠落の5つです。起動時・/status・/hooks・ターミナルの claude doctor のどれにも警告が出ませんでした。存在しないスクリプトだけは、hookが実行された時点でエラーが表示されます。

いちばん驚いたのは、matcherを小文字の "bash" にしたhookです。/hooksを開くと、ちゃんと「bash · command」として登録されて見えます。それなのに、Bashを動かしてもhookは0回も実行されませんでした…。matcherが英数字だけのときは完全一致で比べるので、大文字のBashとは一致しないためです。公式ドキュメントも「よくある原因」の表でこの例を挙げています。よくある誤りなのに、どの画面も教えてくれないんです。

追加で、matcherをツール名の綴り違い(Bassh)にしたhookも試しましたが、こちらも/statusには出ませんでした。今回の実測で/statusが「合わないmatcher」として示したのは、MCPのツール名に .* を付け忘れた形だけです。

残りの4つも、言われれば単純な誤りです。

  • SKILLS.md・.claude/skill/:スキルは .claude/skills/<名前>/SKILL.md にしか置けません。1文字違うだけで、スキルが「無いもの」として扱われます
  • 存在しないスクリプト:settings.jsonの書き方は正しいので、読み込みの段階ではエラーになりません。ファイルを編集してhookが動いた時点で、会話に「PostToolUse:Edit hook failed」と「No such file or directory」が出ました。気づけるのは実行してからです
  • CLAUDE.mdの @docs/rules.md:/context allで見ると、CLAUDE.md自体は読み込まれていて、rules.mdだけが黙って抜けていました。「ルールを書いたのに守られない」の原因がこれだと、なかなか気づけません、、、

どれも「ファイルの書式は正しいが、指す先や名前が違う」タイプです。書式のチェックでは拾えない種類のミスだと考えると、/statusに出ないのも納得できます。

出ないミスはClaudeに聞けば見つかる?

見つかりました。5つを1つのフォルダにまとめ、「設定がうまく効いていない気がする」とだけ聞くと、Haiku 5.5・Sonnet 5.5・Opus 5.5の9回すべてが5つとも挙げました。/doctorはSonnet・Opusでは全回見つけましたが、Haiku 5.5では3回中2回がhooksの2つを見落としました。

頼み方は3通りです。/doctorを実行する、「スキルとフック、CLAUDE.mdのルールが効いていない。原因を一覧にして」とはっきり頼む、「なんだか設定がうまく効いていない気がします。見てもらえますか?」とあいまいに頼む。どれも「まだ直さないで」と添え、ファイルの読み取りだけを許しました。

頼み方Haiku 5.5Sonnet 5.5Opus 5.5
/doctor1/3(2回はhooks 2つを見落とし。約89秒)3/3(約47秒)3/3(約4.7分)
はっきり頼む3/3(約33秒)3/3(約15秒)3/3(約37秒)
あいまいに頼む3/3(約22秒)3/3(約14秒)3/3(約40秒)

※5つのミスをすべて挙げた回数。かっこ内は1回の所要時間の中央値。v2.1.327、claude -p、読み取りのみ許可、各3回。どの回もファイルは変更しなかった

あいまいな頼み方でも、いちばん小さいHaikuでも全部見つけたのは意外でした! Claudeは.claude/の中身を一通り開き、matcherは大文字小文字を区別する、SKILL.mdでないと読み込まれない、と仕様に照らして指摘していました。中には、hookが書き出すはずのログファイルが無いことを根拠に、このhookは一度も動いていないと裏づけた回もあります。

逆に、/doctorのほうが見落としたのは予想外でした。/doctorはインストールの状態や過去7日の利用状況まで、決まった項目を順に点検します。点検の幅が広いぶん、小さいモデルでは目の前のsettings.jsonへの注意が薄くなったのかもしれません。Opusの/doctorは中央値で約4.7分(速い回で約1.6分)かかったので、「hooksが動かない」と分かっているなら、普通に聞くほうが早く、今回の5つでは取りこぼしもありませんでした。

なお/doctorは、このプロジェクトの外にある個人の設定や利用状況にも触れて提案してきます。チームで使っているリポジトリなら、提案のうちどれを採るかは自分で選んでください。

動かないときの確認手順

起動時の警告を読む、/statusのSystem diagnosticsを見る、/hooks・/skills・/context allで読み込まれたかを確かめる、それでも分からなければClaudeに設定を調べてもらう、の順です。

  1. 起動直後の警告を読む:settings.jsonの壊れ、イベント名や権限ルールの誤りはここで出ます。「Continue」で進むと、その項目は無視されたまま動きます
  2. /statusを開く:v2.1.327以降なら、一番下のSystem diagnosticsに壊れたスキル・サブエージェント・コマンド・出力スタイルやmatcherの誤りが出ます
  3. 読み込まれたかを見る:hooksは/hooks、スキルは/skills、CLAUDE.mdとその読み込み先は/context allで確かめます。一覧に無ければ置き場所か名前の誤りです
  4. 一覧にあるのに動かないなら:hookのmatcherの大文字小文字と、呼び出すスクリプトが本当にあるかを見ます。Claudeに「設定を調べて、効いていない原因を一覧にして。まだ直さないで」と頼むのが早道です

スキルとCLAUDE.mdの使い分けはCLAUDE.mdとSkillsの違いで、名前で動きが変わるスキルの例はverifyスキルの検証記事で紹介しています。

検証の方法と限界

Claude Code v2.1.327と v2.1.326(macOS)で、設定ミスを1つずつ仕込んだフォルダを対話モードで起動し、/statusの画面を記録しました。個人の設定の影響を除くため、空の設定フォルダから起動しています。

  • /statusの記録:擬似端末で対話モードを動かし、起動時の画面と/statusの画面を文字として保存しました。正常なフォルダでは、どちらの版も仕込んだミスに関する警告は0件でした
  • 効いていないことの確認:スキルとサブエージェントはclaude -pの起動情報で読み込まれたかを、hooksはHaiku 5.5にBashを1回だけ動かしてもらいhookが実行されたかを、CLAUDE.mdは/context allで確かめました
  • Claudeに探させる実験:5つのミスを1つのフォルダにまとめ、/doctor・はっきり頼む・あいまいに頼むの3通り × 3モデル × 各3回の27回をclaude -pで実行しました。Claudeの全発言を読み、5つそれぞれを原因として挙げたかを数えています

限界もあります。

  • /doctorは対話モードなら修正の選択肢を出しますが、今回はclaude -pで報告までを見ました
  • /doctorは手順の中でBashのコマンドも使いますが、今回は読み取りのツールとls・cat・findだけを許したので、バージョン確認など一部の点検は行われませんでした
  • Claudeへの依頼は4〜8本を並行して走らせたので、所要時間はおおよその目安です。/doctorの差(Haiku 5.5の1/3)は1モデル・各3回の比較です
  • v2.1.326はnpm版、v2.1.327はネイティブ版で起動しました
  • 権限ルール・MCPのmatcher・出力スタイル・keybindingsが効いていないことは、実行ではなく画面の文言と公式ドキュメントで判断しました
  • 5つのミスを1つのフォルダに同居させたので、ミスが1つだけのときやリポジトリが大きいときの見つけやすさは測っていません
  • /statusの文言や対象はバージョンで変わります。Windows・Linuxでは試していません

反対に、人から受け取ったフォルダのhooksが「動いてしまう」側の注意点もあります。未信頼のフォルダを対話モードで開けば「はい」を選ぶまで止まりますが、信頼済みのフォルダの下に置いた場合や claude -p では、ダイアログなしで動きました。詳しくは受け取ったフォルダのhooksと信頼ダイアログの実測にまとめています。

まとめ

v2.1.327の/statusは、仕込んだ設定ミス16個のうち11個を一覧にしました。名前や置き場所、指す先の誤り5つは起動時にも/statusにも出ませんでしたが、Claudeに設定を調べてもらうと、どのモデルでも見つかりました。

この記事のまとめ

  • v2.1.327から、/statusのSystem diagnosticsに壊れたスキル・サブエージェント・コマンド・出力スタイル、合わないmatcher、keybindingsの誤りが出る
  • /statusが示したのは16個中11個(v2.1.326は5個)。増えた6個は起動時にも出ないミスだった
  • SKILLS.md、.claude/skill/、matcherの小文字bash、存在しないhookスクリプト、CLAUDE.mdの読み込み先の欠落は、起動時にも/statusにも出なかった
  • この5つは、あいまいに頼んでもHaiku・Sonnet・Opusの9回すべてが見つけた。/doctorはHaikuで3回中2回がhooksを見落とした
  • 確認の順番は、起動時の警告 → /status → /hooks・/skills・/context all → Claudeに設定を調べてもらう
Claude Code研究所の研修

記事で紹介した設定を、自社の業務に合わせて組み上げる。

CLAUDE.mdによるプロジェクト規約の設定から、業務に合わせたオリジナルskillsの作成まで、一社ごとにヒアリングした業務を題材に対面で進めます。受講者限定のオリジナルskillsとプロンプトテンプレート集もお渡しします。

  • 一社ごとに業務をヒアリングして設計
  • 実際の業務データでハンズオン
  • スパルタ以上は全額返金保証
  • 受講法人数100社超
30分の無料相談を予約するClaude Code研修の内容を見る

オンライン30分・無料。フォームは入力1分で、2営業日以内にご連絡します。

よくある質問

Claude Codeのhooksが動かない原因で多いものは何ですか?

matcherの書き方が原因のことが多いです。matcherは大文字小文字を区別するので、"bash"と書くとBashツールに一致せず、hookは一度も動きません。当研究所の実測では、この誤りは起動時の表示にも/statusにも/hooksにも警告が出ませんでした。ほかに、イベント名の綴り違い(起動時に警告が出る)、呼び出すスクリプトが存在しない、settings.jsonのJSONが壊れている(ファイル全体が読み込まれない)などがあります。

Claude Codeの/statusで何が分かりますか?

バージョン・モデル・ログイン方法・読み込んだ設定の場所に加えて、一番下の「System diagnostics」に設定の警告が出ます。v2.1.327でここに出る項目が増えました。当研究所の実測では、YAMLが壊れたスキル・コマンド・出力スタイル、descriptionの無いサブエージェント、どのツールにも合わないMCPのmatcher、keybindings.jsonの誤り、誤った権限ルール、壊れたsettings.jsonが表示されました。

/statusにも出ない設定ミスはありますか?

あります。当研究所の実測(v2.1.327)では、SKILL.mdのファイル名違い、.claude/skillsのフォルダ名の綴り違い、matcherを小文字のbashにしたhook、存在しないスクリプトを呼ぶhook、CLAUDE.mdから存在しないファイルを@で読み込む指定の5つは、起動時の表示・/status・/hooksに警告が出ませんでした(存在しないスクリプトは、hookが実行された時点で会話にエラーが出ます)。Claudeに設定を調べてもらうと、Haiku 5.5・Sonnet 5.5・Opus 5.5のいずれでも見つかりました。

/doctorと/statusはどう違いますか?

/statusは設定を機械的に読み込んだ結果を表示する画面で、すぐに開けて費用もかかりません。/doctorはClaudeが手順に沿って点検する同梱のスキルで、インストール・設定・拡張機能・CLAUDE.md・過去7日の利用状況まで調べ、修正案を出して確認を取ってから直します。当研究所の実測では、/doctorは1回あたりSonnet 5.5で約47秒、Opus 5.5で約4.7分(いずれも中央値)かかりました。

スキルが読み込まれているか確かめる方法は?

/skillsでプロジェクト・個人・プラグインのスキルの一覧を、/context allでスキルの説明が文脈に入っているかを確かめられます。スキルは .claude/skills/<名前>/SKILL.md に置く必要があり、ファイル名がSKILLS.mdだったり、フォルダが .claude/skill/ だったりすると読み込まれません。当研究所の実測では、この2つは/statusにも警告が出ませんでした。

参考資料・出典

  1. GitHubClaude Code v2.1.327
    Anthropic / GitHub / 2026-11-17

    /statusに、壊れたエージェント・スキル・コマンド・出力スタイルのファイル、keybindingsの誤り、使えないサンドボックス、無視された権限設定、どれにも合わないhookのmatcherの一覧を追加。検証に使ったバージョン

  2. 公式ドキュメントDebug your configuration
    Anthropic / Claude Code Docs / 2026-11-18

    /context・/doctor・/hooks・/skills・/statusの役割と、よくある原因の表(matcherの小文字bash、スキルはフォルダとSKILL.md、settings.local.jsonの優先など)(確認日)

  3. 公式ドキュメントHooks reference(Matcher patterns)
    Anthropic / Claude Code Docs / 2026-11-18

    英数字と _ - 空白 , | だけのmatcherは完全一致として比べること、MCPのツールに合わせるには mcp__memory__.* のように .* が必要なこと(確認日)

  4. 公式ドキュメントErrors(Configuration warnings)
    Anthropic / Claude Code Docs / 2026-11-18

    起動時のバナーの下に出る権限ルールの警告(matches no tool・Write(path) never matches)、Malformed Tool(content) rule(確認日)

  5. 公式ドキュメントExtend Claude with skills(Check your setup with /doctor)
    Anthropic / Claude Code Docs / 2026-11-18

    /doctorは同梱スキルで、結果を先に報告し、変更の前に確認を取ること。点検の範囲(インストール・設定・拡張機能・CLAUDE.md・利用状況)(確認日)

この記事をシェアするXでシェアnoteをフォロー
記事一覧に戻るトップページへ

Claude Codeを実務で活用したい方へ

一社ごとにカスタマイズする対面のClaude Code研修は「スパルタClaude Code塾」。経営者・士業・エンジニア・マーケター・営業職まで、業務をヒアリングしてカリキュラムを設計します。まずは30分の無料相談で、自動化プランと費用対効果をご確認ください。

最新の解説記事

関連記事