Claude をスキルで拡張する

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

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

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

[!NOTE]

/help や /compact などの組み込みコマンド、および /debug や /code-review などのバンドルされたスキルについては、コマンドリファレンスを参照してください。

カスタムコマンドはスキルにマージされました。 .claude/commands/deploy.md のファイルと .claude/skills/deploy/SKILL.md のスキルの両方が /deploy を作成し、同じように機能します。既存の .claude/commands/ ファイルは引き続き機能します。スキルはオプション機能を追加します。サポートファイル用のディレクトリ、スキルを呼び出すユーザーを制御するためのフロントマター、および Claude が関連する場合に自動的にスキルを読み込む機能です。

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 設定を使用します。

[!NOTE]

/doctor セットアップチェックアップは、disableBundledSkills がオンの場合でも入力可能なままです。これを非表示にするには、DISABLE_DOCTOR_COMMAND 環境変数を設定するか、skillOverrides エントリ "doctor": "off" を設定します。

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

/doctor でセットアップを確認する

Claude Code プロンプトで /doctor を実行すると、問題を診断して修正できるセットアップチェックアップが行われます。Claude はまず調査結果を報告し、何かを変更する前に確認を求めます。チェックアップは次の領域を対象とします。

• インストールの健全性: 重複したインストールや残存しているインストール、PATH の問題、解析できない設定ファイル、およびリリースチャネルで新しいバージョンが利用可能かどうか
• 拡張機能: コンテキストコストと比較した未使用のスキル、MCP サーバー、プラグイン、および低速なフック
• CLAUDE.md ファイル: チェックイン済みのものと重複するローカルの CLAUDE.md ファイル、チェックイン済みの Claude がコードベースから導出できる CLAUDE.md の内容、および残りの常時読み込まれるガイダンス。Claude は、このガイダンスをオンデマンドで読み込まれるスキルやネストされた CLAUDE.md ファイルに移行することを提案します
• 権限: auto モードをデフォルトの権限モードにすることと、頻繁に拒否している読み取り専用コマンドを事前承認することの提案
• 使用量: Pro、Max、Team、または Enterprise プランの場合、プランの使用量を減らすために /usage が推奨する変更（過去 7 日間で測定）。Claude は自身で行える変更を提案し、残りはユーザーが実行するコマンドなどのアドバイスとして報告します。使用量のチェックには Claude Code v2.1.305 以降が必要です。また、Remote Control が接続されている間、/doctor はこのチェックを省略します。

セッションを開始せずに読み取り専用のインストール診断を行うには、代わりにターミナルで claude doctor を実行します。

セットアップではなく指示を監査するには、Claude Code プロンプトで /doctor prompt-audit を実行します。Claude はチェックアップを実行する代わりに、CLAUDE.md ファイル、スキル、その他の設定をチェックして、古くなった指示や矛盾する指示がないかを確認します。prompt-audit サブコマンドには Claude Code v2.1.283 以降が必要です。

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

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 は、失敗したコマンドや欠落したステップなど、実行を誤った場合にのみ記録されたファイルを編集するため、セッションごとの差分なしでファイルをコミットできます。

各コミットの前にチェックを実行する

verify または simplify という名前のスキルが存在する状態でセッションが開始されると、Claude Code のコミット指示により、Claude はドキュメントやテストへの変更を除き、各コミットの直前にそのスキルを実行します。これには Claude Code v2.1.286 以降が必要です。セッション開始時に次の条件を満たしている場合、Claude はその指示を受け取ります。

• 場所: スキルがエンタープライズ、個人、プロジェクト、または追加ディレクトリの場所から読み込まれるか、その名前の .claude/commands/ ファイルから読み込まれること。/verify がリポジトリルートに記録するレシピはプロジェクトスキルであるため、対象になります。バンドルされた /verify と /simplify、プラグインスキル、claude.ai アカウントのスキルは対象外です。
• 呼び出し: Claude がスキルを呼び出せること。たとえば disable-model-invocation: true などで Claude による呼び出しを停止した 場合、Claude はこの指示を受け取りません。
• Git の指示: includeGitInstructions をオフにしていないこと。オフにすると、組み込みのコミットおよび PR に関するその他の指示とともに、この指示も削除されます。

Claude API プロジェクトで作業する

バンドルされた /claude-api スキルは、プロジェクトの言語に対して Claude API および Managed Agents リファレンス資料を読み込みます。コードが anthropic または @anthropic-ai/sdk をインポートする場合、Claude はこれを自動的にアクティベートします。

スキルのワークフローの 1 つを開始するには、Claude Code プロンプトでスキル名の後にサブコマンドを入力します。たとえば /claude-api migrate です。表は各サブコマンドが何をするか、およびそれを含む最も古い Claude Code バージョンをリストしています。migrate と managed-agents-onboard は v2.1.221 より前のバージョンです。これは表が追跡する最も古いバージョンです。

はじめに

最初のスキルを作成する

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

1. スキルディレクトリを作成する

個人用スキルフォルダにスキル用のディレクトリを作成します。個人用スキルはすべてのプロジェクト全体で利用できます。

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

2. SKILL.md を作成する

すべてのスキルには SKILL.md ファイルが必要です。このファイルには 2 つの部分があります。Claude がスキルをいつ使用するかを指定する --- マーカー間の YAML frontmatter と、スキルが実行されるときに Claude が従う指示を含む markdown コンテンツです。ディレクトリ名、またはフロントマターの name を設定した場合はそれが、入力するコマンドになり、description は Claude がスキルを自動的に読み込むかどうかを決定するのに役立ちます。

これを ~/.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.

!`git diff HEAD` 行は動的コンテキスト注入を使用します。Claude Code はコマンドを実行し、Claude がスキルコンテンツを見る前にこの行をその出力に置き換えるため、指示は現在の diff がすでにインライン化された状態で到着します。

3. スキルをテストする

Git プロジェクトを開き、任意のファイルに小さな編集を加えて、claude を実行して Claude Code を起動します。スキルは 2 つの方法でテストできます。

説明に一致する内容を質問して Claude に自動的に呼び出させます。

What did I change?

またはスキル名で直接呼び出します。

/summarize-changes

どちらの方法でも、Claude は編集内容の短い要約とリスクのリストで応答する必要があります。

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

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

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

• シンボリックリンク付きフォルダ: enterprise、personal、または project の場所の <skill-name> エントリは、ディスク上の別の場所へのシンボリックリンクにすることができます。Claude Code は、複数の場所が同じターゲットを指している場合でも、ターゲットから SKILL.md を読み込み、スキルを 1 回だけ読み込みます。プラグインスキルは シンボリックリンクを異なる方法で処理します。
• 予約名 synced: スキルフォルダに synced という名前を付けないでください。大文字小文字は問いません。Claude Code は ~/.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 という名前の プラグイン として読み込まれます。これにより、エージェント、hooks、および MCP サーバーをバンドルできます。プロジェクトの .claude/skills/ では、最初にワークスペーストラストダイアログを受け入れる必要があります。

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

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

--worktree または git worktree add で作成したリンクされた 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 以降が必要です。デスクトップアプリから開始する worktree セッションについては、worktrees がメインチェックアウトと共有するもの を参照してください。

ネストされたスキルが別のスキルと同じ名前を共有する場合、両方が利用可能なままです。リポジトリルートに 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 がどちらを実行するかが決まります。フロントマターの name フィールドで設定された名前については、スキルがコマンド名を取得する方法 を参照してください。次の表は、enterprise、personal、project、nested、plugin、および claude.ai の場所、バンドルスキル、組み込みコマンド、およびコマンドファイルを対象としています：

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

Cowork セッションおよび クラウドセッション（クラウドのスケジュールタスク を含む）は、マシン上の ~/.claude/skills/ を読み込みません。対話型の Cowork セッションとスケジュール実行される Cowork セッションはどちらも、claude.ai アカウント用に有効化されたスキルを読み込みます。これらはセッション開始時に同期されます。Desktop アプリサイドバーの Customize または claude.ai のスキル設定から管理します。

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

• Cowork セッション、クラウドセッション、および プロジェクト 内のクラウドスレッドの場合、claude.ai アカウント用にスキルを有効化します。プロジェクトのクラウドスレッドでは、リポジトリの .claude/skills/ にコミットされたスキルは利用できません。セルフホスト環境の一部のセッション は、アカウントのスキルを読み込みません。
• プロジェクトスレッド以外のクラウドセッションの場合、代わりにスキルをリポジトリの .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/ にバックグラウンドでダウンロードし、その後セッション実行中に claude.ai の変更をチェックします。チェックでスキルが claude.ai で追加、編集、またはオフにされたことが判明すると、Claude Code は実行中のセッションで再起動なしにそれを追加、更新、または削除します。ターミナルセッションでの同期には Claude Code v2.1.273 以降が必要です。

セッションがアイドル状態の間は、チェックの頻度が下がります：

• ユーザーまたは Claude がセッションで作業している間: 約 10 分ごとにチェックが実行されます。
• セッションがアイドル状態の間: 約 40 分ごとにチェックが実行されます。セッションで再び入力すると、最後のチェックから 10 分以上経過している場合、Claude Code は数分以内にチェックします。

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

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 は次の同期で有効化したスキルをダウンロードします。

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

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

/ メニュー、/skills、および /context では、同期されたスキルは短い名前の下に表示されるか、別のコマンドがその短い名前を使用している間は完全な名前の下に表示されます。セッションで /skills を実行します。リストの下の注記は、短い名前を失った各同期されたスキルを説明します。~/.claude/ の personal スキルまたはコマンドファイルの 1 つがその名前を使用する場合、注記は名前を変更または削除して解放する内容も説明します。

v2.1.269 から v2.1.280 では、これらのリストはすべての同期されたスキルをその完全な名前の下に表示し、/skills にはそのような注記がありませんでした。両方とも v2.1.281 で変更されました。

短い名前を使用するコマンドは、これらのいずれかにすることができます：

• 組み込みコマンドまたは バンドルされたスキル。例えば、バンドルされたスキルをオフにした後に利用できないもの
• ローカルレベル のスキルまたは .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 は名前 anthropic-skills と、anthropic-skills:pdf などのその名前空間内のすべての名前を、claude.ai から同期されたスキル用に予約しているため、同期されたスキルの完全な名前は他のものを実行しません。この名前は、claude.ai アカウントでサインインするかどうかに関わらず、すべてのセッションで予約されています。

• スキルフォルダ、frontmatter name、.claude/commands/ 内のファイルまたはサブフォルダ、または 保存されたワークフロー: 読み込まれません。スタートアップ通知 は、名前を変更または編集する最初のアイテムに名前を付けます。
• anthropic-skills という名前のプラグイン: 読み込まれます。そのスキルの 1 つと同期されたスキルの両方が <name> という名前の場合、/anthropic-skills:<name> は同期されたスキルを実行します。
• anthropic-skills という名前の MCP サーバー: 接続され、そのツールは機能しますが、そのプロンプトはコマンドとして表示されません。MCP 設定でサーバーの名前を変更してそれらをリストします。

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

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

• フロントマターはあらゆる種類のセッションで適用されるため、allowed-tools による許可は通常の 権限フロー を経由します。組織が allowManagedPermissionRulesOnly を設定している場合、この許可は 適用されません。
• 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 は現在のセッション内で変更を取得します。再起動は不要です。

セッション開始時に存在しなかったトップレベルスキルディレクトリを作成する場合、/reload-skills を実行して、そこに配置したスキルを取得します。Claude Code はまだそのディレクトリを監視していないため、そこで後の変更を行った後、/reload-skills を再度実行します。

ライブ変更検出は 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 フロントマターと、それに続く markdown コンテンツによって設定します。

スキルコンテンツの種類

スキルファイルにはどのような指示でも記述できますが、スキルをどのように呼び出したいかを考えると、何を含めるべきかの指針になります。

参照コンテンツは、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 で直接呼び出したいアクションです。Claude が自動的にトリガーしないようにするには、disable-model-invocation: true を追加します。以下の例では 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 フロントマターで設定し、スキルの指示は閉じの --- の後に Markdown で記述します。フィールド名は、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 がコマンドの最後のセグメントにあるディレクトリ名を置き換えるため、name: fancy を持つ my-plugin/skills/review/SKILL.md は /my-plugin:fancy になります。別のコマンドがすでにその名前を使用していない限り、プレフィックスなしの /fancy でもスキルを呼び出せます。記述した name がすでにプラグイン自身のプレフィックスで始まっている場合、v2.1.246 以降の Claude Code はプレフィックスを再度追加しません。たとえば、name: my-plugin:fancy は /my-plugin:fancy のままになります。v2.1.216 から v2.1.245 までは、name がすでにプレフィックスを含んでいる場合、Claude Code はプレフィックスを二重に付けていました。

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

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

スキル名に使用できない文字

スキルやカスタムコマンドが / メニューに表示されない場合、またはメニューにスキルのフロントマターの name が表示されない場合は、名前を確認してください。Claude Code は、次のような文字を含むコマンド名やフロントマターの name を拒否します。

• ゼロ幅スペースまたは制御文字
• アイコンフォントのグリフなど、私用領域の文字または未割り当ての文字
• 周囲のテキストの方向を変更する文字
• 単語間の半角スペース 1 つ以外の空白（ノーブレークスペース、連続する 2 つのスペース、先頭または末尾のスペースなど）
• < または >

Claude Code がディレクトリ名またはファイル名を拒否した場合、そのカスタムコマンドやスキルは読み込まれません。これらの文字を取り除くように、そのフォルダーまたはファイルの名前を変更してください。これらの文字がプラグインスキルのフォルダー名またはそのフロントマターの name にのみ含まれている場合、スキルは引き続き読み込まれます。

• プラグインの skills/ ディレクトリまたはマニフェストの skills パス内のフォルダー：フォルダー名を変更する必要はありません。これらの文字はスキルのコマンド名でハイフンになるため、ハイフンを使ってコマンドを入力してください。
• フロントマターの name：/ メニューには name の値が表示されず、それを入力してもスキルは呼び出されません。name: の行を編集して文字を取り除いてください。

Claude Code がどの名前を拒否したかを確認するには、シェルから claude --debug で起動し、デバッグログで [names] を検索します。対話型セッションでは、起動時の通知でも名前が拒否されたことが通知されます。名前の変更や name: の編集を行った後は、ファイルが Claude Code が変更を監視しているディレクトリにある場合を除き、セッションを再起動してください。

利用可能な文字列置換

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

Claude Code は、${CLAUDE_SKILL_DIR} と ${CLAUDE_PROJECT_DIR} を 2 つの場所で置換します。スキルの markdown コンテンツと、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 に実行するよう指示する正確なコマンドに一致するため、スクリプトはプロンプトなしで実行されます。

インデックス付きの引数はシェル形式のクォートを使用するため、複数の単語からなる値を 1 つの引数として渡すには引用符で囲みます。たとえば、/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)

Claude が各ファイルの内容と読み込むタイミングを把握できるよう、SKILL.md からサポートファイルを参照してください。

## Additional resources

- For complete API details, see [reference.md](/anthropic/claude-code/history/docs/ja/2026-10-20-2300..2026-10-21-2302/reference/)
- For usage examples, see [examples.md](/anthropic/claude-code/history/docs/ja/2026-10-20-2300..2026-10-21-2302/examples/)

[!TIP]

SKILL.md は 500 行未満に保ってください。詳細な参照資料は別のファイルに移動してください。

スキルを呼び出せる対象を制御する

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

• disable-model-invocation: true：Claude は自らスキルを呼び出せません。/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 はその呼び出しをブロックし、デプロイの手順を別の方法で再現しないよう指示します。そのため、Claude はユーザー自身で /deploy を実行するよう提案することになります。

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

[!NOTE]

通常のセッションでは、Claude が利用可能なものを把握できるようスキルの説明がコンテキストに読み込まれますが、スキルの完全なコンテンツは呼び出されたときにのみ読み込まれます。スキルがプリロードされたサブエージェントは動作が異なり、起動時にスキルの完全なコンテンツが挿入されます。

スキル名を書く位置

スキルを直接実行するには、メッセージの先頭にその名前を置きます。プレーンテキストの後に置いた場合、名前は Claude にスキルを実行する権限を与えますが、スキルを実行はしません。

実行を許可せずにスキルについて書くには、スラッシュを付けないでください。

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

ユーザーまたは Claude がスキルを呼び出すと、レンダリングされた SKILL.md のコンテンツが単一のメッセージとして会話に入り、以降のターンにわたってそこに残ります。この永続性はスキルの指示に適用されるもので、権限には適用されません。allowed-tools による付与は、次のメッセージを送信するとクリアされます。Claude Code は以降のターンでスキルファイルを再読み込みしないため、タスク全体を通じて適用されるべきガイダンスは、1 回限りの手順ではなく、常設の指示として記述してください。

Claude がスキルを再度呼び出し、レンダリングされたコンテンツがすでにコンテキストにあるコピーと同一である場合、Claude Code はコンテンツの 2 つ目のコピーではなく、スキルがすでに読み込まれていることを示す短い注記を追加します。引数が変わった、または動的コンテキストのコマンドが新しい出力を生成したためにレンダリングされたコンテンツが異なる場合、Claude Code は完全なコンテンツを再度追加します。

自動圧縮は、呼び出されたスキルをトークン予算の範囲内で引き継ぎます。コンテキストを解放するために会話が要約されると、Claude Code は各スキルの最新の呼び出しを要約の後に再添付し、それぞれ最初の 5,000 トークンを保持します。再添付されるスキルは、合計 25,000 トークンの予算を共有します。Claude Code はこの予算を最も新しく呼び出されたスキルから順に埋めていくため、1 つのセッションで多くのスキルを呼び出した場合、古いスキルはコンテキスト圧縮後に完全に削除されることがあります。

セッションの途中で Claude がスキルに従わなくなった場合は、Claude がスキルに従わなくなるを参照してください。

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

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

このフィールドは、ワークスペースの信頼によって制限されません。Claude Code は、一度も信頼したことのないフォルダーでの -p 実行であっても、プロジェクトスキルの 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 を除外することはできません。すべてのスキルとプロンプトにわたってツールをブロックするには、権限設定に拒否ルールを追加してください。

管理された権限ルールのみが適用される場合

組織が管理設定で allowManagedPermissionRulesOnly を設定している場合、Claude Code はプロジェクトおよび個人のスキル、ならびにこの設定の項目に記載されているその他のソースにある allowed-tools を無視します。これには Claude Code v2.1.282 以降が必要です。

影響を受けるスキルがリストしているツールは、代わりに組織の管理ルールと通常の権限プロンプトを経由します。/status を実行すると、セッション内でこれまでに Claude Code が allowed-tools を無視した各スキルが一覧表示されます。スキル内の挿入されたコマンドのうち、どの管理ルールでも許可されていないものは、挿入されたコマンドの権限チェックに従います。

スキルに引数を渡す

ユーザーと Claude のどちらも、スキルを呼び出す際に引数を渡せます。引数は $ARGUMENTS プレースホルダーで利用できます。

このスキルは、番号を指定して GitHub の issue を修正します。$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...」を受け取ります。

引数を指定してスキルを呼び出したものの、スキルのコンテンツ内のどのプレースホルダーも引数を受け取らない場合、Claude Code はスキルコンテンツの末尾に ARGUMENTS: <your input> を追加し、Claude が入力内容を確認できるようにします。プレースホルダーとは、$ARGUMENTS、$1 のようなインデックス形式、または名前付き引数のことです。その位置に引数がないインデックス付きプレースホルダーはリテラルテキストのまま残り、引数を受け取ったとはみなされません。名前付きプレースホルダーは空文字列に展開されるため、その位置に引数がない場合でも受け取ったとみなされます。

個々の引数に位置でアクセスするには、$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.

1 つのメッセージで複数のスキルを重ねる

ターミナルの Claude Code プロンプトで入力する場合、1 つのメッセージの先頭に複数のスキルを重ねて指定できます。Agent SDK または claude -p 経由では、Claude Code は最初のスキルのみを読み込み、行の残りをその引数とします。ターミナルのプロンプトで /write-tests /fix-issue 123 と入力すると、両方のスキルが読み込まれ、末尾のテキスト 123 がそれぞれに $ARGUMENTS として渡されます。

Claude Code は、最初のスキルと、その後に重ねられた最大 5 つのスキルを展開します。展開は、インラインのユーザー呼び出し可能なスキルではない最初のトークンで停止します。/code-review のようにフォークされたサブエージェントとして実行されるスキルや、/loop のように引数が別のコマンドで始まる可能性があるスキルを重ねた場合、展開はそこで終了します。そのトークンとそれ以降のすべてが、展開されたすべてのスキルの引数テキストになります。

高度なパターン

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

!`<command>` 構文は、スキルの内容が Claude に送信される前にシェルコマンドを実行します。コマンドの出力がプレースホルダーを置き換えるため、Claude はコマンドそのものではなく実際のデータを受け取ります。スキルが claude.ai アカウントから同期されている場合、Claude Code はこれらのコマンドをユーザーのマシン上で実行しません。この制限には 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
```

ユーザー、プロジェクト、プラグイン、または追加ディレクトリをソースとするスキルとカスタムコマンドでこの動作を無効にするには、設定で "disableSkillShellExecution": true を設定します。各コマンドは実行される代わりに [shell command execution disabled by policy] に置き換えられます。バンドルスキルと管理スキルは影響を受けません。この設定は、ユーザーが上書きできない管理設定で使用すると特に効果的です。

この設定に関係なく、claude.ai アカウントから同期されたスキルにこれらのコマンドが含まれている場合、Claude Code がユーザーのマシン上でそれらを実行することはありません。この制限には Claude Code v2.1.228 以降が必要です。各種セッションで Claude がコマンドの代わりに何を受け取るかについては、同期されたスキルの本文を Claude Code がどのように扱うかを参照してください。

[!TIP]

スキルの実行時により深い推論を求めるには、スキルの内容のどこかに ultrathink を含めます。一回限りの深い推論に ultrathink を使用するを参照してください。

注入されたコマンドの実行方法

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 分のタイムアウトの下で実行されます。Bash ツールがタイムアウトしたコマンドをバックグラウンドに移動した場合でも、スキルはレンダリングされます。注入されるテキストにはその移動が報告され、バックグラウンドタスクとコマンドの出力を収集しているファイルの名前が示されます。Bash ツールが自動的にバックグラウンドに移動することのないコマンドの場合、Claude Code はタイムアウト時にそのコマンドを終了させます。この失敗は呼び出しを中止します。
• 出力サイズ: Bash ツールのインライン上限を超える出力は、切り詰められたテキストではなく、ファイルパスと短いプレビューとして届きます。上限と各境界の調整方法については出力の制限を参照してください。

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

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

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

デフォルトの bash シェルでは、0 以外の終了コードはすべて失敗とみなされます。ただし例外が 1 つあります。Claude Code は検索コマンドと比較コマンドからの終了コード 1 を通常の結果として扱い、その出力を注入します。これらのコマンドでも、終了コードが 2 以上の場合は失敗となります。

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

• デフォルトの bash シェル: 出力の制限に記載されているコマンド
• shell: powershell で PowerShell ツールが有効な場合: grep と git diff を含み、find と diff を含まない別のセット

デフォルトの bash シェルでは、0 以外で終了することが想定されるその他のコマンドには || true を追加してください。問題を検出したときに 1 で終了するチェックスクリプトがその一例です。

注入されたコマンド内の制御文字

No shell command in <name> was run は、ファイル内の ! コマンドのいずれかにタブや改行以外の生の制御文字が含まれているため、どのコマンドも実行されないことを意味します。その文字を見つけて削除する方法を参照してください。

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

注入されたコマンドは、スキルのレンダリング中に権限を求めることはありません。Claude Code はまず各コマンドを権限ルールと照合します。拒否ルールに一致するコマンドは、Shell command permission check failed for pattern "..." で呼び出しを中止します。

auto モード以外では、コマンドの権限チェックが許可以外の結果を返した場合、Claude Code は同じエラーで呼び出しを中止します。これには、通常であればユーザーに確認を求めるルールも含まれます。一致しないコマンドがここで中止されないようにするには、allowed-tools で事前に承認してください。組織が権限ルールを管理設定に限定している場合は、管理された権限ルールのみが適用される場合を参照してください。拒否ルールと確認ルールは引き続き allowed-tools より優先されます。権限を管理するを参照してください。

auto モードでは、本来ユーザーの承認が必要なコマンドでも呼び出しは中止されません。スキルは、最初にそのコマンドを実行するよう Claude に指示する内容とともに読み込まれ、Claude 自身による呼び出しは auto モードの通常のチェックを経由します。ただし、agent を設定するフォークされたスキルや、Claude が注入されたコマンドを実行するシェルツールを持たないセッションでは、引き続き呼び出しが中止されます。

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

スキルを分離された環境で実行したい場合は、フロントマターに context: fork を追加します。Claude Code は agent フィールドで設定されたタイプの新しいサブエージェントを起動し、スキルの内容をそのプロンプトとして渡します。サブエージェントはユーザーの会話履歴を参照しないため、スキルの指示はそれ単体で完結している必要があります。

[!NOTE]

名前に反して、context: fork を持つスキルは現在の会話のフォークでは実行されません。会話のフォークでは、これまでに話し合った内容がすべてサブエージェントに引き渡されます。タスクがその履歴に依存する場合は、context: fork を使用する代わりに会話をフォークしてください。

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

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

• 非対話モードで、-p フラグまたは Agent SDK を使用している場合
• CLAUDE_CODE_DISABLE_BACKGROUND_TASKS を 1 に設定した場合（これにより、他のすべてのバックグラウンドタスク機能もオフになります）
• 同じスキルの以前の呼び出しがまだ実行中のときに、フォークされたスキルを呼び出した場合
• スキルをプロンプトとするセッションスコープのスケジュールタスクが実行された場合

動的ワークフロー内のエージェントがフォークされたスキルを呼び出した場合、スキルで background: false を設定していなくても、そのエージェントは結果を待って受け取ります。v2.1.295 より前は、スキルがバックグラウンドで実行された場合、そのエージェントはスキルを待機しませんでした。その場合、スキルの結果はエージェントに届かず、メインの会話に届いていました。

バックグラウンドで実行されるフォークは、バックグラウンドのサブエージェントに適用される、より限定されたツールセットでも実行されます。スキルのサブエージェントは通常のエージェントタイプであるため、会話をフォークするサブエージェント向けの例外は適用されません。スキルの手順がそのセット外のツールに依存する場合は、background: false を設定して完全なツールセットを維持してください。

バックグラウンドで実行されるフォークされたスキルは、セッションのチェックポイントの外で編集を適用します。その後、/rewind で復元されるのは、Claude が会話内ですでに編集していたファイルのみです。スキルによるその他のファイルへの編集は残るため、git を使用して元に戻してください。

[!WARNING]

context: fork は、明示的な指示を持つスキルでのみ意味があります。スキルにタスクがなく「これらの API 規約を使用する」のようなガイドラインしか含まれていない場合、サブエージェントはガイドラインを受け取るものの実行可能なプロンプトがないため、意味のある出力を返さずに終了します。

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

context: fork では、スキルにタスクを記述し、それを実行するエージェントタイプを選択します。組み込みの Explore エージェントと Plan エージェントは、コンテキストを小さく保つために CLAUDE.md と git status なしで起動します。タスクに必要なものはすべて SKILL.md に記述してください。agent: Explore を使用するフォークされたスキルは、その内容とエージェント自身のシステムプロンプトで起動し、CLAUDE.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 ツールを拒否します。

# 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 より前は、拒否ルールで修飾されていない名前のみを指定した場合、修飾名で一覧表示されるネストされたスキルを Claude Code はブロックしませんでした。

Claude Code は、allow ルールをスキル自身の名前と Claude の呼び出しにおける名前とのみ照合します。同期されたスキルをプロンプトなしで承認するには、その予約済み名前空間内で名前を指定します。

• Skill(anthropic-skills:pdf) は同期された pdf スキルを承認します
• Skill(anthropic-skills *) はすべての同期されたスキルを承認します
• Skill(anthropic *) は anthropic-skills:pdf を対象としません。名前空間外のプレフィックスは、その内部の名前に一致しないためです

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

[!NOTE]

user-invocable: false を設定すると、ユーザーはスキルを呼び出せなくなりますが、Claude は引き続き呼び出せます。Claude が Skill ツールを通じて呼び出せないようにするには、disable-model-invocation: true を設定してください。

設定からスキルの表示を上書きする

skillOverrides 設定は、スキル自身のフロントマターではなく設定からスキルの表示を制御します。共有プロジェクトリポジトリにチェックインされているものなど、SKILL.md を編集したくないスキルに使用してください。/skills メニューがこの設定を書き込んでくれます。スキルをハイライトして Space を押すと状態が切り替わり、Esc を押すと .claude/settings.local.json に保存されます。

各キーはスキル名で、各値は次の 4 つの状態のいずれかです。

/skills メニューでは、"user-invocable-only" 状態は user-only と表示されます。

"off" は、ターミナルの / メニューに加えて、Remote Control クライアントや Agent SDK の呼び出し元に公開されるコマンド一覧からもスキルを非表示にします。非表示のスキルをフルネームで呼び出すと、実行されずに skillOverrides のエラーが返されます。

skillOverrides に含まれていないスキルは "on" として扱われます。次の例では、一方のスキルを名前のみに縮小し、もう一方を完全にオフにしています。

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

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

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

プラグインのスキルは skillOverrides の影響を受けません。それらは代わりに /plugin で管理してください。

使用されていないスキルを見つける

スキル一覧に含まれるすべてのスキルは、Claude が実際に使用するかどうかにかかわらず、毎ターンのコンテキストを増やします。/skill-doctor を実行すると、各スキルのコストと使用頻度を確認でき、どのスキルをオフにするかを判断できます。対話セッションでは、レポートは /plugin マネージャーの Stats タブで開きます。-p を使用した非対話モードでは、Claude Code はレポートをテキストとして出力します。

レポートは、バンドルスキルとエンタープライズスキル以外の、セッション内のスキルを対象とします。一覧に含まれていながら一度も呼び出されていないスキルを指摘し、それらをオフにする場所を示します。オフにする場所が示されたスキルのうち、コンテキストコストが最も高いものから始めてください。レポートには、最近使用していないプラグインも一覧表示されます。

/skill-doctor には Claude Code v2.1.252 以降が必要で、フィーチャーフラグの取得をスキップするセッションでは利用できません。スマートフォンやブラウザから Remote Control 経由で /skill-doctor を実行した場合、Claude Code は代わりに Skill usage reports are not available on this connection. と応答します。セッションが実行されているマシンのターミナルで /skill-doctor を実行してください。

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

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

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

2 番目の実行でスキルをオフにする方法は、スキルの出所によって異なります。

• 個人用またはプロジェクトスキル：skillOverrides で "off" に設定します。
• プラグインが提供するスキル：skillOverrides はプラグインスキルには適用されません。代わりに claude plugin eval を使用します。これはプラグインが読み込まれていない状態で各実行を繰り返します。

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

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

skill-creator プラグイン は Claude Code 内の比較ループを自動化します。VS Code 拡張機能またはデスクトップアプリでは、プラグインをインストールする の手順に従って公式マーケットプレイスからインストールします。ターミナルでは、claude を実行して Claude Code を起動し、そのプロンプトで次のように入力します。

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

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

• Marketplace "claude-plugins-official" not found：/plugin marketplace add anthropics/claude-plugins-official でマーケットプレイスを追加してから、インストールを再試行します。
• Plugin "<name>" not found in marketplace "claude-plugins-official"：マーケットプレイスカタログのローカルコピーが古くなっている可能性があります。/plugin marketplace update claude-plugins-official で更新してから、インストールを再試行します。再試行しても同じメッセージが表示される場合は、プラグインがマーケットプレイスで見つからない を参照してください。

インストール概要が Run /reload-plugins to apply. を報告する場合、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 で直接呼び出してください
5. /skill-name も認識されない場合は、Claude Code がスキルの名前を拒否したかどうかを確認してください
6. スキルが paths を設定している場合は、Claude が読み取り、編集、または書き込むファイルが Claude の現在の作業ディレクトリ内にあることを確認してください。スキルはその外にあるファイル（兄弟関係にある git worktree 内のファイルなど。/add-dir で追加したものであっても同様です）に対してはアクティブになりません。それらのファイルでスキルをアクティブにするには、その worktree で Claude Code を起動するか、/cd でセッションをそこに移動してください。

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 がスキルに従わなくなる

Claude が最初の応答でスキルに従い、その後に従わなくなった場合は、以下のいずれかのケースに該当するもので始めてください：

• Claude が毎回成立する必要があるルールをスキップした：ルールを hook に移動してください。Claude Code は hook をそのイベントが発生するたびに実行します。例えば、ファイル編集の前など、Claude がスキルに従っているかどうかに関わらず実行されます。ルールをスキルと一緒に保つには、スキルの hooks frontmatter で hook を定義してください。その hook はスキルが呼び出された時点からセッション終了まで適用されます。
• Claude が判断を伴って適用すべきガイダンスをスキップした：ガイダンスが全体的なタスクに適用されるように言い換えてください。例えば「すべての編集後にテストを実行する」ではなく「テストを実行する」ではなく、「すべての編集後にテストを実行する」と言ってください。Claude Code はスキルが呼び出された時点で会話にスキルのコンテンツを追加し、後の段階ではファイルを再読み込みしません。
• 会話がコンパクト化された：スキルを再度呼び出してコンテンツを復元してください。コンパクト化後、Claude Code は 呼び出されたスキルの開始部分のみを保持できます。そのため、最も重要な指示を SKILL.md の上部に配置してください。

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

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/ に戻してください。これは 保持期間スイープ がゴミ箱エントリを削除する前に行ってください。デフォルトではゴミ箱に移動されてから 30 日後に削除されます。

関連リソース

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