Claude Code のスキルは、.claude/skills/<名前>/SKILL.md を置くだけで作れる「必要なときだけ読み込まれる手順書」です。自動で使われるかは description の書き方で決まり、/スキル名 で直接呼ぶこともできます。2026 年 10 月時点の公式仕様に沿って、1 つ作って動かすまでの手順と、CLAUDE.md・サブエージェントとの使い分けをまとめます。
SNSでシェアして、他のエンジニアにも教えてあげましょう
Claude Code スキルは、.claude/ に手順や知識を書いておくと、Claude が必要なときだけ読み込んで使う仕組みです。自動で使われるかどうかはフロントマターの description で決まり、/ と打てば自分で直接呼び出せます1。この記事では、2026 年 10 月時点の公式ドキュメントに沿ってスキルを 1 つ作り、実際に Claude Code（v2.1.289）で動かした結果を載せます。フロントマターの主な項目、scripts/ と references/ の置き方、CLAUDE.md やサブエージェントとの使い分けまで、この 1 本で判断できるようにまとめました。
スキルは「必要になったときだけ読み込まれる手順書」です。中身はフォルダ 1 つで、必須なのは SKILL.md だけです。SKILL.md は、YAML のフロントマター（--- で囲んだ設定）と、Claude に渡す指示の本文でできています1。
いちばん大事な特徴は、読み込みが 3 段階に分かれていることです。Anthropic はこれを「段階的な開示（progressive disclosure）」と呼んでいます2。
name と description だけが読み込まれる/ で呼んだとき）に SKILL.md の本文が入るreferences/ の資料や scripts/ のスクリプトは、本文の指示に従って必要な分だけ読む・実行する
CLAUDE.md は毎回すべて読み込まれます。スキルは本文が使うときまで読み込まれないので、長い手順や資料を置いても普段の会話の邪魔をしません。公式ドキュメントも「同じ指示を何度も貼っているとき」や「CLAUDE.md の一部が事実ではなく手順になってきたとき」にスキルを作るよう勧めています1。
スキルは 2025 年 10 月 16 日に Anthropic が「Agent Skills」として発表し、同じ日に出た Claude Code v2.0.20 で使えるようになりました32。2025 年 12 月 18 日には、ほかの AI ツールでも使えるよう仕様が公開標準として公開されています45。
その後、Claude Code v2.1.3（2026 年 1 月 9 日公開）で、それまで別物だった「カスタムスラッシュコマンド」とスキルが統合されました3。いまは次の 2 つが同じ / を作り、同じように動きます1。
| 置き場所 | 呼び出し | 違い |
|---|---|---|
.claude/（従来のコマンド） | / | 1 ファイルだけ。name と paths のフロントマターは使えない |
.claude/（スキル） | / | フォルダに付属ファイルを置ける。Claude が自動で使える |
既存の .claude/ はそのまま動きます。同じ名前があればスキルが優先されます1。新しく作るならスキルにしておくと、あとから資料やスクリプトを足せます。
理由は 3 つあります。1 つ目は、CLAUDE.md を短く保つためです。公式のベストプラクティスは CLAUDE.md を「毎回必要なことだけ」に絞るよう求めています。「たまにしか要らない知識や手順はスキルへ」というのが公式の線引きです6。
2 つ目は、同じ書き方がほかのツールでも通じるためです。スキルは agentskills.io で公開された仕様に沿っています4。この仕様の項目（name・description・license・compatibility・metadata・allowed-tools）だけで書けば、claude.ai へのアップロードや Skills API でもそのまま使えます1。
3 つ目は、Claude Code 自身がスキルを前提に作られ始めているためです。/ や /、/ などの組み込み機能の多くは「バンドルされたスキル」として提供されています。/ のように、手順を学んで .claude/ に書き出すものもあります1。
読み込みの段階ごとの目安は、Agent Skills の仕様に数字で書かれています。起動時の負担はスキル 1 つあたり約 100 トークンで、本文は 5,000 トークン未満が推奨です4。
| 段階 | トークン数の目安（トークン） |
|---|---|
| 1. メタデータ（name・description） | 100 |
| 2. SKILL.md の本文（推奨の上限） | 5,000 |
スキルを 30 個入れても、起動時に増えるのはおおよそ 3,000 トークンです。手順書を全部 CLAUDE.md に書くより、ずっと軽く済みます。
ここからは、未コミットの差分を要約してリスクを指摘する review-diff スキルを作ります。公式のクイックスタートにある例を日本語向けに書き直したものです1。前提は Claude Code v2.1.289（2026 年 10 月 3 日公開）と、git のリポジトリです。
置き場所で、どのセッションから使えるかが決まります1。
| 場所 | パス | 使える範囲 |
|---|---|---|
| 個人 | ~/ | 自分のすべてのプロジェクト（クラウドのセッションでは使えない） |
| プロジェクト | .claude/ | そのリポジトリ。コミットすればチーム全員 |
| サブディレクトリ | <dir>/ | そのディレクトリの中で作業したとき（モノレポ向け） |
| プラグイン | <plugin>/ | プラグインを入れた環境。/ で呼ぶ |
| 組織 | 管理設定のディレクトリ | 組織が配った全員 |
同じ名前が複数あるときは、組織 → 個人 → プロジェクトの順に優先されます1。チームで使う手順はプロジェクトに置いてコミットし、自分だけの癖は個人に置く、と分けるのがわかりやすいです。
フォルダを作り、SKILL.md を置きます。
mkdir -p .claude/skills/review-diff
---
name: review-diff
description: 未コミットの変更を要約し、リスクを指摘する。「何を変えた？」「差分を見て」「コミット前にチェックして」と頼まれたときに使う。
allowed-tools: Bash(git diff *)
---
## 現在の差分
!`git diff HEAD`
## 指示
上の差分を 3 行以内で要約し、そのあと気になる点（エラー処理の漏れ、ハードコードされた値、更新が必要なテスト）を箇条書きで挙げる。
差分が空なら「未コミットの変更はありません」とだけ答える。
!`git diff HEAD` の行は「動的なコンテキストの注入」です。Claude が読む前に Claude Code がコマンドを実行し、その出力で行を置き換えます1。Claude は最新の差分が埋め込まれた状態で指示を読むので、推測ではなく実際の変更に基づいて答えます。
allowed-tools は、このスキルを呼んだターンの間だけ、書いたツールを確認なしで使えるようにする項目です。次のメッセージを送ると許可は消えます。また、ほかのツールを禁止する設定ではありません1。
自動で使われるかどうかは、ほぼ description で決まります。Claude はセッション開始時に全スキルの名前と説明の一覧を受け取り、依頼に合うものを選ぶからです12。書き方のコツは次の 3 つです。
description と when_to_use は合わせて 1,536 文字で切られます。スキルが多いと、使用頻度の低いスキルから説明が省かれます1逆に、勝手に動いてほしくないスキルもあります。本番へのデプロイや Slack への投稿のように副作用があるものは、disable-model-invocation: true を付けます。こうすると Claude は自分では呼べず、説明も一覧から消えるので、/ で呼んだときだけ動きます1。
SKILL.md は 500 行以内に収め、詳しい資料は別ファイルに分けるのが公式の目安です14。Agent Skills の仕様では、次のフォルダ構成が推奨されています4。
review-diff/
├── SKILL.md # 必須。概要と、どのファイルをいつ読むか
├── references/ # 詳しい資料（必要なときだけ読む）
│ └── checklist.md
├── scripts/ # 実行するスクリプト（中身は読み込まれず、実行される）
│ └── collect.sh
└── assets/ # テンプレートなど
付属ファイルは、SKILL.md から「何が書いてあり、いつ読むか」を添えてリンクします。リンクが無いと、Claude はそのファイルがあることを知りません。
## 追加の資料
- セキュリティの観点の詳しいチェック項目は [references/checklist.md](references/checklist.md)
- 差分の統計は `${CLAUDE_SKILL_DIR}/scripts/collect.sh` を実行して得る
${CLAUDE_SKILL_DIR} は、スキルのフォルダの絶対パスに置き換わります。作業ディレクトリがどこでも同じスクリプトを指せるので、スクリプトを呼ぶときはこれを使います。フロントマターに次のように書けば、確認なしで実行させることもできます1。
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/collect.sh *)
まずフロントマターが正しく読めるかを確かめます。claude plugin validate は v2.1.233 以降で使えます1。
claude plugin validate .claude/skills
Validating components in: /private/tmp/write-article/lab/cc-skills/.claude/skills
✔ Validation passed
次に、/ で直接呼びます。下の GIF は、API_KEY のハードコードと 0 で割る関数を足した差分で実行した結果です（実際の出力）。
自然な言葉で頼んだ場合も試しました。Sonnet に「差分を見て」と頼むと、Claude は Skill ツールで review-diff を選びました。一方、Haiku に「コミット前にチェックして」と頼んだときは、スキルを使わずに git diff を直接実行しました。自動起動はキーワードの一致ではなく、モデルの判断です。確実に使わせたいときは / で呼ぶのが確実です。
フロントマターはすべて省略できます。ただし description は書くことが推奨されています1。よく使う項目を表にまとめます。
| 項目 | 役割 | 使いどころ |
|---|---|---|
name | / メニューに出る名前。省略時はフォルダ名 | 英小文字・数字・ハイフンで付ける |
description | 何をするか・いつ使うか | 自動起動の判断材料。最重要 |
when_to_use | 起動のきっかけになる言い回しの追記 | description と合わせて 1,536 文字まで |
argument-hint | 補完時に出す引数のヒント | [issue-number] など |
disable-model-invocation | true で Claude が自分では呼ばない | デプロイ・送信など副作用のある手順 |
user-invocable | false で / メニューから隠す | 背景知識だけを渡すスキル |
allowed-tools | 呼んだターンだけ確認なしで使えるツール | Bash(git add *) など |
context / agent | fork でサブエージェントとして実行 | 調査など、会話を汚したくない作業 |
paths | 対象ファイルのパターンで起動を絞る | src/ など |
model / effort | そのスキルの間だけモデルや思考量を変える | 重い手順だけ強いモデルにする |
フィールド名は表のとおりに書く必要があります。知らない名前は、エラーを出さずに無視されます1。また、本文から引数を使うときは $ARGUMENTS（全部）や $0・$1（位置）で受け取ります。/ と打つと、本文の $ARGUMENTS が 123 に置き換わります1。
このサイト（Skill We Find）では、記事の作成手順を write-article というプロジェクトスキルにしています。SKILL.md には全体の流れだけを書き、詳しい約束は references/（本文の構造）と references/（画像・GIF の作り方）に分けました。lint やカバー画像の生成は scripts/ のスクリプトに任せています。手順書が長くても、記事を書かない日の会話には読み込まれません。
デプロイやリリースのスキルには disable-model-invocation: true を付けます。公式ドキュメントの例えでは「コードが準備できたように見えたからといって、Claude に勝手にデプロイしてほしくはない」とされています1。Claude がそれでも実行しようとした場合、Claude Code が呼び出しを止めます。
---
name: deploy
description: 本番環境にデプロイする
disable-model-invocation: true
---
$ARGUMENTS を本番にデプロイする:
1. テストを実行する
2. ビルドする
3. デプロイ先に反映する
4. デプロイが成功したか確かめる
context: fork を付けると、スキルの本文を指示として新しいサブエージェントが起動します。agent: Explore を指定すれば、読み取り専用で探索向けの組み込みエージェントが使われます。調べた途中経過はメインの会話に入らず、結果の要約だけが戻ります1。サブエージェントそのものの作り方は「Claude Code のサブエージェントの作り方と使い分け」で詳しく扱っています。
迷ったら「いつ読み込まれるか」で決めます。公式の比較をもとに整理すると次のとおりです7。
| CLAUDE.md | スキル | サブエージェント | |
|---|---|---|---|
| 読み込まれるとき | 毎回のセッション | 必要なとき・/ で呼んだとき | 委任されたとき |
| 動く場所 | メインの会話 | メインの会話（context: fork で別にも） | 別のコンテキスト |
| 向いている内容 | 「いつも X する」というルール | 手順、資料、呼び出せるワークフロー | ファイルを大量に読む作業、並列作業 |
| 例 | ビルドコマンド、命名規則 | デプロイ手順、API の規約 | テスト実行、コードベース調査 |
hooks の使い方は「Claude Code の hooks 入門」で紹介しています。スキルをほかのチームに配るなら、プラグインにまとめる方法もあります（「Claude Code のプラグインとマーケットプレイス」）。
公式のトラブルシューティングは、次の順に確かめるよう勧めています1。
description に、ユーザーが実際に使う言葉が入っているかdescription に寄せると使われるか/ で直接呼べるかフロントマターの YAML が壊れていると、本文は読み込まれますが項目は空になります。/ では動くのに自動では使われない、という症状になります。claude --debug か claude plugin validate で原因を確かめます1。なお、開始の --- がファイルの 1 行目にないと、フロントマターとして読まれません。
スキルの本文は、呼ばれたときに 1 つのメッセージとして会話に入り、その後は読み直されません。会話が圧縮（compaction）されると、各スキルは先頭 5,000 トークンだけが残ります。複数のスキルを合わせた上限は 25,000 トークンです1。大事な指示は SKILL.md の先頭に書き、守られなくなったらスキルをもう一度呼びます。
スキルの指示は、Claude の判断で守られるものです。「編集のたびに必ず lint する」のように毎回の実行が必要なら、hooks に移します。スキルのフロントマターの hooks に書けば、スキルと一緒に管理できます1。
argument-hint や disable-model-invocation などは Claude Code 独自の項目です。claude.ai へのアップロードや Skills API では、仕様の 6 項目以外があるとエラーで止まります1。両方で使うスキルは、仕様の項目だけで書きます。
allowed-tools は、ワークスペースを信頼する前の -p 実行でも効きます。つまり、スキルが自分に広い権限を与えることができます1。他人のリポジトリで Claude Code を動かす前に、.claude/ の allowed-tools を読んでおきましょう。
.claude/ を置くだけで作れる「必要なときだけ読み込まれる手順書」description 次第。何をするか・いつ使うか・ユーザーの言い回しを先頭に書くreferences/、処理は scripts/ に分け、SKILL.md は 500 行以内にするdisable-model-invocation: true で手動専用にする.claude/ もそのまま動くが、新しく作るならスキルにする次にやることとして、チャットに何度も貼っている指示を 1 つ選び、スキルにしてみてください。/ で動いたら、description を整えて自動でも使われるか試すのがおすすめです。
いまは同じ仕組みです。Claude Code v2.1.3（2026 年 1 月 9 日公開）でコマンドとスキルが統合されました3。.claude/ も .claude/ も / を作ります。スキルは付属ファイルを置けて、Claude が自動で使える点が加わっています1。
フロントマターに disable-model-invocation: true を書きます。Claude は自分では呼べなくなり、/ で呼んだときだけ動きます。説明も Claude に渡される一覧から消えます1。設定ファイルの skillOverrides で "user-invocable-only" にする方法もあります。
数の上限は書かれていません。ただし、名前と説明の一覧はコンテキストの約 1% に収まるよう調整されます。あふれると、使用頻度の低いスキルから説明が省かれます1。/ で、スキルごとのコストと使用回数を確かめられます。
Agent Skills の仕様の項目（name・description・license・compatibility・metadata・allowed-tools）だけで書けば、同じ仕様に対応したツールでも読めます4。context: fork や !`コマンド` は Claude Code の拡張なので、ほかの環境では動きません1。
不要です。~/ とプロジェクトの .claude/ は監視されていて、編集は同じセッションのうちに反映されます1。セッション開始時に無かったトップレベルのスキルディレクトリを新しく作ったときだけ、/ を実行します。
Extend Claude with skills — Anthropic（Claude Code 公式ドキュメント）（2026-10-05 参照） ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9 ↩10 ↩11 ↩12 ↩13 ↩14 ↩15 ↩16 ↩17 ↩18 ↩19 ↩20 ↩21 ↩22 ↩23 ↩24 ↩25 ↩26 ↩27 ↩28 ↩29 ↩30 ↩31 ↩32 ↩33 ↩34 ↩35
Equipping agents for the real world with Agent Skills — Anthropic Engineering, 2025-10-16（2026-10-05 参照） ↩ ↩2 ↩3
Claude Code CHANGELOG（2.0.20・2.1.3） — Anthropic, GitHub（公開日は npm レジストリの記録: v2.0.20 が 2025-10-16、v2.1.3 が 2026-01-09）（2026-10-05 参照） ↩ ↩2 ↩3
Agent Skills Specification — agentskills.io（2026-10-05 参照） ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7
Skills for organizations, partners, the ecosystem — Anthropic, 2025-12-18（2026-10-05 参照） ↩
Best practices for Claude Code — Anthropic（Claude Code 公式ドキュメント）（2026-10-05 参照） ↩
Extend Claude Code（Compare similar features） — Anthropic（Claude Code 公式ドキュメント）（2026-10-05 参照） ↩