Claude Codeがスキルを5回無視。1行で直った

Claude Codeのスキルは、名前を指定すれば完璧に動くのに、自分では一度も読み込まれないことがある。私たちのスキルは名前を打てば毎回動いた。ところが同じ作業を普通の言葉で頼むと、毎回スキップされた。スキップされる様子を確認し、理由を読み、問題を直す1行を書き直した。

スキルとは、依頼が合致したときにClaude Codeが自動で拾う、保存済みの指示のまとまりだ。合致を決めるのは、Claudeが選ぶ前に読む1行であり、指示の本文ではない。以下の6ステップで、毎回打ち直しているプロンプトから、自動で読み込まれるスキルまでたどり着く。チームに気づかれる前にスキップを見つける、20個の依頼によるテストも付く。

テスト(同じ依頼、新しいセッション)	スキルの読み込み
名前で呼ぶ(/release-notes)	2回中2回
普通の言葉、元のdescription	5回中0回
普通の言葉、書き直したdescription	5回中5回

スキルとは、中にSKILL.mdというファイルが1つ入ったフォルダだ。ファイルの先頭には短いヘッダー(名前と1文のdescription)があり、その後に指示が続く。関数に似ている。呼び出す側はシグネチャとdocstringを読み、本体は呼ばれたときにしか実行されない。ホームフォルダに置けばどのプロジェクトでも使え、リポジトリの中に置けばそこで働く全員に行き渡る。

ファイルではなく、作業から始めよう。毎回打ち直しているプロンプトを選び、欲しい出力を正確に書き出す。私たちの場合は週次のリリースノートだった。月曜以降のコミットを領域ごとにまとめ、chore系は外し、変更ごとに1行、プルリクエスト番号を付ける。オープンソースのHonoリポジトリで、その長いプロンプトはその週のバグ修正8件について整ったノートを出した。その出力が、スキルが再現すべき目標になった。

すべてのプロンプトがスキルに値するわけではない。1回きりの質問は不要だし、二度と使わないスキルは、Claudeが読む行を1つ増やすだけだ。毎週打つプロンプトの短いリストを作り、先頭のものを最初のスキルにしよう。

プロジェクトに.claude/skills/release-notes/SKILL.mdを作る。隠しフォルダ.claudeの中にskillsフォルダ、スキル名のフォルダ、その中にスキルファイルという構成だ。フォルダは重要で、単独のrelease-notes.mdはまったく読み込まれない。ドキュメントも最初に確認すべき点としてこれを挙げている。

ヘッダーは、2本の区切り線の間に置くラベル付きの数行で、ファイルの1行目から始めなければClaude Codeに無視される。私たちのヘッダーには、名前のrelease-notesと、多くの人が書くであろうdescriptionがあった。

---
name: release-notes
description: Generates changelog documents from repository history.
---

ヘッダーの下には、新しいチームメンバーに渡すような番号付きの手順を書く。私たちのは5つ。月曜以降のコミットを探す、choreとdocsのコミットを外す、conventional commitのスコープでまとめる、変更ごとに平易な1行を書く、タイトル付きのブロックの先頭に短い要約を置いて出力する。Anthropicはこの部分を短くすることを勧めている。再起動は不要で、Claude Codeは新規や編集したスキルを、今のセッションのまま拾う。

名前でテストする。スラッシュを打ち、メニューでスキルを選び、Enterを押す。新しいセッションで、私たちのスキルはコミットログを読み、修正を領域ごとにまとめ、望みどおりのノートを毎回書いた。問題は、あなたもチームの全員も、その名前を覚えていなければならないことだ。

チームメイトはスキルの名前を打たない。新しいセッションを開き、あなたに頼むように頼む。だからそれをテストする。新しいセッション(何も読み込まれていない新しい会話)を開き、自分の言葉で作業を頼もう。新しくなければならないのは、一度使ったスキルは会話に残るため、そのセッションでのテストは何も証明しないからだ。

私たちは「今週は何を出荷した?」と打った。Claudeは自分でコミットログを実行し、スキルの気配もなく自分流の要約を書いた。答えは悪くなかったが、実行ごとにぶれた。ある回は月曜から数え、別の回は直近のリリースタグから数えて、スキルなら外すはずのdocsの変更まで拾った。新しいセッション5回で、スキルは5回すべてスキップされた。

5回の実行は統計ではなくデモだ。それでも、名前では動くのに普通の言葉では毎回スキップされるスキルは、役目を果たしていない。しかもステップ2の名前でのテストは通っているので、疑おうとも思わない。

1語でも変える前に、3つの確認をする。

1. **/skills**は、セッションから見えるスキルをすべて一覧にする。自分のものを探そう。私たちのスキルは一覧にあってオンだったが、環境には277個のスキルがあり、私たちのより先に「release」に合致するプラグインのスキルがいくつもあった。
2. **claude --debug**は、Claude Codeが何を読み込むかの詳細なログを書く。skillsの行を見る。私たちのログには、プロジェクトのスキルが読み込まれたことに加え、スキル一覧が予算を超えているという警告があり、いくつかのdescriptionは切り詰められる。
3. **claude plugin validate .claude/skills**は、ヘッダーが正しい形かを確認する。これは重要だ。壊れたヘッダーでもスキルは名前では動くが、Claudeはもう自力で合致させられない。私たちのは通った。

確認	分かること	私たちの結果
/skills	スキルは見えていて、オンか?	一覧にあり、オン(277スキル)
--debug	読み込まれたか? 一覧は切られているか?	読み込み済み、一覧が予算超過の警告
plugin validate	ヘッダーは解析できるか?	通過

ファイルが読み込まれ、ヘッダーも正しいなら、原因はdescriptionだ。Claudeはスキルを読み込むと決めるまで、あなたの指示を読まない。スキルごとに1行、名前とdescriptionを読み、あなたの言葉と照合する。私たちのdescriptionは「generates changelog documents from repository history」で、依頼は「今週は何を出荷した」だった。2つの文には共通する語がない。Claudeは私たちの指示を読んでいない。1行を読み、その行が私たちの言葉を使っていなかったのだ。

予算の警告は、Claude Codeが収まるようにdescriptionを切り詰めるという意味で、使用頻度の低いスキルから順に切られ、できたてのスキルは最も使われていない。自分のスキルが生き残ったか確認しよう。私たちのは生き残っていた。自分の言葉を使った依頼では読み込まれたからだ。

descriptionは、ファイルのためではなく、誰かが頼む瞬間のために書く。スキルが何をするか、いつ使うか、人が実際に打つ言葉を書く。私たちのはこうなった。

description: Writes this week's release notes from git log, grouped by scope (router, css, jsx). Use when the user asks what we shipped, what changed this week, for release notes, a changelog, or a summary of recent commits.

Anthropicの作成ガイドはもう1つルールを加えている。三人称で書くこと("Writes")。「I can help」や「You can use this」は使わない。

次に、新しいセッションで同じ依頼で実証する。「今週は何を出荷した?」は、Claudeが何かに触れる前にスキルを読み込み、ノートは私たちの形式で出た。新しいセッション5回中5回だ。

ベースラインも取る。ローカルの設定ファイルのskill overrideでスキルをオフにする(削除せずに隠せる)。オフではClaudeは自分の要約に戻り、オンではスキルが読み込まれた。違いを生んだのは運ではなくスキルだ。

限界もある。合致しすぎるdescriptionは、発動すべきでない場面でスキルを発動させる。思いつく限りの語ではなく、実際に使う語を足そう。

1つの依頼で修正は証明できたが、チームが頼るスキルはさまざまな言い方で頼まれる。Anthropicのskill-creatorはこのテストを説明している。20個の依頼で、スキルを読み込むべきものと、読み込むべきでないニアミスを混ぜる。ニアミスは近く聞こえても別の仕事で、たとえば「ステージ済みの変更のコミットメッセージを書いて」がそうだ。各依頼を新しいセッションで別々に実行し、スキルが読み込まれたかを記録する。skill-creator自身のスクリプトは、私たちのClaude Codeのバージョンではスキルを検出できなかったので、同じ20個の依頼を自作の短いスクリプトで実行した。

description	読み込むべき依頼のうち読み込んだもの	ニアミスのうち読み込んだもの
元	10回中4回	10回中0回
書き直し後	10回中10回	10回中0回

書き直し前は、スキルが読み込まれたのは「release notes」「changelog」「release」をすでに含む依頼だけだった。ステップ4の語の照合が、目の前で起きている。書き直し後は、読み込むべきすべての依頼で読み込まれ、それでもニアミスはすべて避けた。

絶対に外せないスキルは、強制する。名前を打つか、フックを足す。フックとは、決まったタイミング(ここでは送るメッセージごと)にClaude Codeが実行する小さなスクリプトで、その出力でClaudeにその作業にスキルを使うよう伝える。フックがあれば、元のdescriptionでも普通の依頼で読み込まれた。限界もある。テストの実行ごとに実際の利用量がかかり、フックはメッセージごとに1行を足す。本当に動かす必要のある少数のスキルにとどめよう。descriptionを変えるたびにリストを再実行すること。

私たちのリリースノートのスキルは、名前では毎回動き、普通の言葉の新しいセッションでは毎回スキップされ、書き直した1行で毎回読み込まれるようになった。理由は、Claudeが決める前にスキルごとに1行を読み、あなたの意図ではなくあなたの言葉で照合するからだ。

スキルが役立つのは、固定の出力で繰り返す作業だ。週次のノート、プルリクエストの説明、リリースのチェックリスト。1回きりの質問には向かないし、常に守られるべきルールのための道具でもない。それはフックの仕事だ。使われないスキルの山にも代償がある。多すぎると、Claude Codeは使用頻度の低いものからdescriptionを切り始める。良いdescriptionは確率を上げるが、想定していない仕事でスキルを発動させはしないし、数回の実行はデモなので、本当の確認はテスト依頼のリストだ。

唯一のルール: descriptionは、その作業を頼むときに実際に打つ言葉で書くこと。