Skill（スキル）

自分が繰り返しチャットに貼り付けてる作業手順を「スキル」化して /skill-name で1発で呼び出したい人、または Claude に文脈から自動で発火させたい人向け

Skill（スキル）は、Claude Code の内蔵ツールの1つで、SKILL.md に書いた手順書を「スキル」として登録しておき、ユーザーが /skill-name で呼び出すか、Claude 自身が文脈から判断して自動で発火させる仕組みです。動かしているのは Skill ツール本体ですが、ユーザーが実際に書くのは スキル本体（SKILL.md）で、この2層を分けて理解すると一気に見通しが良くなります。

毎回チャットに貼り付けてた長い指示や、CLAUDE.md にだんだん溜まってきた「やる手順」を、独立した名前付きの呼び出し口に切り出すための場所です。

噛み砕くと

会社の業務マニュアルみたいなものです。「git で変更内容をまとめる時はこの手順」「本番に出す時はこのチェックリスト」と紙に書いて引き出しに入れておく。必要な人が引き出しから出して机に広げると、誰でも同じ手順で作業できる。Skill ツールはその「引き出し」と「机に広げる動作」を担当します。マニュアル本体は SKILL.md。

普通の指示文をチャットに貼ると会話の最初から最後まで重荷になりますが、スキルは呼び出された時だけ机の上に出るので、未使用なら会話の重さにほぼ影響しません。これが Skill が CLAUDE.md と棲み分けてる最大の理由です。

大事な前提：Skill ツールは「呼ばれた時だけ」中身を読む

Skill が普通のテキスト貼り付けと根本的に違うのは progressive disclosure です。スキルの名前と1行説明（description）は常に Claude が見えてる場所に置かれてますが、本体の手順書は誰かが呼び出した瞬間だけ会話に流し込まれます。

呼び出されると、その手順書は会話セッションが終わるまで context window に居続けます。Claude Code は2回目以降のターンで SKILL.md を再読み込みしないので、「1回目だけ守って2回目から忘れる手順」みたいな書き方をしても効きません。「ずっと守ってほしいルール」として書きます。

「git の変更内容をまとめる summarize-changes スキル」を例に、実際の手順を見る

公式 Getting started がそのまま使ってる例を、ここでも追います。やりたいのは、変更を記録する直前に git diff HEAD を要約させて、リスクっぽい箇所を flag させる動作を /summarize-changes 1発で呼べる状態にすること。

ステップ1: スキル置き場のフォルダを作る

個人用スキルはホーム以下の ~/.claude/skills/<スキル名>/ に置きます。ここに置くと全プロジェクトで共通で使えるようになります。今回は summarize-changes という名前にします。

$ mkdir -p ~/.claude/skills/summarize-changes

フォルダ名がそのまま呼び出し用のコマンド名になります。今回なら /summarize-changes。

ステップ2: SKILL.md を書く

~/.claude/skills/summarize-changes/SKILL.md を作って、中身を書きます。frontmatter で動作設定、その下に Claude が読む手順書本体を書く2部構成です。

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

注目してほしいのは !`git diff HEAD` の行です。これは dynamic context injection という機能で、スキルが呼ばれた瞬間に裏で git diff HEAD が実行され、その出力結果が貼り込まれた状態で Claude に届きます。「Claude にコマンドを実行させる」のではなく「Claude が手順書を読む前に出力結果が埋め込まれてる」のがポイント。

ステップ3: 適当な git プロジェクトで試す

何か git 管理のプロジェクトに移動して、テキトーなファイルを1行書き換えてから claude を起動します。

$ cd ~/projects/my-app
$ echo "// test edit" >> src/index.js
$ claude

2通りの呼び出し方を試せます。

ステップ4: 直接呼ぶ（手動発火）

会話の最初の入力で /summarize-changes と打ちます。/ を打った瞬間にメニューが開き、登録済みスキルが一覧に出てるはずです。

> /summarize-changes

すると裏で git diff HEAD が走り、その出力が Claude に渡され、Claude が SKILL.md の Instructions に沿って「変更内容の2〜3行要約 + リスク箇条書き」を返してきます。

ステップ5: 自然に呼ばせる（自動発火）

同じことを / なしで聞きます。

> さっき書き換えたファイル、なに変えたっけ？

Claude は frontmatter の description を読んで、「変更内容を要約」「変更の保存メッセージを書く」「diff レビュー」に該当する場面では使え、と判断する材料を持ってます。なのでこの聞き方でも summarize-changes が自動で発火します。ここが Skill の面白いところで、ちゃんと書けば「自分が呼ぶのを忘れても Claude が拾ってくれる」状態が作れます。

ここで初心者がやりがちな勘違いがあって、description を「git diff を要約する」だけしか書かないと、ユーザーが日本語で「何変えた？」と聞いた時に Claude が拾えません。description はユーザーがどう聞いてくる可能性があるかまで含めて書きます。

ステップ6: Claude に勝手に動かれたくない場面では制御する

「Claude が勝手にデプロイし始めたら困る」みたいなスキルもあります。その時は frontmatter に1行足します。

---
description: Deploy the application to production
disable-model-invocation: true
---

disable-model-invocation: true を付けると、Claude 自身は二度とこのスキルを発火させません。ユーザーが /deploy と明示的に叩いた時だけ動きます。逆に user-invocable: false を付けると、/ メニューから消えて Claude しか呼べなくなります。背景知識用のスキルで使う設定です。

つまり Skill ツールは何をしてくれるのか

• やってくれる: SKILL.md に書いた手順書を、/skill-name で呼ぶか文脈マッチで自動発火するかのどちらかでセッションに流し込む。dynamic context injection を併用すれば、git diff や PR 一覧やファイル一覧のような、呼んだ瞬間の最新データをその場で取り込める
• やってくれない: スキル本体（SKILL.md）の中身を考えてくれるわけではない。手順書はユーザーが書く。良い description を書くのもユーザー側の仕事
• 意味が薄い場面: 1回しか使わない単発作業。長文の固定知識を常に文脈に居続けさせたい場合は CLAUDE.md の役割なのでスキル化は逆効果

使いどころ3シナリオ（具体題材で再現）

シナリオ1: 個人開発の家計簿アプリで、変更を記録する直前のチェックを定型化したい時

1人で家計簿アプリを書いてて、毎回変更を記録する直前に「テスト走らせて、lint かけて、git diff を眺めて、ヤバそうな箇所がないか確認」を手でやってる。これを ~/.claude/skills/pre-commit-check/SKILL.md に集約して、frontmatter で allowed-tools: Bash(npm test *) Bash(npm run lint *) Bash(git diff *) を許可しておく。/pre-commit-check 1発で全部走って、結果のサマリだけ返ってきます。allowed-tools を書いておけば作業のたびに承認を求められないので、毎回 Enter 連打しなくて済むのが地味に効きます。

シナリオ2: 料理ブログを書いてて、レシピ記事の体裁チェックを自動化したい時

料理ブログを WordPress で運営してて、レシピ記事には毎回「材料セクション・分量表記・調理時間・カロリー記載・写真3枚以上」を満たしてほしい。これを .claude/skills/recipe-check/SKILL.md としてプロジェクト直下に置いて、git で共有する。description を「レシピ記事の下書きをチェックする時に使え。『この原稿チェックして』『下書き見て』と頼まれた時も発動」と書いておけば、執筆者が /recipe-check と叩かなくても、Claude が文脈で勝手に拾ってチェック走らせてくれます。チームで共有する時にこの形が便利。

シナリオ3: OSS を手元に複製してきた直後、その OSS 独自の規約を Claude に覚えさせたい時

馴染みのない OSS を手元に持ってきたとします。仮に awesome-something という名前としておきます。この OSS、その OSS には独自の PR テンプレートとブランチ命名規則がある。これを .claude/skills/awesome-pr-rules/SKILL.md に書いて、user-invocable: false を付けます。ユーザーが直接呼ぶ場面はない、Claude が PR を作る時に背景知識として参照すればいい場面だからです。description を「awesome-something で PR を作る時の規約。ブランチ名、PR タイトル、変更履歴の書き方」と書けば、ユーザーが「PR 作って」と頼んだ時に Claude が勝手にこのスキルを引いてくれます。

初心者が踏みやすい落とし穴

• permission 設定で「Skill」と書くとスキル機能ごと止まる。/permissions の deny に裸の Skill を入れると、全スキルが呼べなくなります。bundled の /simplify や /debug 等も含めて全滅します。個別に止めたい時は Skill(deploy) で完全一致、Skill(deploy *) で前方一致＋追加情報任意、の2書式を使い分けます
• SKILL.md は呼んだ後セッション末まで context に残り続ける。長い手順書を書くと、その分だけ全ターンで token を消費し続けます。500行を超えそうなら別ファイル、たとえば reference.md や examples.md に外出しして、SKILL.md からは「詳細は reference.md を見ろ」とリンクするだけにします
• auto-compaction（自動要約）後、各スキルは 5,000 token に切り詰められる。会話が長くなって自動要約が走ると、それまでに呼んだスキルは直近のもの優先で最大 25,000 token 分だけ会話の続きに再添付されます。1セッションで大量のスキルを呼ぶと、古いやつは丸ごと落ちる可能性があるので、要約後に挙動がおかしくなったら手動で再呼び出しします
• 同名スキルが複数の場所にある時の優先順位を覚えておく。上書きの順は、enterprise（組織管理）が最優先、次が personal で置き場は ~/.claude/skills/、最後が project で置き場は .claude/skills/ です。plugin スキルは plugin-name:skill-name という別名前空間なので衝突しません。同名で動作が変わって混乱した時はまずこの順序を疑います
• カスタムコマンドファイル .claude/commands/deploy.md と、スキル .claude/skills/deploy/SKILL.md が同名の時はスキル優先。公式ドキュメントが「Custom commands have been merged into skills」と明記してます。古い .claude/commands/ を残したままスキル側にも作ると、commands 側は無視されます
• 組み込みコマンドの一部はこの Skill ツール経由です。/init /review /security-review がそれ。一方 /compact 等は Skill 経由ではなく直接実行されます。permission で Skill をまるごと拒否すると、Skill 経由の組み込みコマンドも巻き添えで死にます。「なぜか /init が動かない」みたいな事故を防ぐために覚えておきます
• description は「Claude が拾える言葉」で書く。「diff を summarize する」だけ書いても、ユーザーは「何変えたっけ」「変更の保存メッセージ書いて」「これレビューして」みたいに違う言い方で頼んできます。description には想定される呼ばれ方の言い回しを含めます。公式 Getting started の例も「user asks what changed, wants a commit message, or asks to review their diff」と3パターン書いてます
• frontmatter の !`コマンド` 記法は1回しか展開されない。コマンドの実行結果がさらに別の !`コマンド` を含んでいても、それは再展開されません。チェーンしたい時は1回でまとめる工夫が要ります

書き方

/<skill-name> [追加で渡す情報]

やってみるとこうなる

入力

/summarize-changes

出力例

（裏で git diff HEAD が実行され、その出力を読んだ Claude が返してくる）
変更内容:
- src/index.js に1行コメント追加
- README の見出しを更新

リスク:
- テスト未更新（テスト対象の関数は変わってないので影響は小さい）
- TODO コメントが残っている

関連項目

• Skills / Custom Commands（スキル／カスタムコマンド）
• /agents（エージェンツ）
• CLAUDE.md
• /permissions（パーミッションズ）
• /mcp-vs-skills（準備中）

公式ドキュメント

https://code.claude.com/docs/en/skills