スキル

スキル（skill）は、SKILL.md に書いた手順や知識を Claude の道具箱に加える仕組みです。Claude が場面に合わせて自動で読み込むほか、/skill-name で直接呼び出せます。.claude/commands/ のカスタムコマンドはスキルに統合されており、従来のファイルもそのまま使えます。

要点#

• 同じ指示や手順を何度も貼るとき、CLAUDE.md の一節が「事実」ではなく「手順」になってきたときにスキルにする
• スキルの本文は使われたときだけ読み込まれる。長い参考資料も、呼ばれるまでほとんどコストがかからない
• disable-model-invocation と user-invocable で、呼び出せる主体（自分か Claude か）を切り替えられる
• ! で始まるコマンド注入で、実行時点の git diff などを本文に差し込める
• context: fork でサブエージェントに任せられる（サブエージェント参照）
• Claude Code のスキルは Agent Skills のオープン標準に沿い、独自拡張を加えたもの

同梱スキル（bundled skills）#

/doctor・/code-review・/batch・/debug・/loop・/claude-api などが最初から入っています。同梱スキルはプロンプト型で、Claude が詳しい指示を受けてツールで作業を進めます（組み込みコマンドの多くは固定の処理を直接実行します）。呼び出し方は他のスキルと同じです。

• Claude が自動で使うものと、/verify のようにあなたが呼んだときだけ動くものがあります
• 多くは全セッションで使えますが、/workflow-authoring のように特定の機能（ワークフロー）が有効なときだけ使えるものもあります
• 同梱スキルを止めるには disableBundledSkills 設定を使います
• v2.1.205 以降、disableBundledSkills が有効でも /doctor は入力できます。隠すには環境変数 DISABLE_DOCTOR_COMMAND か、skillOverrides の "doctor": "off" を使います。v2.1.205 より前の /doctor は組み込みコマンドでした
• 一覧はスラッシュコマンド一覧で、Purpose 列に Skill と付いています

アプリを動かして確かめる 3 つのスキル#

• /run と /verify は設定なしで動き、プロジェクトの種類や README・package.json・Makefile から起動方法を推測します。データベース・env ファイル・GUI セッション・多段ビルドが要るプロジェクトでは推測が不安定です
• /run-skill-generator はきれいな環境からアプリを動かし、うまくいった手順（インストールコマンド・環境変数・起動スクリプト）を .claude/skills/run-<name>/ にプロジェクトのスキルとして記録します。プロジェクトごとに1回、ビルドや起動手順が変わったら再実行します
• /verify も、記録された手順が無いままビルドして操作した場合、うまくいった手順を .claude/skills/verify/SKILL.md に書きます（モノレポでは触ったパッケージのディレクトリ）。リポジトリ直下に置かれた記録は、同梱の /verify を置き換えます。v2.1.200 以降が必要です
• Claude が記録を書き換えるのは、手順が誤って実行を迷わせたとき（失敗したコマンド・足りない手順）だけです。v2.1.205 より前は、実行で学んだことを何でも書き足すため、マージ競合が頻発しました

/claude-api のサブコマンド#

/claude-api は、プロジェクトの言語向けに Claude API と Managed Agents の資料を読み込みます。コードが anthropic や @anthropic-ai/sdk を import すると自動でも有効になります。/claude-api migrate のように、スキル名の後ろにサブコマンドを付けます。

コミットの前に確認を走らせる#

セッションの開始時に、verify か simplify という名前のスキルが入っていると、Claude Code のコミットの指示が、docs やテストだけの変更を除き、コミットの直前にそれを動かすよう Claude に伝えます。Claude Code v2.1.286 以降が必要です。セッションの開始時に次の条件が揃うと、Claude はこの指示を受け取ります。

• 置き場所：スキルが Enterprise・Personal・Project・追加ディレクトリの置き場所、または同名の .claude/commands/ のファイルから読み込まれる。/verify がリポジトリのルートに記録する手順は Project のスキルなので、数えられる。同梱の /verify と /simplify、プラグインのスキル、claude.ai のアカウントのスキルは数えられない
• 呼び出し：Claude がそのスキルを呼べる。disable-model-invocation: true などで呼べないようにしていると、Claude はこの指示を受け取らない
• git の指示：includeGitInstructions をオフにしていない。オフにすると、組み込みのコミットと PR の指示の残りと一緒に、この指示も消える

最初のスキルを作る#

変更中の差分を要約してリスクを指摘するスキルの例です。

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

~/.claude/skills/summarize-changes/SKILL.md に次を保存します。

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

• SKILL.md は、YAML の frontmatter（--- で囲む）と、実行時に Claude が従う Markdown 本文の2部構成です
• 入力するコマンド名は、ディレクトリ名（または frontmatter の name）です。description は Claude が自動で読み込むかの判断に使われます
• !`git diff HEAD` の行は、Claude が読む前にコマンドが実行され、出力に置き換わります
• 試すには、git プロジェクトで少し編集して claude を起動し、「What did I change?」のように尋ねるか、/summarize-changes と入力します

置き場所#

保存場所で、どのセッションが読み込むかが決まります。

• シンボリックリンク：Enterprise・Personal・Project の <skill-name> は、別の場所のディレクトリへのシンボリックリンクにできます。複数の場所が同じ実体を指しても1回だけ読み込まれます
• 予約名 synced：スキルのフォルダ名に synced（大文字小文字を問わない）を使わないでください。~/.claude/skills/synced/ は claude.ai から同期したスキルの置き場で、同名で自作したものは Enterprise・Personal・Project では読み飛ばされます
• 予約名 anthropic-skills：プラグイン以外で、フォルダ名・コマンドファイル名が anthropic-skills または anthropic-skills: で始まるものは読み込まれません
• コマンドファイル：.claude/commands/ の Markdown ファイルは古い形式で、name と paths 以外の frontmatter が使えます。新しく作るならスキルを使います（補助ファイルを置けるため）
• スキルフォルダをプラグインにする：スキルフォルダに .claude-plugin/plugin.json を置くと、<name>@skills-dir というプラグインとして読み込まれ、エージェント・フック・MCP サーバーも同梱できます。プロジェクトの .claude/skills/ では、先にワークスペースの信頼ダイアログを承認する必要があります

モノレポとサブディレクトリ#

• 起動したディレクトリと、リポジトリルートまでの各親ディレクトリの .claude/skills/ を読み込みます。packages/frontend/ で起動しても、ルートのスキルが使えます
• v2.1.246 以降は、/cd でセッションを移すと、移動先のプロジェクトスキルが加わります
• リンクされた git worktree では、親の探索は worktree のルートまでです。v2.1.277 以降は、worktree に .claude/skills が無ければ、メインのチェックアウトのプロジェクトスキルを読み込みます（worktree参照）
• 起動した場所より下にある .claude/skills/ は、起動時には読み込まれません。そのサブディレクトリのファイルを Claude が初めて読む・編集するときに読み込まれ、以降セッション中は有効です。それまでは / メニューに出ず、名前で呼べません。先に読み込むには、そのパスで /add-dir を実行します（v2.1.257 以降）
• 親と入れ子で同名のスキルがあるときは両方残ります。ルートの deploy と apps/web/.claude/skills/ の deploy なら、/deploy はルートのもの、/apps/web:deploy は入れ子のものを実行します

追加ディレクトリのスキル#

--add-dir や /add-dir で加えたディレクトリは、.claude/skills/ のほか .claude/commands/ と .claude/agents/ も読み込まれます。Agent SDK の additionalDirectories（TypeScript）や add_dirs（Python）も同じ扱いです。settings.json の permissions.additionalDirectories はファイルへのアクセスを許可するだけで、これらは読み込みません。

• 起動時に --add-dir で渡したディレクトリの .claude/skills/ は監視されますが、.claude/commands/ と .claude/agents/ は監視されないので、変更後はセッションを再起動します
• この読み込みは project の設定ソース（既定で有効）に依存します。strictPluginOnlyCustomization ポリシー・bare モード・--safe-mode では制限されます

同名のスキルの優先順位#

Cowork とクラウドセッション#

Cowork とクラウドセッション（ルーティンを含む）は、手元の ~/.claude/skills/ を読みません。claude.ai アカウントで有効なスキルを、セッション開始時に同期して使います（Desktop アプリの「Customize」か claude.ai のスキル設定で管理）。クラウドセッションは、クローンしたリポジトリの .claude/skills/ のプロジェクトスキルも読み込みます。

• ~/.claude/skills/ にしか無いスキルをルーティンが呼ぶと、見つからないと報告されます（実行のたびに新しいクラウドセッションが始まるため）
• 使えるようにするには、claude.ai アカウントで有効にするか、クラウドセッションならリポジトリの .claude/skills/ にコミットします。リポジトリの .claude/settings.json で宣言したプラグインや、ユーザー設定だけで有効にしたプラグインは、クラウドセッションに読み込まれません
• デスクトップのスケジュールタスクはローカルで動くので、~/.claude/skills/ を読み込みます

claude.ai から同期されるスキル#

Cowork・クラウドセッション・claude.ai アカウントでサインインしたターミナルでは、アカウントで有効なスキル（自分で作った・組織が提供する・pdf や xlsx などの Anthropic 組み込みスキル）が設定なしで読み込まれます。

• ターミナルでの同期（v2.1.273 以降）：開始時に ~/.claude/skills/synced/ へバックグラウンドでダウンロードし、実行中は約10分ごとに変更を確認します。追加・編集・無効化は再起動なしで反映されます。起動を遅らせず、そのスキルを呼ぶときにだけダウンロードを待ちます
• 短い非対話実行は、新しいスキルのダウンロード前に終わることがあります。待たせるには環境変数 CLAUDE_CODE_SYNC_SKILLS を 1 にします
• 同期されないセッション：/login 以外の認証（API キー・ANTHROPIC_AUTH_TOKEN・CLAUDE_CODE_OAUTH_TOKEN・apiKeyHelper）／機能フラグを取得しないセッション（Amazon Bedrock・CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 設定時）／bare モードと --safe-mode／管理設定でスキルをプラグインに限定している場合や --setting-sources から user を外した場合
• セッション中に /login した場合は、再起動すると同期が始まります
• 一度同期されたスキルはディスクに残り、claude.ai に接続できなくても同じアカウントの後のセッションで読み込まれます
• ダウンロードのみで、アップロードはしません。~/.claude/skills/synced/ の中を編集しても保存されず、次の同期で上書き・削除されることがあります。変更は claude.ai で行います
• 同期されたスキルは /skills の「claude.ai sync」の下に出ます。pdf や xlsx などは常に同期され、他は claude.ai のスキル設定のオン・オフで決まります
• 同期を止めるには、ユーザー設定の syncClaudeAiSkills を false にします。次の起動で、同期済みのスキルは ~/.claude/skills/.trash/ へ移り、読み込まれなくなります。組織が claude.ai で Skills をオフにすると全員の同期が止まり、Skills を残したまま止めるには管理設定に同じキーを置きます。組織が Skills をオフにしたときも、ダウンロード済みのスキルは .trash/ へ移り、保持期間の掃除で消えるまで復元できます

同期スキルの名前が他と重なるとき#

同期スキルは短い名前 /<name> か完全名 /anthropic-skills:<name> で呼べます。短い名前を他のコマンドが使っていれば、/<name> はそちらを実行し、同期スキルは完全名でのみ動きます（ローカルの deploy と同期の deploy なら、/deploy がローカル、/anthropic-skills:deploy が同期）。v2.1.269 より前は短い名前しかありませんでした。

• 短い名前を使う側は、組み込みコマンド・同梱スキル（無効にして使えない場合を含む）・ローカルのスキルや .claude/commands/ のファイル・プラグインのスキル・MCP プロンプトのいずれでもよい
• / メニュー・/skills・/context では、短い名前（他が使っていれば完全名）で表示されます。/skills の一覧の下に、短い名前を失った同期スキルの説明が出ます
• v2.1.269〜v2.1.280 は、これらの一覧が全部の同期スキルを完全名で出し、/skills に説明がありませんでした。v2.1.281 で変わりました
• 名前の比較では、大文字小文字・空白・不可視文字を無視し、全角文字やダッシュの異体字は通常の形として扱います（同期の Commit とローカルの commit は同じ名前）。他の文字体系の似た文字で違うだけの名前は別の名前です。この判定と表示は v2.1.228 以降が必要です

予約名 anthropic-skills#

anthropic-skills と、その名前空間の中の名前（anthropic-skills:pdf など）は、同期スキルのために全セッションで予約されています。

• スキルフォルダ・frontmatter の name・.claude/commands/ のファイルやサブフォルダ・保存済みワークフロー：読み込まれません。起動時の通知が、直す最初の項目を示します
• anthropic-skills という名前のプラグイン：読み込まれます。そのスキルと同期スキルが同名なら、/anthropic-skills:<name> が同期スキルを実行します
• anthropic-skills という名前の MCP サーバー：接続されツールも動きますが、プロンプトはコマンドとして出ません。サーバー名を変えると出ます

同期スキルの frontmatter と本文の扱い#

• frontmatter はすべての種類のセッションで有効です。allowed-tools の許可は通常の権限の流れを通ります。組織が allowManagedPermissionRulesOnly を設定していると、その許可は適用されません（「managed の権限ルールだけが効くとき」）
• description など表示用テキストは無害化されます（制御文字を除き、Claude に届く文章では山括弧をエスケープ）。v2.1.228 以降
• 本文：クラウドセッションではローカルのスキルと同じ動作です。デスクトップの Cowork では、! コマンド行が disableSkillShellExecution のプレースホルダーに置き換わる以外は同じです。それ以外のセッションでは、! コマンドを実行せず、@ 参照のファイル添付も ${CLAUDE_PROJECT_DIR}・${CLAUDE_SESSION_ID} の置換もしないので、そのまま文字として Claude に届きます（v2.1.228 以降）

セッション中の編集#

bare モード以外では、スキルのディレクトリを監視しています。~/.claude/skills/・プロジェクトの .claude/skills/・--add-dir ディレクトリの .claude/skills/ で追加・編集・削除すると、再起動なしで反映されます。

• セッション開始時に無かったトップレベルのスキルディレクトリを新しく作ったときは /reload-skills を実行します（まだ監視されていないので、その後の変更のたびにも実行します）
• 検知されるのは SKILL.md の本文だけです。スキルフォルダがプラグインでもある場合、hooks/・.mcp.json・agents/・output-styles/ の変更には /reload-plugins が必要です

スキルを取り除く#

スキルを残しつつ Claude の自動呼び出しだけ止めるには、frontmatter に disable-model-invocation: true を書くか、ファイルを編集したくない場合は skillOverrides に "user-invocable-only" を設定します。

スキルを設定する#

内容の種類#

• 参考型：規約・パターン・スタイルガイド・業務知識など、Claude が今の作業に適用する知識。会話の文脈の中でインラインで使われる
• タスク型：デプロイ・コミット・コード生成などの手順書。/skill-name で直接呼ぶことが多く、disable-model-invocation: true で Claude の自動起動を防ぐ。context: fork を付けると独自のサブエージェントの文脈で動く

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

Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target

frontmatter のフィールド一覧#

SKILL.md の先頭の --- で囲んだ YAML です。フィールド名は小文字をハイフンでつなぐ形（when_to_use だけ例外）です。.claude/commands/ のコマンドファイルは、name と paths 以外が使えます。

---
name: my-skill
description: What this skill does
disable-model-invocation: true
allowed-tools: Read Grep
---

Your skill instructions here...

• すべて任意ですが、Claude が使いどきを判断できるよう description は推奨です
• 名前はハイフンも含めて表のとおりに一致させる。未知のフィールドはエラーなしで無視される
• frontmatter は、開きの --- がファイルの1行目にあるときだけ読まれる。そうでなければ --- を含めた全体が本文になる。YAML が壊れていると、フィールドなしで読み込まれる
• 真偽値は true・false のほか、yes・no・on・off・1・0（大文字小文字を問わない）が使える。v2.1.218 より前は true・false だけ

Claude Code の外で使える frontmatter#

• 個人のスキルを claude.ai アカウントで有効にする（Cowork・クラウドセッション・ルーティン用など）のはアップロードなので、同じ規則が当てはまります
• 仕様にないフィールドが入っていると、無視されずパッケージ化・アップロードがエラーで失敗します（例：argument-hint があると "Unexpected key(s) in SKILL.md frontmatter" と出る）。仕様の6フィールドに絞れば避けられ、そのスキルは変更なしで Claude Code でも読み込まれます
• 動的コンテキスト注入のような Claude Code 専用の本文機能は、claude.ai のチャットや API では動きません

コマンド名の決まり方#

呼び出すコマンド名は、スキルファイルの置き場所と、スキルディレクトリ・プラグインスキルでは frontmatter の name で決まります。個人・プロジェクトのスキルディレクトリでは、name が / メニューと入力するコマンドになります（他のコマンドが同名を使っていない限り）。ディレクトリ名でも呼べます。プラグインのスキルでは、name がコマンドの最後の部分になり、プラグインの接頭辞は残ります。

• プラグインのスキルでは、他のコマンドが使っていない限り、接頭辞なしの /fancy でも呼べます
• v2.1.246 以降は、name がすでにプラグインの接頭辞で始まっていても接頭辞を二重に付けません（name: my-plugin:fancy でも /my-plugin:fancy）。v2.1.216〜v2.1.245 は二重になっていました
• 非対話セッションでは、help と feedback は端末専用の組み込みコマンド用に予約されないので、その名前のプラグインスキルは接頭辞なしでも動きます。他の端末専用の組み込み名（/login など）は予約されたままです

文字列の置換#

${CLAUDE_SKILL_DIR} と ${CLAUDE_PROJECT_DIR} は、本文と、allowed-tools の Bash ルールの2か所で置換されます（プラグインでは ${CLAUDE_PLUGIN_ROOT}・${CLAUDE_PLUGIN_DATA} も同じ2か所）。両方に同じ変数を使うと、同梱スクリプトを確認なしで実行できます。

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

• 位置引数はシェル風の引用符を使う。/my-skill "hello world" second なら $0 が hello world、$1 が second。$ARGUMENTS は入力されたままの全文字列
• 引数のない位置のプレースホルダー（1つしか渡していない時の $2）は、そのまま残る。arguments で宣言した名前付きの値で引数が無いものは、空文字列になる
• 引数の値に $1 や $ARGUMENTS のような文字が含まれていても、展開されず文字のまま挿入される。${CLAUDE_*} は引数の挿入後に置換される
• 本文に $1.00 のように書きたいときは \$1.00 とバックスラッシュで逃がす。直前の1つのバックスラッシュだけが有効で、\\$1 は両方残り $1 は展開される。この逃がしは引数のプレースホルダーだけが対象で、${CLAUDE_*} の置換は防げない

---
name: session-logger
description: Log activity for this session
---

Log the following to logs/${CLAUDE_SESSION_ID}.log:

$ARGUMENTS

補助ファイルを置く#

スキルのディレクトリには複数のファイルを置けます。SKILL.md は要点にとどめ、詳しい資料は必要なときだけ読ませます。

my-skill/
├── SKILL.md (required - overview and navigation)
├── reference.md (detailed API docs - loaded when needed)
├── examples.md (usage examples - loaded when needed)
└── scripts/
    └── helper.py (utility script - executed, not loaded)

SKILL.md から、各ファイルの中身と読むべき場面を参照させます。

## Additional resources

- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

誰が呼べるかを決める#

既定では、あなたも Claude もどのスキルも呼べます。2つのフィールドで制限します。

• disable-model-invocation: true：Claude が自分では呼べない。/commit・/deploy・/send-slack-message のように副作用があったり、タイミングを自分で決めたい手順向け。コードが整ったように見えただけで Claude にデプロイを決めさせたくない場合に使う
• user-invocable: false：Claude だけが呼べる。コマンドとして意味のない背景知識向け（古いシステムの仕組みを説明する legacy-system-context など）

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

Deploy $ARGUMENTS to production:

1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

Claude が呼ぼうとしても、Claude Code はその呼び出しを止め、手順を別の方法で再現しないよう指示します。Claude は /deploy を自分で実行するよう提案します。

スキルの名前をどこに書くか#

スキルを直接動かすには、メッセージの先頭にその名前を置きます。ふつうの文のあとに置いた名前は、Claude にスキルを動かす許可を与えますが、直接は動かしません。

スキルについて書くだけで、動かす許可は与えたくないときは、スラッシュを付けません。

スキル内容のライフサイクル#

スキルを呼ぶと、展開済みの SKILL.md が1つのメッセージとして会話に入り、後のターンも残ります。残るのは指示であり、権限ではありません（allowed-tools の許可は次のメッセージで失効）。Claude Code は後のターンでスキルのファイルを読み直しません。そのため、作業全体に効かせたい指針は、1回きりの手順ではなく常時有効な指示として書きます。

• 展開結果が同じスキルを再度呼んだときは、2つ目の本文は入れず「すでに読み込み済み」という短い注記を入れる。引数が変わった・動的コンテキストの出力が変わったなどで内容が違えば、全文を再び追加する
• 自動コンパクションでは、呼ばれたスキルがトークン予算内で引き継がれる。要約の後に、各スキルの最新の呼び出しを再添付し、それぞれ先頭 5,000 トークンまで残す。再添付されるスキル全体の予算は合計 25,000 トークンで、最近呼んだスキルから順に埋める。1セッションで多数のスキルを呼ぶと、古いものはコンパクション後に完全に落ちることがある

ツールの事前承認#

allowed-tools は、スキルを呼んだターンの間、リストしたツールを確認なしで使えるようにします。次のメッセージを送ると失効し（スキルの内容は文脈に残っても）、もう一度呼ぶとそのターン分が再び有効になります。使えるツールを制限するものではなく、全ツールは呼べるままで、リストにないツールは通常の権限設定が決めます。セッション全体で事前承認したいなら、権限設定に許可ルールを足します。

• ワークスペースの信頼は、このフィールドの条件になりません。プロジェクトのスキルの allowed-tools は、信頼していないフォルダの -p 実行でも適用されます。スキルは自分で広いツールアクセスを許可できるので、リポジトリに入っているスキルの allowed-tools は、そこで Claude Code を動かす前に確認します。組織全体でリポジトリのスキルのこのフィールドを効かなくするには、「managed の権限ルールだけが効くとき」を参照してください
• disallowed-tools は、スキルが有効な間、Claude の使えるツールから外します（次のメッセージで解除）。全スキル・全プロンプトで禁止するなら、権限設定に deny ルールを足します

---
name: commit
description: Stage and commit the current changes
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

managed の権限ルールだけが効くとき#

組織が managed settings で allowManagedPermissionRulesOnly を設定していると、Claude Code は、Project と Personal のスキルの allowed-tools、および設定キーの項目が挙げる他の出どころの allowed-tools を無視します。Claude Code v2.1.282 以降が必要です。

影響を受けるスキルが挙げるツールは、組織の managed のルールと通常の権限の確認を通ります。/status を実行すると、セッションでこれまでに allowed-tools が無視されたスキルが一覧に出ます。managed のルールが許さない、スキルの中の注入コマンドは、「注入コマンドの権限チェック」に従います。

引数を渡す#

あなたも Claude も、スキルに引数を渡せます。$ARGUMENTS が、スキル名の後ろの文字列に置き換わります。

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit

/fix-issue 123 と実行すると、「Fix GitHub issue 123 following our coding standards...」が Claude に渡ります。

• どのプレースホルダー（$ARGUMENTS・$1 などの添字形・名前付き引数）にも引数が渡らなかったときは、末尾に ARGUMENTS: <入力> が追加される。引数のない添字形はそのまま残り、受け取ったことにならない。名前付きは位置に引数が無くても空文字列になるので、受け取ったことになる
• 1つのメッセージの先頭で、複数のスキルを重ねられる。/write-tests /fix-issue 123 は両方を読み込み、後ろの 123 を両方の $ARGUMENTS として渡す
• 展開されるのは最初のスキルと、続く最大5つです。インラインでユーザーが呼べるスキル以外のトークンに当たると展開は止まります。フォークされたサブエージェントとして動くスキル（/code-review など。v2.1.218 から。それ以前はインラインで重ねられた）や、引数がスラッシュコマンドで始まりうるもの（/loop）もそこで止まり、そのトークン以降全部が、展開された各スキルの引数文字列になります

添字で個別に取るには $ARGUMENTS[N] か短縮形の $N を使います。

---
name: migrate-component
description: Migrate a component from one language to another
---

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

/migrate-component SearchBar JavaScript TypeScript なら、$0 が SearchBar、$1 が JavaScript、$2 が TypeScript になります。

応用#

動的コンテキストの注入#

!`<command>` の書式は、スキルの内容が Claude に送られる前にシェルコマンドを実行し、出力でその場所を置き換えます。Claude にはコマンドでなく実際のデータが届きます。claude.ai から同期したスキルでは、手元でこれらのコマンドは実行されません（v2.1.228 以降）。

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...

• 置換は元のファイルに対して1回だけ。コマンドの出力は、さらなる !`<command>` として再走査されない
• インライン形は、! が行頭か空白の直後にあるときだけ認識される。KEY=!`cmd` のように他の文字の後ろでは、文字のまま残りコマンドは動かない
• 複数行のコマンドは、```! で開いたフェンスのコードブロックを使う

## Environment
```!
node --version
git status --short
```

• ユーザー・プロジェクト・プラグイン・追加ディレクトリ由来のスキルとカスタムコマンドで無効にするには、設定に "disableSkillShellExecution": true を書く。各コマンドは [shell command execution disabled by policy] に置き換わる。同梱スキルと管理スキルは対象外。ユーザーが上書きできない管理設定に置くのが有効
• claude.ai 同期スキルのコマンドは、この設定に関わらず手元では実行されない（v2.1.228 以降）

注入コマンドの実行方法#

実行に使うツールは、frontmatter の shell と環境で決まります。どの組み合わせも Bash ツールか PowerShell ツールで動き、例外が1つあります。

• shell: powershell で PowerShell ツールが有効：PowerShell ツールで動く
• shell: bash で bash が使えない：コマンドが走る前に呼び出しが失敗する（Git Bash の無い Windows）。"Skill <name> requires bash (shell: bash in frontmatter) but Git Bash was not found" と出る
• それ以外：bash が使えれば Bash ツール、使えなければ PowerShell ツール

Claude 自身のシェルコマンドと同じ扱いで、作業ディレクトリ・タイムアウト・出力処理を共有します。

• 作業ディレクトリ：セッションのシェルの現在のディレクトリ（Claude が cd すると動く）。毎回同じに解決させたいパスには ${CLAUDE_SKILL_DIR} か ${CLAUDE_PROJECT_DIR} を使う
• stderr：既定の bash では stdout に混ぜられ、stderr に書いた内容も注入されるテキストに入る
• タイムアウト：各コマンドに Bash ツールの既定の2分のタイムアウトがかかる。Bash ツールがタイムアウトしたコマンドをバックグラウンドへ移した場合、スキルは展開され、注入テキストに移動したこととバックグラウンドタスク・出力ファイルが書かれる。自動でバックグラウンドへ移さない種類のコマンドは、タイムアウトで kill され、呼び出しが中止される
• 出力サイズ：Bash ツールのインライン上限を超えた出力は、切り詰めたテキストでなく、ファイルのパスと短いプレビューで届く

注入コマンドが失敗したとき#

失敗したコマンドは、そのプレースホルダーだけでなくスキルの呼び出し全体を中止します。Claude にはそのスキル内容が見えません。Shell command failed for pattern "..." と出て、エラーに [stderr] の下にコマンドの出力が入ります。

• 既定の bash では、0 以外の終了コードはすべて失敗。例外として、検索・比較系のコマンドの終了コード 1 は正常な結果として扱われ、出力が注入される。終了コード 2 以上は、それらでも失敗する
• 例外の対象は、既定の bash ではツール一覧の出力制限の節にあるコマンド。shell: powershell で PowerShell ツールが有効なら別の集合（grep と git diff を含み、find と diff は含まない）
• 既定の bash で、他に非 0 で終わると分かっているコマンドには || true を付ける（問題を見つけると 1 で終わるチェックスクリプトなど）

注入コマンドの権限チェック#

注入コマンドは、スキルの展開中に確認を出しません。先に権限ルールで判定され、deny ルールに当たると Shell command permission check failed for pattern "..." で呼び出しが中止されます。

• auto モード以外では、判定が allow 以外（普段なら確認が出るルールを含む）だと、同じエラーで中止される。一致しないコマンドで中止しないよう、allowed-tools で事前承認する。組織が権限ルールを managed settings だけに制限しているなら、「managed の権限ルールだけが効くとき」を参照してください。deny と ask のルールは allowed-tools より優先される
• auto モードでは、確認が要るコマンドでも中止されない。そのコマンドを先に実行するよう Claude に指示した状態でスキルが読み込まれ、Claude 自身の呼び出しが auto モードの通常の判定を通る。ただし、agent を指定したフォークされたスキルと、注入コマンドを動かすシェルツールを Claude が持たないセッションでは中止される

サブエージェントで実行する#

frontmatter に context: fork を書くと、スキルを隔離して実行します。agent で指定した種類の新しいサブエージェントが起動し、スキルの内容がそのプロンプトになります。サブエージェントは会話履歴を見ないので、指示だけで完結している必要があります。

• フォークされたサブエージェントは、既定でバックグラウンドで動きます。作業を続けられ、結果は完了時に会話へ届きます。呼んだターンで結果を待つには、background: false にします。v2.1.218 より前は、フォークされたスキルは終わるまでターンを止めていました
• background: false がなくても待つ場合：-p や Agent SDK の非対話モード／CLAUDE_CODE_DISABLE_BACKGROUND_TASKS が 1（他のバックグラウンド機能も全部止まる）／同じスキルの前の呼び出しがまだ動いている間に呼んだとき／スケジュールタスクがそのスキルをプロンプトとして発火したとき
• バックグラウンドのフォークは、バックグラウンドのサブエージェント向けの狭いツールセットで動く。会話をフォークするサブエージェントへの例外は、通常の種類のエージェントであるスキルのサブエージェントには当てはまらない。外のツールに依存する手順なら background: false にして全ツールを保つ
• バックグラウンドのフォークが行った編集は、セッションのチェックポイントの外で適用されるので、/rewind で戻せない。git で戻す（チェックポイント参照）

スキルとサブエージェントは2方向で組み合わせられます。

context: fork では、タスクをスキルに書き、実行するエージェントの種類を選びます。組み込みの Explore と Plan は文脈を小さく保つため CLAUDE.md と git status を読み込まないので、agent: Explore のフォークされたスキルが見るのは、SKILL.md の内容とそのエージェントのシステムプロンプトだけです。逆に、カスタムサブエージェントがスキルを参考資料に使う形はサブエージェントにあります。

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

実行の流れ：新しい隔離された文脈が作られる → サブエージェントがスキルの内容をプロンプトとして受け取る → agent が実行環境（モデル・ツール・権限）を決める → サブエージェントが結果を要約して、終了時にメインの会話へ返す。agent には、組み込み（Explore・Plan・general-purpose）か .claude/agents/ のカスタムサブエージェントを指定でき、省略すると general-purpose です。

Claude のスキルアクセスを制限する#

Claude は、disable-model-invocation: true でないスキルをすべて呼べます。allowed-tools を持つスキルは、そのターンの間、そのツールを確認なしで使えます。それ以外のツールの承認は権限設定が決めます。/init や /security-review などの一部の組み込みコマンドも Skill ツール経由で呼べますが、/compact などは呼べません。制限の方法は3つです。

すべてのスキルを無効にする：/permissions で Skill ツールを deny にします。

# Add to deny rules:
Skill

特定のスキルを許可・拒否する：権限ルールを使います。

# Allow only specific skills
Skill(commit)
Skill(review-pr *)

# Deny specific skills
Skill(deploy *)

書式は、完全一致が Skill(name)、任意の引数を含む前方一致が Skill(name *) です。deny ルールは、書いた名前の他に何を止めるかが、名前の種類で変わります。

• v2.1.260 より前は、deny ルールが修飾なしの名前だけのとき、修飾名で並ぶ入れ子のスキルは止まりませんでした
• allow ルールは、スキル自身の名前と Claude の呼び出しの名前にだけ一致します。同期スキルを確認なしで承認するには、予約された名前空間の中で書きます：Skill(anthropic-skills:pdf) は同期の pdf、Skill(anthropic-skills *) は同期スキル全部。Skill(anthropic *) は名前空間の外の接頭辞なので anthropic-skills:pdf に一致しません

個別に隠す：frontmatter に disable-model-invocation: true を足します。スキルが Claude の文脈から完全に外れます。

設定からスキルの表示を変える#

skillOverrides 設定は、スキル自身の frontmatter でなく設定で、スキルの見え方を決めます。共有リポジトリに入っているなど、SKILL.md を編集したくないスキル向けです。/skills メニューでスキルを選び Space で状態を切り替え、Esc で .claude/settings.local.json に保存できます。キーはスキル名、値は次の4つです。

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

• /skills メニューは "user-invocable-only" を user-only と表示します。skillOverrides に無いスキルは "on" として扱われます
• "off" は、ターミナルの / メニューに加え、Remote Control のクライアントと Agent SDK の呼び出し側に出るコマンド一覧からも隠します。隠したスキルを完全名で呼ぶと、skillOverrides のエラーが返ります
• 同梱スキルには /doctor の checkup のようなエイリアスがあります。管理設定か --settings で渡したファイルのエイリアス名の項目は、エイリアスの先のスキルに適用されます。エイリアス経由では、より制限する方向にしか設定できず、管理設定でスキル自身の名前の項目があれば、それが優先されます。v2.1.260 より前は、どの設定ソースでもエイリアス名の項目は適用されませんでした
• ユーザー・プロジェクト・ローカル設定では、スキル名にだけ一致します（review の項目は review という名前のスキルに効き、エイリアス /review 経由の同梱 /code-review には効かない）
• プラグインのスキルは skillOverrides の対象外です。/plugin で管理します

使われていないスキルを探す#

スキル一覧の各エントリは、Claude が使うかどうかに関わらず、毎ターン文脈を使います。/skill-doctor を実行すると、各スキルのコストと使用頻度が分かり、オフにするものを決められます。対話セッションでは /plugin マネージャーの「Stats」タブにレポートが開き、-p の非対話モードではテキストで出ます。

• 対象は同梱スキルと Enterprise スキルを除く、セッション内のスキル。一覧にあるのに一度も呼ばれていないスキルに印を付け、オフにする場所を示す。文脈コストの大きいものから手を付ける。最近使っていないプラグインも一覧に出る
• v2.1.252 以降が必要で、機能フラグの取得を省くセッションでは使えない
• Remote Control 越し（スマホやブラウザ）では、Skill usage reports are not available on this connection. と返る。セッションの動くマシンのターミナルで実行する

スキルを評価して改善する#

スキルが起動したのを見ても、意図どおりに働いたことにはなりません。Claude が呼ぶべきプロンプトで呼んでいるかと、呼んだときの出力が期待どおりかを、別々に測ります。

どちらも、ベースライン比較で確かめます。現実的なプロンプトをいくつか集め、それぞれを新しいセッションで、スキルありとなしで実行して結果を比べます。スキルを作ったときの文脈が残っていると、指示の書き漏れが隠れるので、新しいセッションにします。2回目にスキルを切る方法は次のとおりです。

• Personal・Project のスキル：skillOverrides で "off" にする
• プラグインのスキル：skillOverrides は効かない。各実行をプラグインを読み込まずに繰り返す claude plugin eval を使う（プラグインの評価参照）

比較を自動化する道具は2つあります。プラグインに入ったスキルには claude plugin eval があり、各プロンプトを、プラグインありとなしの隔離セッションで実行し、自分で定義するか自動生成させた採点基準で評価して、しきい値を下回れば 0 以外で終了するので CI で止められます。Claude Code の会話の中で1つのスキルを改善するには、次の skill-creator プラグインが、独自の evals/evals.json 形式で似たループを回します。2つの形式は互換ではありません。

skill-creator で評価する#

skill-creator プラグインは、公式マーケットプレイスから入れます。VS Code 拡張かデスクトップアプリでは、プラグインを使うの「プラグインを入れる」の手順で入れます。ターミナルでは、claude で Claude Code を起動し、そのプロンプトに次を入力します。

/plugin install skill-creator@claude-plugins-official

インストールに失敗したときは、表示されたメッセージで判断します。

• Marketplace "claude-plugins-official" not found：/plugin marketplace add anthropics/claude-plugins-official でマーケットプレイスを足し、入れ直す
• マーケットプレイスにプラグインが見つからない：プラグイン名を確認する

インストールの要約に Run /reload-plugins to activate. と出たら、Claude Code がその再読み込みを実行します。再読み込みが「次のメッセージで会話を読み直すことになる」と警告したら、/reload-plugins --force で現在のセッションにプラグインのスキルを入れます。その後、Claude に既存のスキルを評価させます（例：evaluate my summarize-changes skill with skill-creator）。プラグインがテストケース作りを案内し、次のループを回します。

• テストケース：プロンプト・入力ファイル・期待する挙動を、スキルディレクトリの evals/evals.json に保存する
• 隔離された実行：テストケースごとにサブエージェントを立て、毎回きれいな文脈で始め、トークン数と所要時間を記録する
• 採点：各アサーションを出力と突き合わせ、合否と根拠を grading.json に書く
• ベンチマーク：スキルありとなしの合格率・時間・トークンを benchmark.json に集計し、合格率の改善をトークン・時間のコストと比べられる
• バージョン比較：スキルの2つの版でブラインドの A/B を行い、編集が改善かをコミット前に確かめられる
• description の調整：起動すべき・すべきでないプロンプトを生成してヒット率を測り、誤った依頼で起動するなら description の修正案を出す
• レビュー画面：各出力を見て定性的な所感を記録できる HTML のレポートを開く。所感は次の反復で読まれる

共有する#

• プロジェクトスキル：.claude/skills/ をバージョン管理にコミットする
• プラグイン：プラグインに skills/ ディレクトリを作る（作り方はプラグインを作って配る）
• 管理：管理設定で組織全体へ配る

視覚的な出力を作る#

スキルは任意の言語のスクリプトを同梱して実行できるので、1つのプロンプトを超えた機能を Claude に持たせられます。ブラウザで開く対話的な HTML を生成し、データの調査・デバッグ・レポート作成に使うパターンがあります。例として、ディレクトリを展開・折りたたみでき、ファイルサイズが一目で分かり、種類が色で分かるコードベースの探索図を作るスキルです。

mkdir -p ~/.claude/skills/codebase-visualizer/scripts

~/.claude/skills/codebase-visualizer/SKILL.md：

---
name: codebase-visualizer
description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.
allowed-tools: Bash(python3 *)
---

# Codebase Visualizer

Generate an interactive HTML tree view that shows your project's file structure with collapsible directories.

## Usage

Run the visualization script from your project root:

```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .
```

This creates `codebase-map.html` in the current directory and opens it in your default browser.

• description が Claude にいつ有効にするかを伝え、本文が同梱スクリプトの実行を指示する
• スクリプトのパスに ${CLAUDE_SKILL_DIR} を使うので、個人・プロジェクト・プラグインのどの場所に置いても解決される
• scripts/visualize.py は、ディレクトリを走査して自己完結した HTML を作り、ファイル数・ディレクトリ数・合計サイズ・ファイル種別の数を出すサイドバー、種別ごとの棒グラフ（サイズ上位8）、色分けされた折りたたみツリーを備える。Python 3 の標準ライブラリだけで動き、追加のパッケージは要らない
• 試すには、任意のプロジェクトで「Visualize this codebase.」と頼みます。Claude がスクリプトを実行し、Generated /path/to/codebase-map.html のように生成したファイルのパスを出して、ブラウザで開きます。ブラウザが開かないヘッドレス環境でも、出力されたパスでスクリプトの成功が分かります

この方法は、依存関係グラフ・テストカバレッジのレポート・API ドキュメント・データベーススキーマの図にも使えます。スクリプトが処理をし、Claude は段取りを担当します。

トラブルシューティング#

スキルが起動しない#

1. description に、ユーザーが自然に言うキーワードが入っているか確かめる
2. 「What skills are available?」と尋ねて、スキルが一覧に出るか確かめる
3. description に近い言い方に依頼を言い換える
4. ユーザーが呼べるスキルなら、/skill-name で直接呼ぶ

frontmatter の YAML が壊れていると、メタデータが空のまま本文が読み込まれるので、/skill-name は動きますが、Claude は description で照合できません。--debug で実行するとパースエラーが見えます。

• プラグインのスキルなら、tool_used: Skill のグレーダーで評価ケースを書き、description を変えるたびに claude plugin eval で起動頻度を測れる（プラグインの評価参照）
• frontmatter が解析できない SKILL.md を探すには、スキルのディレクトリに対して claude plugin validate を実行する（プロジェクトなら claude plugin validate .claude/skills、個人なら claude plugin validate ~/.claude/skills）。v2.1.233 以降が必要

スキルが頻繁に起動しすぎる#

1. description をより具体的にする
2. 手動でだけ呼びたいなら disable-model-invocation: true を足す

Claude がスキルに従わなくなる#

最初の応答では従うのに、後で従わなくなるときは、当てはまるものから対処します。

• 毎回必ず守らせたい規則を飛ばした：規則をフックに移す。フックは、各ファイル編集の前など、そのイベントが起きるたびに、Claude がスキルに従っているかに関係なく動く。規則をスキルと一緒に持たせるには、スキルの hooks frontmatter にフックを定義する。そのフックは、スキルを呼んだときからセッション終了まで有効（フックのリファレンス参照）
• 判断して適用すべき指針を飛ばした：作業全体に当てはまる文にする。たとえば「Run the tests」でなく「Run the tests after every edit」。スキルは呼ばれたときに内容が会話に追加され、後のターンでファイルを読み直さない
• 会話がコンパクトされた：スキルをもう一度呼んで全文を戻す。コンパクション後は、呼ばれたスキルの先頭部分しか残らないことがあるので、重要な指示は SKILL.md の上のほうに置く

スキルの description が切り詰められる#

Claude Code は、スキルの名前と description の一覧を文脈に読み込みます。名前は常に全部入りますが、スキルが多いと一覧の文字数の予算に収めるため、一部の description が落とされ、Claude が依頼と照合するキーワードが消えます。予算はモデルの文脈ウィンドウの 1% です。あふれたときは、呼んだ回数の少ないスキルから description が落とされるので、よく使うスキルは全文が残ります。

• /doctor で一覧の文脈コストの見積もりと大きい要因が分かる。オフにするスキルを探すには /skill-doctor。予算を超えると、デバッグログに警告が出る（--debug で見える）
• /context の Skills の行は、予算を適用した後の一覧のサイズ（モデルが受け取るとおりの値）。v2.1.196 より前は、全 description の全文を数えていたため、設定した予算の数倍になることがあった
• 予算を増やすには、skillListingBudgetFraction 設定（0.02 なら 2%）か、環境変数 SLASH_COMMAND_TOOL_CHAR_BUDGET に固定の文字数を設定する。他のスキルの枠を空けるには、優先度の低いエントリを skillOverrides で "name-only" にして description なしで載せる
• description と when_to_use を元で削る方法もある。1エントリあたりの合計は、予算に関係なく 1,536 文字で切られるので、主な用途を先頭に書く。この上限は skillListingMaxDescChars で変えられる

個人のスキルが消えた#

~/.claude/skills/ に作ったスキルのフォルダが無くなっていたら、~/.claude/skills/.trash/ を見ます。claude.ai からの同期は、別の synced サブフォルダにダウンロードするので、自分で作ったフォルダを移動・削除しません。

• v2.1.280 より前は、~/.claude/skills/ に manifest.json があると、そこに列挙されたスキルフォルダが .trash/ の下の日時付きフォルダへ移され、読み込まれなくなっていた
• 復元するには、日時付きフォルダからスキルのフォルダを ~/.claude/skills/ へ戻す。保持期間の掃除でゴミ箱の中身が消える前（既定では移動の 30 日後）に行う