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 以降）:
/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 以降が必要- 記録ファイルは、実行が誤った方向に導かれたとき（失敗したコマンド、欠けていた手順）にのみ編集される
配置場所
- 同名の 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 以降）。
Claude Code の外での frontmatter
- spec が許さないフィールドを含めると、無視されるのではなくパッケージング・アップロードがハードエラーで失敗する
- dynamic context injection のような Claude Code 固有の本文機能は claude.ai チャットや API では機能しない
コマンド名の決まり方
- personal / project の skill では
name は一覧の表示ラベルのみを決め、コマンドはディレクトリ名・ファイル名から来る
- plugin skill では
name がコマンドの最後のセグメントを置き換え、plugin 接頭辞は残る。素の /fancy も、他のコマンドがその名前を使っていなければ呼び出せる。v2.1.216 より前は frontmatter 名がコマンド名全体を置き換えていた
- 非対話セッションでは
help と feedback はターミナル専用組み込みのために予約されないため、それらの名前の plugin skill は素のコマンドを保つ。/login など他のターミナル専用組み込みの名前は予約される
文字列置換
${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 行未満に保ち、詳細なリファレンスは別ファイルへ移す
呼び出しの制御
- 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 が丸ごと落ちることがある
- 列挙したツールを、その 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 にのみ意味がある。タスクの無いガイドラインだけの 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 に保存できる。
/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 の全文を数えていた）
関連
facts/claude-code/commands.mdfacts/claude-code/sub-agents.mdfacts/claude-code/plugins.mdfacts/claude-code/memory.mdfacts/claude-code/hooks.mdfacts/claude-code/permissions.mdfacts/claude-code/settings.mdfacts/claude-code/model-config.mdfacts/claude-code/context-window.mdfacts/claude-code/cli-reference.md