Claude CodeのSkillsが動かない原因。3割が眠ってる問題と6つの型
この記事を読むとわかること：
- ✅ なぜSkillsが「作っても呼ばれない」のか、その正体がわかる
- ✅ 動くSkillsだけが守ってる「6つの型」を全部把握できる
- ✅ コピペで使える「動くSkills」の完成版テンプレが手に入る
- ✅ 自分のSkillsを1分で診断できる「7チェックリスト」が使える
- ✅ 眠ってるSkillsを復活させる具体的な手順がわかる
Contents
- 1 そもそも「Skills」って何？（30秒でおさらい）
- 2 私のSkills、3割が「眠ってる」状態でした
- 3 動くSkillsだけが守ってる「6つの型」
- 4 法則1：descriptionは「いつ使うか」を書く
- 5 法則2：命令形で書く（お願い口調はやめる）
- 6 法則3：アウトプット形式を最初に書ききる
- 7 法則4：「まず読め」のステップを必ず入れる
- 8 法則5：「やらないこと」を明示する
- 9 法則6：500行以内に収める
- 10 完成版コピペ：/commit Skills 全文
- 11 動かないSkillsを1分で見抜く「7チェックリスト」
- 12 私が眠ってたSkillsを復活させた手順
- 13 Skillsは「資産」になる
- 14 今日できること（ひとつだけ）
そもそも「Skills」って何？（30秒でおさらい）
本題に入る前に、Skillsって何だっけ？を30秒だけおさらいさせてください。すでにご存知の方は次の章へ進んでくださいね。
Skillsは、ものすごく雑に言うと「Claude Code 専用のショートカット」みたいなものです。決まった場所（パソコン内の専用フォルダ）にファイルを1つ置くだけで、Claude Codeが「あ、こういう場面が来たらこのやり方で動こう」と覚えてくれる仕組みなんですよ。
呼び出し方には2種類あります。1つは「自動発動」で、あなたが「コミットして」と話しかけたとき、Claude Codeが手元のSkills一覧を見て、合うものを引っ張り出すパターン。もう1つは「スラッシュ呼び出し」で、`/commit` と打って明示的に呼ぶパターンです。
つまり、自動発動は「察してくれる」、スラッシュ呼び出しは「名指しで呼ぶ」。この違いが、後の話でとても大事になってきます。
私のSkills、3割が「眠ってる」状態でした
Skillsは、作るのは思ったより簡単です。専用フォルダに「SKILL.md」という名前のファイルを1つ置くだけ。中身は文章と、上のほうに名前と説明を書くだけ。コードが書けない私でも、軽い気持ちで作れちゃいました。
3週間くらいで、私は十数個のSkillsを書きました。コミットメッセージ生成、コードレビュー、文章のリライト、リサーチ整理、画像配置、命名チェック…と次々に。
ところが1ヶ月後に振り返って数えてみたら、こんな状態だったんです。
- 週1回以上使ってるSkills：5〜6個
- たまに思い出して呼ぶSkills：4個
- 作ったことすら忘れてたSkills：6個
全体の3割が「眠ってるSkills」だったんですよ。しかも厄介なのが、Skillsって「動かない」ことに気づきにくいんです。普通のプログラムならエラーが出ますよね。でもSkillsは、そもそも呼ばれていないだけなので、エラーすら出ない。気づかないまま、ファイル置き場の肥やしになっていく。
ある研究者の方が、22個のテストケースでSkillsの発動率を測ったデータがあります。何も対策せずに「自動発動」を期待した場合、発動率はだいたい50%。2回に1回しか動かない、ということです。逆に、ユーザーが明示的に呼び出した場合は100%近くになる。
動くSkillsだけが守ってる「6つの型」
そこで私は、公開されている優秀なSkillsを100個ほど読み解いてみました。すると、動いているSkillsだけが共通して守っている「型」が、はっきり6つ見えてきたんです。
Skillsの書き方を考える前に、CLAUDE.md・AGENTS.md・SKILL.md の関係を押さえておくと理解が早いですよ。気になる方は「Claude CodeのCLAUDE.md使い分けガイド」もあわせてどうぞ。
- 法則1：descriptionは「いつ使うか」を書く
- 法則2：命令形で書く（お願い口調はやめる）
- 法則3：アウトプット形式を最初に書ききる
- 法則4：「まず読め」のステップを必ず入れる
- 法則5：「やらないこと」を明示する
- 法則6：500行以内に収める（段階的に開示する）
この章では、特に効果が大きい法則1と法則2を、無料パートでしっかりお伝えします。残りの4つは有料パートで完成版テンプレと一緒にお見せしますね。
法則1：descriptionは「いつ使うか」を書く
6つの型の中で、これがいちばん大事です。順位を付けるなら、これだけで全体の半分の効果が出ると言っても言い過ぎではありません。
Skillsが発動するかどうかの判断材料は、ファイル上部に書く「description」（つまり「説明文」）ただ1つ。Claude Codeは新しい依頼を受けたとき、まず全Skillsのdescriptionだけをザッと見比べて、「これかな」と思ったやつの本文をやっと読みに行きます。
知っておくべき数字もあります。descriptionは最大1,024文字まで書けますが、自動発動の判定で実質効くのは「最初の50文字」なんです。大事なきっかけ言葉（トリガー語）は、必ず最初の50文字に詰める。これだけで発動率がぐっと上がります。
ダメな書き方の例を見てくださいね。
description: コードレビューのツール
これ、私が最初に書いたやつなんですけど、まったく動きませんでした。「何をするか」しか書いていないし、きっかけ言葉も曖昧。直したのがこちらです。
description: バグ・セキュリティ問題（権限漏れなど）・保守性の観点でコードをレビューする。プルリクエスト（つまりコードの変更提案）のレビュー時、コード品質の確認時、差分の分析時、または「レビュー」「PR」「コードクオリティ」「ベストプラクティス」と言われたときに使う。
「何をする」「いつ使う」「きっかけ言葉が複数」、これがセットで入っています。同じSkills、本文も同じ。descriptionだけ書き換えただけで、発動率が50%から90%に上がった検証データもあるんですよ。
法則2：命令形で書く（お願い口調はやめる）
descriptionで呼ばれるようになったら、次は本文の書き方です。ここでも、書き方ひとつでSkillsの動作が大きくブレます。
ポイントはたった1つ。お願い口調をやめて、命令形で書くこと。私もここを最初すごく間違えていました。
ダメな例から見てくださいね。
コードをレビューしてもらえませんか？
バグがあったら教えてもらえると助かります。
できれば、改善案も出してもらえるとありがたいです。
人にお願いするときの自然なトーンですが、Skillsの中身としては最弱です。「もらえませんか」「助かります」のような表現は、必須なのか任意なのかが曖昧。結果として、毎回出力がブレます。
直すとこうなります。
現在の差分をレビューする。次の3点をチェックする：
1. セキュリティ問題（権限の漏れ、入力チェック忘れ）
2. パフォーマンス（つまり処理の重さ。無駄なデータベース＝情報の保管庫への問い合わせ）
3. 命名と構造の一貫性
各項目に重大度を付けて、チェックリスト形式で出力する。
命令形、番号付き手順、明確な出力形式。これでSkillsの動きがピシッと揃います。
ここまでが、6つの型のうち「最も効果が大きい2つ」のお話でした。実はこの2つだけ守るだけでも、あなたの眠ってるSkillsの半分くらいは目を覚ますはずですよ。
少しだけ一息いれて、次は残る4つの型に進んでいきましょう。後半では、コピペで使える完成版テンプレと、自分のSkillsを1分で診断できる「7チェックリスト」もお渡ししますね。
法則3：アウトプット形式を最初に書ききる
ここからは「再現性」の話に入っていきます。Skillsは、毎回違う出力が返ってくると使い物になりません。同じSkillsを10回呼んで、10回違う形で結果が返ってきたら、信頼できないですよね。
そのカギが、アウトプット形式（出力の形）を最初に書ききることなんです。
雑な書き方の例を見てください。
テスト結果から、レポートを生成してください。
これだと、ある時は1行のサマリ、ある時は段落つきの長文、ある時は表組み、ある時は箇条書き。10回試したら10通りの形が返ってきます。Skillsとして使い物になりません。
直すと、こうなります。
テスト結果を以下の形式で出力する：
＃ Test Report：日付
＃＃ サマリ：通過／失敗／スキップの件数
＃＃ 失敗テスト一覧（表組み：テスト名／ファイル／エラー）
＃＃ Next Action（箇条書きで3個まで）
これだと10回試しても、同じ構造で返ってきます。出力フォーマットを明示しているSkillsは、構造の一貫性が95%を超えるというデータもあります。明示なしと比べると、3〜4倍の差です。
法則4：「まず読め」のステップを必ず入れる
Skillsって、思った以上に「読まずに動く」ことが多いんです。ユーザーがざっくり「リファクタリングして」（つまり、コードの中身を整え直してほしい、ということ）と言うと、Claudeは何を読むべきか考える前に動き出してしまう。過去の傾向や一般論で答えを返そうとするんですよね。
これだと、出力があなたのプロジェクトに合いません。使ってる道具も違うし、書き方の決まりも違うし、テストのやり方も違う。ジェネリックな「リファクっぽい何か」が出てきてしまう。
これを防ぐのが「まず読め」のステップです。Skills本文の最初に「読む」を強制すると、出力が一気に正確になります。
このステップを最初に入れるだけで、検証データでは出力精度が70%から95%以上に上がります。プロジェクトに合わない汎用的な出力ではなく、その現場のコードに馴染んだ出力になる、ということなんです。
法則5：「やらないこと」を明示する
ここまでの4つの型で、Skillsは「呼ばれて、動いて、再現性を持って、的外れにならない」ようになります。次の型は、少し逆説的なんですが、Skillsに「やらないこと」を書くこと、です。
「やることだけ書けば良くない？」と最初は思いますよね。でも実はこれが、Skillsの誤発火（呼ばれちゃいけない場面で動いてしまうこと）を防ぐ最強の武器なんです。
たとえば、CSVファイルを処理するSkillsを作ったとします。descriptionが「CSVを処理する」だけだと、ユーザーが「PDFを読んで」と言ったときに、Claudeが「ファイル処理ならこれかな」とCSV用Skillsを引っ張り出すことがあるんです。
これを防ぐのが、「やらないこと（Out of Scope）」のリストを書くこと。書き方はとてもシンプルです。
＃＃ やらないこと
このSkillsは以下のことはしない：
– スキャンしたPDFの処理（別途OCR Skillsを使う）
– ゼロからのPDF作成（document-generation Skillsを使う）
– パスワード付きファイルの処理
「やらないこと」と「代わりに何を使うか」の2点セット。これで読者（Claude）が間違ったSkillsを引いたときに、「これは自分の担当じゃない」と判断できるようになります。
法則6：500行以内に収める
最後の型は、長さの話です。Skills本文は500行以内に収める。これは公式のベストプラクティスにも明記されている数字です。
長すぎるSkillsには2つの問題があります。
- 問題1：呼ばれた瞬間に本文全体がClaudeの作業記憶に流れ込むので、長いほど他のことを考えるスペースを奪う
- 問題2：長すぎる指示書は、人間でも最後まで読みませんよね。AIも同じで、後ろの指示が薄れていく
公式の主要Skillsを見ると、ほぼ全部300行以下に収まっています。500行を超えそうなときは、本体と参照ファイルに分割するのがおすすめです。本体には「メインの流れ」と「参照ファイルへのリンク」だけ書いて、詳しい例や応用は別ファイルに切り出す。これを「段階的に開く（progressive disclosure）」と呼びます。
②命令形で書く
③アウトプット形式を最初に書ききる
④「まず読め」のステップを入れる
⑤「やらないこと」を明示する
⑥500行以内に収める
完成版コピペ：/commit Skills 全文
ここまでの6つの型を全部適用すると、こんなSkillsができます。コピーしてあなたの環境にそのまま貼り付けて使ってくださいね。
---
name: commit
description: 現在の変更をステージしてコミットする。「コミットして」「保存」「commit」「変更を確定」と言われたとき、または機能の実装が一区切りついたタイミングで使う。Conventional Commits 形式のメッセージを生成する。
disable-model-invocation: true
---
# Git Commit Skill
## 手順
1. git status と git diff を実行して、現在の変更を把握する
2. 関連する変更を論理的な単位にグルーピングする（1機能 = 1コミット）
3. 各単位に対して、以下の形式でコミットメッセージを生成する：
type(scope): short description
- 何が変わったか
- なぜ変わったか（自明じゃない場合のみ）
4. git add で対応ファイルをステージし、git commit で個別にコミットする
5. 最後に「N個のコミットを作成しました：[タイトル一覧]」とサマリを出す
## ルール
- type は次のいずれか：feat, fix, refactor, docs, test, chore
- description は 50字以内、小文字、現在形
- bullet は簡潔に。冗長な説明は不要
- 関係ない変更は同じコミットに混ぜない
## やらないこと
このSkillsは以下のことはしない：
- リモートへのプッシュ（/push を使うか、手動で git push）
- プルリクエストの作成（/pr Skillsを使う）
- ブランチのマージこの短いファイルの中に、6つの型がすべて入っています。descriptionの最初の50字に目的ときっかけ言葉。本文は命令形で番号付き手順。出力フォーマットも明示。「まず読め」（git status と git diff）も最初に組み込み済み。「やらないこと」セクションで他のSkillsとの棲み分け。全体50行以下。
「disable-model-invocation: true」も忘れずに。/commit は実行したら戻せないので、勝手に動かれたら困ります。明示呼び出しのときだけ動くように固定しておく、これが安心のコツです。
動かないSkillsを1分で見抜く「7チェックリスト」
ここまでで、動くSkillsの「型」は全部お伝えしました。最後に、すでに作ってあるSkillsを1分で診断できる7項目を用意しました。1つでも引っかかったら、そこが原因です。
- ✅ チェック1：descriptionにきっかけ言葉が3個以上ありますか？
- ✅ チェック2：大事なきっかけ言葉が最初の50文字に入っていますか？
- ✅ チェック3：本文は命令形・番号付きの手順になっていますか？
- ✅ チェック4：アウトプット形式（出力の型）が明示されていますか？
- ✅ チェック5：「まず読め」のステップが本文の最初にありますか？
- ✅ チェック6：「やらないこと」セクションがありますか？
- ✅ チェック7：SKILL.md が500行以内に収まっていますか？
7項目のうち3個以上引っかかったら、そのSkillsは「ほぼ動いていない」と思ってください。逆に全部クリアしているSkillsは、安定して呼ばれて、安定した出力を返してくれます。
私が眠ってたSkillsを復活させた手順
この7チェックリストで私が自分のSkillsを診断したら、十数個のうち何個もが「3個以上引っかかる」状態でした。そこから、修正の旅が始まったんです。
復活させる手順は、6つの型を「逆順」で当てるのが早かったんですよ。なぜかと言うと、上から順だと「descriptionだけ直して動かない」というループに入りやすいから。先に構造を整えてから、最後にdescriptionに戻ったほうが、たどり着くのが速いんです。
朝のコーヒー時間に、1日1個のペースで淡々と。私の場合、十数個の眠ってたSkillsのうち、1週間で9個が復活、2個は「別Skillsに分割」、1個は「もう要らない」と気づいて削除、という結末でした。
Skillsは「資産」になる
動くSkillsが揃ってくると、Claude Codeでの作業が一段別物になります。毎回ゼロから指示するのではなく、「この場面ではこう動く」を仕込んでおく。その積み重ねが、Claude Codeをあなた専用の作業パートナーに変えていきます。
副業として「AIで仕事をこなして時間単価を上げたい」と考えている方にとって、Skillsの整備は最強の投資です。1個整えるだけで、その後の毎日が少しずつ速くなる。1ヶ月、3ヶ月と積み上がっていくと、Skillsを整えていない人との差は、想像以上に大きくなります。
もう一歩踏み込みたい方は、最新の指示文ルールも組み合わせるとSkillsの精度がさらに上がります。「Claude 4.7指示文の新ルール」もあわせてどうぞ。
② 公式が守ってる型は6つだけ。中でも description が最重要
③ 眠ってるSkillsは7チェックリストで診断 → 逆順で直すと早い
今日できること（ひとつだけ）
最後に、今日試してほしいことを1つだけお伝えしますね。それは「自分のSKILL.md を1つだけ開いて、7チェックリストを上から当ててみる」ことです。たった5分でできます。
たぶん、最初に開いた1個から「あ、descriptionにきっかけ言葉が足りない」「あ、お願い口調になってる」と気づくはずです。気づけたら、もう半分終わったようなものですよ。
