Agent SDK Skillsが検出されないときの切り分け手順
設定を確認したはずのAgent SDKでSkillsが検出されないとき、バージョン・settingSources・cwd・許可リストの4点を順に切り分ける手順です。
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経由の呼び出しに限定されることも確認されています。
Unknown skillエラーは、許可リストで弾かれたときに出るis not in this session's skills allowlistとは別のメッセージです。後者はSkillが発見された上で呼び出しを拒否されている状態、前者はそもそも発見されていない状態を示します。まず自分が受け取っているエラー文字列を確認すると、以降のどの診断ステップから当たるべきかが決まります。
この報告(SDK 0.1.22、実行環境はBun 1.2.23とNode.js v23.5.0)には、翌日にはユーザーレベルの~/.claude/skillsに置けば動くという回避策が示され、2日後の0.1.25で修正されています。実際にはCLI単体では再現せず、SDKが内部でCLIを起動する経路にだけ症状が出ていました。同じ症状に遭遇したら、まず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検出の状態 |
|---|---|
| 0.1.22 | Skills検出の状態プロジェクトレベルのSkillsが検出されない既知のバグを含む |
| 0.1.25 | Skills検出の状態修正版。SDKSystemMessageにskills配列が追加された |
| 0.3.221以降 | Skills検出の状態skills配列の名前検証が追加され、不正な名前はquery()開始前にエラーで弾かれる |
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が読み込まれない: settingSourcesがuser/projectを含まない
const optionsWithoutSkills = {
settingSources: [],
skills: "all"
};
// Skillsが読み込まれる
const optionsWithSkills = {
settingSources: ["user", "project"],
skills: "all"
};'project'だけを渡して'user'を渡さない設定も、ホームディレクトリのSkillsだけを取りこぼす形で見落とされがちです。skillsオプションとsettingSourcesの役割分担はAgent SDK Skillsの使い方に詳しくまとめています。
診断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はすべて許可された状態になります。
toolsやallowedTools(Pythonはallowed_tools)を明示的なリストで渡している場合は、リストに"Skill"が入っているかも確認します。skillsオプションを設定するとSDKはSkillツールをallowedToolsへ自動的に追加しますが、ツールリスト自体を上書きするような書き方をしていると、この自動追加が効かずSkill toolそのものが使えない状態になります。
もう1つ別系統の失敗もあります。TypeScript Agent SDK 0.3.221以降(Pythonは0.2.129以降)では、skills配列に空文字・括弧やカンマを含む名前・前後に空白のある名前・*や:*のようなワイルドカードを渡すと、セッションが始まる前にquery()自体がエラーで止まります。これは発見や許可の失敗ではなく、名前の形式チェックによる拒否です。エラーメッセージに違反したルールがそのまま書かれているため、skills配列の中身を1つずつ見直せば直せます。
Skillがinitメッセージのskills配列にも載っていて許可リストにも入っているのに、Claudeが自律的に呼び出してくれない場合は、許可の問題ではなくdescriptionの書き方が原因のことがあります。公式のTroubleshootingは、descriptionを具体的にし関連キーワードを含めるよう挙げています。「発見されない」と「発見済みだが使われない」はここで切り分けます。
それでも直らないときに見る3点
initメッセージのskills配列を見る: セッション開始直後に届くsubtype: "init"のsystemメッセージには、descriptionまたはwhen_to_useを持つuser-invocableなSkillsの一覧が、Claude Code同梱のbundled skillsも含めて入ります。自分のSkill名がここに無ければ、許可リストより前の発見の段階でつまずいています。ただしuser-invocable: falseを設定したSkillは、正常に読み込まれていてもこの配列には載らないので、その場合はこの手がかりだけで判定しません。
userレベルのSkillsだけ試す: プロジェクトレベルのSkillsが検出されない場合でも、~/.claude/skills/に置いたSkillは動くことがあります。同じSKILL.mdをホームディレクトリ側にも置いてsettingSources: ["user"]だけで試すと、問題がプロジェクト側の設定に限定されているか切り分けられます。
同じ構成でCLIを直接動かす: cwdをSDKと同じディレクトリにしてClaude Code CLIを直接起動し、CLI側ではSkillsが検出されるかを確認します。CLIでは動くのにSDK経由でだけ動かない場合、原因はSDKのオプション設定かバージョンに絞られます。
よくある質問
Python版のAgent SDK(claude-agent-sdk-python)でも同じバグはありますか
Python SDKの公式CHANGELOGを確認した限り、「project-level skillsが読み込まれない」という同種の修正記録は見当たりません。0.1.22の不具合はTypeScript SDK固有の報告で、Python側で同じ症状が出ている場合は、この既知のバグではなくsetting_sourcesやcwdの設定側を先に疑うのが妥当です。
settingSourcesを何も指定していないのにSkillsが検出されません
settingSourcesを省略した場合はデフォルトでuser / project / localのすべてが読み込まれるため、この場合はバージョンかcwdが原因である可能性が高くなります。診断1と診断3を先に確認します。
4点すべて確認しても直らない場合はどうすればいいですか
最新バージョンでsettingSources / cwd / skillsオプション / allowedToolsのすべてが噛み合っているのに検出されないなら、新しい既知の不具合の可能性があります。今回取り上げた0.1.22の報告も、再現手順とバージョン情報を添えてissueを立てたところ翌日には回避策のコメントが付き、2日後には修正版がリリースされています。再現できる最小構成とnpm ls @anthropic-ai/claude-agent-sdkの出力を添えて、TypeScript SDKならclaude-agent-sdk-typescriptリポジトリのissueに報告すると対応が早いようです。
まとめ
Agent SDKでSkillsが「設定は合っているのに」検出されないときは、まずSDKのバージョンを確認します。0.1.22には既知のバグがあり0.1.25で修正済みなので、それより古ければ更新が最初の一手です。バージョンが新しければsettingSourcesがuser / projectを含むか、cwdが.claude/skills/を含むディレクトリを指しているか、skillsオプションの許可リストに名前が入っているかの順で切り分けます。
Skillファイル自体の書き方やSKILL.mdのfrontmatter設計に不安がある場合は、Claude Code Skills完全ガイドを先に確認しておくと切り分けの母数が減ります。Agent SDKのquery()オプション全体の基礎からやり直したい場合はClaude Agent SDK入門、サンドボックス関連の設定を疑う場合はAgent SDKのsandbox設定も合わせて確認できます。
原因の層が「バージョンのバグ」「発見の設定」「呼び出しの許可」の3つに分かれていることさえ意識しておけば、次に似た症状に当たったときも同じ順番でつぶせます。