最近、参画先でClaude Codeが配布されたので、改めてスキルについて調べたのでまとめてみました。
※本記事は2026年9月時点のClaude Codeの仕様・公式ドキュメントをもとにしています。Claude Codeはアップデートが頻繁なため、最新仕様については公式ドキュメントもあわせてご確認ください。
スキルとは
スキルはSKILL.mdという指示書ファイルを作ることでClaude Codeの能力を拡張する仕組みです。
自然言語で指示を出して、関連するとClaude Codeが判断したときに自動で使ったり、/skill-nameで直接呼び出したりできます。
同じ指示や手順書を毎回チャットに貼り付けて使用している、あるいはCLAUDE.mdに固有の指示を書き込んでいて、その指示内容が膨らんできていたり毎回呼び出す必要性が無い——そんなときスキルを作る目安です。
CLAUDE.mdの内容と違い、スキルの本文は使いたい時だけ読み込まれるため、長い参照資料もほとんどコストなく置いておけます。
最小構成のスキルを作る
スキルはディレクトリ単位で管理され、SKILL.mdをエントリーポイントとして必須で持ちます。まずは個人用フォルダに作ってみましょう。
mkdir -p ~/.claude/skills/summarize-changes
SKILL.mdは「YAMLフロントマター（---で囲まれた部分）」と「Markdown本文」の2部構成です。フロントマターはClaude Codeがいつ使うべきかを判断する材料、本文は実際にClaude Codeが従う指示になります
---
description: 未コミットの変更を要約し、リスクがあれば指摘する。何が変わったか聞かれたとき、コミットメッセージが欲しいとき、diffのレビューを頼まれたときに使う。
---
## 現在の変更
!`git diff HEAD`
## 指示
上記の変更を2〜3個の箇条書きで要約し、エラー処理の欠落やハードコードされた値、更新が必要なテストなど気づいたリスクを列挙してください。diffが空なら「未コミットの変更はありません」と伝えてください。
フロントマターの主要フィールド
すべて省略可能ですが、覚えておくと便利な代表的フィールドは次の通りです。
| フィールド | 役割 | 使い方の例 |
|---|---|---|
description |
いつこのスキルを使うべきかをClaude Codeに伝える説明文。実質必須 | 「未コミットの変更を要約する。何が変わったか聞かれたときに使う」のようにトリガーとなる言い回しを含めて書く。曖昧だと発火しない、具体的すぎると必要な場面で発火しないので調整が必要。 |
disable-model-invocation |
trueにするとClaude Codeは自動起動できず、/nameでの手動呼び出しのみになる |
/deployや/commitのような副作用のある操作に設定。コードが良さそうに見えても、Claudeが勝手にデプロイ判断してしまうのを防げる。 |
user-invocable |
falseにするとユーザーは呼び出せず、Claude Codeだけが使える背景知識になる |
「レガシーシステムの仕様説明」など、ユーザーが/コマンドとして叩く意味がない背景知識に設定。Claudeが関連する話題のときだけ自動で参照する。 |
allowed-tools |
そのスキル実行ターン中、確認なしで使えるツールを事前承認 |
commitスキルにBash(git add *) Bash(git commit *)を指定しておけば、実行のたびに確認プロンプトが出ずgitコマンドを実行できる。 |
argument-hint / arguments
|
/skill 引数のように渡す引数の名前・ヒント |
argument-hint: [issue-number]は補完時の見た目のヒントのみ。arguments: [issue, branch]にすると本文中で$issueや$branchとして名前付きで参照できる。 |
context: fork |
サブエージェント（隔離されたコンテキスト）でスキルを実行 | 会話履歴を持ち込みたくない独立した調査タスク（agent: Exploreとの組み合わせなど）で、メインの会話を汚さずにバックグラウンド実行させたいときに使う。 |
model / effort
|
そのスキル実行中だけモデルや思考の強度を上書き | 普段は軽量モデルで会話しつつ、複雑なリファクタスキルの実行時だけmodel: opusやeffort: highに切り替えて精度を上げる、といった使い方ができる。 |
disable-model-invocation: trueは、/commitや/deployのように副作用があり実行タイミングを自分で制御したいワークフローに向いています。コードが良さそうに見えたからといってClaude Codeが勝手にデプロイを判断してしまうのを防げます。
逆にuser-invocable: falseは、レガシーシステムの背景知識のようにユーザーが直接実行する意味を持たない、Claude Codeだけが参照すればいい情報に向きます。
実行内容を「参照系」と「タスク系」で分ける
スキルの中身には何を書いても構いませんが、参照コンテンツ（規約やスタイルガイドなど、現在の作業にそのまま適用する知識）とタスクコンテンツ（デプロイやコミットなど、段階的な手順）を意識して分けると設計しやすくなります。
タスク系は/skill-nameで明示的に叩くことが多いのでdisable-model-invocation: trueと相性が良いです。
また、スキルが一度呼ばれるとその内容は会話に残り続けるため、本文は簡潔に保つべきです。「なぜ」「どうやって」を説明するのではなく「何をするか」だけを書きましょう。
補助ファイルで肥大化を防ぐ
スキルはディレクトリ内に複数ファイルを持てるので、SKILL.mdは要点だけにして、詳細なリファレンスやAPI仕様、サンプル集は別ファイルに分離できます。
my-skill/
├── SKILL.md # 必須：概要とナビゲーション
├── reference.md # 詳細なAPIドキュメント（必要な時だけ読み込み）
├── examples.md # 使用例
└── scripts/
└── helper.py # 実行はされるが読み込まれないスクリプト
SKILL.md本文からこれらを参照しておくと、Claude Codeが「いつ」「何を」読めばいいか分かります。目安としてSKILL.mdは500行未満に収め、詳細な資料は別ファイルに逃がすのが推奨されています。
どこに置くか（スコープ）
そのスキルは誰が使うか、使う対象（スコープ）によりどこに配置するかが変わってきます
| 置き場所 | 適用範囲 |
|---|---|
~/.claude/skills/ |
自分の全プロジェクト（このマシン限定） |
.claude/skills/（プロジェクト直下） |
そのプロジェクト。コミットすればチーム全体に共有可能 |
プラグインのskills/
|
プラグインが有効な場所どこでも |
| 組織のmanaged settings | 組織全体に強制配布 |
チーム共有したいなら、そのプロジェクトのルートディレクトリの.claude/skills/、個人の作業効率化なら~/.claude/skills/、組織のルールとして徹底したいならmanaged settingsやプラグイン配布、という使い分けが基本です。
managed settingsの説明については以下を参照ください。
公式の「skill-creator」プラグインで検証する
「動いた」ことと「意図通りに動いた」ことは別物です。公式マーケットプレイスのskill-creatorプラグインを使うと、スキルありなしでの比較実行、判定基準に沿った採点、説明文のトリガー精度の測定までを自動化できます。
/plugin install skill-creator@claude-plugins-official
※Claude Code CLI (ターミナル)のインタラクティブセッションに入ったら、上記コマンドを打ちます。
インストール後は「summarize-changesスキルをskill-creatorで評価して」のように頼むだけで、テストケースの作成から実行、レポート表示まで一通り実行してくれます。
まとめ
Claude Codeのスキルは、SKILL.mdというシンプルな仕組みでありながら、フロントマターで起動条件・権限・実行環境まで細かく制御でき、補助ファイルで無制限に複雑化できるのが特徴です。
まずは「何度も貼り付けている指示」を1つ、簡易的なdescriptionと１から２行だけのシンプルなスキルにしてみるのがおすすめです。
参考にしたサイト