Agent SDK Skillsが検出されないときの切り分け手順

Claude Agent SDK(TypeScript)で.claude/skills/を用意しsettingSourcesも渡したのに、Claudeが「Skillsが1つもない」と答えるケースがあります。設定を何度見直しても原因が分からないときは、バージョン・settingSources・cwd・許可リストの4点を順番に切り分けると絞り込めます。Python版で同じ症状が出た場合の注意点は、記事後半のよくある質問にまとめました。

「設定は合っている」のにSkillsが検出されない現象とは

これはTypeScript Agent SDK 0.1.22で実際に報告された既知の不具合です。報告者の構成はcwdをプロジェクトルートに向け、settingSources: ['project']もオプションとして明示していました。.claude/skills/todo-task-management/SKILL.mdもAgent Skills仕様どおりに用意されています。

報告された動作は3点にまとめられます。

• Claudeに「利用可能なSkillsを一覧して」と聞くと、<available_skills>セクションが空だと答える
• Skill toolは16個中15番目のツールとして存在しているが、todo-task-managementを呼び出すとUnknown skill: todo-task-managementが返る
• BashやReadツールを使えば同じSKILL.mdをClaude自身が手動で見つけて読むことはできる

3つ目の挙動から、ファイルの配置や中身自体は正しいことが分かります。問題は「ファイルが読めるか」ではなく「起動時にSkillとして登録されるか」の部分に絞り込めます。同じディレクトリ構成のままClaude Code CLI 2.0.22を直接使うとSkillsは正常に検出されており、症状はSDK経由の呼び出しに限られていました。

この報告(SDK 0.1.22、実行環境はBun 1.2.23とNode.js v23.5.0)には、Anthropic側から「影響を受けるのはプロジェクトレベルのSkillsだけで、~/.claude/skillsに置いたSkillは動く」とコメントがあり、2日後の0.1.25で修正されました。同じ症状に遭遇したら、まずSDK経由かCLI直接かで切り分けると原因の当たりが早くつきます。

エラー文字列で入口を決める

受け取ったエラー文字列によって、次にどの診断から当たるかが変わります。

診断1: SDKのバージョンを確認する

上記の不具合は、プロジェクトレベルのSkillsが'project'設定ソースを指定していても読み込まれないというSDK側のバグでした。TypeScript Agent SDKの公式CHANGELOGには、0.1.25で「project-level skills were not loading when 'project' settings source was specified」という記述で修正が記録されています。

バージョンによって、Skillsまわりの前提が変わっている点にも注意が必要です。CHANGELOGから拾った節目を年表にまとめます。

package.jsonの依存バージョンを確認し、0.1.25より古ければまず更新します。

npm ls @anthropic-ai/claude-agent-sdk
npm install @anthropic-ai/claude-agent-sdk@latest

バージョンを上げても症状が変わらない場合は、原因はこの既知のバグではなく設定側にあります。次の診断へ進みます。

診断2: settingSourcesがuserとprojectを含んでいるか

settingSources(Pythonはsetting_sources)は、Skillsをどのファイルシステム階層から発見するかを決めるオプションです。現行の公式ドキュメントでは、省略時はuser / project / localのすべてが読み込まれ、配列を明示すると挙げなかったソースは除外されると説明されています。Skillsのページでは、既定のquery()オプションではuserとprojectが読み込まれるとも書かれています。

上の年表のとおり、0.1.0のCHANGELOGは「ファイルシステムの設定を既定では読まない」と記しています。古いバージョンのまま省略してSkillsが読まれないときは、既定値の違いが原因の可能性があります。バージョンが古い場合は診断1で更新してから、この点を見直します。

// Skillsが読み込まれない: settingSourcesがuser/projectを含まない
const optionsWithoutSkills = {
  settingSources: [],
  skills: "all"
};
 
// Skillsが読み込まれる
const optionsWithSkills = {
  settingSources: ["user", "project"],
  skills: "all"
};

'project'だけを渡して'user'を渡さない設定も、ホームディレクトリのSkillsだけを取りこぼす形で見落とされがちです。skillsオプションとsettingSourcesの役割分担はAgent SDK Skillsの使い方に詳しくまとめています。

SDKは内部でCLIに--setting-sourcesを渡しています。冒頭の報告者がstderrに出したCLIコマンドにも--setting-sources projectがありました。Claude Code CLIでも同じフラグが使えます。Claude Code v2.1.289でclaude --helpを実行すると、次のように表示されます。

claude --version
claude --help | grep -A1 -e "--setting-sources"

2.1.289 (Claude Code)
  --setting-sources <sources>           Comma-separated list of setting sources
                                        to load (user, project, local).

SDKのsettingSourcesの値は、この3種類(user / project / local)から選ぶ形になっています。

診断3: cwdと.claude/skills/の位置関係

SDKはcwdで指定したディレクトリと、そこからリポジトリルートまでの各親ディレクトリにある.claude/skills/を探します。cwdが対象ディレクトリの外を指していると、設定自体は正しくてもSkillsは見つかりません。

たとえばリポジトリの中にagent/というサブディレクトリを作り、その下に.claude/skills/を置く構成では、cwdをagent/まで進めておく必要があります。この.claude/skills/はcwdと同じリポジトリ内にある必要があり、別リポジトリのディレクトリを親に持ってきても対象になりません。

import path from "node:path";
 
const options = {
  cwd: path.join(process.cwd(), "agent"), // .claude/skills/ はこの下
  settingSources: ["project"]
};

additionalDirectories(Pythonはadd_dirs)で追加したディレクトリの.claude/skills/も、プロジェクトソースの一部としてまとめて探索対象になります。モノレポで複数の作業ディレクトリをまたぐ構成なら、目的のSkillが置かれたディレクトリをadditionalDirectoriesに加えているかも合わせて確認します。

実際にファイルが期待した場所にあるかは、Agent SDKを起動する前にシェルで確認できます。

ls .claude/skills/*/SKILL.md
ls ~/.claude/skills/*/SKILL.md

診断4: skillsオプションと許可リスト

skillsオプションに配列を渡している場合、その中に対象のSkill名が入っているかを確認します。名前が抜けていると、Skill toolはSkill <name> is not in this session's skills allowlistという発見済みだが呼び出し不可を示すエラーを返します。許可リストの外にあるSkillは、モデルから見えなくなる点も公式ドキュメントに書かれています。skillsオプションを省略すれば、発見済みのSkillsはすべて許可された状態になります。

許可リストを経由せずに動作確認したいときは、プロンプトの中に/<skill名>と直接書いて呼び出せます。この呼び出しはskillsオプションに左右されず、一覧に無い名前でもユーザー起動のSkillなら実行されます。

呼び出した名前がコマンドにもSkillにも一致しない場合は、クエリがエラーで終わる代わりに、Claude Codeがそのプロンプトを通常のメッセージとしてClaudeに送ります。コマンドが実行されなかったという注記が付き、モデルの1ターンを消費して返答が返ります。v2.1.274より前は、Unknown command: /<name>が結果として返り、モデルのターンは使いませんでした。名前のつづりを間違えても失敗に見えにくいため、initメッセージのslash_commandsに名前があるかを先に見ると確実です。

skillsオプションを設定すると、SDKはSkill toolをallowedToolsへ自動的に追加します。一方、toolsに明示的なリストを渡している場合は、そのリストに"Skill"を入れておかないとClaudeはSkillを呼び出せません。allowedToolsに"Skill"を足す書き方は、年表のとおり0.2.133で非推奨になっています。

もう1つ別系統の失敗もあります。TypeScript Agent SDK 0.3.221以降(Pythonは0.2.129以降)では、skills配列に空文字・括弧やカンマを含む名前・前後に空白のある名前・*や:*のようなワイルドカードを渡すと、セッションが始まる前にquery()自体がエラーで止まります。これは発見や許可の失敗ではなく、名前の形式チェックによる拒否です。たとえばskills: ["docs:*"]は次のエラーになります。

Invalid skill name "docs:*": wildcard-suffix names are not allowed; list each skill by its exact name.

エラーメッセージに違反したルールがそのまま書かれているため、skills配列の中身を1つずつ見直せば直せます。すべてを許可したいときは、ワイルドカードの代わりにskills: "all"を使います。

Skillがinitメッセージのskills配列にも載っていて許可リストにも入っているのに、Claudeが自律的に呼び出してくれない場合は、許可の問題ではなくdescriptionの書き方が原因のことがあります。公式のTroubleshootingは、descriptionを具体的にし関連キーワードを含めるよう挙げています。「発見されない」と「発見済みだが使われない」はここで切り分けます。

それでも直らないときの3つの手がかり

よくある質問

Python版のAgent SDK(claude-agent-sdk-python)でも同じバグはありますか

Python SDKのCHANGELOGには、TypeScriptの0.1.25に当たる「project-level skillsが読み込まれない」という修正項目がありません。0.1.22の不具合はTypeScript SDK固有の報告で、Python側で同じ症状が出ている場合は、この既知のバグではなくsetting_sourcesやcwdの設定側を先に疑うのが妥当です。

settingSourcesを何も指定していないのにSkillsが検出されません

現行のSDKではsettingSourcesを省略するとuser / project / localのすべてが読み込まれるため、この場合はバージョンかcwdが原因である可能性が高くなります。診断1と診断3を先に確認します。

4点すべて確認しても直らない場合はどうすればいいですか

最新バージョンでsettingSources / cwd / skillsオプション / toolsのすべてが噛み合っているのに検出されないなら、新しい既知の不具合の可能性があります。冒頭の0.1.22の報告は、再現手順とバージョン情報を添えたissueに2日後の修正版で応えた例です。再現できる最小構成とnpm ls @anthropic-ai/claude-agent-sdkの出力を添えて、TypeScript SDKならclaude-agent-sdk-typescriptリポジトリのissueに報告できます。

まとめ

Skillsが検出されない原因は、「バージョンのバグ」「発見の設定」「呼び出しの許可」の3層のどれかにあります。0.1.25より古いSDKなら更新が最初の一手で、新しければsettingSources、cwd、skillsの許可リストの順に見ます。エラー文字列がUnknown skillかallowlistかで、最初に疑う層は決まります。

Skillファイル自体の書き方やSKILL.mdのfrontmatter設計に不安がある場合は、Claude Code Skills完全ガイドも合わせて確認できます。Agent SDKのquery()オプション全体の基礎はClaude Agent SDK入門、サンドボックス関連の設定を疑う場合はAgent SDKのsandbox設定にあります。