SKILL.mdを書いて保存したのに、スラッシュコマンドを打っても反応しない。関連する話題を振っても自動で発動しない。そもそもSkill一覧に名前が出てこない。編集部は数十本のSkillを社内運用していますが、新しいSkillを追加するたびに、この種のつまずきをどれかしら踏んできました。
まず押さえておきたいのは、症状によって原因の層が違うことです。一覧に名前すら出ないなら、ファイルの置き場所や名前、フロントマターの構文といった「読み込み以前」の問題です。一覧には出るのに呼んでも期待どおり動かないなら、中身の記述の問題です。呼べば動くのに自動発動だけしないなら、descriptionの書き方の問題です。この切り分けを頭に置いたうえで、原因になりやすい順に7つの確認点を見ていきます。そもそもSkillの仕組み自体を確認したい場合は、先にSkillとは何かの解説記事を読んでください。
確認点1: 置き場所が正しいか
Skillの置き場所は決まっています。プロジェクト用は .claude/skills/スキル名/SKILL.md、ユーザー用（全プロジェクト共通）は ~/.claude/skills/スキル名/SKILL.md です。つまり「skillsディレクトリの直下にスキル名のディレクトリを作り、その中にSKILL.mdを置く」という2階層の構造が必要です。
ありがちな失敗は、.claude/skills/ の直下にいきなり my-skill.md のようなファイルを置いてしまうことです。ディレクトリを挟まずに置いたファイルは読まれません。編集部でも、急いで作ったSkillをディレクトリなしで直置きして、しばらく気づかなかったことがあります。
確認点2: ファイル名がSKILL.md（大文字）か
ファイル名は SKILL.md で固定です。すべて大文字のSKILLに拡張子.mdをつけます。skill.md や Skill.md では認識されません。Macの標準ファイルシステムは大文字小文字を区別しないため手元では気づきにくいのですが、名前が違えばSkillとしては読まれません。一覧に出ないSkillは、まずファイル名の綴りを疑ってください。
確認点3: フロントマターが壊れていないか
SKILL.mdの冒頭には、--- の行で挟んだYAML形式のフロントマターが必要です。ここに name と description の2項目を書きます。最低限の形は次のとおりです。
---
name: my-skill
description: 〇〇の作業を依頼されたときに使う。△△を実行して結果を返す。
---このYAMLが構文として壊れていると、Skill全体が読み込まれません。編集部が実際に踏んだ壊し方は3つあります。コロンの後の半角スペースを忘れる（name:my-skill と書いてしまう）。日本語入力のまま全角コロン「：」を打ってしまう。descriptionを引用符で囲み始めたのに閉じ忘れる。どれも見た目にはほとんど気づけないので、認識されない時はフロントマターを1文字ずつ確認する価値があります。YAMLフロントマターの書式の詳細はWikiのフロントマター解説にまとめています。
確認点4: nameとディレクトリ名が一致しているか
フロントマターの name は、SKILL.mdを置いているディレクトリ名と一致させます。ディレクトリ名が my-skill なのに name: my_skill と書くような不一致があると、正しく扱われません。ハイフンとアンダースコアの混在、単数形と複数形の揺れは特に起きやすいので、ディレクトリ名をコピーしてnameに貼り付けるのが確実です。
確認点5: descriptionが具体的か（自動発動しない場合）
スラッシュコマンドで明示的に呼べば動くのに、関連する依頼をしても自動で発動しない。この症状の原因はほぼdescriptionです。Claude Codeは、ユーザーの依頼内容とdescriptionの記述が合致するかどうかでSkillを自動発動させるか判断します。つまりdescriptionは飾りの説明文ではなく、発動条件の定義そのものです。
「便利なタスク支援スキル」のような抽象的な文では、どんな依頼とも合致しないため発動しません。「請求書PDFからデータを抽出するよう頼まれたときに使う」のように、いつ使うかというトリガー条件を具体的な言葉で書きます。ユーザーが実際に打ちそうな語をdescriptionに含めておくのがコツです。descriptionを含むSKILL.md全体の書き方はSkillの書き方の記事で詳しく扱っています。
確認点6: セッションを再読み込みしたか
Skillの一覧はセッション開始時に読み込まれます。そのため、いま開いているセッションの途中でSkillを追加しても、そのセッションには反映されません。ファイルは完璧なのに認識されない場合、単に追加前から開きっぱなしのセッションで試している可能性があります。Skillを追加したり修正したりした直後は、新しいセッションを開いて確認してください。編集部では「Skillを直したら新規セッションで検証する」を手順として固定しています。
確認点7: 文字コードがUTF-8（BOMなし）か
日本語環境特有の落とし穴です。日本語版Windowsのエディタは、設定によってファイルをcp932（Shift_JIS系）で保存したり、UTF-8にBOMと呼ばれる目印のバイト列を付けて保存したりします。cp932で保存された日本語や、先頭のBOMは、YAMLフロントマターの解析を失敗させることがあります。中身は正しく書けているのに認識されない場合、エディタの保存設定を確認し、UTF-8（BOMなし）で保存し直してください。Windowsで作ったSKILL.mdをMacに持ってきたら動いた、という場合はほぼこれです。
まとめ: それでも直らない時の切り分け手順
7つすべて確認しても動かない時は、原因探しの前に切り分けをします。手順は2つです。
1つ目は、最小構成のSkillを同じ場所に作ってみることです。フロントマターにnameとdescriptionだけ、本文1行だけのSKILL.mdを新しいディレクトリに置き、新規セッションで認識されるか確認します。これが認識されるなら環境は正常で、原因は元のSkillの中身にあります。認識されないなら、置き場所か環境側の問題です。
2つ目は、壊れたSkillと最小構成のSkillの差分を半分ずつ埋めていくことです。本文を半分移し、認識されるか確認し、また半分移す。これを繰り返せば、壊れている箇所を数回の試行で特定できます。認識されない原因は1ファイルの中のどこか1点にあることがほとんどです。総当たりで眺めるより、確実に範囲を狭める方が早く着きます。