Claudeのスキルがサブエージェントで動かない?4段階で原因を確認
Claude Codeのスキルがサブエージェントで使えない原因を、検出・プリロード・呼び出し・実行に分けて確認。設定例、失敗条件、診断用サンプルを紹介します。
Claudeのスキルがメインの会話では使えるのに、カスタムサブエージェントでは使えない場合は、検出、プリロード、呼び出し、実行を分けて確認します。ツール一覧に Skill を追加しても、指示はプリロードされません。skills: に名前を追加しても、その指示の実行に必要なツールがすべて許可されるわけではありません。
現在のClaude Codeのドキュメントでは、サブエージェントでの起動時プリロードと、実行中の動的なスキル呼び出しの両方が説明されています。「サブエージェントはスキルを一切呼び出せない」という古い説明は、当時のバージョンに関する情報として扱ってください。skills フィールド(英語)は起動時に指示を読み込み、Skill ツールは実行中に別の経路でスキルを呼び出します。
この記事の対象は、ローカルのClaude Codeで使うカスタムエージェントとプロジェクトスキルです。2026年11月18日に公式ドキュメントと照合しました。ダウンロードできるサンプルは、編集部で作成した診断用のテストデータです。ファイルと期待結果のチェッカーはローカルで検証しましたが、モデルの推論実行や成功率の測定は行っていません。以下の期待応答は判定基準であり、Claudeの実際の出力ではありません。
設定を変える前に、失敗する段階を特定する
| 症状 | 最初に確認する段階 | 手掛かり |
|---|---|---|
| 親セッションでもスキルを使えない | 検出または呼び出し制御 | 実際に認識されたスキル名、ファイルの場所、frontmatter、ポリシー |
| 親では使えるが、カスタムエージェントが指示に従わない | プリロードまたは動的呼び出し | 実際に選ばれたエージェント定義、プリロードの警告、Skill呼び出し |
| Skill呼び出しが拒否される | ツールへのアクセスと権限 | 拒否されたツール名と該当するルール |
| 指示はあるが、スクリプトやファイル操作が失敗する | 実行 | ファイルパス、作業ディレクトリ、拒否された操作、スクリプトのエラー |
| あるフォルダでは動き、別のフォルダでは動かない | スコープまたは名前の衝突 | 起動ディレクトリ、リポジトリルート、読み込まれたスキルの場所 |
失敗する入力を固定し、1回につき1項目だけ変えます。各パターンでは親セッションとサブエージェントを両方新しくし、前の結果が次の委任に混ざらないようにします。マーカーと期待する回答を、委任するタスクや自動読込されるプロジェクト指示に入れないでください。ファイル移動、ツールの許可、説明文の書き換えを同時に行うと、どの変更が効いたのか分からなくなります。概念全体はHooks・Subagents・Skillsの解説を参照してください。この記事では故障の切り分けに集中します。
1. 読み込みを確認できる小さなスキルを作る
使い捨てのローカルディレクトリを用意します。Claude Codeがインストールされていて、利用を許可されたモデル接続がすでにあることが前提です。推論を実行する前に、claude --version と使用するモデル、プロバイダーを記録してください。モデルへのリクエストは通常の利用枠やAPI残高を消費する場合があります。サンプルをダウンロードするだけではリクエストは実行されません。
診断用プロジェクトをダウンロードするか、以下のファイルを作成します。ZIPには同じファイル、プロンプト、結果チェッカー、説明が入っています。新しいフォルダに展開して内容を確認し、そのフォルダからClaude Codeを起動します。サンプルにフック、ネットワーク呼び出し、認証情報ファイルは含まれていません。コードと同梱の説明は英語のままです。
skill-diagnostic/
├── .claude/
│ ├── agents/
│ │ ├── audit-preloaded.md
│ │ └── audit-dynamic.md
│ └── skills/
│ └── sample-audit/
│ └── SKILL.md
├── sample.csv
└── check_result.py
次の内容を .claude/skills/sample-audit/SKILL.md に保存します。マーカーは、スキルの出力形式の指示が反映されたかを見るためのものです。セキュリティ機構でも、指示がどの経路で届いたかを証明する仕組みでもありません。
---
name: sample-audit
description: Audit the synthetic sample.csv fixture and report missing amounts.
---
Read sample.csv in the working directory. Do not change any files.
Return exactly four lines, with no Markdown fences:
SKILL_MARKER=sample-audit-v1
ROWS=<number of data rows, excluding the header>
MISSING_AMOUNT_IDS=<comma-separated IDs, or none>
TOTAL_KNOWN_AMOUNT=<sum of nonempty amounts, two decimal places>
Keep IDs as text. A blank amount is missing, not zero.
入力の sample.csv は、意図的に小さくしてあります。
id,amount
0007,12.50
0008,
0009,7.50
期待する回答の4行を委任プロンプトに貼らないでください。それではスキルを使わずに答えを再現できてしまいます。スキルの指示と入力ファイルを組み合わせなければ回答できない状態にすることで、この比較に意味が生まれます。
2. カスタムエージェントでプリロードを確認する
.claude/agents/audit-preloaded.md を保存します。
---
name: audit-preloaded
description: Audit sample.csv using the preloaded sample-audit instructions.
tools: Read
skills:
- sample-audit
---
Follow the preloaded audit instructions on sample.csv.
Do not read SKILL.md yourself. If the audit instructions are absent,
report PRELOAD_MISSING rather than inventing a format.
現在、プリロードされるのはリストの先頭から重複を除いて32個の名前までです。読み込まれるのはスキル本文であり、フォルダ内の補助ファイルすべてではありません。このサンプルはスキルが1つだけなので、これらの制限は問題になりません。
ファイルを準備したら新しいセッションを開始し、次のように依頼します。
Use the audit-preloaded subagent to audit sample.csv.
Return its result verbatim. Do not perform the audit in the parent.
実行履歴で audit-preloaded が選ばれたことを確認します。このエージェントには意図的に Read だけを与えています。プリロードの確認では、Skill ツールの呼び出しがなくても正常です。SKILL.md を直接読んだ場合や、親が代わりに作業した場合は、この比較は成立しません。別の方法で答えを取得できたのであって、起動時のプリロード成功を示したことにはならないためです。
期待する応答は次のとおりです。
SKILL_MARKER=sample-audit-v1
ROWS=3
MISSING_AMOUNT_IDS=0008
TOTAL_KNOWN_AMOUNT=20.00
そのエージェントの応答だけを result.txt にコピーし、python3 check_result.py result.txt を実行します。チェッカーが確認するのはサンプルの4行です。読み込み経路は証明できないため、実行履歴とデバッグ情報も確認してください。
失敗側の比較として、エージェントの skills: リストにある sample-audit を、存在しない sample-audit-missing などの名前に置き換え、新しいセッションとエージェントで実行します。期待する診断結果は PRELOAD_MISSING ですが、応答の表現までは保証されません。現在のドキュメントでは、存在しない、または無効なプリロード項目はスキップされ、デバッグログに警告が残ると説明されています。次へ進む前に名前を元へ戻します。それでも通常の結果が返る場合は、親が指示を渡していないか、別のエージェントが選ばれていないか、別ファイルにマーカーが含まれていないかを確認します。

この記事のために取得した公式ドキュメントの画面です。推論の成功結果を撮影したものではありません。
3. プリロードなしの動的呼び出しと比較する
.claude/agents/audit-dynamic.md を保存します。
---
name: audit-dynamic
description: Audit sample.csv by invoking the sample-audit skill.
tools: Read, Skill
---
First invoke the sample-audit skill using the Skill tool.
Then follow it on sample.csv. Do not read SKILL.md directly.
If the skill cannot be invoked, report INVOCATION_FAILED and the reason.
この定義には skills: フィールドがありません。親に audit-dynamic への委任と、その応答をそのまま返すよう依頼します。動的経路の確認に合格するには、エージェントの実行履歴に sample-audit への Skill 呼び出しがあり、その後に同じ4行の結果が出る必要があります。マーカーだけでは不十分です。
次に、ほかの条件を固定したまま、このエージェントの tools: リストから Skill を削除します。定義が要求するツールを利用できなくなるため、呼び出しの失敗が期待されます。確認後は Skill を元へ戻してください。この失敗側の確認中に skills: を追加すると、別のプリロード経路が入ってしまいます。
この明示的なテストで分かるのは、呼び出しが可能かどうかです。Claudeが自発的にスキルを選ぶかどうかは分かりません。自動選択を別に確認するには、tools: Read, Skill は残しつつ、sample-audit を明示的に呼ぶ指示を削除した新しいエージェント定義を作ります。説明も Audit local CSV files のような中立的なものにします。スキル名を出さずに通常の監査タスクを渡し、Skill 呼び出しの有無を確認してください。明示的な呼び出しは成功し、この自動選択の確認だけが失敗するなら、スキルの説明とタスクの一致を調べます。明示的な呼び出しの成功は、自動選択の証明にはなりません。
4. 呼び出し制御と実行権限を確認する
使い捨てのサンプルで次の変更を1つずつ試し、その都度元の状態へ戻します。
| 変更する項目 | 確認したい違い | 対処 |
|---|---|---|
スキルに disable-model-invocation: true を追加 | モデルによる動的呼び出しにもプリロードにも使われないはず | 意図的に手動にしている処理では設定を維持し、この実験にはモデルが呼べる適切なスキルを使う |
代わりに user-invocable: false を追加 | 手動コマンドは非表示になるが、モデルによる呼び出し自体は禁止しない | メニューにないことと、モデルが使えないことを混同しない |
動的エージェントの明示的なツール一覧から Skill を削除 | 動的経路が使えなくなる。プリロード側のエージェントとは別の話 | 動的呼び出しが必要な場所でのみ Skill を公開する |
| 入力ファイルへのアクセスを外す | 指示が読み込まれていても、データの読み取りで失敗する | 対象のファイル・ツールの権限または配置を修正する |
2つの呼び出しフラグは目的が異なります。スキルを呼び出せる主体の制御(英語)を参照してください。デプロイや破壊的操作を意図的に手動実行にしているスキルから、自動で使わせたいという理由だけでその設定を外さないでください。
ツールが一覧にあることと、そのすべての操作が許可されることも別です。Claude Codeの権限ルール(英語)で、拒否ルール、管理ポリシー、該当スキル名へのルールを確認します。スキルの allowed-tools は、エージェントのツール集合から除外されたツールを復活させたり、拒否ルールを無効にしたりできません。Pythonスクリプトを呼ぶ実際のスキルなら、指示の読み込みを確認した後で Bash とスクリプトのパスを調べます。このサンプルの監査には Read しか必要ないので、その変数を排除できます。
診断のために bypassPermissions を使わないでください。調べたい条件そのものが変わり、3行を読み取るだけの例には不要です。
5. ディレクトリと名前の問題を切り分ける
スキルをグローバルな個人用ディレクトリへ移す前に、プロジェクトを確認します。
pwd
claude --version
ls -l .claude/skills/sample-audit/SKILL.md
ls -l .claude/agents/audit-preloaded.md
ls -l .claude/agents/audit-dynamic.md
エージェントファイルとスキルファイルは、役割も置き場所も違います。.claude/agents/ にあるファイルは、本文に「skill」と書いてあるだけではスキルになりません。このサンプルではフォルダ名、frontmatterの名前、プリロード項目をそろえます。skills: リストにファイルパスや /sample-audit を入れないでください。
モノレポの packages/web/.claude/skills/ に置いたスキルは、ルートに置いたスキルと同じではありません。入れ子になったスキルの検出は、Claudeがどの領域にアクセスするかに依存します。まずサンプルをプロジェクトルートに置いて不確定要素を取り除き、その後で実際のサブディレクトリを再導入します。想定と異なる指示が実行される場合は、個人用とプロジェクト用の名前の衝突、プラグインの名前空間を確認します。どの読み込み元が優先されるかは、公式のスキルの検出・命名ルール(英語)にあります。すべてのスキルをグローバルへ移すと、元の問題を直す代わりに新しい衝突を起こすことがあります。
ファイルが ../shared/.claude/skills/sample-audit/SKILL.md にあるなら、claude --add-dir ../shared で起動し、新しいセッションにスキルが表示されるか確認します。permissions.additionalDirectories だけではファイルへのアクセスは許可されても、そのフォルダのスキルは読み込まれません。入れ子のスキルは、そのスキルを置いたサブディレクトリから開始するか、対応バージョンで /add-dir を使い、名前を指定した呼び出しを再実行します。バグ報告には開始ディレクトリと --add-dir の引数を記録してください。補助ファイルの相対パスがスキルディレクトリ基準なのか作業ディレクトリ基準なのかも確認します。この例の sample.csv は明示的に後者です。
セッション開始後に最上位のskillsディレクトリを作った場合は、スキルが見つからない原因を調べる前にセッションを再起動します。このサンプルでは、ファイルを作成してから新規セッションを始める手順にしています。
6. 最小構成でも失敗する場合に残す証拠
現在のCLIリファレンス(英語)に従い、新しいローカルセッションで非公開のデバッグファイルを使います。
claude --debug-file ./claude-skill-debug.log
1つのパターンだけを再現します。選択されたエージェント、実際に認識されたスキル名、スキル不在・無効の警告、動的経路なら Skill 呼び出し、拒否された Read や Bash の操作を確認してください。ログにはパス、プロンプト、ほかのセッション情報が含まれることがあります。共有前に内容を確認し、認証情報や無関係な会話履歴を公開しないでください。
報告には次のテンプレートを使えます。バージョン、OS、モデルとプロバイダー、作業場所、定義、試した経路、期待値と実際の結果を記録します。
Claude Code version / OS:
Model / provider (no secrets):
Working directory / repository root:
Agent name and definition:
Skill name, path and frontmatter:
Route: preload OR dynamic invocation
Exact prompt and synthetic input:
Expected result / actual result:
Selected-agent evidence / relevant tool call or warning:
Single change made / result after restoring baseline:
起動、認証、TLS、レート制限の失敗は、この監査でスキルの挙動を確認するより前の段階で起こります。該当する症状はClaude CodeのTLSエラー対処やレート制限の対処で切り分けてください。拒否されたモデルリクエストを繰り返してもプリロード名の誤字は直らず、スキルを編集しても証明書エラーは直りません。
context: fork、SDK、Ofoxの場合は?
context: fork を持つスキルは、そのスキルのタスクを実行するためにエージェントを起動します。skills: を持つエージェントは、エージェント自身の指示から開始し、追加のスキル内容を受け取ります。ワークフローに合う方向を選んでください。この2つのfrontmatterは相互に置き換えられるものではありません。サブエージェントでスキルを実行する方法(英語)を参照できます。
ここで使うカスタムエージェントが、親と話した内容をすべて引き継ぐと考えないでください。必要な入力は明示的に渡します。Claude Codeには別のfork動作についての説明もあるので、このサンプルの分離の仕方を、すべてのエージェントや会話のforkへ一般化しないでください。
Claude Agent SDKから起動する場合は、SDKのスキルドキュメント(英語)で、ファイルシステムの設定とSkillツールの設定を別途確認します。ターミナルのセッションがローカルスキルを検出できても、別ディレクトリから開始したSDKプロセスが同じ設定を読む証明にはなりません。
すでにOfox経由でClaude Codeを接続している場合、接続設定はClaude Code連携ドキュメント、APIの失敗はエラー処理リファレンスを参照してください。プロバイダーへの接続とローカルスキルの読み込みは別々に確認します。APIエンドポイントの変更だけでClaudeのアカウント機能が使えるようになったり、ローカルのエージェント定義が直ったりするわけではありません。
完了の基準は具体的に置きます。意図したエージェントが起動し、意図した読み込み経路が確認でき、4行の出力がサンプルと一致し、対応する失敗側の条件では異なる動作になることです。その記録を残してから、実際のワークフローを元に戻してください。


