Claude Codeのスキル（Skills）とは｜CLAUDE.mdに書いた手順を、必要な時だけ読ませる

Claude Codeのスキル（Skills）は、手順や調べものの資料を入れておく「SKILL.md」というファイルで、使うときだけ会話に読み込まれる。
CLAUDE.mdは毎回読まれるので、長くなるほど毎回その分のコストがかかる。
公式のドキュメントには、CLAUDE.mdの一部が「事実」ではなく「手順」になってきたら、スキルにする合図だ、と書いてある。

僕は今日、自分の環境を数えてみた。
全プロジェクト共通のCLAUDE.mdは112行・25,855バイトで、個人用のスキルのフォルダは14個ある。
この記事は、公式ドキュメントの内容と、その数字を見ながら僕が考えたことを書いている。

スキルとは何か

公式の説明では、スキルはSKILL.mdというファイルを作ると、Claudeが使える道具箱に加わるものだ。
Claudeが必要だと判断したときに使うこともできるし、「/スキル名」と打って自分で呼ぶこともできる。

SKILL.mdは二つの部分でできている。

• 上の部分（フロントマター）：いつ使うかを書く。descriptionに書いた文が、Claudeが自動で呼ぶかを決める手がかりになる
• 下の部分（本文）：呼ばれたときにClaudeが従う手順や資料

置き場所は、使いたい範囲で決まる。
~/.claude/skills/ の下に置くと、自分のすべてのプロジェクトで読み込まれる。
プロジェクトの .claude/skills/ に置いてリポジトリに入れると、そのプロジェクトで作業する人全員が使える。

CLAUDE.mdとの違いは「いつ読まれるか」

公式ドキュメントの言い方では、スキルの本文は使われたときにだけ読み込まれる。
だから、長い参考資料を置いても、必要になるまでコストはほとんどかからない。

では、毎回読まれる部分はどこか。
ドキュメントによると、Claude Codeは全スキルの名前と説明の一覧を会話に入れている。
この一覧は、スキルがあるだけで毎ターン分のコストになる。

つまり、整理するとこうなる。

• CLAUDE.md：本文が毎回読まれる
• スキル：名前と説明だけが毎回読まれ、本文は使うときだけ読まれる

僕のCLAUDE.mdは、冒頭に「常時効かせる最小ルールと、発火条件だけを置く。規約の本文は各スキルが持つ」と書いてある。
それでも25,855バイトまで育っていて、「最小」とは言いにくい。
ただ、コーディング規約やPowerPointの作り方のような長い手順は、すでにスキル側に逃がしてある。
たとえば人間の行動についての調査ノートは、SKILL.mdが8,035バイトの目次で、中身は別ファイルに分けてある。

スキルにする目安

公式ドキュメントが挙げているのは、次のような場面だ。

• 同じ指示やチェックリスト、複数の手順を、何度もチャットに貼っている
• CLAUDE.mdの一部が、事実ではなく手順になってきた

僕はここに、もう一つ足して考えている。
「特定の作業のときだけ要る」ものは、スキルに向いている。
「どんな作業でも守ってほしい」ものは、CLAUDE.mdに残す。
この線引きは公式にそう書いてあるわけではなく、僕の整理だ。

CLAUDE.mdに規約ファイルを書いておく話は、コーディングエージェントにCMS改修を任せる前に、規約ファイルを1枚書いた話に書いた。
あの規約ファイルが育ちすぎたら、次に考えるのがスキルへの切り出しだと思う。

descriptionの書き方と、1,536文字の上限

Claudeがスキルを自動で選ぶ手がかりは、descriptionだ。
公式ドキュメントによると、descriptionとwhen_to_useを合わせた文は、一覧の中では1,536文字で切られる。
なので、いちばん大事な使いどころを先頭に書く。

スキルが増えすぎたときの挙動も書いてある。
一覧に使える文字数は、モデルのコンテキストウィンドウの1%を目安に決まる。
あふれると、あまり呼ばれていないスキルから順に、説明が削られる。
名前は残るが、説明が削られると、Claudeが依頼とスキルを結びつけるためのキーワードが消える。

だから、14個ぐらいなら気にしなくていいが、数十個になったら、使っていないスキルを減らすことも大事になる。
公式には、スキルごとのコストと使われた回数を見る「/skill-doctor」というコマンドが用意されている（v2.1.252以降）。

スキルを無視されたときの考え方

これは、使う側として一番ありそうな悩みだと思う。
公式のトラブルシューティングには、いくつかの原因が書いてある。

• 毎回必ず守らせたいルールを、スキルに書いている：その場合は、スキルではなくフックに移す。フックはイベントのたびにClaude Codeが実行するので、Claudeが従ったかどうかに関係なく動く
• 判断を伴う指示が、最初のターンだけ守られる：Claude Codeはスキルを呼んだ時点で本文を会話に入れ、後のターンでファイルを読み直さない。「テストを実行する」ではなく「編集のたびにテストを実行する」のように、作業全体にかかる書き方にする
• 会話が圧縮（compact）された後に効かなくなった：もう一度スキルを呼んで、内容を戻す

フックについては、Claude Codeのフック（hooks）の使い方に書いた。
「必ず守らせたいこと」は、文章で頼むのではなく、仕組みで止める。
スキルとフックは、役割が違う。

まず一つ作るなら

公式の最初の例は、短い。
~/.claude/skills/summarize-changes/ というフォルダを作り、中にSKILL.mdを置いて、descriptionに「未コミットの変更を要約し、危ない点を指摘する。変更点を聞かれたとき、コミットメッセージが欲しいとき、差分のレビューを頼まれたときに使う」と書く。
これだけで、スキルとして動く。

僕なら、最初に切り出すのは「毎回同じ順番でやっている作業」だと思う。
CLAUDE.mdを開いて、事実ではなく手順になっている段落を探す。
それを一つだけ、SKILL.mdに移す。
効果の大きさは測っていないので、まずは一つ試して、CLAUDE.mdの行数が減るかを見るのがいい。

まとめ

• スキルは、使うときだけ本文が読み込まれる手順や資料のファイル（SKILL.md）
• CLAUDE.mdは毎回読まれる。手順が育ったら、スキルに切り出す
• スキルの名前と説明は毎ターン読まれる。説明は1,536文字で切られ、増えすぎると説明が削られる
• 必ず守らせたいことは、スキルではなくフックで止める
• 僕の環境は、CLAUDE.mdが112行・25,855バイト、個人用スキルが14個（2026年10月28日に数えた）

出典

• Extend Claude with skills｜Claude Code Docs（2026年10月28日に確認。SKILL.mdの構成・置き場所・本文が使うときだけ読まれること・1,536文字の上限・一覧の予算・/skill-doctor・トラブルシューティング）