ポッドキャスト世界の声を聴き、思考の刻みを見る。

Claude Code には組み込みのサブエージェントが用意されているが、カスタムサブエージェントを作れば特定のタスクに特化した動作を組み込める。このチュートリアルではコードレビュー用サブエージェントをゼロから作成し、`/agents` コマンド、ツール選択、モデル選択、そして Claude がいつ・どのようにタスクを委譲するかを制御する設定フィールドを順を追って確認する。 ## [00:03] カスタムサブエージェントとは Claude Code には組み込みのサブエージェントがあるが、特定のタスクに特化した独自のサブエージェントを作ることもできる。カスタムサブエージェントは YAML フロントマターを持つ Markdown ファイルだ。フロントマターは Claude がいつそのエージェントにルーティングするか、どんな機能を持つかを伝え、Markdown 本文はサブエージェントが実行時に参照するシステムプロンプトになる。 > *"Custom sub aents are markdown files with YAML front matter. These markdown files contain configuration that helps claude understand when to use the sub aent and provides directions to the sub aent itself."* ## [00:28] /agentsでサブエージェントを作る `/agents` コマンドを実行するとエージェント管理パネルが開く。「新規エージェントを作成」を選ぶと、スコープ（現在のプロジェクト限定か、マシン上の全プロジェクトで共有するか）と生成方法の二点を確認される。推奨するのは Claude に自動生成させる方法だ。チュートリアルでは、コードの品質とセキュリティ上の問題をレビューするサブエージェントを自然言語でリクエストし、Claude が残りを処理している。 > *"Now, the easiest way to create a sub agent is with the / agents command. Next, you can create a sub agent manually, but we recommend using claw code to automatically generate it for you."* ## [00:56] ツール・モデル・カラーの設定 Claude がファイルを生成する前に、サブエージェントがアクセスできるツールを選ぶ。コードレビュー専用のエージェントなら編集ツールは必須ではないが、実行を有効にしておけばステージ中の変更を確認しやすくなる。ツールを選んだらモデルを選択する。速度重視なら haiku、深い分析が必要なら opus、その中間が sonnet だ。最後にカラーを選ぶ。UI 上に表示され、どのサブエージェントが動いているか一目で分かる。 > *"Now, given that our sub agent is only responsible for reviewing code, you might decide to disallow tools for editing, but I'll leave an execution to allow the sub agent to more easily identify pending changes."* ## [01:43] 設定ファイルを読み解く 生成されたファイルはサマリーウィンドウに表示されたパスにプロジェクト内へ保存される。特に重要なフィールドは四つある。`name` は一意の識別子で、メッセージ中に `@agent-code-quality-reviewer` と入力すれば参照できる。`description` は Claude がタスクを委譲するかどうかを判断するために読む文章で、一行に収める必要がある（エスケープされた `\n` はリテラル文字として扱われる）。説明に「proactively」を加えると Claude がより積極的にこのエージェントを呼び出すようになり、会話例を追加するとルーティングの精度が上がる。`tools` は生成時に付与したアクセス権を反映しているが、ファイルを直接編集して変更できる。 > *"If you want Claude to use the sub agent automatically more often, add in the word proactively to the description."* ## [02:41] システムプロンプトとClaudeの活用方法 `model` フィールドには `haiku`、`sonnet`、`opus`、または `inherit` を指定できる。`inherit` を選ぶと、サブエージェントは親会話と同じモデルで動作する。フロントマター以下のすべてがシステムプロンプトになり、サブエージェントがタスクをどう進めるか、結果をメインエージェントへどう返すかを指示する。 > *"The system prompt will provide guidance to the sub agent, helping it understand how to complete its task and how it should return information back to the main agent."* ## [03:15] サブエージェントをテストする 設定を保存したら、コードを変更して Claude にレビューを依頼してみよう。期待どおりにサブエージェントが起動しない場合は、まず `description` フィールドを見直す。より具体的な例を加えることで、Claude がいつ委譲すべきかを正確に把握できるようになる。 > *"If the sub agent isn't being used when you expect, check your description. Adding more specific examples helps Claude understand when to delegate."* ## 登場人物 - **Anthropic Tutorial Narrator**（人物）：本エピソードの唯一のホスト。Anthropic 公式 YouTube チャンネルで Claude Code サブエージェントチュートリアルシリーズを担当 - **Claude Code**（ソフトウェア）：Anthropic の AI コーディングアシスタント。組み込みサブエージェントとユーザー作成のカスタムサブエージェントの両方をサポート - **Custom subagent**（概念）：YAML フロントマターを持つ Markdown ファイル。Claude Code が特定のタスクを専用エージェントインスタンスに委譲するよう設定する - **/agents command**（概念）：サブエージェントの作成・管理を行う Claude Code の UI エントリポイント。プロジェクトスコープまたはグローバルスコープを選択できる - **System prompt**（概念）：サブエージェント設定ファイルの Markdown 本文。実行時にサブエージェントへタスクの指針と出力フォーマットの指示を与える - **Anthropic**（組織）：Claude および Claude Code プラットフォームの開発元

Anthropic の Claude Code シリーズによるチュートリアル。サブエージェントが脱線・停止・ファイルの誤操作を起こさず安定して動くための4つの具体的なパターンを解説する。コードレビューと Web 検索のサブエージェントを例に、各設定項目の意味と調整方法を順に示す。 ## [00:03] 名前と説明でサブエージェントの動作を制御する メイン・コンテキストウィンドウ・エージェントが受け取るすべてのメッセージには、登録済みサブエージェントの名前と説明がシステムプロンプトに含まれる。つまり説明文は二重の役割を担う——オーケストレーターにサブエージェントを*いつ*起動するかを伝え、入力プロンプトを書く際のテンプレートを提供する。 チュートリアルはコードレビューのサブエージェントを使って実演する。元の設定ではオーケストレーターが汎用プロンプトを書き、サブエージェント自身が `git diff` を呼ぶよう指示するだけだった。説明文を「どのファイルをレビューするか正確に伝えなければならない」という内容に変えると、ファイル選択の責任がオーケストレーター側に移り、次の実行では入力プロンプトが明らかに具体的になる。同じレバーは Web 検索サブエージェントにも有効で、説明文に「引用可能なソースを返すこと」と加えるだけで、委任時にメインスレッドが自動でその指示を含めるようになる。 > *"If you want to better control when the main agent launches a sub agent automatically, you should modify the name and description."* ## [01:41] 出力形式を定義する 出力形式の定義は、単一の改善策の中で最もインパクトが大きいと解説者は指摘する。形式がなければ、サブエージェントには作業完了の明確なシグナルがなく、動き続けてコンテキストを積み上げ、トークンを消費し続ける。 構造化された出力形式は自然な停止点を生む——必須フィールドがすべて埋まれば、サブエージェントは完了を認識できる。実践的には、サマリーブロック・発見事項リスト・ステータスフィールドなどの明示的なスキーマをサブエージェントのシステムプロンプトに直接追加する。 > *"Without a defined output format, sub agents struggle to decide when enough research has been done and they tend to run much much longer than sub agents that are given an output format."* ## [02:04] サマリーで障害を報告する サブエージェントが問題を解決した場合——依存関係の競合、予期しないフラグが必要なコマンド、環境の癖など——メインスレッドがその情報を受け取れなければ、次のステップで同じ壁にぶつかる。解決策は、出力形式そのものに障害の報告を組み込むことだ。 解説者が必ず浮上させるべき内容として挙げるのは、遭遇した障害・セットアップの問題・発見した回避策・特別なフラグや設定が必要だったコマンド・問題を引き起こした依存関係や import の各カテゴリ。これらを必須スキーマに組み込めば、メインスレッドはサブエージェントが苦労して得た知見を引き継ぎ、同じ試行錯誤を繰り返さずに済む。 > *"Otherwise, the main thread has to rediscover the same solutions, obstacles encountered, any setup issues, workarounds discovered or environment quirks, commands that needed special flags or configuration, dependencies or imports that cause problems."* ## [02:42] 役割に応じてツールアクセスを制限する ツールアクセスはセキュリティ制御であるだけでなく、役割を明確にするための手段でもある。`glob`・`grep`・`read` だけを持つ読み取り専用サブエージェントはファイルを誤って変更できないため、設定を見ればその役割が一目でわかる。 解説者は3つのアクセス層を3つのサブエージェントの役割に対応づける。調査用サブエージェントは読み取り専用——コードベースの探索に書き込みは不要だ。レビュー用サブエージェントは `git diff` のために `bash` を使えるが、ファイル編集ツールは持たない。CSS 更新を適用するスタイリングエージェントのように、コードを実際に変更するタスクを担うサブエージェントにのみ `edit` と `write` を付与する。複数のサブエージェントが動く環境では、ツールリストがそれぞれの役割を示す機械可読なサマリーになる。 > *"Only give edit and write to sub agents that should actually change your code, like a styling agent applying CSS updates."* ## [03:27] 効果的なサブエージェントの4つのパターン チュートリアルは4つのパターン全体を一文でまとめて締めくくる——構造化出力・障害報告・的確な説明文・ツールアクセスの制限。各パターンは互いを補強する。的確な説明文は入力プロンプトの曖昧さを減らし、出力形式は停止点を作り、障害報告はエージェント境界をまたいでコンテキストを引き継ぎ、最小限のツールアクセスは残った曖昧さを増幅させる副作用を防ぐ。 > *"So effective sub agents use structured output report obstacles have specific descriptions and limit tool access."* ## 登場人物 - **Anthropic Tutorial Narrator**（人物）：Anthropic を代表して Claude Code サブエージェントチュートリアルシリーズを担当する解説者 - **Claude Code**（ソフトウェア）：Anthropic のエージェント型コーディングツール。サブエージェントをオーケストレーションして多段階のエンジニアリングタスクを完遂する - **Subagent**（概念）：オーケストレーターエージェントが起動する専用 Claude インスタンス。独自のシステムプロンプト・ツールアクセス・入力プロンプトを持つ - **出力形式**（概念）：サブエージェントのシステムプロンプトで定義する必須スキーマ。停止条件を作り、メインスレッドへ返す情報を構造化する - **障害報告**（概念）：回避策・依存関係の問題・環境の癖をサブエージェントの出力に含めることを義務付けるパターン。オーケストレーターが同じ問題を再調査しなくて済む - **ツールアクセスのスコープ限定**（概念）：各サブエージェントに役割上必要なツールだけを与えること——調査は読み取り専用、レビューは bash、ファイル変更が必要なエージェントにのみ edit/write を付与 - **Anthropic**（組織）：Claude および Claude Code エージェント型コーディングプラットフォームの開発元

サブエージェントは Claude Code がタスクを委譲できる専門アシスタントだ。それぞれが独立したコンテキストウィンドウで動作し、自律的に作業を完了させたうえで要点だけを返す。中間の処理トレースはすべて破棄される。この2分間のチュートリアルでは、その分離設計がメインのコンテキストウィンドウを維持するうえでなぜ重要かを解説し、具体的なコード探索シナリオでトレードオフを示したあと、Claude Code に標準搭載されているサブエージェントを紹介する。 ## [00:03] サブエージェントとは サブエージェントは独立した会話コンテキストウィンドウで動作し、任意のカスタムシステムプロンプトで初期化される。親エージェント（メインスレッドの Claude Code）がユーザーの指示をもとにサブエージェントへタスク内容を渡す。サブエージェントは自律的に作業を進め、結果の要約だけをメインスレッドへ返す。途中の作業はすべて隔離されたままだ。 > *「サブエージェントは、Claude がタスクを委譲できる専門アシスタントです。」* 設計上の重要なポイント：サブエージェントが完了すると、その会話スレッド全体が完全に破棄される。メインの会話に戻ってくるのは返された要約だけだ。 ## [00:24] コンテキストウィンドウの管理 メインスレッドで Claude が行うツール呼び出し、ファイル読み込み、検索、関数トレースはすべてメインのコンテキストウィンドウに積み上がる。長いセッションではあっという間に満杯になる。サブエージェントは、こうした個別の調査や操作タスクをオフロードして、その負荷をメインウィンドウに持ち込まないためにある。 > *「各サブエージェントは独自の会話コンテキストウィンドウで動作し、自分で定義したカスタムシステムプロンプトで初期化されます。」* トレードオフははっきりしている。メインウィンドウはきれいなコンテキストを保てるが、サブエージェントがどう結論に至ったか、途中で何を見つけたかは見えなくなる。手に入るのは答えであって、推論の経緯ではない。 ## [01:13] 具体例：決済システム たとえば Claude Code を使って、未知のコードベースの中でどのサービスが返金を処理しているかを調べるとする。サブエージェントなしの場合、Claude は15個のファイルを読み込み、複数の検索を実行し、関数呼び出しをたどるかもしれない。必要だったのは1つの事実だけなのに、そのすべてがメインのコンテキストウィンドウを埋めてしまう。 > *「サブエージェントを使えば、道のりではなく答えだけが手に入ります。」* サブエージェントがコードベースを探索して答えを見つけ、要約だけを返す。メインのコンテキストはきれいなままだ。失われるのは可視性だ。どのファイルを読んだか、どのトレースをたどったかは見えなくなる。 ## [02:00] Claude Code 組み込みのサブエージェント Claude Code には3つのサブエージェントが標準搭載されており、すぐに使える。 - **汎用サブエージェント** — 探索と操作の両方を必要とするマルチステップタスク向け。 - **Explore サブエージェント** — フルタスクループのオーバーヘッドなしにコードベースを高速検索する。 - **Plan サブエージェント** — プランモード中にコードベースを調査・分析してから計画を提示する。 > *「カスタムシステムプロンプトとツールアクセスを設定した独自のサブエージェントを作ることもできます。」* この3つに加えて、独自のシステムプロンプトとツールアクセスリストを持つカスタムサブエージェントを定義し、特定のワークフローに合わせて使うこともできる。 ## [02:30] サブエージェントを使うタイミング サブエージェントが効果を発揮するのは、独立した完結型の問いやタスクがあるときだ。そのまま実行すれば大量の中間コンテキストがメインウィンドウに流れ込む類のものが対象になる。 > *「Claude Code のサブエージェントは作業を集中した単位に分割し、メインのコンテキストウィンドウをきれいに保ち、必要なものだけを返してくれます。標準搭載のものを使っても、独自に作っても同じです。」* コンテキストウィンドウの圧迫が蓄積する長時間の Claude Code セッションで特に価値を発揮する。サブタスクをサブエージェントに委ねることで、セッションの有効稼働時間が実質的に延びる。 ## エンティティ - **Anthropic チュートリアルナレーター** (人物): Anthropic が制作する「Claude Code subagents」チュートリアルシリーズのナレーター - **Claude Code** (ソフトウェア): Anthropic のエージェント型コーディングアシスタント。サブエージェントが動作するホスト環境 - **Claude** (ソフトウェア): Claude Code とそのサブエージェントを動かす基盤 AI モデル - **サブエージェント** (概念): Claude Code がタスクを委譲する専門アシスタント。独自のシステムプロンプトを持ち、隔離されたコンテキストウィンドウで動作する - **コンテキストウィンドウ** (概念): 会話履歴、ツール呼び出し、結果をすべて保持する有限のトークンバッファ。サブエージェントにより中間作業が蓄積するのを防ぐ - **汎用サブエージェント** (ソフトウェア): 探索と操作を組み合わせたマルチステップタスク向けの Claude Code 組み込みサブエージェント - **Explore サブエージェント** (ソフトウェア): コードベースの高速検索に最適化された Claude Code 組み込みサブエージェント - **Plan サブエージェント** (ソフトウェア): プランモード中にコードベースを調査してから計画を提示する Claude Code 組み込みサブエージェント - **Anthropic** (組織): Claude および Claude Code の開発元。このチュートリアルシリーズの制作者

Claude Code スキルは、専門知識を一度書き込んでおける再利用可能な Markdown ファイルだ。リクエストが合致すれば Claude が自動的に起動するため、ユーザーが同じ説明を繰り返す必要も、スラッシュコマンドを手動で入力する必要もない。この3分のチュートリアルでは、スキルとは何か、どこに置くか、CLAUDE.md とどう違うか、そして書くべきタイミングのサインを説明する。 ## [00:03] スキルが解決する繰り返し問題 チームのコーディング規約を Claude に説明するたび、PR フィードバックの形式を再度伝えるたび、好みの commit メッセージ形式をリマインドするたびに——あなたは同じことを繰り返している。ナレーターは3つの例を続けて挙げ、スキルが狙い撃ちにするその摩擦点を明確にする。 > *"Every time you explain your team's coding standards to Claude, you're repeating yourself."* ## [00:20] スキルの正体とClaudeが選ぶ仕組み スキルとは、何かをやり遂げる方法を Claude に一度だけ教える Markdown ファイルだ。Claude はその指示を保持し、状況が合致すれば自動的に適用する。Claude Code ではこのファイルを SKILL.md と呼ぶ。ファイル内の description フィールドが鍵となる仕組みで、「この PR をレビューして」と頼むと、Claude はリクエストを全スキルの説明と照合し、一致するものを起動する。 > *"Claude reads your request, compares it to all available skill descriptions, and activates the ones that match."* ## [01:05] スキルの保存場所：個人用とプロジェクト用 スキルの保存場所は、誰が使うかによって2種類ある。個人スキルは `~/.claude/skills` に置き、すべてのプロジェクトに持ち運べる——commit メッセージのスタイル、ドキュメントの形式、コードの説明の好み。プロジェクトスキルはリポジトリのルート直下の `.claude/skills` に置き、リポジトリをクローンした人全員が自動的に手に入れる。チームの標準——ブランドガイドライン、Web デザインで使うフォントや色——はこちらに置く場所だ。 > *"Anyone who clones the repository gets these skills automatically."* ## [01:42] スキルとCLAUDE.md：自動化とコンテキスト効率 Claude Code にはいくつかのカスタマイズレイヤーがあり、スキルは独自のポジションを占めている。CLAUDE.md はすべての会話に無条件で読み込まれるため、「常に TypeScript の strict mode を使う」といったルールに向いている。スキルはオンデマンドで読み込まれ、現在のリクエストと一致したときだけ起動する。起動前にコンテキストに入るのは名前と説明だけで、スキル本体は実際にトリガーされて初めて読み込まれる。おかげで、デバッグ中は PR レビューチェックリストがコンテキストを占有せず、レビューを依頼したときだけ引き込まれる。スラッシュコマンドはタイプが必要だが、スキルは不要だ。 > *"Skills are unique because they're automatic and task-specific."* ## [02:27] スキルを書くべきタイミング スキルは特定のタスクに紐づいた専門知識に最も向いている——チームが従うコードレビュー基準、commit メッセージ形式、ブランドガイドライン。締めの言葉はシンプルで実用的だ：同じことを Claude に何度も説明していると気づいたら、それはスキルとして書く合図だ。 > *"If you find yourself explaining the same thing to Claude repeatedly, well, that's a skill waiting to be written."* ## 登場人物 - **Anthropic Tutorial Narrator**（人物）：Claude Code skills チュートリアルシリーズのナレーターおよびホスト - **Claude Code**（ソフトウェア）：Anthropic の AI コーディングアシスタント。スキルが発見・適用されるランタイム - **SKILL.md**（概念）：スキルを定義する Markdown ファイル。名前、説明、Claude への指示を含む - **CLAUDE.md**（概念）：プロジェクトレベルまたはグローバルの指示ファイル。すべての Claude Code 会話に無条件で読み込まれる。スキルと対比して語られる - **Anthropic**（組織）：Claude および Claude Code の開発元

一人のエンジニアが使う PR レビュースキルは便利だが、同じスキルをチーム全体に展開すれば、コードレビューの基準が統一され、組織全体で一貫した体験が生まれる。このチュートリアルでは、リポジトリへのコミット、プラグイン、エンタープライズ管理設定、カスタムサブエージェントという4つの具体的な配布方法を取り上げ、それぞれの適切な使い所を解説する。サブエージェントのセクションには見落としやすい注意点がある——サブエージェントはスキルを自動的に継承せず、組み込みエージェントに至ってはスキルにまったくアクセスできない。 ## [00:01] 共有がスキルの価値を何倍にもする理由 スキルが一人の開発者の手元にとどまる間は、その効果も限定的だ。チームに広げた瞬間、標準が定着し、個人差がなくなり、レビューのスタイルと品質が揃う。冒頭では個人利用とチーム規模の対比を軸に、4つの共有メカニズムが紹介される。 > *"A PR review skill that only you use is helpful. The same skill shared across your team standardizes code review and provides a consistent experience amongst your organization which is much better."* ## [00:18] スキルをリポジトリにコミットする 最も手軽な方法は、スキルをプロジェクトリポジトリの `.claude/skills` に置くことだ。リポジトリをクローンするだけで誰でもすぐ使える——追加インストールも余分なツールも不要。更新は通常の `git pull` で届く。チームの開発規約、プロジェクト固有のワークフロー、コードベースの構造を参照するスキルに向いている。 > *"Anyone who clones the repository gets these skills automatically. No extra installation, it's just what you're doing already."* ## [00:45] プラグインでスキルを配布する プラグインは Claude Code にカスタム機能を追加しつつ、単一プロジェクトの枠を超えて広まる設計になっている。プラグインプロジェクト内の `skills/` ディレクトリは `.claude/` の構造を踏襲し、スキル名と `SKILL.md` を持つ。マーケットプレイスに公開すれば、どの Claude Code ユーザーもダウンロードして有効化できる。特定チームの慣習に縛られず、より広いコミュニティで使えるスキルに最適なチャネルだ。 > *"Think of plugins as ways to extend Claude Code with custom functionality, but designed to be shared across teams and projects."* ## [01:26] 管理設定によるエンタープライズ全体への展開 管理者は管理設定を通じて、組織内のすべての開発者にスキルを配布できる。エンタープライズスキルは最高優先度を持ち、同名の個人・プロジェクト・プラグインスキルを上書きする。セキュリティ要件、コンプライアンスフロー、統一必須のコーディング規約など、強制適用すべき標準に適している。チュートリアルでは「必須」という言葉が強調される——あくまで推奨ではなく義務だ。 > *"This is for mandatory standards, security requirements, compliance workflows, or coding practices that must be consistent across the organization."* ## [01:52] カスタムサブエージェントと明示的なスキル読み込み サブエージェントはメイン会話のスキルを引き継がない。組み込みエージェント（explorer、planner、verify）はスキルにまったくアクセスできない。`.claude/agents` 内の `agent.md` ファイルで定義したカスタムサブエージェントだけがスキルを使え、しかもそのファイルの `skills:` フィールドに明示的に列挙したものに限られる。スキルはサブエージェントの起動時に読み込まれ、オンデマンドではないため、リストはそのエージェントの目的に常に関連するスキルだけに絞るべきだ。チュートリアルでは、Claude Code のサブエージェント作成ツールで新しいサブエージェントを作り、既存の `agent.md` にスキルを追加する流れが実演される。 > *"Built-in agents like the explorer, planner, and verify can't access skills at all. Only custom sub-agents you define can use them, and only when you explicitly list them."* ## [03:18] まとめ：適切な配布方法の選び方 締めくくりでは各方法のシナリオが整理される。チームアクセスにはプロジェクトディレクトリ、リポジトリをまたぐ共有にはプラグイン、組織全体の必須標準にはエンタープライズ展開、そして隔離されたタスク委譲にはサブエージェントへの明示的なスキルリスト。サブエージェントへの注意喚起は最後にも繰り返される——スキルは起動時に読み込まれるのであり、遅延ロードではないから、常に関連するものだけをリストに入れること。 > *"Share skills through project directories for team access, plugins for cross-repository distribution, or enterprise deployment for organization-wide standards."* ## 登場人物・用語 - **Anthropic チュートリアルナレーター** (人物)：Claude Code スキルチュートリアルシリーズの単独プレゼンター - **Claude Code** (ソフトウェア)：Anthropic の AI コーディングアシスタント；スキルを作成・展開するランタイム環境 - **Skills（スキル）** (概念)：`.claude/skills` に置く再利用可能な命令セット；Claude Code の動作を拡張する - **Plugins（プラグイン）** (概念)：スキルをバンドルしてチームやマーケットプレイスユーザー間で共有できる配布可能パッケージ - **Managed settings（管理設定）** (概念)：エンタープライズ管理者がスキルを最高優先度で組織全体に展開する仕組み - **Sub-agents（サブエージェント）** (概念)：`.claude/agents` の `agent.md` で定義するカスタム Claude Code エージェント；スキルを読み込める唯一のエージェント種別で、明示的に列挙する必要がある - **Anthropic** (組織)：Claude Code を開発した企業；Claude Code スキルチュートリアルシリーズを制作

Claude Code skills シリーズの 4 分間チュートリアル。基本的な skill を信頼性が高くコンテキスト効率のよいツールへ仕上げるための高度な設定フィールドを取り上げる。agentskills.io が定義するフィールド全体——`name`、`description`、`allowed_tools`、`model`——をひとつずつ解説し、参照資料やスクリプトをユーザーのリクエストが実際に必要とする場合にのみ読み込むよう、段階的開示で大規模 skill を整理する方法を示す。 ## [00:02] 高度な skill フィールドの概要 agentskills.io オープン標準は、必須の `name` と `description` に加えていくつかのフィールドを定義している。`name` は小文字とハイフンのみで構成し、64 文字以内に収め、ディレクトリ名と一致させる必要がある。`description` は最大 1,024 文字で、Claude が skill をマッチングする際の主要シグナルとなる。任意フィールドとして `allowed_tools`（呼び出せるツールを制限）と `model`（特定の Claude バージョンに固定）の 2 つが用意されている。 > *"name と description だけで基本的な skill は動作しますが、Claude Code で skill をより効果的にするための高度なヒントをいくつか紹介します。"* ## [00:39] 効果的な description の書き方 「help with dogs」のような曖昧な description では、Claude は skill の適用範囲やトリガー条件を推測するしかない。良い description が答えるべき問いはふたつだけ——この skill は何をするのか、そしていつ使うべきなのか。キーワードをユーザーの自然な言い回しに合わせることが、トリガーされない skill を直す最も効果的な手段だ。 > *"良い description はふたつの問いに答えます。この skill は何をするのか？そして、いつ使うべきなのか？"* ## [01:20] allowed_tools によるツール制限 `allowed_tools` は、skill を特定の操作面に閉じ込めるための仕組みだ——セキュリティ上の機密を扱うワークフローでは読み取り専用アクセスに限定できる。このフィールドを設定すると、Claude は許可されたツールだけを許可申請なしに呼び出せる。編集・書き込み・Bash コマンドは一切使えなくなる。フィールドを省略した場合は Claude の通常の権限モデルがそのまま適用される。 > *"この skill がアクティブな間、Claude はこれらのツールだけを許可なしに使えます。編集も書き込みも bash コマンドもありません。"* ## [01:49] 複数ファイル skill の段階的開示 skill はライブの会話と Claude のコンテキストウィンドウを共有する。2 万行の `SKILL.md` にすべてを詰め込むと、呼び出すたびにコンテキストが膨れ上がり、メンテナンスも苦痛になる。解決策は、必須の指示を `SKILL.md` に置き、参照資料は別ファイルに移して、ユーザーのリクエストが実際に必要とするときだけ Claude が読み込む構成にすること。標準が推奨するサポートディレクトリは 3 種類——実行コード用の `scripts/`、ドキュメント用の `references/`、画像やテンプレート用の `assets/`。`SKILL.md` 内のリンクは目次の項目として機能し、そのトピックが話題に上らなければファイルは一切読み込まれない。 skill ディレクトリ内のスクリプトはソースをコンテキストに読み込まずに実行できるため、消費するのは出力のトークンだけ。`SKILL.md` は 500 行以内に収めるのが推奨で、それを超えたら skill を分割するサインだ。 > *"コンテキストウィンドウにドキュメント全体を詰め込むのではなく、目次を置くようなイメージです。"* ## [03:18] まとめ：skill メタデータとベストプラクティス チュートリアルの締めくくりとして設定の全体像を改めて整理する。`name` と `description` は必須、`allowed_tools` はツール操作面を制限、`model` は Claude バージョンを固定。description には具体的な動詞とトリガーフレーズを含めることで安定したマッチングが実現する。大規模な skill では段階的開示を用いて `SKILL.md` を 500 行以内に保ち、サポートファイルは実際に必要になるまで読み込みを遅らせる。スクリプトはソースを読み込まずに実行できるため、コンテキストをスリムに保てる。 > *"スクリプトはその内容を読み込まずに実行できるため、コンテキストを効率的に保てます。"* ## 登場人物・エンティティ - **Anthropic チュートリアルナレーター** (人物): このチュートリアルシリーズの単独ホスト。Claude Code skill の設定について解説する。 - **Claude Code** (ソフトウェア): agentskills.io 標準に基づく skill を読み込んで実行する Anthropic の CLI ツール。 - **agentskills.io** (組織): `name`、`description`、`allowed_tools`、`model`、ディレクトリ規約などを定義する skill マニフェストスキーマのオープン標準。 - **SKILL.md** (概念): Claude Code skill の主要マニフェストファイル。500 行以内に収め、サポートファイルへのリンクを置くことが推奨される。 - **allowed_tools** (概念): 特定の Claude ツールをホワイトリスト指定する任意 skill フィールド。読み取り専用またはサンドボックス化された skill モードを実現する。 - **段階的開示** (概念): 参照ファイルやスクリプトを、アクティブなリクエストが実際に必要とするときのみコンテキストに読み込む多ファイル skill の構成手法。 - **コンテキストウィンドウ** (概念): 会話と skill ファイルが共有するトークン予算。段階的開示が節約しようとする主要なリソース。

この 3 分間のチュートリアルでは、Claude Code の個人スキルをゼロから構築する手順を通しで示す。SKILL.md を含むディレクトリを作成し、スキルが起動時にロードされることを確認して、実際のリクエストに Claude が適用する様子を観察する。後半ではスキルのロードパイプラインを詳しく解説——4 か所のスキャン場所、名前のみを読み込む起動フェーズ、確認ゲート、そして名前の競合を解決する 4 段階の優先順位。 ## [00:03] このチュートリアルで作るもの まず具体的な目標を提示する。視覚的な図や類比を使ってコードを説明するよう Claude に教えるスキルを構築する。スキルが完成したら、Claude が内部でどのようにスキルを受け取り実行するかも追う。 > *"This skill will teach Claude how we would like it to explain code using visual diagrams and analogies."* ## [00:18] スキルファイルの作成 個人スキルはホームディレクトリ下（プロジェクト内ではない）に置く。最初のステップは `~/.claude/skills/` の中にスキル名のディレクトリを作り、その中に SKILL.md ファイルを一つ置くことだ。3 つのセクションが重要になる。`name`（起動時に Claude が保存する識別子）、`description`（スキルを発動するかどうかを Claude が判断する際の照合基準）、そして 2 番目の `---` 区切り文字以降のすべて（スキルが発動したときに Claude が従う実際の指示）。 > *"Take into consideration that we're creating a directory with the skill name inside of the skills directory."* ## [00:52] スキルのロードとテスト Claude Code はスキルを起動時にスキャンするため、ファイルを作成したらセッションの再起動が必要だ。`/skills` を実行すると、作成したスキル名が一覧に表示されるはずだ。テストするには、変更を加えたブランチに切り替え、「Write a PR description for my changes」と自然言語でリクエストを送る。Claude は PR description スキルを使用していることを表示し、diff を読み込んでテンプレートに合った説明を毎回同じフォーマットで書き出す。 > *"Claude will then show you that it's using the PR description skill."* ## [01:25] Claude がスキルをロードする仕組み 起動時、Claude Code は 4 か所をスキャンする。エンタープライズ管理設定、個人の `~/.claude/skills/`、プロジェクトの `.claude/` ディレクトリ、インストール済みのプラグイン。この段階では `name` と `description` だけをロードし、全コンテンツはロードしない。リクエストが届くと、Claude は保存された説明と照合する。「explain what this function does」は「explain code with visual diagrams」と重なるため、スキルが一致する。Claude は完全な SKILL.md を読み込む前に確認を求め、どのコンテキストが注入されているかをユーザーが常に把握できるようにする。 > *"It loads only the name and description of each skill, not the full content. This is important later."* ## [02:02] 優先順位ルールと名前の競合 スキルを同梱したリポジトリをクローンすると名前の競合が生じる可能性がある。Claude は固定の優先順位で解決する。エンタープライズ（最高位）→ 個人 → プロジェクト → プラグイン（最低位）。エンタープライズの `code-review` スキルは、同名の個人スキルを常に上書きする。実践的な対策は説明的な命名だ。汎用的な `review` の代わりに `security-review` や `frontend-pr-review` を使えば、そもそも競合が起きない。 > *"If your company has an enterprise code review skill and you create a personal code review skill, the enterprise version of that takes precedence."* ## [02:52] スキルの更新と削除 スキルの更新は SKILL.md を直接編集して保存するだけでよい。削除はディレクトリごと消す。どちらの操作も、変更を反映させるには Claude Code の再起動が必要だ。スキルのリストはセッション起動時に一度だけ構築され、ファイルの変更はリアルタイムで監視されない。 > *"Edit the skill.md file to update a skill and restart Claude Code for changes to take effect."* ## 登場人物・用語 - **Anthropic チュートリアルナレーター** (人物): Claude Code スキルシリーズのスキル作成チュートリアルを一人で進行するホスト - **Claude Code** (ソフトウェア): Anthropic が提供する Claude の CLI ツール。起動時にスキルをスキャンし、ユーザーのリクエストがスキルの説明と一致すると適用する - **SKILL.md** (概念): スキルを定義する唯一のファイル。YAML フロントマター（name、description）と、2 番目の `---` 区切り文字以降の自由記述の指示テキストで構成される - **スキル** (概念): Claude に一貫した動作パターンを教える、再利用可能な名前付き指示セット。SKILL.md を含むディレクトリとして保存される - **エンタープライズスキル** (概念): 組織が管理するスキルで、4 段階の優先順位の最上位に位置し、個人・プロジェクト・プラグインのスキルより優先される - **Anthropic** (組織): Claude および Claude Code の開発元。claude.com/resources/courses でこのチュートリアルシリーズを公開している

Claude Code には5つのカスタマイズ手段がある——Skills、CLAUDE.md、サブエージェント、Hooks、MCP サーバーだ。それぞれ異なる用途のために設計されている。この3分間のチュートリアルでは、各選択肢を正しいユースケースに対応させ、CLAUDE.md で十分な場面で Skills を作ってしまったり、サブエージェントが必要な場面で Hooks を設定してしまうミスを防ぐ。 ## [00:02] 5つのカスタマイズ手段、1つの選択問題 Claude Code には動作を制御する5つの手段がある：Skills、CLAUDE.md、サブエージェント、Hooks、MCP サーバー。解説者はこの5つを素早く挙げた後、「これらは何か？」という問いから「どれをここで使うべきか？」という問いへすぐに軸を移す。 > *"それぞれ異なる問題を解決します。いつどれを使うかを知ることで、間違ったものを作らずに済みます。"* その後の内容は、この一文への答えとして構成されている。 ## [00:18] CLAUDE.md vs Skills：常時適用 vs オンデマンド CLAUDE.md は Claude が会話の開始時に毎回読み込むファイルで、有効化の操作は不要だ。フレームワークの選択、コーディングスタイル、データベースのルールなど、忘れてはならないプロジェクト全体の制約を置く場所として適している。Skills は対照的にオンデマンドで読み込まれる——PR レビューのチェックリストは、実際にレビューを依頼したときだけコンテキストに入り、コードを書いているときには現れない。 > *"Use Claude MD for project-wise standards that always apply constraints like never modify the database schema, framework preferences, and coding style."* 判断基準は「常時性」と「関連性」だ。プロジェクト内のすべてのプロンプトに適用すべき指示なら CLAUDE.md へ。特定の場面でしか使わないなら Skills へ。 ## [01:03] Skills vs サブエージェント：共有コンテキスト vs 独立実行 Skills は現在の会話に知識を注入する——その指示は既存のコンテキストに加わる。サブエージェントは異なる動き方をする：タスクを受け取り、独立した実行コンテキストで処理し、メインの会話に触れることなく結果を返す。 > *"Use sub agents when you want to delegate a task to a separate execution context. You need different tool access that the main conversation does. You want isolation between delegated work and your main context."* 専門知識を会話全体を通じて Claude の推論に反映させたいなら Skills を使う。メインセッションと委託作業の間に明確な境界を設けたい場合——異なるツールアクセス、コンテキストの汚染なし——はサブエージェントを使う。 ## [01:42] Hooks vs Skills：イベント駆動 vs リクエスト駆動 Hooks はイベントに応じて自動的に実行される——Claude がファイルを保存するたびにリンターを走らせたり、特定のツール呼び出しの前に入力を検証したりする。トリガーは問いかけの内容ではなく、Claude の行動だ。Skills はその逆で、リクエスト駆動——クエリが一致したときに起動する。 > *"A hook might run a llinter every time Claude saves a file or validate input before certain tool calls. They're all event driven, while skills, they're request driven. They activate based on what you're asking."* システムイベントに対して無条件で発動させたい動作は Hooks へ。聞かれたときに Claude の思考を形作るものは Skills へ。 ## [02:15] 5つを組み合わせた包括的なカスタマイズ うまく設定された Claude Code では、各ツールがその本来の役割を担う：CLAUDE.md は常時有効なプロジェクト標準を持ち、Skills はすべてのプロンプトに混在させるべきでないタスク固有の知識を提供し、Hooks は自動化された副作用を処理し、サブエージェントは分離された委託作業を行い、MCP サーバーは外部ツールへのアクセスを提供する。これらは代替関係にあるのではなく、組み合わせて使うものだ。 > *"Don't force everything into skills when another option fits best. You can use multiple at a time."* Skills はトピックが関連したときに自動起動し、CLAUDE.md は常に存在し、サブエージェントは独立して動き、Hooks はイベントで発火し、MCP は外部ツールを提供する。各関心事に適したレイヤーを選び、自由に組み合わせよう。 ## 登場人物・概念 - **Anthropic チュートリアルナレーター** (人物)：Anthropic を代表してこの Claude Code skills チュートリアルシリーズを進行する人物。 - **Claude Code** (ソフトウェア)：Anthropic の AI 搭載コーディングアシスタント。本チュートリアルシリーズの主題。 - **Skills** (概念)：ユーザーのリクエストと一致したときに起動するオンデマンドの知識パッケージ。指示を現在の会話コンテキストに注入する。 - **CLAUDE.md** (概念)：Claude Code のすべての会話で自動的に読み込まれる設定ファイル。常時有効なプロジェクト全体の標準と制約に使用する。 - **サブエージェント** (概念)：委託されたタスクをメインの会話から分離して処理するために独立起動される実行コンテキスト。 - **Hooks** (概念)：ファイル保存やツール呼び出しなど、特定の Claude アクションに対してユーザーのリクエストとは無関係に自動発火するイベント駆動の自動化。 - **MCP サーバー** (ソフトウェア)：Claude Code セッションに外部ツールを提供する Model Context Protocol サーバー。 - **Anthropic** (組織)：Claude Code の開発元。Claude Code skills チュートリアルシリーズの制作・公開者。