Skills（スキル）　手順書を渡す

一行でいうと

Claudeに手順を教える指示書ファイルです。SKILL.md という1つのファイルに「こういうときは、こうやる」と書いておくと、Claudeがその場面で自分で読みに行きます。

Skillsが必要な情報を三段階で開く仕組み

Skillsは、存在を知る、手順を読む、資料を使う、の順に必要な分だけ開きます。

なぜ必要になったのか

CLAUDE.mdに手順を書き足すほど、会話は重くなります。Skillsは、この矛盾を解決する仕組みです。

Claude Codeを毎日使っていると、必ずこうなります。

「議事録はこの形式で、この順番でまとめて」を毎回貼っている
「資料を要約するときは、必ず5W1Hで整理して」を毎回書いている
CLAUDE.mdに手順を書き足していたら、どんどん長くなってきた

最後の問題が地味に効きます。CLAUDE.mdは毎セッション全文が読み込まれるので、手順書を足すほど、毎回の会話が重くなる。しかもその手順の9割は、今日の作業には関係ありません。

Skillsはここを解決します。普段は名前と説明文だけが待機していて、必要な場面が来たときに初めて本文が読み込まれる。だから何十個持っていても、日常の会話は軽いままです。

仕組み: 3段階で開いていく

Skillsは3段階を経て開きます。待機、発火、実行の順です。公式には progressive disclosure（段階的開示）と呼ばれます。

図書館の本に似ています。棚には背表紙（名前と説明）だけが並んでいて、必要な1冊だけを抜いて開く。全部の本を最初から広げておく人はいません。

ファイルの形はごく単純です。

~/.claude/skills/gijiroku-memo/SKILL.md

---
name: gijiroku-memo
description:
会議メモを社内フォーマットに整えるとき。「メモを整形」「議事録用に」で発火
---
# 会議メモの整形手順

「背景・決定事項・ネクストアクション」の順に並べ替える
2. 略語は初出でフルスペルを併記する
3. 機密の識別情報は絶対に書き出さない

上のYAML部分が「背表紙」、その下が「本文」です。

ファイル名にも厳密なルールがあります。中身を書き始める前に知っておくと、あとの事故が減ります。

SKILL.md というファイル名は、大文字小文字も含めて完全に一致していないと認識されません。skill.md や SKILL.MD といった表記ゆれは通りません。フォルダ名は kebab-case、つまり gijiroku-memo のようにハイフン区切りの小文字だけで書きます。スペース、アンダースコア、大文字はどれも避けてください。もう一つ、スキルのフォルダの中に README.md を置かないこと。ドキュメントは全部 SKILL.md 本体か、その先に置く参照ファイルに書きます。別にREADME.mdを用意しても、Claudeはそちらを読みには行きません。

「軽い」という感覚は、実は具体的な数字に支えられています。

普段は名前と説明文だけが待機している、という設計は、この数字の積み上げの上に成り立っています。

よくある誤解と罠

罠1: 「スキルが発火しない」の原因はたいてい説明文

いちばん多いつまずきがこれです。原因の大半は、description に書いた言葉が弱いこと。

Claudeは説明文を読んで「今これを開くべきか」を判断します。だから、自分が実際に打つ言葉を説明文に入れておくのがコツです。「文書整形スキル」より、「『メモを整形して』『議事録用にまとめて』と言われたとき」のほうが確実に発火します。

視点

説明文は検索キーワードだと思う

自分が将来どんな言い方で頼むかを想像して、その言い回しをそのまま説明文に書く。これだけで発火率が変わります。

公式ガイドは、descriptionの書き方を1つの式にまとめています。「何をするか」＋「いつ使うか」＋「主要な能力」の3つを、この順で書く。

良い例と悪い例を並べると分かりやすくなります。

descriptionの悪い例／良い例

悪い例

「プロジェクトを助けます」は、何をするかが曖昧すぎます。「洗練されたマルチページ文書システムを作成」は、いつ使うかが書かれていません。「階層関係を持つProjectエンティティモデルを実装」は、専門的すぎてユーザーが実際に打つ言葉と合いません。

良い例

「Figmaのデザインファイルを分析し、開発者向けのハンドオフ資料を生成する。.figファイルがアップロードされたとき、『design specs』『component documentation』『design-to-code handoff』と言われたときに使う」。何をするか、いつ使うか、主要な能力の3つが、この1文に収まっています。

発火の異常は、2方向で診断できます。

過少発火のサインは、発火すべき場面で発火しない、使う側が毎回手動で有効化している、いつ使うのかという質問が飛んでくる、の3つです。直し方はdescriptionに詳細とニュアンスを足すこと。専門用語のキーワードを具体的に入れると効きます。

過剰発火のサインは逆に、関係ない話題でも発火する、使う側がスキルを無効化し始める、目的が伝わらず混乱が起きる、の3つ。直し方は、descriptionに「これはしない」を書き足すことです。「CSVファイル向けの高度なデータ分析。統計モデリング・回帰・クラスタリングに使う。単純なデータ探索には使わない」のように、Do NOT use for に当たる一文を足すと、境界がはっきりします。

自分で診断する簡単な方法もあります。Claudeに直接「このスキルをいつ使う?」と聞くと、descriptionの文面を引用して答えが返ってきます。その引用に、自分が想定している使いどころが含まれているかを確かめるだけで、足りない部分が見えてきます。

罠2: カスタムコマンドとスキルを別物だと思っている

以前は .claude/commands/ に置くカスタムコマンドと、スキルは別の仕組みでした。今は統合されていて、どちらも /名前 で呼べます。古い記事を読むとここで混乱しがちです。

この統合は、思っているより徹底しています。/doctor や /code-review、/batch、/debug、/loop といった、一見「組み込みコマンド」に見えるものの多くも、実はスキルです。固定ロジックをそのまま実行するタイプのコマンドと違い、これらはプロンプトベースで動いています。Claudeに詳細な指示を渡し、あとはツールを使ってその場で組み立てさせる仕組みです。disableBundledSkills という設定で無効化しない限り、どのセッションでも最初から使える状態になっています。

罠3: 誰が呼べるかを設計していない

2つの軸があります。

disable-model-invocation: true … 人間しか呼べない。デプロイのような副作用のある操作に付ける
user-invocable: false … Claudeしか呼べない。背景知識として持たせたいものに付ける

うっかりClaudeが自分でデプロイを始めないように、という設計です。

使いどころ

共通するのは「毎回同じ品質で出したい仕事」です。品質を安定させたい作業ほど、スキル化の効果が出ます。

資料レビュー会のフォーマット（批判的吟味の型を固定する）
社外資料の構成テンプレート（字数制限と章立てを毎回同じに）
顧客向け説明文のトーン規定（専門用語を開く・断定を避ける）
自分の書き癖のチェックリスト（推敲を任せる）

発火率は測れる

公式マーケットプレイスの skill-creator を入れると、スキルのテストができます。テストケースを作り、スキルあり・なしで結果を比較し、説明文を自動で調整してくれる。

Anthropic自身がこう書いています。「テストは、動いている『ように見える』スキルを、動くと『分かっている』スキルに変える」。作りっぱなしにしないための道具です。

スキルの数が増えてくると、また別の問題が出てきます。同時に有効化しているスキルが20から50個を超えたら、選択的な有効化を検討したほうがいいというのが公式の目安です。関連する能力ごとにスキルを「パック」としてまとめる、普段使わないものは無効化しておく、といった手当てが要ります。持っているスキルの数と、実際に効いているスキルの数は、別の話だからです。