Claude Codeのスキルが発動しない・一覧に出ないときの確認【Claude Codeスキル入門第9回】

「スキルのフォルダーを作ったのに、一覧に出てきません。何から確かめればいいですか」
「/名前 で呼べば動くのに、普通に頼んでも発動しません。これは description の問題ですか」

第8回までで、スキルの作り方、検証スキルの作例、Git での共有まで来ました。ところが、実際に使い始めると、スキルが期待どおりに動かない場面が必ず出ます。そのとき、闇雲に SKILL.md を書き直すと、原因と違う所を直して時間を失います。症状から原因を絞る手順を、手元に置いておくと役に立ちます。

第9回では、症状別のチェックリスト、確かめ方（一覧を聞く・/skills・/名前・claude --debug・バリデーター）、Windows と Linux の注意を扱い、あわせて連載全体の早見表と持ち帰りの3点で締めます（残りの第10〜12回は演習です）。冒頭の1つ目の相談は「症状別チェックリスト」、2つ目は「確かめ方」の /名前 の項目で答えます。数値・仕様は2026年10月時点です。

症状別チェックリスト
確かめ方
Windows と Linux の注意
連載の早見表
持ち帰りの3点
1. 次に学ぶなら
考えてみよう
まとめ
連載「Claude Codeスキル入門」全12回

症状別チェックリスト

症状	まず見ること	直し方
発動しない	一覧に出るか。`/名前` で呼べるか。description に言い回しがあるか	言い回しを足す。YAML が壊れていると description が使われない
一覧に出ない	`SKILL.md` が名前付きフォルダーの中か。先頭の `---` が1行目か	置き場所・ファイル名・YAML を直し、新しいセッションで聞き直す
別のスキルが動く	description が似ていないか	対象と場面で区別する（第3回の「似たスキルを分ける・名前を具体的に」）
隠れている	同じ名前が優先順位の高い場所にないか	名前を変える（第8回の「優先順位と名前の付け方」）
スクリプトが失敗	実行権限・パス・依存	`bash` で呼ぶか `chmod +x`。依存は SKILL.md に書く
途中で守られない	会話が圧縮（compact）されていないか	大事な指示を SKILL.md の先頭へ。必ず守らせるならフック

表の根拠を補います。

YAML が壊れているとき：公式は、frontmatter は先頭の --- がファイルの1行目にあるときだけ読む、と書いています。そうでないと、--- の行を含めたファイル全体を、スキルの本文として扱います。--- の間の YAML が解釈できないときは、スキルは「項目が何も設定されていない」状態で読み込まれます。つまり、/名前 では呼べるのに、Claude は description と照らし合わせられません（公式の「Skill not triggering」の節）
一覧に出ないとき：SKILL.md は、スキルのルートではなく名前付きのフォルダーの中に置き、ファイル名は正確に SKILL.md（SKILL は大文字、md は小文字）にします。これは Academy のレッスン6（Troubleshooting skills）の言い方です。公式の本文には、「名前付きフォルダーの中」という要件の直接の記述は見つかりませんでした
セッション中に直したとき：公式は、~/.claude/skills/・プロジェクトの .claude/skills/ の中でスキルを足す・編集する・消すと、Claude Code は再起動せずに同じセッションで変更を拾う、と書きます。ただし、この変更の検知は SKILL.md の本文が対象です。セッションの開始時に無かったトップレベルの skills フォルダーを新しく作ったときは /reload-skills を実行します。/reload-skills が Code タブで使えるかどうかは、筆者は確かめていません
スクリプトが失敗するとき：Academy のレッスン6は、スクリプトには実行権限が必要で、chmod +x を実行するよう書いています。公式のスキルのページには chmod の記述が見つかりませんでした（公式のフックのページには、フックのスクリプトに chmod +x を付ける例があります）。Platform のベストプラクティスは、必要なパッケージを SKILL.md に書くよう勧めています
スキルが多いとき：公式は、スキルの一覧には名前が必ず全部入るが、スキルが多いと、一覧の文字数の予算に収めるために、いくつかの description が切り詰められる、と書いています。一致に必要なキーワードが落ちるので、重要な用途を description の先頭に置きます（公式の「Skill descriptions are cut short」の節）
途中で守られないとき：会話の圧縮は、連載「Claude Code実践入門」第3回の「/compactには指示を付ける」を参照してください。大事な指示は SKILL.md の先頭に置き、必ず守らせたいことはフックにします（連載「Claude Codeフック入門」第3回の「何を止めるか」）。スキルは強制ではありません

組織のプラン（Team・Enterprise）の補足：組織の管理設定の strictPluginOnlyCustomization で、ユーザー・プロジェクトのスキルが止められていると、そのスキルは使えません（公式の管理設定のページ。この設定は、スキル・エージェント・フック・MCP サーバーを、ユーザーとプロジェクトの出どころからはブロックします）。プラグインのスキルが出ないときは /reload-plugins です。公式のプラグインのトラブルシュートも、セッション中にインストールしたなら /reload-plugins を実行するよう書いています。この連載は、プラグインを扱いません。

出典は https://code.claude.com/docs/ja/skills （Skill not triggering ほか）、https://code.claude.com/docs/ja/managed-settings 、https://code.claude.com/docs/ja/plugins/troubleshooting と、Academy の講座「Introduction to agent skills」（日本語版は「Agent Skills入門」）のレッスン6です。

確かめ方

一覧を聞く：「利用可能なスキルは？」と聞く。公式のトラブルシュートの最初の手順の1つ（公式は「What skills are available?」と聞くよう書いています）
/skills：スキルの一覧を、名前・説明・場所で絞り込める。Code タブの候補に出るかは、筆者は確かめていません。筆者が試した非対話の claude -p では、「/skills isn’t available in this environment.」と出て使えませんでした（CLI 2.1.289、2026-10-18）
/名前 で直接呼ぶ：呼べるのに自動で発動しないなら、description の問題。呼べないなら、名前か置き場所の問題
claude --debug：読み込みエラーを調べる CLI の起動オプション。YAML のエラーや、拒否された名前がログに出る。Code タブでの代わりの手段は、筆者は確かめていません
バリデーター：オープン標準の仕様（agentskills.io）の skills-ref validate ./my-skill が、frontmatter と命名の規則を点検する。Claude Code の claude plugin validate .claude/skills（v2.1.233 以降）は、解釈できない frontmatter を探す（CLI のコマンド。Code タブで Claude に実行させられるかは、筆者は確かめていません）
使えないとき：「SKILL.md の構造を上の表で点検して」と Claude に頼む

スキルが発動しないときの切り分けの流れ図。見出しは「発動しないとき：上から順に切り分ける」。赤い箱「発動しない」から、橙色の箱「「利用可能なスキルは？」で一覧に出る？」へ進む。「いいえ」の場合は右の枠へ：SKILL.md が名前付きフォルダーの中か。先頭の --- が1行目か。置き場所・ファイル名・YAML を直し、新しいセッションで聞き直す。「はい」の場合は次の橙色の箱「/名前で呼べる？」へ進む。「いいえ」の場合は右の枠へ：名前か置き場所の問題。同じ名前が優先順位の高い場所にないか。あれば名前を変える。「はい（呼べるのに自動で発動しない）」の場合は、緑の枠「description の問題」へ進み、description に言い回しを足す。YAML が壊れていると description が使われない、とある。下の灰色の枠「ほかの症状」には3行ある。別のスキルが動く：description が似ていないか。対象と場面で区別する。スクリプトが失敗：実行権限・パス・依存。bash で呼ぶか chmod +x。依存は SKILL.md に書く。途中で守られない：会話が圧縮（compact）されていないか。大事な指示を SKILL.md の先頭へ。必ず守らせるならフック。

詳しく見ます。

claude --debug：公式の CLI リファレンスでは、--debug は「カテゴリーを絞って、デバッグモードを有効にする」オプションで、--debug='mcp,startup' や --debug='!1p' のように書きます。絞り込みが効くのは = でつないだ形だけで、スペースで区切ると、絞り込みなしでデバッグモードになります。--debug-file <path> は、ログを指定したファイルに書き、暗黙にデバッグモードを有効にします。claude --help は全部のフラグを載せないので、--help に無いからといって、使えないとは限りません（公式の注意）。スキルについては、公式のスキルのページに次の2つがあります。

名前が拒否されたとき：claude --debug で起動し、デバッグログを [names] で検索すると、どの名前が拒否されたか分かる。対話のセッションなら、名前が拒否されたことは起動時の通知にも出る
YAML の誤り：--debug で解析のエラーが見える

セッションの中では、/debug [issue] が、そのセッションのデバッグログを有効にし、ログと設定のパスを使って Claude に診断させます（公式のコマンドの表）。--debug で起動しなかった場合は、/debug を実行した時点からの記録になります。Code タブで /debug が使えるかどうかは、筆者は確かめていません。カテゴリーの一覧は公式の CLI リファレンスには例示しかなく、スキルの読み込みエラー専用のログの場所の記述は見つかりませんでした。

バリデーターは、2つあり、別のツールです。

	`claude plugin validate`	`skills-ref validate`
どこの	Claude Code	オープン標準（agentskills.io）の参照ライブラリ
使い方	`claude plugin validate .claude/skills`（個人のスキルは `~/.claude/skills`）	`skills-ref validate ./my-skill`
点検すること	frontmatter が解釈できない `SKILL.md` を探す。ディレクトリ内のスキル・エージェント・コマンドを点検する	`SKILL.md` の frontmatter が正しく、命名の規則に従っているか
条件	v2.1.233 以降（マニフェストなしでファイルを点検する場合）	仕様のページは、参照ライブラリへのリンクを載せている

claude plugin validate は、終了コードで CI から使えるように作られています。0 は合格（警告つきの合格を含む）、1 は不合格、2 は検証中の予想外のエラーです。--strict を付けると、警告をエラーとして扱い、実行時には許される未知のフィールドやメタデータの不足も不合格にします（公式のプラグインの CLI リファレンス）
Academy のレッスン6は、バリデーターを uv で入れる手順を紹介しています。この連載では入れ方は扱わず、名前の紹介だけにします。公式の仕様のページには、uv での入手方法の記述は見つかりませんでした

出典は https://code.claude.com/docs/ja/cli-reference 、https://code.claude.com/docs/ja/skills 、https://code.claude.com/docs/ja/commands 、https://code.claude.com/docs/ja/plugins/cli-reference 、https://agentskills.io/specification です。

Windows と Linux の注意

パスはスラッシュ：Windows でも reference/guide.md のようにスラッシュで書く。バックスラッシュは、Unix 系ではエラーになる（Platform のベストプラクティス。原文は「Always use forward slashes in file paths, even on Windows」）
個人のスキルの場所：公式の表記は ~/.claude/skills/<skill-name>/SKILL.md です。Windows では ~/.claude は %USERPROFILE%\.claude を指します（公式の設定のページ）。Academy のレッスン1は C:/Users/<ユーザー名>/.claude/skills と書きます。PowerShell で見るなら Get-ChildItem $HOME\.claude\skills、Linux なら ls ~/.claude/skills
SSH の検証用ホストで作業する場合：Ansible の作業は、SSH の検証用ホストにあるリポジトリを開いて行います。verify.sh は手元の PC ではなく、ホストで動きます。公式のデスクトップのページは、ローカルのセッションは ~/.claude/skills/ から個人のスキルを読み込み、SSH のセッションは、手元の PC ではなく、接続先ホストのホームの ~/.claude/skills/ を読む、と書いています。ホスト上のリポジトリの .claude/skills が読まれるかどうかは、筆者は確かめていません（筆者は、SSH 接続を確かめていません。連載「Claude Code実践入門」第8回の「環境を選ぶ」と同じです）
bash が要る：verify.sh は bash のスクリプト。PowerShell には書き直さず、Linux ホスト側で動かす

公式は、スキルの shell フィールドは bash（既定）か powershell で、Windows に Git Bash が無いと、shell: bash の差し込みコマンドは、どのコマンドも動く前に失敗する、と書いています（https://code.claude.com/docs/ja/skills ）。出典は https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices と https://code.claude.com/docs/ja/desktop 、Academy のレッスン1・6です。

連載の早見表

テーマ	押さえること
スキルとは（第1回）	同じ指示を2回打ったらスキルにする（目安）。いつもは CLAUDE.md、必ずはフック。スキルは強制ではない
SKILL.md と発動（第2・3回）	frontmatter（`name`・`description`）＋本文。description は「何を・いつ」と普段の言い回し。言い回しを変えて試す
複数ファイル（第4・5回）	SKILL.md は短く。資料は reference、決まった処理は scripts を読まずに実行。allowed-tools は事前承認で、狭く
検証スキル（第6・7回）	ansible-verify は①〜③を受け持ち、③の結果を見せて止まる。本実行と prod は人
共有（第8回）	`.claude/skills` を Git で共有。同名は優先順位で隠れる。PR で description と allowed-tools を読む
うまく動かないとき（第9回）	発動しない→言い回し。出ない→置き場所・SKILL.md・YAML。隠れる→名前。失敗→実行権限・パス

持ち帰りの3点

同じ指示を2回打ったらスキルにする：いつもは CLAUDE.md、必ずはフック
description は「何を・いつ」と普段の言い回し：言い回しを変えて試す
SKILL.md は短く、資料は reference、処理は scripts：.claude/skills を Git で共有する

演習は、自分の環境で、第10〜12回の手順を試すことです。足した言い回しと詰まったところは、自分の description や SKILL.md に反映してください。

次に学ぶなら

この連載のスキルは、今の会話に手順と知識を足すものでした。次の連載「Claude Codeサブエージェント入門」で扱うサブエージェントは、別のコンテキストで動く担当で、担当ごとにモデル（model）とツール（tools）を決められます。スキルから担当を呼び分ければ、役割ごとにモデルを分けられます。最終回の第12回の「次に学ぶなら：サブエージェント」でも、スキルとサブエージェントのつなぎ方を触れます。

役割ごとのモデルの選び方は、公式の言い方に合わせて書いておきます。

Claude Code の既定は Opus 5.5、Effort は medium（公式）。まず既定で始め、足りなければ Effort を上げます。モデルを替えるより、Effort の調整が効くことが多いです
簡単なサブエージェントの作業には model: haiku を勧める公式の言い方（コストのページ）、組み込みの Explore がメインの会話と同じモデルで動くこと、haiku が Haiku 5.5 に解決される版（v2.1.293 以降）は、第12回の「次に学ぶなら：サブエージェント」にまとめています

「調べる担当は Haiku、書く担当と確かめる担当は Sonnet、判断は本体（Opus 5.5）と人」のような分け方は、筆者の例で、公式の推奨ではありません。詳しくは、連載「Claude Codeサブエージェント入門」で扱います。

次の連載の前に読める公式の教材（Academy の講座「サブエージェントの概要」と、「Claude Codeを実践する」のレッスン9「プラグイン」）も、第12回の同じ節に載せています。

出典は https://code.claude.com/docs/ja/model-config と、第12回に挙げたページです。

考えてみよう

置いたスキルが一覧に出ません。最初に確かめる2つは何でしょうか
/名前 では呼べるのに、普通に頼むと発動しません。これは名前・置き場所・description のどれの問題でしょうか。何を直しますか
Windows の PC から、SSH の検証用ホストで ansible-verify を使うとき、verify.sh はどこで動きますか。個人のスキルはどこから読まれますか

ヒント：1は「症状別チェックリスト」の「一覧に出ない」の行、2は「確かめ方」の /名前 の項目、3は「Windows と Linux の注意」の3つ目を見直してください。

まとめ

症状から原因を絞る。発動しない→言い回し、出ない→置き場所・SKILL.md・YAML、隠れる→名前、失敗→実行権限・パス、途中で守られない→圧縮（必ず守らせるならフック）
frontmatter は先頭の --- が1行目にあるときだけ読まれる。YAML が壊れていると、/名前 では呼べても description が使われない
確かめ方は、一覧を聞く、/skills、/名前 で直接呼ぶ（呼べるのに発動しないなら description）、claude --debug、バリデーター（claude plugin validate・skills-ref validate。別のツール）
パスはスラッシュ。SSH の検証用ホストで作業するなら、verify.sh はホストで動き、個人のスキルはホストの ~/.claude/skills/ から読まれる
持ち帰りは3点：2回打ったらスキル／description は「何を・いつ」／SKILL.md は短く、資料は reference、処理は scripts
次に学ぶなら、連載「Claude Codeサブエージェント入門」。モデルは公式の既定から始め、軽い担当には model: haiku を勧める公式の言い方に合わせる