Claude をスキルで拡張する

Claude Code でスキルを作成、管理、共有して Claude の機能を拡張します。カスタムコマンドとバンドルされたスキルが含まれます。

スキルは Claude ができることを拡張します。SKILL.md ファイルに指示を記述すると、Claude はそれをツールキットに追加します。Claude は関連する場合にスキルを使用するか、/skill-name で直接呼び出すことができます。

同じ指示、チェックリスト、または複数ステップの手順をチャットに何度も貼り付けている場合、または CLAUDE.md のセクションが事実ではなく手順に成長している場合は、スキルを作成してください。CLAUDE.md のコンテンツとは異なり、スキルの本体は使用される場合にのみ読み込まれるため、長い参考資料は必要になるまでほぼコストがかかりません。

Claude Code スキルは Agent Skills オープンスタンダードに従い、複数の AI ツール全体で機能します。Claude Code は 呼び出し制御、サブエージェント実行、動的コンテキスト注入などの追加機能でスタンダードを拡張します。Claude Code 外でスキルフロントマターを使用するを参照して、どのフロントマターフィールドがスタンダードの一部であり、どれが Claude Code 拡張機能であるかを確認してください。

バンドルされたスキル

Claude Code には、/doctor、/code-review、/batch、/debug、/loop、/claude-api などのバンドルされたスキルが含まれています。バンドルされたスキルはプロンプトベースです。Claude に詳細な指示を与え、ツールを使用して作業を調整させます。ほとんどの組み込みコマンドは、代わりに固定ロジックを直接実行します。

バンドルされたスキルは、他のスキルと同じ方法で呼び出します。/ の後にスキル名を入力します。Claude は関連する場合、一部のバンドルされたスキルを自動的に呼び出します。/verify を含む他のスキルは、呼び出した場合にのみ実行されます。これにより、これらの長時間実行されるチェックが時間とトークンを費やすタイミングを制御できます。

ほとんどのバンドルされたスキルはすべてのセッションで利用可能です。いくつかは特定の機能に依存しています。たとえば、/workflow-authoring は 動的ワークフロー が有効な場合にのみ利用可能です。

バンドルされたスキルをオフにするには、disableBundledSkills 設定を使用します。

バンドルされたスキルは、コマンドリファレンス に組み込みコマンドと一緒にリストされており、目的列に Skill とマークされています。

アプリを実行して検証する

3 つのバンドルされたスキルが連携して、アプリを起動し、テストだけでなく実行中のアプリに対して変更を確認します。

/run と /verify はセットアップなしで動作します。プロジェクトタイプ（CLI、サーバー、TUI、ブラウザ駆動）と README、package.json、または Makefile の内容から起動を推測します。その推測は、標準的な起動を超えて何かが必要なプロジェクト（データベース、env ファイル、グラフィカルセッション、マルチステップビルド）では信頼性が低くなります。

/run-skill-generator は代わりにレシピを記録します。クリーン環境からアプリを実行し、機能したもの（インストールコマンド、環境変数、起動スクリプト）をキャプチャし、.claude/skills/run-<name>/ でプロジェクトごとのスキルとしてコミットします。その後、/run、/verify、およびリポジトリ内の他のエージェントは、記録されたレシピに従い、再度発見することはありません。プロジェクトごとに 1 回 /run-skill-generator を実行し、ビルドまたは起動プロセスが変更された場合は再度実行します。

/verify は独自のレシピを記録することもできます。記録されたレシピなしでアプリをビルドして駆動する必要がある場合、機能したもの（.claude/skills/verify/SKILL.md をリポジトリルートに、またはモノレポの場合は変更されたパッケージディレクトリに）を書き込むため、後の実行と他のエージェントは同じステップに従います。リポジトリルートでは、記録されたスキルはバンドルされた /verify に置き換わります。これには Claude Code v2.1.200 以降が必要です。

Claude は、失敗したコマンドや欠落したステップなど、実行を誤った場合にのみ記録されたファイルを編集するため、セッションごとの差分なしでファイルをコミットできます。v2.1.205 より前では、バンドルされたスキルは Claude に実行から学んだことをすべて折り込むよう指示し、頻繁なマージコンフリクトを引き起こしていました。

はじめに

最初のスキルを作成する

この例では、Git リポジトリ内のコミットされていない変更を要約し、危険な点にフラグを付けるスキルを作成します。ライブ diff をプロンプトに取り込んでから Claude が読むため、Claude が開いているファイルから推測できるものではなく、実際の作業ツリーに基づいた応答が得られます。Claude は、変更について質問するときに自動的にスキルを読み込むか、/summarize-changes で直接呼び出すことができます。

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

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

What did I change?

/summarize-changes

スキルの読み込み場所を選択する

スキルを保存する場所によって、どのセッションがそれを読み込むかが決まります。ホームディレクトリに保存すると、すべてのプロジェクトで読み込まれます。リポジトリにコミットすると、そこで作業するすべてのユーザーと共有できます。プラグインまたはマネージドセッティングを通じて配布すると、チーム全体に到達します。

スキルフォルダは、これらのルールにも従います：

• シンボリックリンク付きフォルダ: enterprise、personal、または project の場所の <skill-name> エントリは、ディスク上の別の場所へのシンボリックリンクにすることができます。Claude Code は、複数の場所が同じターゲットを指している場合でも、ターゲットから SKILL.md を読み込み、スキルを 1 回だけ読み込みます。プラグインスキルは シンボリックリンクを異なる方法で処理します。
• 予約名: スキルフォルダに synced という名前を付けないでください。大文字小文字は問いません。Claude Code は ~/.claude/skills/synced/ を claude.ai からダウンロードされたスキル に使用し、enterprise、personal、および project の場所でこの名前で作成したスキルをスキップします。
• コマンドファイル: .claude/commands/ 内の Markdown ファイルは古い形式ですが、まだ機能します。name と paths を除く同じ frontmatter をサポートしています。それを呼び出すために入力するコマンド名を見つけるには、スキルがコマンド名を取得する方法 を参照してください。新しい作業にはスキルを使用してください。スキルは サポートファイル もサポートしているためです。
• プラグインとしてのスキルフォルダ: .claude-plugin/plugin.json をスキルフォルダに追加すると、<name>@skills-dir という名前の プラグイン として読み込まれます。これにより、エージェント、hooks、および MCP サーバーをバンドルできます。プロジェクトの .claude/skills/ では、最初にワークスペーストラストダイアログを受け入れる必要があります。

monorepos と subdirectories でスキルを読み込む

Claude Code は、開始したディレクトリと、リポジトリルートまでのすべての親ディレクトリの .claude/skills/ からプロジェクトスキルを読み込みます。そのため、packages/frontend/ で開始しても、ルートで定義されたスキルが取得されます。v2.1.246 以降で /cd でセッションを移動する と、Claude Code は新しいディレクトリのプロジェクトスキルを追加します。

リンクされた git worktree で実行されているセッションでは、Claude Code は worktree ルートまでのみ親ディレクトリを検索します。Claude Code v2.1.277 以降では、worktree チェックアウトのルートに .claude/skills ディレクトリがない場合、Claude Code はメインチェックアウトのプロジェクトスキルを代わりに読み込みます。worktrees がメインチェックアウトと共有するもの を参照してください。

開始した場所の下の .claude/skills/ ディレクトリ内のスキルは、起動時には読み込まれません。Claude がそのサブディレクトリ内のファイルを初めて読み込むか編集するときに読み込まれ、セッションの残りの間利用可能なままです。それまでは、/ メニューに表示されず、名前で呼び出すことはできません。より早く読み込むには、サブディレクトリのパスで /add-dir を実行します。これには Claude Code v2.1.257 以降が必要です。

ネストされたスキルが別のスキルと同じ名前を共有する場合、両方が利用可能なままです。リポジトリルートに deploy スキルがあり、apps/web/.claude/skills/ に別のスキルがある場合：

• /deploy はルートスキルを実行します。Claude Code は、Claude 用のディレクトリ修飾バリアントもリストし、作業しているファイルが存在するディレクトリのスキルを呼び出すように指示するため、ネストされたスキルは apps/web/ での作業に適用されます。
• /apps/web:deploy はネストされたスキルを単独で実行します。その説明は、それが適用されるディレクトリに名前を付けます。

プロジェクト外のディレクトリからスキルを読み込む

--add-dir または /add-dir でディレクトリを追加すると、Claude Code はそのディレクトリの .claude/skills/ 内のスキルを、その .claude/commands/ および .claude/agents/ とともに読み込みます。Agent SDK が TypeScript の additionalDirectories または Python の add_dirs を通じて追加するディレクトリは、SDK が --add-dir として渡すため、同じ方法で読み込まれます。settings.json の permissions.additionalDirectories セッティングはファイルアクセスのみを付与し、これらのいずれも読み込みません。

Claude Code は、起動時に --add-dir で渡したディレクトリの .claude/skills/ を監視します。セッション中にスキルを編集する で説明されています。追加されたディレクトリの .claude/commands/ または .claude/agents/ は監視しないため、そこでファイルを変更した後はセッションを再開してください。

これらの読み込みは、デフォルトで有効な project セッティングソース に依存します。strictPluginOnlyCustomization ポリシー、bare mode、および --safe-mode はそれぞれ、これらのページで説明されているようにさらに制限します。追加されたディレクトリが読み込むもの（CLAUDE.md およびプラグインセッティングを含む）の完全なテーブルについては、追加ディレクトリはファイルアクセスを付与し、設定は付与しない を参照してください。

同じ名前のスキルを解決する

2 つのスキルが同じ名前を共有する場合、各スキルがどこから来たかが、/name が実行するスキルを決定します。テーブルは、enterprise、personal、project、nested、plugin、および claude.ai の場所、バンドルされたスキル、およびコマンドファイルをカバーしています：

Cowork およびクラウドセッションでスキルを使用する

Cowork セッションおよび クラウドセッション（routines を含む）は、マシン上の ~/.claude/skills/ を読み込みません。インタラクティブおよびスケジュール済み Cowork セッションの両方は、claude.ai アカウント用に有効化されたスキルを読み込みます。これらはセッション開始時に同期されます。Desktop アプリサイドバーの Customize またはclaude.ai のスキルセッティングから管理します。クラウドセッションは、さらにクローンされたリポジトリの .claude/skills/ にコミットされたプロジェクトスキルを読み込みます。

スキルがマシン上の ~/.claude/skills/ にのみ存在する場合、routine がそれを呼び出すと、Claude Code はスキルが見つからないと報告します。各 routine 実行は新しいクラウドセッションとして開始されるためです。これらのセッションで personal スキルを利用可能にするには：

• Cowork およびクラウドセッションの場合、claude.ai アカウント用にスキルを有効化します。
• クラウドセッションの場合、代わりにスキルをリポジトリの .claude/skills/ にコミットできます。リポジトリの .claude/settings.json で宣言されたプラグインおよびユーザーセッティングでのみ有効化されたプラグインは クラウドセッションで読み込まれません。

Desktop scheduled tasks はマシン上でローカルに実行されるため、~/.claude/skills/ を読み込みます。

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

このセクションは、Cowork またはクラウドセッションを使用する場合、またはターミナルで claude.ai アカウントで Claude Code にサインインする場合に適用されます。これらのセッションでは、Claude Code は claude.ai アカウント用に有効化されたスキルを読み込みます。セットアップは不要です。同期されたスキルが読み込まれる場所 で説明されています。これらのスキルには、claude.ai セッティングで作成または有効化したスキル、組織がそこで提供するスキル、および pdf や xlsx などの Anthropic の組み込みスキルが含まれます。

Claude Code は、セッションが実行されるマシンで作成したファイルを読み込むのではなく、アカウントから同期されたスキルをダウンロードするため、スキルの場所 に保存するスキルには適用されないルールを同期されたスキルに適用します。

同期されたスキルが読み込まれる場所

Cowork またはクラウドセッションでは、Claude Code は claude.ai アカウント用に有効化されたスキルを読み込みます。Cowork およびクラウドセッションでのスキル は、これらのセッションが取得するスキルを選択する方法を説明しています。

ターミナルでは、Claude Code は claude.ai アカウントでサインインするセッションでこれらのスキルを同期します。セッションが開始されると、Claude Code はアカウントのスキルを ~/.claude/skills/synced/ にバックグラウンドでダウンロードし、セッション実行中は約 10 分ごとに claude.ai の変更をチェックします。チェックでスキルが claude.ai で追加、編集、または無効化されたことが判明すると、Claude Code は実行中のセッションでそれを追加、更新、または削除します。再起動は不要です。ターミナルセッションでの同期には Claude Code v2.1.273 以降が必要です。

同期は起動を遅延させません。Claude がスキルを呼び出すときにのみ、スキルのダウンロードを待つためです。短い 非インタラクティブ 実行は、新しく追加されたスキルがダウンロードされる前に終了する可能性があります。その場合、後のセッションがそれをダウンロードします。非インタラクティブ実行がスキルをダウンロードし、プロンプトに答える前にリストを待つようにするには、CLAUDE_CODE_SYNC_SKILLS を 1 に設定します。

Claude Code は、claude.ai アカウントでサインインし、Anthropic からフィーチャーフラグを取得する セッションでのみ同期します。これらのセッションでは同期しません：

• /login で保存されたサインインを使用しないセッション。例えば、API キーで認証するセッション、または ANTHROPIC_AUTH_TOKEN、CLAUDE_CODE_OAUTH_TOKEN、または apiKeyHelper スクリプトが認証情報を提供するセッション
• フィーチャーフラグを取得しないセッション。例えば、Amazon Bedrock 上のセッション、または CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC を設定したセッション
• bare mode のセッション、または --safe-mode で開始したセッション
• 組織のマネージドセッティングが スキルをプラグインソースにロック するセッション、または user を除外する --setting-sources リストで開始したセッション

セッション中に /login でサインインする場合、Claude Code を再起動して同期を開始します。

以前のセッションが同期したスキルはディスク上に残ります。Claude Code は、同じアカウントにサインインした後のセッションでそれらを読み込みます。claude.ai に到達できない場合でも同様です。

Claude Code は同期されたスキルをダウンロードし、アップロードしません。~/.claude/skills/synced/ の下のファイルを編集する場合、変更は claude.ai アカウントに保存されず、後の同期で上書きまたは削除される可能性があります。同期されたスキルを変更するには、claude.ai で更新します。次の同期で新しいバージョンがダウンロードされます。

同期されたスキルを確認するには、/skills を実行します。メニューは claude.ai sync の下にそれらをリストします。

pdf や xlsx などの Anthropic のスキルの一部は常に同期します。その他については、claude.ai のスキルセッティングでスキルをオンまたはオフにして、同期するかどうかを変更します。

マシンでの同期を停止するには、ユーザーセッティングで syncClaudeAiSkills を false に設定します。Claude Code はダウンロードを停止し、次回起動時に既に同期したスキルを ~/.claude/skills/.trash/ に移動し、それ以上読み込みません。組織は claude.ai で Skills をオフにすることで、すべてのユーザーの同期をオフにできます。同期を停止しながら Skills をオンのままにするには、マネージドセッティング で同じキーを設定できます。

組織が claude.ai で Skills をオフにする場合、Claude Code はダウンロードされたスキルを削除し、読み込みを停止します。削除されたスキルは ~/.claude/skills/.trash/ に移動されます。保持期間スイープ がそれらを削除するまで、ファイルを復旧できます。組織が Skills を再度オンにすると、Claude Code は次の同期で有効化したスキルをダウンロードします。

同期されたスキル名が別のコマンドと一致する場合

同期されたスキルは、その完全な名前 /anthropic-skills:<name> または短い名前 /<name> で呼び出すことができます。別のコマンドがその短い名前を使用する場合、/<name> は他のコマンドを実行し、同期されたスキルは /anthropic-skills:<name> としてのみ実行されます。ローカル deploy スキルと同期された deploy がある場合、/deploy はローカルスキルを実行し、/anthropic-skills:deploy は同期されたスキルを実行します。v2.1.269 より前では、同期されたスキルは短い名前のみを持っていました。

他のコマンドは、これらのいずれかにすることができます：

• 組み込みコマンドまたは バンドルされたスキル。例えば、バンドルされたスキルをオフにした後に利用できないもの
• ローカルレベル のスキルまたは .claude/commands/ 内のファイル
• プラグインスキル
• MCP プロンプト

Claude Code は同期されたスキルにラベルを付けるため、どこから来たかを判断できます。/skills メニューと /context は同期されたスキルを claude.ai sync の下にグループ化し、/ コマンドメニューは claude.ai から来たものとしてマークします。

名前を比較するとき、Claude Code は大文字小文字、スペース、および目に見えない文字を無視し、全幅文字とダッシュバリアントなどの互換性形式をそれらのプレーン等価物として扱います。例えば、Commit という名前の同期されたスキルとローカル commit スキルは同じ名前と見なされるため、/commit はローカルスキルを実行し続けます。

別のアルファベットの見た目が似た文字だけで異なる名前は異なる名前と見なされ、claude.ai sync ラベルは 2 つを区別する方法です。これらのチェックとラベルには Claude Code v2.1.228 以降が必要です。

Claude Code が同期されたスキルの frontmatter をどのように処理するか

Claude Code は、同期されたスキルの frontmatter に 2 つのルールを適用します：

• Claude Code は、あらゆる種類のセッションで frontmatter を尊重するため、allowed-tools グラントは通常の 権限フロー を通じて進みます。
• Claude Code は、スキルが提供する表示テキスト（説明など）をサニタイズします。制御文字を削除し、Claude に到達するテキスト（説明など）では、テキストが Claude Code の内部フォーマットを模倣できないように、角括弧をエスケープします。このサニタイズには Claude Code v2.1.228 以降が必要です。

Claude Code が同期されたスキルの本体をどのように処理するか

Claude Code が同期されたスキルの本体で何をするかは、セッションが実行される場所によって異なります：

• クラウドセッションでは、本体はローカルスキルが持つ動作を保持します。セッションは分離されたコンテナで実行されるためです。
• デスクトップ上の Cowork セッションでは、本体はローカルスキルが持つ動作を保持します。ただし、Claude Code はすべての ! コマンドラインを disableSkillShellExecution プレースホルダ に置き換えます。すべてのスキルに対して行うように、そこで提供します。
• マシン上の他のセッションでは、Claude Code は ! コマンド を実行しません。@ 参照が名前を付けるファイルをローカルスキルの場合のように添付しません。${CLAUDE_PROJECT_DIR} および ${CLAUDE_SESSION_ID} プレースホルダを置き換えません。そのため、@ 参照と両方のプレースホルダは Claude にリテラルテキストとして到達します。! コマンドラインも disableSkillShellExecution がオンの場合、リテラルテキストまたはそのプレースホルダとして到達します。この処理には Claude Code v2.1.228 以降が必要です。

セッション中にスキルを編集する

Claude Code は bare mode を除き、スキルディレクトリのファイル変更を監視します。~/.claude/skills/、プロジェクト .claude/skills/、または --add-dir ディレクトリ内の .claude/skills/ の下のスキルを追加、編集、または削除すると、Claude Code は現在のセッション内で変更を取得します。再起動は不要です。セッション開始時に存在しなかったトップレベルスキルディレクトリを作成する場合、Claude Code を再起動して新しいディレクトリを監視できるようにします。

ライブ変更検出は SKILL.md テキストのみをカバーします。スキルフォルダが プラグイン でもある場合、hooks/、.mcp.json、agents/、および output-styles/ への変更は /reload-plugins で有効になります。

スキルを削除する

スキルを削除する方法は、どこから来たかによって異なります：

• Personal または project スキル: スキルのディレクトリ ~/.claude/skills/<skill-name>/ または .claude/skills/<skill-name>/ を削除します。Claude Code は 現在のセッションの /skills からそれを削除します。Claude Code が既に読み込んだコンテンツは スキルコンテンツライフサイクル に従います。
• Enterprise スキル: 管理者が マネージドセッティングディレクトリ 内の .claude/skills/ からスキルのディレクトリを削除します。例えば、Linux では /etc/claude-code/.claude/skills/<skill-name>/。
• Plugin スキル: /plugin メニューから、または /plugin uninstall <plugin-name>@<marketplace-name> でプラグインを無効化またはアンインストールします。Claude Code は 変更が適用される か、再起動するときにプラグインのスキルをアンロードします。
• claude.ai から同期されたスキル: claude.ai のスキルセッティングで、有効化した 同じ場所でスキルをオフにします。Claude Code は スキルを同期する 次回にそれを ~/.claude/skills/synced/ から削除します。代わりに手動でディレクトリを削除する場合、次の同期はスキルが claude.ai で有効なままの間、それを再度ダウンロードします。
• バンドルされたスキル: disableBundledSkills を true に設定してバンドルされたスキルをオフにするか、skillOverrides で 1 つのスキルを "off" に設定して非表示にします。

personal または project スキルを保持しながら Claude がそれを自動的に呼び出すのを停止するには、frontmatter で disable-model-invocation: true を設定するか、ファイルを編集したくない場合は skillOverrides で "user-invocable-only" を設定します。

スキルを設定する

スキルは SKILL.md の上部にある YAML フロントマターと、その後に続くマークダウンコンテンツを通じて設定されます。

スキルコンテンツのタイプ

スキルファイルには任意の指示を含めることができますが、それらをどのように呼び出したいかを考えることで、何を含めるべきかを決めるのに役立ちます。

リファレンスコンテンツ は、Claude が現在の作業に適用する知識を追加します。規約、パターン、スタイルガイド、ドメイン知識などです。このコンテンツはインラインで実行されるため、Claude は会話コンテキストと一緒にそれを使用できます。

---
name: api-conventions
description: API design patterns for this codebase
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

タスクコンテンツ は、デプロイメント、コミット、コード生成など、特定のアクションのステップバイステップの指示を Claude に提供します。これらは、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

本体自体は簡潔に保ちます。スキルが読み込まれると、そのコンテンツは ターン全体でコンテキストに留まる ため、すべての行は繰り返されるトークンコストになります。何をするかを述べ、どのように、なぜするかを説明するのではなく、CLAUDE.md コンテンツ に対して適用するのと同じ簡潔性テストを適用します。

フロントマターリファレンス

SKILL.md の上部にある --- マーカー間の YAML フロントマター でスキルを設定し、閉じる --- の後にマークダウンとしてスキルの指示を記述します。フィールド名は when_to_use を除いてハイフンで区切られた小文字の単語を使用します。.claude/commands/ の コマンドファイル は name と paths を除いて同じフィールドを受け入れます。この例は 4 つのフィールドを設定しています。

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

Your skill instructions here...

すべてのフィールドはオプションです。Claude がスキルをいつ使用するかを知るために、description のみが推奨されます。フィールド名はテーブルと正確に一致する必要があります。ハイフンを含めて、Claude Code は認識しないフィールドをエラーを報告せずに無視します。

Claude Code はフロントマターを読み込むのは、開く --- がファイルの最初の行である場合のみです。そうでない場合、--- マーカーを含むファイル全体をスキルコンテンツとして扱います。マーカー間の YAML が解析されない場合、スキルはフィールドセットなしで読み込まれます。スキルがトリガーされない を参照して、エラーを見つけて修正してください。

ブール値フィールドは、true と false に加えて、任意の大文字小文字で yes、no、on、off、1、0 を受け入れます。v2.1.218 より前では、Claude Code は true と false のみを認識していました。

Claude Code 外でスキルフロントマターを使用する

Claude Code はテーブル上のすべてのフィールドを受け入れます。Claude Code 外では、Agent Skills 仕様のフィールドのみを使用できます。

たとえば、Cowork とクラウドセッション とルーチンで使用するために個人スキルを claude.ai アカウント用に有効にする場合、それを claude.ai にアップロードするため、同じルールが適用されます。

仕様が許可しないフィールドを含める場合、パッケージングまたはアップロードはフィールドを無視する代わりにハードエラーで失敗します。

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

フロントマターを仕様の 6 つのフィールドに制限すると、上記の予期しないキーエラーを回避できます。Agent Skills 仕様 および Skills API 要件 は、これらのパスが検証するその他すべてを定義します。動的コンテキスト注入 などの Claude Code のみの本体機能は、claude.ai チャットまたは API を通じて機能しません。Claude Code はすべての 6 つのフィールドを受け入れるため、仕様に従うフロントマターは変更なしに Claude Code で読み込まれます。

スキルがコマンド名を取得する方法

スキルを呼び出すために入力するコマンドは、スキルファイルが存在する場所から、およびプラグインスキルの場合はフロントマター name フィールドからも来ます。個人またはプロジェクトスキルでは、name はスキルリストに表示される表示ラベルのみを設定し、コマンドはディレクトリ名から来ます。プラグインスキルでは、name はコマンドの最後のセグメントを設定し、プラグインプレフィックスは所定の位置に留まります。

以下のテーブルは、各レイアウトのコマンド名がどこから来るかを示しています。

プラグインスキルでは、フロントマター name はコマンドの最後のセグメント内のディレクトリ名を置き換えるため、my-plugin/skills/review/SKILL.md と name: fancy は /my-plugin:fancy になります。別の /fancy もスキルを呼び出します。別のコマンドがその名前をまだ使用していない場合。書き込む name がプラグイン独自のプレフィックスで既に始まる場合、Claude Code は v2.1.246 以降でプレフィックスを再度追加しません。たとえば、name: my-plugin:fancy は依然として /my-plugin:fancy になります。v2.1.216 から v2.1.245 まで、Claude Code は name がそれを既に実行していた場合、プレフィックスを倍にしました。

非対話型セッション では、名前 help と feedback はターミナルのみの組み込みコマンド用に予約されていないため、これらの名前を持つプラグインスキルはそこで裸のコマンドを保持します。他のすべてのターミナルのみの組み込みの名前（/login など）は、これらのセッションでコマンドを実行できないにもかかわらず、予約されたままです。

プラグインルート SKILL.md の場合、スキルディレクトリがないため、name は最後のセグメント全体を提供します。name フィールドがない場合、Claude Code はプラグインのディレクトリ名にフォールバックします。

利用可能な文字列置換

スキルはスキルコンテンツの動的値の文字列置換をサポートしています。

Claude Code は ${CLAUDE_SKILL_DIR} と ${CLAUDE_PROJECT_DIR} を 2 つの場所で置換します。スキルのマークダウンコンテンツ、および allowed-tools フロントマターの Bash ルール。プラグインスキルでは、Claude Code は ${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.

このスキルが ~/.claude/skills/render-chart/ にインストールされている場合、${CLAUDE_SKILL_DIR} の両方の出現はそのディレクトリに展開されます。allowed-tools ルールはスキル本体が Claude に実行するよう指示する正確なコマンドと一致するため、スクリプトはプロンプトなしで実行されます。

${CLAUDE_PROJECT_DIR} 置換には Claude Code v2.1.196 以降が必要です。

インデックス付き引数はシェルスタイルのクォートを使用するため、複数単語の値をクォートで囲んで単一の引数として渡します。たとえば、/my-skill "hello world" second は $0 を hello world に展開し、$1 を second に展開します。$ARGUMENTS プレースホルダーは常に入力されたとおりの完全な引数文字列に展開されます。

対応する引数がないインデックス付きプレースホルダー（1 つの引数のみが渡された場合の $2 など）はコンテンツで変更されないままです。arguments フロントマターからの対応する引数がない名前付きプレースホルダーは空の文字列に展開されます。

$1 または $ARGUMENTS などのテキストを含む引数値を渡す場合、Claude Code はそれをリテラルテキストとして挿入し、展開しません。たとえば、スキルの本体に Summarize $0 が含まれており、/summarize "$ARGUMENTS from yesterday" を実行する場合、Claude は Summarize $ARGUMENTS from yesterday を受け取ります。Claude Code は、引数を挿入した後、${CLAUDE_SKILL_DIR} などの ${CLAUDE_*} 変数を置換します。

数字、ARGUMENTS、または宣言された引数名の前にリテラル $ を含めるには（例：散文の $1.00）、バックスラッシュでエスケープします。\$1.00。他の $ の前のバックスラッシュは変更されないままです。トークンの直前の単一バックスラッシュのみがそれをエスケープします。\\$1 などの二重バックスラッシュは両方のバックスラッシュを所定の位置に残し、$1 は依然として引数値に展開されます。バックスラッシュエスケープはこれらの引数プレースホルダーのみをカバーします。バックスラッシュは、変数が適用される ${CLAUDE_*} 変数の置換を防ぎません。

置換を使用した例：

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

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

$ARGUMENTS

サポートファイルを追加する

スキルはディレクトリに複数のファイルを含めることができます。これにより、SKILL.md は本質的なものに焦点を当てることができ、Claude は必要に応じてのみ詳細なリファレンス資料にアクセスできます。大規模なリファレンスドキュメント、API 仕様、またはサンプルコレクションは、スキルが実行されるたびにコンテキストに読み込む必要はありません。

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 からサポートファイルを参照して、Claude が各ファイルに何が含まれているか、いつそれを読み込むかを知るようにします。

## Additional resources

- For complete API details, see [reference.md](/anthropic/claude-code/history/docs/ja/2026-09-24-2257..2026-09-25-2358/reference/)
- For usage examples, see [examples.md](/anthropic/claude-code/history/docs/ja/2026-09-24-2257..2026-09-25-2358/examples/)

スキルを呼び出すユーザーを制御する

デフォルトでは、あなたと Claude の両方がスキルを呼び出すことができます。/skill-name を入力して直接呼び出すことができ、Claude は会話に関連する場合に自動的に読み込むことができます。2 つのフロントマターフィールドでこれを制限できます。

• disable-model-invocation: true：あなたのみがスキルを呼び出すことができます。/commit、/deploy、/send-slack-message など、副作用があるワークフロー、またはタイミングを制御したいワークフローに使用します。コードが準備完了に見えるため、Claude がデプロイすることを望みません。

• user-invocable: false：Claude のみがスキルを呼び出すことができます。アクションとして実行できないバックグラウンド知識に使用します。legacy-system-context スキルは古いシステムがどのように機能するかを説明します。Claude はこれが関連する場合に知るべきですが、/legacy-system-context はユーザーが実行する意味のあるアクションではありません。

この例は、あなたのみがトリガーできるデプロイスキルを作成します。disable-model-invocation: true を設定した場合、Claude はスキルを自動的に実行できません。

---
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 は呼び出しをブロックし、デプロイステップを別の方法で再現しないよう指示するため、/deploy を自分で実行することを提案することを期待してください。

2 つのフィールドが呼び出しとコンテキスト読み込みにどのように影響するかは次のとおりです。

スキルコンテンツのライフサイクル

あなたまたは Claude がスキルを呼び出すと、レンダリングされた SKILL.md コンテンツが会話に単一のメッセージとして入力され、後のターン全体で留まります。この永続性はスキルの指示に適用され、その権限には適用されません。allowed-tools 許可はあなたが次のメッセージを送信するときにクリアされます。Claude Code は後のターンでスキルファイルを再度読み込まないため、タスク全体に適用すべき指導を 1 回限りのステップではなく、スタンディング指示として記述します。

Claude が、レンダリングされたコンテンツがコンテキストに既にある複製と同じであるスキルを再呼び出すと、Claude Code はスキルが既に読み込まれていることを示す短いメモを追加します。コンテンツが異なる場合（引数が変更されたか、動的コンテキスト コマンドが新しい出力を生成したため）、Claude Code は完全なコンテンツを再度追加します。

自動コンパクション はトークン予算内で呼び出されたスキルを前方に実行します。会話が要約されてコンテキストを解放するとき、Claude Code は各スキルの最新の呼び出しを要約の後に再度アタッチし、最初の 5,000 トークンを保持します。再度アタッチされたスキルは 25,000 トークンの結合予算を共有します。Claude Code はこの予算を最近呼び出されたスキルから開始して埋めるため、セッション内で多くを呼び出した場合、古いスキルはコンパクション後に完全にドロップできます。

スキルが最初の応答の後に動作に影響を与えるのを停止しているように見える場合、コンテンツは通常まだ存在し、モデルは他のツールまたはアプローチを選択しています。スキルの description と指示を強化して、モデルがそれを優先し続けるようにするか、フック を使用して動作を決定的に強制します。スキルが大きい場合、または他のスキルを呼び出した後、コンパクション後に再呼び出しして完全なコンテンツを復元します。

スキルのツールを事前承認する

allowed-tools フィールドは、スキルを呼び出すターン中にリストされたツールの権限を付与するため、Claude は承認を求めることなくそれらを使用できます。許可はあなたが次のメッセージを送信するときにクリアされます。スキルコンテンツは コンテキストに留まる にもかかわらず。スキルを再呼び出すと、そのターンに対して再度適用されます。これはどのツールが利用可能かを制限しません。すべてのツールは呼び出し可能なままであり、権限設定 はリストされていないツールを引き続き管理します。セッション全体ではなく単一のターンのツールを事前承認するには、代わりにそれらの権限設定に許可ルールを追加します。

ワークスペーストラストはこのフィールドをゲートしません。Claude Code は、信頼したことのないフォルダで -p 実行を含む、あなたまたは Claude がスキルを呼び出すときはいつでも、プロジェクトスキルの allowed-tools を適用します。スキルは自身に広いツールアクセスを付与できるため、Claude Code をそこで実行する前に、リポジトリにチェックインされたスキルの allowed-tools を確認してください。

このスキルでは、スキルを呼び出すときはいつでも、Claude は許可を求めることなく git コマンドを実行できます。

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

スキルがアクティブな間、Claude の利用可能なプールからツールを削除するには、スキルのフロントマターの disallowed-tools にそれらをリストします。制限はあなたが次のメッセージを送信するときにクリアされます。拒否ルールと同様に、フィールドは他のツールが残っている間、EndConversation を削除できません。すべてのスキルとプロンプト全体でツールをブロックするには、権限設定 に拒否ルールを追加します。

スキルに引数を渡す

あなたと Claude の両方がスキルを呼び出すときに引数を渡すことができます。引数は $ARGUMENTS プレースホルダーを通じて利用可能です。

このスキルは GitHub の問題を番号で修正します。$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 を実行すると、Claude は「Fix GitHub issue 123 following our coding standards...」を受け取ります。

スキルに引数を指定して呼び出しても、スキルのコンテンツのプレースホルダーが 1 つも受け取らない場合、Claude Code は ARGUMENTS: <your input> をスキルコンテンツの最後に追加するため、Claude は依然として入力したものを見ます。プレースホルダーは $ARGUMENTS、$1 などのインデックス形式、または名前付き引数です。対応する引数がないインデックス付きプレースホルダーはリテラルテキストのままで、1 つを受け取ったとしてカウントされません。名前付きプレースホルダーは、位置に引数がない場合でも、空の文字列に展開されるため、カウントされます。

1 つのメッセージの開始時に複数のスキルをスタックすることもできます。/write-tests /fix-issue 123 を入力すると、両方のスキルが読み込まれ、末尾のテキスト 123 が $ARGUMENTS として各スキルに渡されます。v2.1.199 より前では、最初のスキルのみが読み込まれ、/fix-issue 123 をリテラル引数テキストとして受け取りました。

Claude Code は最初のスキルと、その後にスタックされた最大 5 つのスキルを展開します。展開は、インラインユーザー呼び出し可能スキルではない最初のトークンで停止するため、フォークされたサブエージェント として実行されるスキル（/code-review など）、またはその引数自体がスラッシュコマンドで始まる可能性があるスキル（/loop など）も、そこで実行を終了します。そのトークンとその後のすべてが、展開されたすべてのスキルの引数テキストになります。v2.1.218 から /code-review はフォークされたサブエージェントとして実行されます。以前のバージョンではインラインで実行され、スタックされました。

位置で個別の引数にアクセスするには、$ARGUMENTS[N] または短い $N を使用します。

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

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

/migrate-component SearchBar JavaScript TypeScript を実行すると、$ARGUMENTS[0] が SearchBar に、$ARGUMENTS[1] が JavaScript に、$ARGUMENTS[2] が TypeScript に置き換えられます。$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.

高度なパターン

動的コンテキストを注入する

!`<command>` 構文は、スキルコンテンツが Claude に送信される前にシェルコマンドを実行します。コマンド出力がプレースホルダーを置き換えるため、Claude はコマンド自体ではなく実際のデータを受け取ります。Claude Code は、スキルが claude.ai アカウントから同期される 場合、マシン上でこれらのコマンドを実行しません。この制限には Claude Code v2.1.228 以降が必要です。

このスキルは GitHub CLI を使用してライブ PR データを取得することで、プルリクエストを要約します。!`gh pr diff` およびその他のコマンドが最初に実行され、その出力がプロンプトに挿入されます。

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

ユーザー、プロジェクト、プラグイン、または additional-directory ソースからのスキルおよびカスタムコマンドについてこの動作を無効にするには、settings で "disableSkillShellExecution": true を設定します。各コマンドは実行される代わりに [shell command execution disabled by policy] に置き換えられます。バンドルされたスキルと管理されたスキルは影響を受けません。この設定は managed settings で最も有用です。ここではユーザーはそれをオーバーライドできません。

Claude Code は、claude.ai アカウントから同期されたスキル に表示されるコマンドをマシン上で実行することはありません。この制限には Claude Code v2.1.228 以降が必要です。Claude Code がどのように同期されたスキルの本体を処理するか は、各種セッションで Claude が受け取るコマンドの代わりになるものを説明しています。

注入されたコマンドがどのように実行されるか

Claude Code は、スキルのフロントマターの shell キーと環境からスキルの注入されたコマンドを実行するツールを選択します。すべての組み合わせはコマンドを Bash ツールまたは PowerShell ツールを通じて実行します。ただし、呼び出しを完全に失敗させる 1 つの組み合わせを除きます。

• shell: powershell、PowerShell ツール が有効な場合：コマンドは PowerShell ツールを通じて実行されます。
• shell: bash で bash が利用できない場合：コマンドが実行される前に呼び出しが失敗します。これは Git Bash のない Windows で発生します。Claude Code は Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found を表示します。
• その他の組み合わせ：bash が利用可能な場合、コマンドは Bash ツールを通じて実行されます。利用できない場合、PowerShell ツールを通じて実行されます。

どちらのツールも、Claude 独自のシェルコマンドを実行するのと同じ方法でコマンドを実行します。これらは作業ディレクトリ、タイムアウト、および出力処理を共有します。

• 作業ディレクトリ：Claude Code は各コマンドをセッションシェルの現在の作業ディレクトリで実行します。Claude が cd を実行するとそのディレクトリが移動します。毎回同じ方法で解決する必要があるパスで ${CLAUDE_SKILL_DIR} または ${CLAUDE_PROJECT_DIR} を使用します。
• stderr：デフォルトの bash シェルでは、Claude Code は stderr を stdout にマージします。コマンドが stderr に書き込むすべてのものが注入されたテキストに表示されます。
• タイムアウト：各コマンドは Bash ツールのデフォルト 2 分 timeout の下で実行されます。Bash ツールが タイムアウトしたコマンドをバックグラウンドに移動 する場合、スキルは引き続きレンダリングされます。注入されたテキストは移動を報告し、バックグラウンドタスクとコマンドの出力を収集するファイルに名前を付けます。コマンドが Bash ツールが自動的にバックグラウンドに移動しないコマンドの場合、Claude Code はタイムアウト時にそれを強制終了します。その失敗は 呼び出しを中止します。
• 出力サイズ：Bash ツールのインライン上限を超える出力は、切り詰められたテキストではなく、ファイルパスと短いプレビューとして到着します。出力制限 は上限とそれぞれの境界を調整する方法をカバーしています。

PowerShell ツールは、実行するコマンドに同じタイムアウト、バックグラウンド処理、および出力上限の動作を適用します。その詳細については、PowerShell ツール セクションを参照してください。

注入されたコマンドが失敗する場合

失敗したコマンドは、スキル全体の呼び出しを中止します。独自のプレースホルダーだけではありません。Claude はその呼び出しのスキルコンテンツを見ることはありません。中止は Shell command failed for pattern "..." を表示します。エラーメッセージには [stderr] の下のコマンドの出力が含まれます。

デフォルトの bash シェルでは、ゼロ以外の終了コードはすべて失敗としてカウントされます。1 つの例外が適用されます。Claude Code は 検索および比較コマンド からの終了コード 1 を通常の結果として扱い、その出力を注入します。終了コード 2 以上はこれらのコマンドでも失敗します。

どのコマンドが例外を取得するかはシェルによって異なります。

• デフォルト bash シェル：出力制限 の下にリストされているコマンド
• shell: powershell、PowerShell ツールが有効な場合：grep と git diff を含むが find や diff は含まない 異なるセット

デフォルトの bash シェルでは、ゼロ以外で終了することが予想される他のコマンドに || true を追加します。問題を見つけたときに 1 で終了するチェックスクリプトは 1 つの例です。

注入されたコマンドの権限チェック

注入されたコマンドは、スキルのレンダリング中に権限を求めるプロンプトを表示することはありません。Claude Code は最初に 権限ルール に対して各コマンドをチェックします。deny ルールが一致するコマンドは Shell command permission check failed for pattern "..." で呼び出しを中止します。

auto mode の外では、コマンドの権限チェックが allow 以外のものを返す場合、Claude Code は同じエラーで呼び出しを中止します。これには通常あなたに尋ねるルールが含まれます。一致しないコマンドが中止されるのを防ぐには、allowed-tools で事前に承認します。Deny および ask ルールは引き続き allowed-tools をオーバーライドします。権限を管理する を参照してください。

auto mode では、そうでなければあなたの承認が必要なコマンドは呼び出しを中止しません。スキルは Claude にコマンドを最初に実行するよう指示して読み込まれ、Claude 独自の呼び出しは auto mode の通常のチェック を通じて進みます。呼び出しは、agent を設定する フォークされたスキル でも、Claude が 注入されたコマンドを実行するシェルツール を持たないセッションでも中止されます。

スキルをサブエージェントで実行する

スキルを分離して実行したい場合は、フロントマターに context: fork を追加します。Claude Code は agent フィールドで設定されたタイプの新しいサブエージェントを開始し、スキルコンテンツをそのプロンプトとして提供します。サブエージェントは会話履歴を見ないため、スキルの指示は独立して機能する必要があります。

フォークされたサブエージェントは バックグラウンド で実行されます。スキルが実行されている間、あなたは作業を続けることができ、その結果は完了時に会話に到着します。フロントマターで background: false を設定して、代わりにスキルを呼び出した順番で結果を待ちます。v2.1.218 より前では、フォークされたスキルは常に完了するまでターンをブロックしていました。

Claude Code は、スキルが background: false を設定しない場合でも、次のような場合に結果を待ちます。

• -p フラグまたは Agent SDK を使用した非対話モード
• CLAUDE_CODE_DISABLE_BACKGROUND_TASKS を 1 に設定した場合。これはすべての他のバックグラウンドタスク機能もオフにします
• 同じスキルの以前の呼び出しがまだ実行中の間にフォークされたスキルを呼び出す場合
• スケジュールされたタスク がスキルをそのプロンプトとして発火する場合

バックグラウンドで実行されるフォークされたスキルは、バックグラウンドサブエージェントに適用される狭いツールセット で編集を適用します。スキルのサブエージェントは通常のエージェントタイプなので、会話をフォークするサブエージェントの例外はそれをカバーしません。スキルのステップがそのセット外のツールに依存する場合、background: false を設定して完全なツールセットを保持します。

バックグラウンドで実行されるフォークされたスキルは、セッションの checkpoints の外で編集を適用するため、/rewind はそれらを元に戻しません。git を使用してそれらを元に戻します。

スキルと サブエージェント は 2 つの方向で連携します。

context: fork では、スキルにタスクを記述し、それを実行するエージェントタイプを選択します。組み込みの Explore および Plan エージェントは CLAUDE.md と git status をスキップ して、コンテキストを小さく保ちます。そのため、agent: Explore を使用するフォークされたスキルは SKILL.md コンテンツとエージェント独自のシステムプロンプトのみを見ます。逆に、参照資料としてスキルを使用するカスタムサブエージェントを定義する場合は、サブエージェント を参照してください。

例：Explore エージェントを使用した研究スキル

このスキルはフォークされた Explore エージェントで研究を実行します。スキルコンテンツはタスクになり、エージェントはコードベース探索に最適化された読み取り専用ツールを提供します。

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

このスキルが実行される場合：

1. 新しい分離されたコンテキストが作成されます
2. サブエージェントはスキルコンテンツをそのプロンプトとして受け取ります（「Research $ARGUMENTS thoroughly」指示）
3. agent フィールドは実行環境（モデル、ツール、および権限）を決定します
4. サブエージェントはその結果を要約し、完了時にメイン会話に返します

agent フィールドは使用するサブエージェント構成を指定します。オプションには組み込みエージェント（Explore、Plan、general-purpose）または .claude/agents/ からのカスタムサブエージェントが含まれます。省略された場合、general-purpose を使用します。

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

デフォルトでは、Claude は disable-model-invocation: true が設定されていないスキルを呼び出すことができます。allowed-tools を定義するスキルは、スキルを呼び出すターン中に、事前承認なしでこれらのツールへのアクセスを Claude に付与します。許可は次のメッセージを送信するときにクリアされます。権限設定 は引き続き、他のすべてのツールの基本的な承認動作を管理します。/init や /security-review を含むいくつかの組み込みコマンドも Skill ツールを通じて利用可能です。/compact などの他の組み込みコマンドはそうではありません。

Claude が呼び出すことができるスキルを制御する 3 つの方法：

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

# Add to deny rules:
Skill

特定のスキルを許可または拒否する には permission rules を使用します。

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

# Deny specific skills
Skill(deploy *)

権限構文：正確な一致の場合は Skill(name)、任意の引数を持つプレフィックス一致の場合は Skill(name *)。

deny ルールがスキルの別名または修飾されていない名前ではなくスキル独自の名前を指定する場合、Claude Code はスキルをブロックします。Skill(review) でバンドルされた /code-review をその /review エイリアスを通じてブロックし、Skill(deploy) で ネストされたスキル を apps/web:deploy として修飾されていない名前を通じてブロックします。v2.1.260 より前では、Claude Code は deny ルールが修飾されていない名前のみを指定する場合、修飾された名前の下にリストされたネストされたスキルをブロックしませんでした。

Claude Code は allow ルールをスキル独自の名前と Claude の呼び出しの名前に対してのみ一致させます。

個別のスキルを非表示にする には、フロントマターに disable-model-invocation: true を追加します。これはスキルを Claude のコンテキストから完全に削除します。

設定からスキルの可視性をオーバーライドする

skillOverrides 設定は、スキル独自のフロントマターの代わりに settings からスキルの可視性を制御します。SKILL.md を編集したくないスキル（共有プロジェクトリポにチェックインされたものなど）に使用します。/skills メニューはあなたのために書き込みます。スキルをハイライトして Space を押して状態をサイクルし、Esc を押して .claude/settings.local.json に保存します。

各キーはスキル名で、各値は 4 つの状態の 1 つです。

/skills メニューは "user-invocable-only" 状態を user-only とラベル付けします。

v2.1.199 以降、"off" はターミナル / メニューに加えて、Remote Control クライアントと Agent SDK 呼び出し元に宣伝されるコマンドリストからもスキルを非表示にします。修飾された名前でスキルを呼び出すと、引き続き実行する代わりに skillOverrides エラーが返されます。

skillOverrides に存在しないスキルは "on" として扱われます。以下の例は 1 つのスキルをその名前に折りたたみ、別のスキルを完全にオフにします。

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

一部のバンドルされたスキルには、/doctor の checkup などのエイリアスがあります。managed settings または --settings フラグで渡すファイルでエイリアスの下に skillOverrides エントリを設定する場合、Claude Code はそれをエイリアスの背後にあるスキルに適用します。エイリアスを通じてスキルをさらに制限することのみが可能で、より可視化することはできません。また、managed settings でスキル独自の名前の下にエントリも設定する場合、そのエントリが優先されます。v2.1.260 より前では、Claude Code はいかなる設定ソースでもエイリアスの下のエントリをスキルに適用しませんでした。

ユーザー、プロジェクト、およびローカル設定では、Claude Code はスキル名に対してのみエントリを一致させます。そこで review のエントリを設定する場合、それは review という名前のスキルに適用され、バンドルされた /code-review にはその /review エイリアスを通じて適用されません。

プラグインスキルは skillOverrides の影響を受けません。/plugin を通じてそれらを管理します。

未使用のスキルを見つける

スキルリスト のすべてのスキルは、Claude がそれを使用するかどうかに関係なく、すべてのターンでコンテキストに追加されます。/skill-doctor を実行して、各スキルのコストと使用頻度を確認し、どのスキルをオフにするかを決定します。対話型セッションでは、レポートは /plugin マネージャーの Stats タブで開きます。非対話モード で -p を使用する場合、Claude Code はテキストとして出力します。

レポートはバンドルされたスキルとエンタープライズスキル以外のセッション内のスキルをカバーします。リストに表示されたスキルのうち、呼び出されたことのないスキルにフラグを付け、どこでそれらをオフにするかを示します。オフにする場所を示すスキルのうち、最も高いコンテキストコストを持つものから始めます。レポートは最近使用していないプラグインもリストします。

/skill-doctor には Claude Code v2.1.252 以降が必要で、feature-flag fetching をスキップするセッションでは利用できません。Remote Control から電話またはブラウザで /skill-doctor を実行する場合、Claude Code は Skill usage reports are not available on this connection. で返信します。セッションが実行されているマシンのターミナルで /skill-doctor を実行します。

スキルを評価して反復する

スキルがトリガーされたことを確認することは、Claude がそれを見つけたことを意味しますが、意図した動作をしたことを意味しません。スキルが機能していることを知るには、Claude がそれを呼び出すべきプロンプトで実際に呼び出すかどうか、および呼び出す場合に出力が期待と一致するかどうかを個別に測定する必要があります。

両方をチェックするには、ベースライン比較を行います。現実的なプロンプトをいくつか収集し、スキルが利用可能な新しいセッションで各プロンプトを実行し、無効化した状態でも実行して、結果を比較します。新しいセッションが重要なのは、スキルの作成時に残されたコンテキストが、書かれた指示のギャップをマスクするためです。

その比較を自動化する 2 つのツールがあります。プラグインで配布されるスキルの場合、claude plugin eval は各プロンプトを分離されたセッションでプラグインの有無で実行し、定義したグレーダーまたはそれが作成したグレーダーでスコアリングし、閾値以下の場合はゼロ以外で終了するため、CI でそれをゲートできます。Claude Code 会話内の単一スキルを反復する場合、以下のスキル作成者プラグインは独自の evals/evals.json 形式で同様のループを実行します。2 つの形式は相互交換可能ではありません。

skill-creator でエバルを実行する

skill-creator プラグイン は Claude Code 内の比較ループを自動化します。公式マーケットプレイスからインストールします。

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

インストールが失敗した場合は、Claude Code が報告するメッセージと一致させます。

• 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 テストを実行して、編集をコミットする前に改善であることを確認できます
• 説明チューニング：トリガーすべきおよびトリガーすべきでないプロンプトを生成し、ヒット率を測定し、スキルが間違ったリクエストで起動する場合は説明編集を提案します
• レビュービューアー：各出力を検査し、次の反復が読み込む定性的フィードバックを記録できる HTML レポートを開きます

エバルファイル形式と完全な反復ワークフローについては、agentskills.io の スキル出力品質の評価 を参照してください。ベンチマークと比較モードの背景については、skill-creator アナウンスメント を参照してください。

スキルを共有する

スキルはオーディエンスに応じて異なるスコープで配布できます。

• プロジェクトスキル: .claude/skills/ をバージョン管理にコミットする
• プラグイン: プラグインに skills/ ディレクトリを作成する
• マネージド: マネージド設定を通じて組織全体にデプロイする

ビジュアル出力を生成する

スキルは任意の言語でスクリプトをバンドルして実行でき、Claude に単一のプロンプトでは不可能な機能を提供します。1 つのパターンはビジュアル出力を生成することです。つまり、ブラウザで開いてデータを探索したり、デバッグしたり、レポートを作成したりするためのインタラクティブな HTML ファイルです。

この例は、コードベースエクスプローラーを作成します。これはインタラクティブなツリービューで、ディレクトリを展開・折りたたんだり、ファイルサイズを一目で確認したり、ファイルタイプを色で識別したりできます。

スキルディレクトリを作成します。

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

これを ~/.claude/skills/codebase-visualizer/SKILL.md に保存します。説明は Claude にこのスキルをいつ有効化するかを伝え、指示は Claude にバンドルされたスクリプトを実行するよう伝えます。スクリプトパスは ${CLAUDE_SKILL_DIR} を使用するため、スキルが個人、プロジェクト、またはプラグインレベルでインストールされているかどうかに関わらず正しく解決されます。

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

## What the visualization shows

- **Collapsible directories**: Click folders to expand/collapse
- **File sizes**: Displayed next to each file
- **Colors**: Different colors for different file types
- **Directory totals**: Shows aggregate size of each folder

これを ~/.claude/skills/codebase-visualizer/scripts/visualize.py に保存します。このスクリプトはディレクトリツリーをスキャンし、以下を含む自己完結型の HTML ファイルを生成します。

• ファイル数、ディレクトリ数、合計サイズ、ファイルタイプ数を表示するサマリーサイドバー
• コードベースをファイルタイプ別（サイズ上位 8 つ）に分類する棒グラフ
• ディレクトリを展開・折りたたんだり、色分けされたファイルタイプインジケーターを表示したりできる折りたたみ可能なツリー

スクリプトは Python 3 を必要としますが、組み込みライブラリのみを使用するため、インストールするパッケージはありません。

#!/usr/bin/env python3
"""Generate an interactive collapsible tree visualization of a codebase."""

import json
import sys
import webbrowser
from html import escape
from pathlib import Path
from collections import Counter

IGNORE = {'.git', 'node_modules', '__pycache__', '.venv', 'venv', 'dist', 'build'}

def scan(path: Path, stats: dict) -> dict:
    result = {"name": path.name, "children": [], "size": 0}
    try:
        for item in sorted(path.iterdir()):
            if item.name in IGNORE or item.name.startswith('.'):
                continue
            if item.is_file():
                size = item.stat().st_size
                ext = item.suffix.lower() or '(no ext)'
                result["children"].append({"name": item.name, "size": size, "ext": ext})
                result["size"] += size
                stats["files"] += 1
                stats["extensions"][ext] += 1
                stats["ext_sizes"][ext] += size
            elif item.is_dir():
                stats["dirs"] += 1
                child = scan(item, stats)
                if child["children"]:
                    result["children"].append(child)
                    result["size"] += child["size"]
    except PermissionError:
        pass
    return result

def generate_html(data: dict, stats: dict, output: Path) -> None:
    ext_sizes = stats["ext_sizes"]
    total_size = sum(ext_sizes.values()) or 1
    sorted_exts = sorted(ext_sizes.items(), key=lambda x: -x[1])[:8]
    colors = {
        '.js': '#f7df1e', '.ts': '#3178c6', '.py': '#3776ab', '.go': '#00add8',
        '.rs': '#dea584', '.rb': '#cc342d', '.css': '#264de4', '.html': '#e34c26',
        '.json': '#6b7280', '.md': '#083fa1', '.yaml': '#cb171e', '.yml': '#cb171e',
        '.mdx': '#083fa1', '.tsx': '#3178c6', '.jsx': '#61dafb', '.sh': '#4eaa25',
    }
    lang_bars = "".join(
        f'<div class="bar-row"><span class="bar-label">{ext}</span>'
        f'<div class="bar" style="width:{(size/total_size)*100}%;background:{colors.get(ext,"#6b7280")}"></div>'
        f'<span class="bar-pct">{(size/total_size)*100:.1f}%</span></div>'
        for ext, size in sorted_exts
    )
    def fmt(b):
        if b < 1024: return f"{b} B"
        if b < 1048576: return f"{b/1024:.1f} KB"
        return f"{b/1048576:.1f} MB"

    html = f'''<!DOCTYPE html>
<html><head>
  <meta charset="utf-8"><title>Codebase Explorer</title>
  <style>
    body {{ font: 14px/1.5 system-ui, sans-serif; margin: 0; background: #1a1a2e; color: #eee; }}
    .container {{ display: flex; height: 100vh; }}
    .sidebar {{ width: 280px; background: #252542; padding: 20px; border-right: 1px solid #3d3d5c; overflow-y: auto; flex-shrink: 0; }}
    .main {{ flex: 1; padding: 20px; overflow-y: auto; }}
    h1 {{ margin: 0 0 10px 0; font-size: 18px; }}
    h2 {{ margin: 20px 0 10px 0; font-size: 14px; color: #888; text-transform: uppercase; }}
    .stat {{ display: flex; justify-content: space-between; padding: 8px 0; border-bottom: 1px solid #3d3d5c; }}
    .stat-value {{ font-weight: bold; }}
    .bar-row {{ display: flex; align-items: center; margin: 6px 0; }}
    .bar-label {{ width: 55px; font-size: 12px; color: #aaa; }}
    .bar {{ height: 18px; border-radius: 3px; }}
    .bar-pct {{ margin-left: 8px; font-size: 12px; color: #666; }}
    .tree {{ list-style: none; padding-left: 20px; }}
    details {{ cursor: pointer; }}
    summary {{ padding: 4px 8px; border-radius: 4px; }}
    summary:hover {{ background: #2d2d44; }}
    .folder {{ color: #ffd700; }}
    .file {{ display: flex; align-items: center; padding: 4px 8px; border-radius: 4px; }}
    .file:hover {{ background: #2d2d44; }}
    .size {{ color: #888; margin-left: auto; font-size: 12px; }}
    .dot {{ width: 8px; height: 8px; border-radius: 50%; margin-right: 8px; }}
  </style>
</head><body>
  <div class="container">
    <div class="sidebar">
      <h1>📊 Summary</h1>
      <div class="stat"><span>Files</span><span class="stat-value">{stats["files"]:,}</span></div>
      <div class="stat"><span>Directories</span><span class="stat-value">{stats["dirs"]:,}</span></div>
      <div class="stat"><span>Total size</span><span class="stat-value">{fmt(data["size"])}</span></div>
      <div class="stat"><span>File types</span><span class="stat-value">{len(stats["extensions"])}</span></div>
      <h2>By file type</h2>
      {lang_bars}
    </div>
    <div class="main">
      <h1>📁 {escape(data["name"])}</h1>
      <ul class="tree" id="root"></ul>
    </div>
  </div>
</body></html>'''
    output.write_text(html)

if __name__ == '__main__':
    target = Path(sys.argv[1] if len(sys.argv) > 1 else '.').resolve()
    stats = {"files": 0, "dirs": 0, "extensions": Counter(), "ext_sizes": Counter()}
    data = scan(target, stats)
    out = Path('codebase-map.html')
    generate_html(data, stats, out)
    print(f'Generated {out.absolute()}')
    webbrowser.open(f'file://{out.absolute()}')

テストするには、任意のプロジェクトで Claude Code を開き、「Visualize this codebase.」と尋ねます。Claude はスクリプトを実行し、生成されたファイルのパス（例：Generated /path/to/codebase-map.html）を出力し、ブラウザで開きます。ブラウザが開かないヘッドレス環境で作業している場合、出力されたパスはスクリプトが成功したことを確認します。

このパターンはあらゆるビジュアル出力に対応します。依存関係グラフ、テストカバレッジレポート、API ドキュメント、またはデータベーススキーマの可視化です。バンドルされたスクリプトが作業を行い、Claude がオーケストレーションを処理します。

トラブルシューティング

スキルがトリガーされない

Claude がスキルを期待通りに使用しない場合：

1. 説明にユーザーが自然に言うキーワードが含まれているか確認してください
2. スキルが「What skills are available?」に表示されていることを確認してください
3. 説明により密接に一致するようにリクエストを言い換えてみてください
4. スキルがユーザー呼び出し可能な場合は、/skill-name で直接呼び出してください

frontmatter YAML が不正な形式の場合、Claude Code はスキル本体を空のメタデータで読み込むため、/skill-name は機能しますが Claude は description と照合できません。--debug で実行してパースエラーを確認してください。

スキルがプラグインに含まれている場合、1 つずつ確認するのではなく、現実的なプロンプト全体でスキルがどのくらいの頻度でトリガーされるかを測定できます。tool_used: Skill グレーダーを使用して eval ケースを作成し、説明を変更するたびに claude plugin eval で実行してください。

frontmatter がパースされない SKILL.md ファイルを見つけるには、スキルディレクトリで claude plugin validate を実行してください。例えば、プロジェクトスキルの場合は claude plugin validate .claude/skills、個人スキルの場合は claude plugin validate ~/.claude/skills です。Claude Code v2.1.233 以降が必要です。

スキルが頻繁にトリガーされる

Claude がスキルを不要な時に使用する場合：

1. 説明をより具体的にしてください
2. 手動呼び出しのみが必要な場合は disable-model-invocation: true を追加してください

スキルの説明が短くカットされている

Claude Code はスキル名と説明のリストをコンテキストに読み込み、Claude が利用可能なものを認識できるようにします。リストには常にすべてのスキル名が含まれていますが、スキルが多い場合、Claude Code はリストの文字予算に合わせて説明を短縮し、Claude が一致させるために必要なキーワードを削除する可能性があります。予算はモデルのコンテキストウィンドウの 1% でスケーリングされます。リストが予算を超える場合、Claude Code は最も呼び出しが少ないスキルから説明を削除するため、最も使用するスキルは完全なテキストを保持します。

/doctor を実行してリストのコンテキストコストとその最大の貢献者の推定値を取得してください。オフにする価値のあるスキルを見つけるには、/skill-doctor を実行してください。リストが予算を超える場合、Claude Code はデバッグログに警告も書き込みます。これは --debug で表示できます。

/context の Skills 行は、予算が適用された後のリストのサイズを報告するため、モデルが受け取るものと一致します。v2.1.196 より前は、この行はすべての説明の完全なテキストをカウントし、設定された予算の数倍大きい値を表示する可能性がありました。

予算を増やすには、skillListingBudgetFraction 設定（例：0.02 = 2%）または SLASH_COMMAND_TOOL_CHAR_BUDGET 環境変数を固定文字数に設定してください。他のスキルの予算を解放するには、skillOverrides で低優先度のエントリを "name-only" に設定して、説明なしでリストされるようにしてください。また、ソースで description と when_to_use テキストをトリミングすることもできます。各エントリの結合テキストは予算に関係なく 1,536 文字でキャップされているため、主要なユースケースを最初に配置してください。キャップは skillListingMaxDescChars で設定可能です。

個人スキルが消えた

~/.claude/skills/ に作成したスキルフォルダが消えている場合は、~/.claude/skills/.trash/ を確認してください。Claude Code が claude.ai からスキルを同期する場合、それらは別の synced サブフォルダにダウンロードされ、作成したフォルダは移動または削除されません。

v2.1.280 より前は、~/.claude/skills/ に manifest.json という名前のファイルがあると、Claude Code はそのファイルがリストしたスキルフォルダを ~/.claude/skills/.trash/ の下のタイムスタンプ付きフォルダに移動し、それらのスキルは読み込まれなくなりました。

スキルを復元するには、タイムスタンプ付きフォルダからそのフォルダを ~/.claude/skills/ に戻してください。これは retention sweep がゴミ箱エントリを削除する前に行ってください。デフォルトではゴミ箱に移動されてから 30 日後に削除されます。

関連リソース

• 設定をデバッグする：スキルが表示されない、またはトリガーされない理由を診断する
• スキル出力品質の評価：agentskills.io の eval ファイル形式と反復ワークフロー
• スキル作成のベストプラクティス：Claude 製品全体に適用される作成ガイダンス
• サブエージェント：特化したエージェントにタスクを委任する
• プラグイン：他の拡張機能でスキルをパッケージ化して配布する
• フック：ツールイベント周辺のワークフローを自動化する
• メモリ：永続的なコンテキストのための CLAUDE.md ファイルを管理する
• コマンド：組み込みコマンドとバンドルされたスキルのリファレンス
• 権限：ツールとスキルアクセスを制御する
• Claude Tag スキル：リポジトリにコミットされたプロジェクトスキルは、そのリポジトリが Claude Tag チャネルで使用される場合にも読み込まれます