Extend Claude with skills

概要

SKILL.md に指示を書いて Claude の能力を拡張する仕組み。Claude が関連する場面で自動的に使うか、/skill-name で直接呼び出す。CLAUDE.md と違い、skill の本文は使用時にのみ読み込まれる。

仕様

custom commands との関係

custom commands は skills に統合された。.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md はどちらも /deploy を作り、同じように動く
既存の .claude/commands/ ファイルは引き続き動作する。skill は補助ファイル用のディレクトリ、呼び出し制御の frontmatter、関連時の自動読み込みを追加する
同名の skill と command があるときは skill が優先される
Claude Code の skill は Agent Skills のオープン標準に従い、invocation control / subagent execution / dynamic context injection といった拡張を加えている

bundled skills

/doctor、/code-review、/batch、/debug、/loop、/claude-api などが同梱される。bundled skill はプロンプトベースで、Claude に詳細な指示を与えツールで作業を組み立てさせる（多くの組み込みコマンドは固定ロジックを直接実行する）
一部は関連時に Claude が自動で呼ぶ。/verify と /code-review はユーザーが呼んだときのみ実行される（v2.1.215 より前は Claude も実行できた）
すべてのセッションで利用できる。disableBundledSkills 設定で無効化できるが、/doctor を除くすべてが対象
v2.1.205 以降、disableBundledSkills が有効でも /doctor は入力できる。隠すには DISABLE_DOCTOR_COMMAND 環境変数か skillOverrides の "doctor": "off"

/run / /verify / /run-skill-generator（いずれも v2.1.145 以降）:

Skill	用途
`/run`	アプリを起動・操作して変更の動作を確認する
`/verify`	テストや型チェックに頼らず、アプリをビルド・実行して変更が意図どおりかを確認する
`/run-skill-generator`	`/run` と `/verify` にプロジェクトのビルド・起動方法を教える

/run と /verify は設定なしでも動き、プロジェクト種別と README / package.json / Makefile から起動方法を推測する
/run-skill-generator はクリーンな環境からアプリを動かし、うまくいった手順（インストールコマンド、環境変数、起動スクリプト）を .claude/skills/run-<name>/ にプロジェクト固有の skill として記録する
/verify も自前のレシピを記録できる。レシピが無い状態でビルド・実行した場合、リポジトリルート（monorepo では触れたパッケージディレクトリ）の .claude/skills/verify/SKILL.md に手順を書く。リポジトリルートでは記録された skill が bundled /verify を置き換える。v2.1.200 以降が必要
記録ファイルは、実行が誤った方向に導かれたとき（失敗したコマンド、欠けていた手順）にのみ編集される

配置場所

種別	パス	適用範囲
Enterprise	managed settings 参照	組織の全ユーザー
Personal	`~/.claude/skills/<skill-name>/SKILL.md`	自分の全プロジェクト
Project	`.claude/skills/<skill-name>/SKILL.md`	そのプロジェクトのみ
Plugin	`<plugin>/skills/<skill-name>/SKILL.md`	plugin が有効な場所

同名の skill があるとき enterprise > personal > project の順で上書きする。いずれかのレベルの skill は同名の bundled skill も上書きする
plugin skill は plugin-name:skill-name の名前空間を持つため他レベルと衝突しない
作業ディレクトリより下のネストした .claude/skills/ からも読み込まれる。Claude がそのサブディレクトリのファイルを読む・編集すると利用可能になる
ネストした skill が他と同名の場合、両方が利用可能なままになる。ネストしたものはディレクトリ修飾名（apps/web:deploy）で現れ、description にどのディレクトリ向けかが書かれる
修飾なしの名前を呼ぶとプロジェクトルートの skill が読み込まれ、Claude Code はディレクトリ修飾された variant の一覧をその内容に追記し、作業対象のファイルがあるディレクトリの variant も呼ぶよう指示する。v2.1.203 以降が必要
enterprise / personal / project の <skill-name> エントリはディレクトリへの symlink でもよい。同じ対象が複数の場所から到達できる場合、skill は 1 回だけ読み込まれる
skill フォルダに .claude-plugin/plugin.json を置くと <name>@skills-dir という plugin として読み込まれ、agent・hook・MCP サーバーを同梱できる。プロジェクトの .claude/skills/ ではまず workspace trust ダイアログの承認が必要

読み込みのタイミング

project skill は Claude Code を起動したディレクトリと、リポジトリルートまでの各親ディレクトリの .claude/skills/ から読み込まれる
起動時にそのパス外のディレクトリから読み込むには --add-dir を渡す。追加ディレクトリ内の .claude/skills/ は project skill と並んで読まれる（--add-dir / /add-dir のみの例外で、permissions.additionalDirectories 設定はファイルアクセスのみを与え skill は読み込まない）
起動ディレクトリより下のネストした .claude/skills/ は起動時には読み込まれない。Claude がそのサブディレクトリ内のファイルを初めて読む・編集したときに読み込まれ、以後セッション中は使える。それまでは autocomplete にも出ず名前でも呼べない

live change detection

~/.claude/skills/、プロジェクトの .claude/skills/、--add-dir ディレクトリ内の .claude/skills/ の変更は、再起動なしに現在のセッションで反映される
セッション開始時に存在しなかったトップレベルの skills ディレクトリを作った場合は再起動が必要
live change detection は SKILL.md のテキストのみが対象。skills-directory plugin の hooks/、.mcp.json、agents/、output-styles/ の変更は /reload-plugins が必要

Cowork / cloud セッション

Cowork セッションと cloud セッション（routines を含む）は、マシン上の ~/.claude/skills/ を読まない
Cowork は claude.ai アカウントで有効にした skill をセッション開始時に同期して読み込む
cloud セッションは加えて、クローンしたリポジトリの .claude/skills/ にコミットされた project skill を読み込む
Desktop scheduled tasks はローカルで動くため、他のローカルセッションと同じ場所から読み込む

frontmatter

すべてのフィールドは任意。description のみ推奨。boolean は true / false に加えて yes / no / on / off / 1 / 0 を大小文字問わず受け付ける（v2.1.218 以降）。

フィールド	説明
`name`	skill 一覧に表示される表示名。既定はディレクトリ名
`description`	何をするか・いつ使うか。Claude はこれで適用を判断する。省略時は markdown 本文の最初の段落を使う。`description` と `when_to_use` の合計テキストは skill 一覧で 1,536 文字に切り詰められる
`when_to_use`	Claude が呼ぶべき場面の追加情報（トリガーフレーズ、リクエスト例）。一覧では `description` に追記され 1,536 文字の上限に算入される
`argument-hint`	autocomplete に表示される引数のヒント（例: `[issue-number]`）
`arguments`	`$name` 置換用の名前付き位置引数。スペース区切り文字列または YAML リスト。名前は順に引数位置へ対応する
`disable-model-invocation`	`true` で Claude による自動読み込みを禁止する。subagent への preload も防ぐ。v2.1.196 以降、scheduled task がこの skill をプロンプトとして発火したときの実行も防ぐ。既定 `false`
`user-invocable`	`false` で `/` メニューから隠す。既定 `true`
`allowed-tools`	この skill を呼んだターンの間、許可を求めずに使えるツール。次のメッセージを送ると解除される。スペースまたはカンマ区切り文字列、あるいは YAML リスト
`disallowed-tools`	この skill がアクティブな間、Claude の利用可能プールから外すツール。次のメッセージを送ると解除される。deny ルール同様、他のツールが残っている限り `EndConversation` は外せない
`model`	この skill がアクティブな間のモデル。現在のターンの残りに適用され設定には保存されない。`/model` と同じ値、または現在のモデルを保つ `inherit`。組織の `availableModels` allowlist に含まれない値は使われない。`context: fork` のときは forked subagent のモデルを設定する
`effort`	この skill がアクティブな間の effort level。セッションの effort を上書きする。既定はセッションから継承。`low` / `medium` / `high` / `xhigh` / `max`
`context`	`fork` で forked subagent のコンテキストで実行する
`agent`	`context: fork` のときに使う subagent の種類
`background`	`context: fork` のときのみ有効。`false` で、呼び出したターン内で forked subagent の結果を待つ。既定 `true`。v2.1.218 以降が必要
`hooks`	この skill のライフサイクルにスコープした hooks
`paths`	この skill が有効になるファイルを限定する glob パターン。カンマ区切り文字列または YAML リスト。path-specific rules と同じ形式
`shell`	この skill 内の !`command` と ```! ブロックに使うシェル。`bash`（既定）または `powershell`。`powershell` は PowerShell ツールが有効なときにインラインシェルコマンドを PowerShell 経由で実行する（Git Bash の無い Windows では既定で有効、それ以外では `CLAUDE_CODE_USE_POWERSHELL_TOOL=1` で有効化）
`metadata`	自前のツールが読む自由形式の YAML マップ。Claude Code は内容に基づく動作をせず、マップでない値は落とす。`paths` などの frontmatter 名をキーに再利用しない
`license`	skill のライセンス。Agent Skills spec の一部。Claude Code は受け付けるが動作しない
`compatibility`	skill の環境要件。最大 500 文字の文字列。Claude Code は受け付けるが動作しない

Claude Code の外での frontmatter

配布経路	使えるフィールド
Claude Code の skill（plugin skill を含む）	上表のすべて
claude.ai の skill アップロード、Skills API、`package_skill.py` によるパッケージング	`name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`

spec が許さないフィールドを含めると、無視されるのではなくパッケージング・アップロードがハードエラーで失敗する
dynamic context injection のような Claude Code 固有の本文機能は claude.ai チャットや API では機能しない

コマンド名の決まり方

skill の場所	コマンド名の由来	例
`~/.claude/skills/` または `.claude/skills/` 配下の skill ディレクトリ	ディレクトリ名	`.claude/skills/deploy-staging/SKILL.md` → `/deploy-staging`
ネストした `.claude/skills/`（名前が衝突する場合）	作業ディレクトリからの相対サブディレクトリパス + skill ディレクトリ名	`apps/web/.claude/skills/deploy/SKILL.md` → `/apps/web:deploy`
`.claude/commands/` 配下のファイル	拡張子を除いたファイル名	`.claude/commands/deploy.md` → `/deploy`
plugin の `skills/` サブディレクトリ	frontmatter の `name` またはディレクトリ名を plugin で名前空間化	`my-plugin/skills/review/SKILL.md` → `/my-plugin:review`、`name: fancy` なら `/my-plugin:fancy`
plugin ルートの `SKILL.md`	frontmatter の `name`、無ければ plugin ディレクトリ名	`name: review` の `my-plugin/SKILL.md` → `/my-plugin:review`

personal / project の skill では name は一覧の表示ラベルのみを決め、コマンドはディレクトリ名・ファイル名から来る
plugin skill では name がコマンドの最後のセグメントを置き換え、plugin 接頭辞は残る。素の /fancy も、他のコマンドがその名前を使っていなければ呼び出せる。v2.1.216 より前は frontmatter 名がコマンド名全体を置き換えていた
非対話セッションでは help と feedback はターミナル専用組み込みのために予約されないため、それらの名前の plugin skill は素のコマンドを保つ。/login など他のターミナル専用組み込みの名前は予約される

文字列置換

変数	説明
`$ARGUMENTS`	呼び出し時の全引数。本文に `$ARGUMENTS` が無い場合は `ARGUMENTS: <value>` として追記される
`$ARGUMENTS[N]`	0 始まりのインデックスで特定の引数にアクセスする
`$N`	`$ARGUMENTS[N]` の短縮形
`$name`	`arguments` frontmatter で宣言した名前付き引数。名前は順に位置へ対応する
`${CLAUDE_SESSION_ID}`	現在のセッション ID
`${CLAUDE_EFFORT}`	現在の effort level（`low` / `medium` / `high` / `xhigh` / `max`）。ultracode は独立した水準ではなく `xhigh` として報告される
`${CLAUDE_SKILL_DIR}`	その skill の `SKILL.md` があるディレクトリ。plugin skill では plugin ルートではなく skill のサブディレクトリ
`${CLAUDE_PROJECT_DIR}`	プロジェクトルートディレクトリ。hooks と MCP サーバーが `CLAUDE_PROJECT_DIR` として受け取るのと同じパス。v2.1.196 以降が必要

${CLAUDE_SKILL_DIR} と ${CLAUDE_PROJECT_DIR} は、skill の markdown 本文と allowed-tools frontmatter の Bash ルールの両方で置換される
インデックス引数はシェル形式のクォートを使う。複数語の値は引用符で囲むと 1 引数として渡る。$ARGUMENTS は常に入力された引数文字列全体に展開される
対応する引数が無いインデックスプレースホルダ（引数 1 つで $2 など）は本文にそのまま残る。対応する引数が無い名前付きプレースホルダは空文字列に展開される
数字・ARGUMENTS・宣言済み引数名の前のリテラルな $ はバックスラッシュでエスケープする（\$1.00）。他の $ の前のバックスラッシュはそのまま残る。\\$1 は両方のバックスラッシュを残し $1 は引数値に展開される

補助ファイル

skill ディレクトリには SKILL.md（必須）のほかテンプレート、例、スクリプト、詳細リファレンスを置ける
どのファイルに何が入っていていつ読むかを SKILL.md から参照する
SKILL.md は 500 行未満に保ち、詳細なリファレンスは別ファイルへ移す

呼び出しの制御

frontmatter	ユーザーが呼べる	Claude が呼べる	コンテキストへの読み込み
（既定）	はい	はい	description は常にコンテキストにあり、呼び出し時に全体が読み込まれる
`disable-model-invocation: true`	はい	いいえ	description はコンテキストに入らず、ユーザーが呼んだときに全体が読み込まれる
`user-invocable: false`	いいえ	はい	description は常にコンテキストにあり、呼び出し時に全体が読み込まれる

Claude が disable-model-invocation: true の skill を呼ぼうとすると Claude Code は呼び出しをブロックし、手順を別の方法で再現しないよう指示する

skill 本文のライフサイクル

呼び出すと、レンダリング済みの SKILL.md の内容が 1 つのメッセージとして会話に入り、セッションの残りの間そこに留まる。これは指示についてであり、allowed-tools の付与は次のメッセージ送信時に解除される
Claude Code は後のターンで skill ファイルを再読み込みしない
レンダリング結果が既にコンテキストにあるものと同一なら、2 つ目のコピーではなく「既に読み込み済み」という短い注記が追加される。引数や dynamic context の出力が変わって内容が異なる場合は全体が再度追記される。v2.1.202 より前は毎回全文が追記されていた
auto-compaction では、各 skill の最新の呼び出しが要約の後に再アタッチされ、それぞれ先頭 5,000 トークンまでが保たれる。再アタッチされる skill は合計 25,000 トークンの予算を共有し、最近呼んだものから埋めるため、多く呼んだセッションでは古い skill が丸ごと落ちることがある

`allowed-tools`

列挙したツールを、その skill を呼んだターンの間だけ許可なしで使えるようにする。次のメッセージ送信で解除され、再度呼ぶとそのターンに再適用される
利用可能なツールを制限するものではない。列挙していないツールは permission 設定に従う
セッション全体で事前承認するには permission 設定に allow ルールを追加する
プロジェクトの .claude/skills/ にチェックインされた skill では、.claude/settings.json の permission ルールと同様、workspace trust ダイアログを承認した後に有効になる

引数の受け渡し

引数付きで呼んだが $ARGUMENTS を含まない skill では、ARGUMENTS: <入力> が本文末尾に追記される
1 つのメッセージの先頭で複数の skill を並べられる。/write-tests /fix-issue 123 は両方を読み込み、後続テキスト 123 を各 skill の $ARGUMENTS として渡す
最初の skill に加えて最大 5 つまで展開される。展開はインラインの user-invocable skill でない最初のトークンで止まる。forked subagent として動く skill（/code-review など）や、引数自体がスラッシュコマンドで始まりうる skill（/loop）もそこで止める。そのトークン以降は展開されたすべての skill の引数テキストになる

dynamic context injection

!`<command>` 構文は、skill の内容が Claude に送られる前にシェルコマンドを実行し、出力でプレースホルダを置き換える
置換は元ファイルに対して 1 回だけ走る。コマンド出力はプレーンテキストとして挿入され、さらなるプレースホルダとして再走査されない
インライン形式は ! が行頭または空白の直後にあるときのみ認識される。KEY=!`cmd` のように他の文字に続く場合はリテラルとして残り実行されない
複数行コマンドには ```! で開くフェンス付きコードブロックを使う
user / project / plugin / 追加ディレクトリ由来の skill とカスタムコマンドでこの挙動を無効にするには settings で "disableSkillShellExecution": true を設定する。各コマンドは [shell command execution disabled by policy] に置き換えられる。bundled と managed の skill は影響を受けない
skill 内のどこかに ultrathink を含めると、より深い推論を要求できる

`context: fork`

skill をコンテキストから隔離して実行する。skill の内容が subagent を駆動するプロンプトになる。会話履歴へのアクセスは無い
forked subagent はバックグラウンドで動き、完了時に結果が会話に届く。background: false で呼び出したターン内に結果を待つ。v2.1.218 より前は常にターンをブロックしていた
background: false を設定していなくても待つケース: 非対話モード（-p や Agent SDK）、CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1、同じ skill の以前の呼び出しがまだ実行中のとき、scheduled task がこの skill をプロンプトとして発火したとき
バックグラウンドの fork はバックグラウンド subagent 向けの狭いツールセットで動く。手順がそのセット外のツールに依存するなら background: false にする
バックグラウンドで動く forked skill の編集はセッションの checkpoint の外で適用されるため /rewind では戻せない。git で戻す
agent フィールドで subagent の設定を指定する。組み込み（Explore、Plan、general-purpose）または .claude/agents/ のカスタム subagent。省略時は general-purpose

方式	システムプロンプト	タスク	追加で読み込むもの
`context: fork` の skill	agent 種別から	SKILL.md の内容	CLAUDE.md（agent が Explore / Plan の場合を除く）
`skills` フィールドを持つ subagent	subagent の markdown 本文	Claude の委譲メッセージ	preload した skill + CLAUDE.md

context: fork は明示的な指示を持つ skill にのみ意味がある。タスクの無いガイドラインだけの skill では、subagent は実行可能なプロンプトを受け取らず意味のある出力を返さない

Claude の skill アクセス制御

/permissions で Skill ツールを deny するとすべての skill を無効にできる
permission ルールで個別に許可・拒否する。Skill(name) は完全一致、Skill(name *) は任意の引数を伴う前方一致
disable-model-invocation: true を frontmatter に付けると、その skill は Claude のコンテキストから完全に外れる
user-invocable フィールドはメニューの可視性のみを制御し、Skill ツール経由のアクセスは制御しない
/init と /security-review を含むいくつかの組み込みコマンドは Skill ツール経由でも使える。/compact などは使えない

`skillOverrides`

skill 自身の frontmatter ではなく settings から可視性を制御する。/skills メニューで skill を選び Space で状態を循環、Enter で .claude/settings.local.json に保存できる。

値	Claude への一覧表示	`/` メニュー
`"on"`	名前と description	表示
`"name-only"`	名前のみ	表示
`"user-invocable-only"`	非表示	表示
`"off"`	非表示	非表示

/skills メニューは "user-invocable-only" を user-only と表示する
v2.1.199 以降、"off" は Remote Control クライアントと Agent SDK 呼び出し元に広告されるコマンド一覧からも隠す。隠された skill をフルネームで呼ぶと skillOverrides のエラーが返る
skillOverrides に無い skill は "on" として扱われる
plugin skill は skillOverrides の影響を受けない。/plugin で管理する

配布

Project skills: .claude/skills/ をバージョン管理にコミットする
Plugins: plugin に skills/ ディレクトリを作る
Managed: managed settings で組織全体に配布する

設定

---
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...

---
name: deploy
description: Deploy the application to production
context: fork
disable-model-invocation: true
---

---
name: render-chart
description: Render a chart from a CSV file
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)
---

Run `${CLAUDE_SKILL_DIR}/scripts/render.sh <csv-file>` to render the chart.

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

制約・注意点

skill 本文は簡潔に保つ。読み込まれた内容はターンをまたいでコンテキストに残るため、行ごとに継続的なトークンコストになる
frontmatter の YAML が壊れている場合、Claude Code は本文をメタデータ空で読み込むため /skill-name は動くが description によるマッチングができない。--debug でパースエラーを確認する
skill 名と description の一覧はコンテキストに読み込まれる。skill が多いと description が予算に合わせて短縮され、マッチングに必要なキーワードが落ちることがある。予算はモデルのコンテキストウィンドウの 1%。溢れると呼び出し回数の少ない skill から description が落とされる
- 予算を上げるには skillListingBudgetFraction 設定（例: 0.02 = 2%）または SLASH_COMMAND_TOOL_CHAR_BUDGET 環境変数（固定文字数）
- 低優先度のエントリを skillOverrides で "name-only" にすると予算を空けられる
- 各エントリの合計テキストは予算に関わらず 1,536 文字が上限。上限は skillListingMaxDescChars で設定できる
- /doctor で一覧のコンテキストコストの見積もりと主な要因を確認できる。予算超過時は debug log に警告が書かれる
/context の Skills 行は予算適用後の一覧サイズを報告する（v2.1.196 より前は全 description の全文を数えていた）