Claude Codeのskillとは？

Claude Code を使っていると、同じ指示を毎回貼ることになります。「レポートを書くときはこの順番で進めて」「コミットメッセージはこの形式で」といった、自分の中では決まっている手順です。会話を変えるたびに、同じ説明を繰り返すことになります。

その手順をファイルに置いておき、必要なときにだけ読ませる仕組みが skill（スキル） です。中身はただのテキストで、プログラムは書きません。

導入して効果が大きかったのは、入力の手間が減ることではありませんでした。自分が毎回は思い出せない観点を、漏らさず検査できること。そして、一度調べた内容を型として蓄積できること。 この2点です。

この記事で扱うのは、スキルとは何か、導入すると何が変わるのか、CLAUDE.md との違い、指摘した内容を自動で蓄積させる設定、探し方と最初の1枚、そしてスキル化に向かないものです。仕組みの説明は公式ドキュメント（Extend Claude with skills）に沿い、数字は自分の環境で計測したものを使いました。

Claudeに渡しておく手順書

スキルは、Claude に前もって渡しておく手順書です。新しく入った人に業務マニュアルを渡しておき、必要な場面で参照してもらうのに近い形になります。

たとえば、記事を書かせるとき。スキルが無い状態では、毎回こう打つことになります。

毎回貼るのは手間なので、同じ内容をファイルに書き出して置いておきます。次からは「この件で記事を書いて」の一言で、同じ水準の指示が適用されます。

重要なのは、このファイルが会話のたびに読み込まれるわけではないという点です。必要になった瞬間だけ開かれます。細かい手順を長く書いても、普段の会話は重くなりません。

呼び出し方は2通りあります。

• 自分で /名前 と打って呼ぶ（/summarize-changes のように、スラッシュコマンドとして表示されます）
• Claude が「この依頼にはあのスキルが必要だ」と判断し、自動で読み込む

観点の抜けを防ぐ使い方

導入すると何が変わるのか。効果が分かりやすいのは開発です。

AIにコードを書かせると、動作するものは出てきます。問題は、動くかどうかとは別の観点が毎回落ちることです。性能、アクセシビリティ、セキュリティ。指摘されなければ気づかず、指摘できるかどうかは、その時の自分がその観点を覚えているかに依存します。

ここにスキルを1枚置くと、この依存が外れます。

たとえばアクセシビリティ。公開されている accessibility スキルは、WCAG 2.2 の項目を「知覚できる / 操作できる / 理解できる / 堅牢である」の4系統で保持しています。導入しておくと、画面を作るたびに次の観点まで検査されます。

• コントラスト比が基準を満たしているか
• キーボードだけで操作でき、フォーカスが視認できるか
• フォーカスされた要素が、固定ヘッダーなどに隠れていないか（2.2で追加）
• タップ領域が小さすぎないか（2.2で追加）
• 認証時にパスワードのコピー&ペーストを禁止していないか（2.2で追加）

太字にした3つは、WCAG 2.2 で新設された項目です。意識して追っていなければ知らないまま通過しますし、把握していても毎回思い出すのは現実的ではありません。

性能も同様です。Vercel が公開している react-best-practices は、React / Next.js の規則を8カテゴリに分け、優先度を付けて保持しています。データ取得が直列につながって待ち時間が積み上がっていないか。バンドルサイズを膨らませる書き方をしていないか。無駄な再レンダリングが発生していないか。いずれも動作確認では表面化せず、運用に入ってから影響が出る種類の問題です。

重要なのは、これらを自分で書く必要がない点です。公開されているものを導入するだけで済みます。コストはフォルダ1つ分で、使わない間の消費はほぼありません。

自分で書き足すなら、レビューで実際に指摘された内容が向いています。同じ指摘が二度出た時点で、その観点を1行加える。次回からは自動で検査されます。

調査結果を型に落とす使い方

もう一段効果が大きいのは、調査した結果そのものをスキルにする使い方です。ここからは自分で書く側の話になります。

コンサルの調査には型があります。論点を立てて依頼主と合意する。一次情報に当たる。構造化する。自分の結論に反証を試みる。納品形式に落とす。手順として理解していても、毎回この順序で同じ品質が出るわけではありません。

そこで、一般論として通用する部分を調べ切り、ワークフローとして書き出します。 調査範囲は日本語に限定しません。規格や公式ドキュメント、実務家が公開している資料は英語圏のほうが充実しており、日本語で検索すると二次情報の要約に当たりやすいためです。海外の一次資料まで確認したうえで、日本の商習慣に合わせて補正し、型に落とします。

自社で使っている調査用のスキルは、この形になっています。

1. 型の選択 — 何を出すのか（市場調査か、事業評価か、提言か）を先に決める
2. 論点設計 — 何を明らかにするかを箇条書きにし、承認を取ってから動く
3. 調査実行 — 出典付きで一次情報を集める
4. 統合・構造化 — 事実と解釈を分けて並べ直す
5. 批判レビュー — 自分の結論に反証を試みる。数字の出所、因果と相関の取り違え、逆風を追い風と読んでいないか
6. 仕上げ・納品 — 決まった体裁に落とす

本体とは別に、フレームワーク集、良い報告書の実例、品質チェックリスト、報告書のテンプレートを分けて置いています。分量の多い資料は必要なときだけ読まれるため、本体は薄いまま維持できます。実物はコンサルファームアナリストレベルのSKILL公開で配布しています。

こうしておくと、「この業界を調べて」の一言で、論点設計から批判レビューまでが順に流れます。単発の質問だったものが、毎回同じプロセスになります。

最も効果があるのは、同じ失敗を繰り返さなくなることです。 出来上がったものを見て「ここが甘い」と指摘すれば、その観点がチェックリストに1行加わります。次回からは、言わなくても検査されます。指摘がそのまま資産として蓄積される形です。

分量についても触れておきます。自分の環境にあるスキルは合計で1万行近くありますが、常時読み込ませれば会話は成立しません。必要な1枚だけが開かれるため成立しています。

フォルダ1つとファイル1枚という実体

ここまでの内容が、ファイル1枚で動きます。実物を見たほうが早いので、中身を示します。

スキルは、フォルダを1つ作り、その中に SKILL.md という名前のファイルを1枚置くだけです。

~/.claude/skills/summarize-changes/
└── SKILL.md

先頭の ~ はホームフォルダのことで、Mac なら /Users/自分の名前、Windows なら C:\Users\自分の名前 にあたります。その下の .claude は、Claude Code が設定を置く場所です。フォルダ名の summarize-changes が、そのままコマンド名 /summarize-changes になります。

.md は Markdown（マークダウン）という書き方のテキストファイルです。見出しに # を付ける、箇条書きに - を使う、という程度のもので、専用のソフトは不要です。メモ帳でも書けます。

ファイルの中身は2つに分かれます。

---
description: 未コミットの変更を要約し、リスクのある箇所を指摘する。
  ユーザーが「何が変わった?」と聞いたとき、コミットメッセージを求めたときに使う。
---

## 現在の変更

!`git diff HEAD`

## 手順

上の差分を2〜3個の箇条書きで要約し、そのあとに気づいたリスク
（エラー処理の漏れ、ハードコードされた値、更新が要りそうなテスト）を挙げる。
差分が空なら、未コミットの変更はないと答える。

--- で挟まれた上半分を frontmatter（フロントマター） と呼びます。ここはファイルの設定欄で、Claude 向けの説明書きや動作のオプションを置きます。description: が「いつ使うスキルなのか」の説明です。

--- から下が本文で、スキルが起動したときに Claude が実際に従う指示になります。書式の決まりはなく、通常の日本語で手順を並べれば動作します。

一箇所だけ独自の記法があります。本文中の !`git diff HEAD` は、Claude が読む前にそのコマンドを実行し、出力に置き換える書き方です。指示が届く時点で、実際の変更内容が組み込まれた状態になります。

前章で触れた資料の分割も、このフォルダの中で行います。詳しい資料は reference.md、実行させたい処理は scripts/ へ。公式の推奨は、SKILL.md を500行以内に収め、細かい資料を別ファイルに逃がす形です。

置き場所によって、効く範囲が変わります。

自分がどのプロジェクトでも使うものは個人の場所へ。チームで共有したいものはプロジェクトの .claude/skills/ に置き、リポジトリに一緒にコミットします。同じ名前が両方にある場合は、個人のほうが優先されます。

なお、以前からあるカスタムコマンド（.claude/commands/deploy.md のようなファイル）は、スキルに統合されました。既に作成済みであれば、そのまま動作するので置き換えは不要です。

CLAUDE.md との違い

ここまで読むと、「その手順は CLAUDE.md に書けば済むのでは」という疑問が出ます。

CLAUDE.md は、プロジェクトのルールを書いておくファイルです。会社の前提、サーバーの構成、やってはいけないこと。Claude Code はこれをセッションの開始時に全文読み込み、その会話の間ずっと効かせます。実質的に、常設の指示書として機能します。

スキルとの違いは、読み込まれるタイミングです。

この差は、量が増えたときに表れます。

前提として、Claude が一度に読める文章量には上限があります。これをコンテキストと呼びます。ここに入れた文章はモデルが毎回読み直すため、常時読み込ませるものが増えるほど、本題に使える余地が減ります。

自分の環境で計測すると、次のとおりでした。

30万字を CLAUDE.md に書けば毎回全文が読み込まれますが、スキルであれば該当する1つが呼ばれたときだけ本文が入ります。

公式ドキュメントの整理が的確です。同じ指示を何度も貼っているとき、あるいは CLAUDE.md の一節が「事実」ではなく「手順」に育ってきたときが、スキルに切り出すタイミングです。会社の前提や禁止事項は CLAUDE.md のまま。「レポートを作るときの進め方」のような長い段取りはスキルへ、という分け方になります。

フィードバックを自動で蓄積させる設定

2つのファイルの役割を踏まえたうえで、育て方の話に戻ります。

指摘を1行加える、と前に書きました。ただし、手作業で加えていると続きません。指摘した直後は次の作業に移りたい状態にあり、ファイルを開いて追記する手間が挟まると、そのまま忘れます。

そこで、反映するルール自体を書いておきます。 置き場所は、全プロジェクトに効くグローバルの CLAUDE.md（~/.claude/CLAUDE.md）です。書くことは2つあります。

1つめは、失敗したときの扱い。

反省文ではなくルールとして書かせる点が重要です。「以後気をつけます」は次回に反映されません。「この確認をしてから報告する」であれば機能します。

2つめは、フィードバックの振り分け。

判断基準を1行書いておくかどうかで、結果が大きく変わります。 これが無いと、特定の案件の事情がスキル本体に混ざり、次の案件で前提が違ったまま動きます。

この2つを置いておくと、「その言い回しは硬い」「この観点が抜けている」と指摘した時点で、スキル側に反映されます。こちらは指摘するだけで済み、同じ修正を二度伝える場面が減ります。

ただし、自動で蓄積される分、放置すると矛盾したルールが増えます。 ときどき SKILL.md を通しで読み返し、重複と古くなった記述を落としてください。追記させる仕組みと、整理する時間は対で必要です。

起動可否を決める description

常時読み込まれる側の説明文、つまり description が、実務では最も重要です。中身が同じスキルでも、ここを書けているかどうかで、使われるものにも死蔵されるものにもなります。

書くべきことは2つ。何をするかと、いつ使うかです。しかも、自分が実際に打ちそうな言葉で書く必要があります。Claude は description の文面と依頼文を照らして起動を決めるため、書いていない言い回しには反応しません。

• 弱い例: 記事作成スキル
• 有効な例: 記事・ブログ・コラムの執筆依頼で使う。「記事を書いて」「note用にまとめて」「この調査を記事化して」等の依頼が来たら適用する。企画設計→フック→本文→セルフレビューの順で進める。

省略した場合はどうなるか。Claude Code は、description が無いと本文の最初の段落を説明文の代わりに使います。# 記事作成スキル という見出し1行がそれに充てられると、どの依頼で起動すべきか判断できません。厄介なのは、手動で /名前 と打てば正常に動作してしまう点です。 自動起動しないだけなので、不備に気づけません。

CLAUDE.md 側に「記事の依頼ではこのスキルを使う」と書いて補う方法はあります。ただしスキル単体では機能していない状態なので、別のプロジェクトに移した時点で呼ばれなくなります。人に配布することもできません。

長ければよいわけでもありません。description と when_to_use を合わせた文字列は、一覧に載る時点で1,536字に切られます。要点は先頭に置いてください。

さらに、一覧全体にも予算があります。予算はモデルのコンテキスト長の1%で決まり、あふれると呼び出し回数の少ないスキルから説明文が削られます。名前だけは残るため、一見すると導入できているように見えて、Claude が起動を判断する材料だけが消えている状態になります。現在の消費量は /doctor で確認できます。一覧のコンテキスト消費量と、その内訳の上位が出ます。

スキルを増やすほど賢くなるわけではない、という根拠がここにあります。使わないスキルが、使うスキルの説明文を押し出します。

探し方と最初の1枚

自分で書く前に、既存のものを探すほうが早い場合もあります。開発まわりの網羅系は、多くが既に公開されています。

find-skills を導入しておくと、会話の中で「◯◯できるスキルはあるか」と聞いた時点で起動し、検索から提案まで実行します。内部で使っているのは Skills CLI です。

npx skills find react performance   # キーワードで検索
npx skills add <パッケージ名>        # 導入
npx skills update                   # まとめて更新

npx は Node.js に付属するコマンドで、インストールせずにその場で実行できます。ターミナルを使いたくない場合は、Claude に「Reactのパフォーマンス改善のスキルを探して」と頼めば、find-skills が同じ処理を行います。ブラウザで見るなら skills.sh に一覧があり、インストール数のランキングが出ています。

導入前の確認として、find-skills には次の基準が書かれています。インストール数は1,000以上が目安で、100未満は慎重に扱う。発行元は公式アカウント（anthropics、vercel-labs など）のほうが安全で、リポジトリのスター数が100未満のものは懐疑的に見る。検索結果だけを見て勧めない、とも明記されています。

もうひとつ、外部スキルを19個導入して分かったことがあります。外部スキルは自作スキルと領域が重なります。 「調査して」「LP作って」のような依頼で、どちらが起動するかが安定しなくなりました。自社では各領域の主役を自作スキル側に固定し、外部スキルは観点や型を借りる部品として使う、という整理をしています。既定の出力言語が日本語でないスキルも混ざっているため、そのまま前面に立てると想定と違う出力になります。

自分で書く場合の手順

該当するものが無ければ書きます。手順は4つです。

1. フォルダを作る。ターミナルで mkdir -p ~/.claude/skills/名前 と打つか、エクスプローラーやFinderで作成しても構いません
2. その中に SKILL.md を作る。frontmatter に description、その下に手順を書きます
3. 保存する。Claude Code は再起動しなくても読み込みます
4. 通常どおり依頼し、起動するか確認する

題材は、新たに考案せず、自分が毎回貼っている指示か、同じ指摘を二度した観点から選んでください。先に効果が出るのは、既に手順が固まっているほうです。

最初の1枚は、これだけでも動作します。

---
description: コミットメッセージを作る。
  ユーザーが「コミットして」「コミットメッセージ考えて」と言ったときに使う。
---

変更内容を確認し、日本語1行のコミットメッセージを作る。

- 50文字以内。何をしたかを動詞で書く
- 「修正」「更新」だけで終わらせず、何を修正したか書く
- 複数の変更が混ざっていたら、コミットを分けるよう提案する

慣れたら、依頼ごとに変わる値を渡せます。本文に $ARGUMENTS と書いておくと、/fix-issue 123 と打ったときの 123 がそこに入ります。

起動しないときの確認は3つ。まず「使えるスキルを教えて」と聞いて一覧に出るか。次に description に自分が使う言葉が入っているか。それでも起動しなければ /名前 で直接呼びます。frontmatter の書式が壊れていると本文だけ読み込まれるため、原因は --debug を付けて起動すると確認できます。

誤起動を防ぐ設定

frontmatter には、挙動を絞る設定も置けます。いずれも任意ですが、表の上2つは早めに把握しておく価値があります。

デプロイ・送信・コミットのような副作用のあるスキルには、disable-model-invocation: true を付けてください。 コードが良さそうだから、という理由で Claude がデプロイを判断する状況を作らないためです。逆に user-invocable: false は、自分がコマンドとして打つ意味のない背景知識に使います。

一覧の管理は /skills メニューから行えます。スキルを選んで Space を押すと、オン / 名前だけ / 手動専用 / オフ の4状態を切り替えられます。共有リポジトリに入っていて中身を編集したくないスキルは、ここで名前のみの表示に切り替えると、説明文の予算が空きます。

スキル化に向かないもの

作り方が分かると何でもスキルにしたくなりますが、向かないものもあります。

• 一度きりの作業。 会話で頼めば済みます。次に使う予定がないなら、ファイルが増えるだけです
• 変わらない事実・前提。 会社情報、サーバーの構成、禁止事項。常に効いている必要があるため CLAUDE.md 側です
• その案件だけに通じる事実。 個別の数字や現場の事情は、別ファイルに分けます。スキルに混ぜると、他の案件で前提が違ったまま動きます
• 確実に毎回守らせたい規則。 スキルは「読まれる」だけで、強制力はありません。特定のコマンドを必ずブロックしたい、コミット前に必ずフォーマッタをかけたい、といった要求はフック（hooks）という別の仕組みのほうが確実です
• 数を増やすこと自体が目的になっているとき。 前述のとおり、使わないスキルは使うスキルの説明文を押し出します

導入したのに機能していない、という状態も起こります。多くの場合、本文は残っているのにモデルが別の手段を選んでいます。対処は、description と本文を具体的にするか、フックで強制するか。長い会話が自動で要約されたあとは、スキルの内容が先頭だけに切り詰められて再添付されるため、重要なスキルは呼び直すと戻ります。

---

導入は、公開されている網羅系を1つ入れて効果を見るところからが早いです。アクセシビリティでも性能でも、自分が毎回は思い出せない領域を選んでください。そのうえで、グローバルの CLAUDE.md に反映ルールを1つ書いておく。あとは通常どおり指摘するだけで、その内容が蓄積されていきます。