Introduction to Agent Skills — 日本語学習ガイド

Anthropic Academy「Introduction to Agent Skills」コースの日本語学習ガイド。原文ノート（全6セクション）の内容を、試験勉強・実務参照に使える形に再構成したもの。NotebookLM 等で音声概要／動画概要を作る際のソース資料にもなる。

対象は Claude Code の skills（スキル）機能。「Claude に同じ説明を繰り返させない」ための仕組みであり、CLAUDE.md・スラッシュコマンド・サブエージェント・フック・MCP サーバーといった Claude Code の他機能とどう役割分担するかが一貫したテーマになっている。

1. What are skills?（スキルとは何か）

学習目標

このセクションを終えると、次のことができるようになる。

• Claude Code の skills とは何か、どう動作するかを定義できる。
• スキルがどこに置かれるか（personal ディレクトリ vs project ディレクトリ）を説明できる。
• skills・CLAUDE.md・スラッシュコマンドの違いを区別できる。
• スキルが適切なカスタマイズ手段となる場面を見極められる。

スキルの正体

skill とは、Claude Code が発見して使える「指示とリソースのフォルダ」 である。1つのスキルは必ず SKILL.md というファイルを持ち、その frontmatter（ファイル冒頭のメタデータ部分）に name と description を記述する。frontmatter より下の本文には、実際にどう振る舞うべきかの指示を書く。

言い換えると、skill は「あることを一度だけ Claude に教えておくための markdown ファイル」 であり、一度書いておけば、以降 Claude はそれが関連する場面で自動的にその知識を適用する。

frontmatter の例は次の通り。

---
name: pr-review
description: Reviews pull requests for code quality. Use when reviewing PRs or checking code changes.
---

この --- で囲まれた部分より下に、実際の指示本文を書く。

Claude がスキルを選ぶ仕組み

Claude はユーザーからのリクエストを、利用可能な各スキルの description と突き合わせて比較し、内容が一致するものを起動する。つまり description こそが「このスキルをいつ使うべきか」をClaudeに伝える唯一の手がかり であり、スキルが正しく起動するかどうかは description の書き方に懸かっている（この点は第3セクションでさらに深掘りされる）。

スキルの置き場所

スキルは置き場所によって性質が変わる。

Windows の場合、personal skills は C:/Users/<user>/.claude/skills に置かれる。project skills はバージョン管理にコミットされる対象であり、チームの標準を共有する手段になる。

skills vs CLAUDE.md vs スラッシュコマンド

3つの仕組みはいずれも「Claude の振る舞いを調整する」ものだが、いつ読み込まれるか が根本的に異なる。

CLAUDE.md は「常にオン」、skills は「一致したら自動でオン」、スラッシュコマンドは「呼んだときだけオン」——という三段構えで覚えるとよい。

いつスキルを使うべきか

判断の目安はシンプルで、「Claude に同じ説明を何度も繰り返している」と気づいたら、それはスキルとして書き出すべきタイミング である。具体的には次のような場面が挙げられている。

• コードレビューの基準
• コミットメッセージのフォーマット
• ブランドガイドライン
• ドキュメントのテンプレート
• デバッグのチェックリスト

2. Creating your first skill（はじめてのスキルを作る）

学習目標

• 適切な frontmatter を備えたスキルをゼロから作成できる。
• 作成したスキルが Claude Code に読み込まれることをテスト・確認できる。
• Claude がリクエストをスキルにどうマッチさせるかを説明できる。
• 優先順位の階層（Enterprise、Personal、Project）と、プラグインが名前空間で衝突を避ける仕組みを説明できる。

スキルの構造とロードの仕組み

1つのスキルは、SKILL.md を含むディレクトリである。SKILL.md の frontmatter には name と description というメタデータがあり、その下に実際の指示本文が続く。

Claude は起動時に、スキルの名前と description だけ を読み込む。その後、実際のリクエストが来た時点で、Claude はそのリクエストと読み込み済みの description 群とを意味的に（semantic matching）比較する。一致するスキルが見つかると、Claude は bash コマンド経由で SKILL.md をファイルシステムから直接読み込む。この読み込みにユーザーへの確認プロンプトは介在せず、自動的に行われる。つまり、スキルの内容が実際にコンテキストへ展開されるのは、Claude がマッチを検出したその時点になる。

個人用スキルを作る例（PR説明文スキル）

まずディレクトリを作る。

mkdir -p ~/.claude/skills/pr-description

続けて、そのディレクトリの中に SKILL.md を作成する。

---
name: pr-description
description: Writes pull request descriptions. Use when creating a PR, writing a PR, or when the user asks to summarize changes for a pull request.
---
When writing a PR description:
1. Run `git diff main...HEAD` to see all changes on this branch
2. Write a description following this format:
## What  (one sentence) / ## Why (brief context) / ## Changes (bullets)

この例における各要素の役割は次の通り。

• name — スキルを識別する名前。
• description — Claude がこのスキルを使うべきかどうかを判定するためのマッチング基準。
• 2つ目の --- より後ろ — 実際の指示内容。この例では「PR説明文を書くときは、まず git diff main...HEAD でブランチ上の全変更を確認し、## What / ## Why / ## Changes という書式で説明文を書く」という手順が書かれている。

テストと確認の手順

スキルの追加・変更・削除は、現在は多くの場合その場でホットリロードされ（Live change detection）、セッションを再起動しなくても現在のセッション内で反映される。再起動が必要になるのは、セッション開始前には存在しなかった新しい skills ディレクトリを新規作成した場合など、限られたケースのみである。反映されたかは、利用可能なスキルの一覧（available-skills list）にそのスキルが載っているかで確認する。実際に動作するかは、たとえば「write a PR description for my changes」のように話しかけてテストする。

マッチングの仕組み（詳細）

Claude Code の起動時、Claude は4箇所（後述する Enterprise / Personal / Project / Plugins の各所在）をスキャンするが、このときロードするのは 名前と description だけ である。ユーザーからリクエストが来ると、Claude はそのメッセージを、読み込み済みの全 description と意味的に比較する。マッチが見つかると、Claude は bash コマンド経由で SKILL.md を読み込む。ユーザーへの確認は介在せず、マッチした時点で自動的にコンテキストへ取り込まれる。

優先順位（名前が衝突した場合）

同じ名前のスキルが Enterprise・Personal・Project に重複して存在する場合、次の優先順位で解決される（先頭ほど優先度が高い）。

1. Enterprise（管理者が設定する managed settings） — 最優先
2. Personal（~/.claude/skills）
3. Project（リポジトリ内の .claude/skills）

Plugins のスキルはこの優先順位の序列には含まれない。プラグインのスキルは plugin-name:skill-name という名前空間を使うため、そもそも他のレベルと名前が衝突しない設計になっている。

Enterprise が最優先である理由は、組織が標準を強制できるようにするためである。名前の衝突を避けるには、frontend-review のように 説明的で具体的な名前 を付けることが推奨される。

更新・削除の方法

スキルを更新したい場合は、その SKILL.md を編集すればよい。削除したい場合は、ディレクトリごと削除する。これらの変更は多くの場合、現在のセッション内でそのままホットリロードされ、再起動は不要である。 再起動が必要になるのは、セッション開始前には存在しなかった新しい skills ディレクトリを新規作成した場合など、限られたケースのみである。

3. Configuration and multi-file skills（設定と複数ファイル構成のスキル）

学習目標

• allowed-tools や model といった高度なメタデータを設定できる。
• 確実に起動する description を書けるようになる。
• allowed-tools を使って、確認なしに使えるツールを事前承認できる（利用範囲そのものを制限したい場合は disallowed-tools を使う）。
• progressive disclosure（段階的開示）の考え方で、複雑なスキルを複数ファイルに整理できる。

メタデータフィールド一覧

Agent Skills のオープンスタンダードで定義されている frontmatter フィールドは、必須の name・description と、任意の license・compatibility・metadata・allowed-tools（experimental）を合わせた次の6つ。

name と description は Agent Skills のオープンスタンダード上は必須とされるが、Claude Code CLI では実際には任意（省略可能）である。allowed-tools はオープンスタンダードにも含まれる任意フィールドである一方、model はオープンスタンダードの仕様には存在せず、Claude Code CLI 固有の拡張フィールドである。いずれも任意でありながら強力な機能である、という位置づけになっている。

効果的な description の書き方

良い description は、次の2つの問いに答えるものである。

1. このスキルは何をするのか？
2. Claude はいつこのスキルを使うべきか？

書き方のコツとして、曖昧にせず明示的に書くこと、そして狙い通りに起動しない場合は、ユーザーが実際にリクエストを言い回す際に使いそうなキーワードを description に追加することが挙げられている。

allowed-tools によるツール事前承認

allowed-tools を設定すると、そのスキルが有効な間、リストしたツールは確認プロンプトなしに使えるようになる（＝事前承認リスト）。ただしこれはツールの利用範囲を制限するものではなく、リストにないツールも通常のパーミッションモデルに従って引き続き呼び出せる。Claude が使えるツールの範囲そのものを制限したい場合は、allowed-tools ではなく disallowed-tools フィールドを使う。設定しなければ、通常のパーミッションモデルがそのまま適用される。

例（コードベースのオンボーディング用スキル）:

---
name: codebase-onboarding
description: Helps new developers understand how the system works.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---

この設定では、Claude は Read / Grep / Glob / Bash を確認プロンプトなしに使えるが、それ以外のツール（ファイルの編集など）が禁止されるわけではなく、通常どおり確認を求められた上で使うことができる。

Progressive disclosure（段階的開示）

スキルは Claude のコンテキストウィンドウを他の情報と共有している。そのため、SKILL.md 本体には本当に必須な指示だけを残し、詳細な参照情報は別ファイルに切り出して、必要なときだけ Claude に読ませる という設計が推奨される。

整理の型として、次の3種のサブディレクトリが挙げられている。

• scripts/ — 実行可能なコード
• references/ — ドキュメント類
• assets/ — 画像・テンプレート・データなど

これらの補助ファイルは SKILL.md からリンクし、「いつそのファイルを読み込むべきか」の指示も添えておく。目安として、SKILL.md は500行未満に収める ことが推奨されている。

スクリプトを効率よく使う

スクリプトは実行されるだけで、その中身がコンテキストに読み込まれることはない。トークンを消費するのは実行結果（出力）だけ である。そのため、Claude に対しては「スクリプトを読め」ではなく「スクリプトを実行しろ」と指示する。

スクリプトが向いている用途としては、環境の検証、一貫したデータ変換、そして「テスト済みのコードとして実行する方が、Claude に都度判断させるより信頼できる」ような処理が挙げられる。

4. Skills vs. other Claude Code features（スキルと他の Claude Code 機能の比較）

学習目標

• skills を CLAUDE.md・サブエージェント・フック・MCP サーバーと比較できる。
• 場面に応じて適切な機能を選べる。
• これらを組み合わせた、補完的なセットアップを設計できる。

各機能の役割分担

このセクションの一番の要点は、それぞれの機能には得意分野があり、すべてを1つの機能に無理やり詰め込むのではなく、組み合わせて使うべき だという点にある。

CLAUDE.md vs Skills

CLAUDE.md は すべての会話に常時読み込まれる。TypeScript strict mode のようなプロジェクト全体の標準、「DBスキーマを絶対に変更しない」といった制約、コーディングスタイルなど、常に効かせておきたいルールに向く。

Skills は オンデマンドで読み込まれる。タスク固有の専門知識、時々しか関係しない知識、毎回の会話に含めるとかえって邪魔になるような詳細な手順に向く。

Skills vs Subagents

Skills は、現在の会話に知識を追加する もの。

一方 Subagents（サブエージェント）は、別の独立したコンテキストで実行される。タスクを受け取り、独立して作業し、結果を返す、という委譲の形を取る。委譲したい場合、異なるツールアクセス権が必要な場合、コンテキストを分離したい場合はサブエージェントを使う。現在のタスクに対して Claude の知識を強化したいだけなら、スキルを使う。

Skills vs Hooks

Hooks（フック）は イベント駆動。ファイル保存のたび、あるいはツール呼び出しの前後といった「イベント」で発火する（例: 保存のたびにリンターを走らせる、ツール呼び出し前にバリデーションする）。

Skills は リクエスト駆動。ユーザーが何を頼んだかに応じて起動する。保存ごとの処理・バリデーション・自動化された副作用にはフックを、Claude がリクエストをどう処理するかを左右する知識にはスキルを使う。

まとめると

Claude Code の機能群は、次のように役割分担されている。

MCP サーバーは、外部ツールや外部サービスとの統合を提供するものであり、これらとはまったく別のカテゴリに位置づけられる。それぞれが自分の専門分野を担当するので、状況に応じて複数を同時に使うのが基本の考え方になる。

5. Sharing skills（スキルを共有する）

学習目標

• Git リポジトリ経由でスキルを共有できる。
• プラグイン／マーケットプレイス経由でスキルを配布できる。
• Enterprise の managed settings を使って組織全体にスキルを展開できる。
• 特定のスキルを使うカスタムサブエージェントを設定できる。

リポジトリへのコミットによる共有

スキルを .claude/skills に置くと、それは Git を通じて自動的に共有される。リポジトリを clone した人全員が、そのスキルを自動的に手に入れる ことになる。更新をプッシュすれば、次回 pull した全員がその更新を受け取る。チームのコーディング標準、プロジェクト固有のワークフロー、コードベースの構造を説明するスキルなどに向く。.claude ディレクトリ（agents・hooks・skills・settings を含む）は、そのままバージョン管理の対象になる。

プラグイン経由の配布

プラグインは、共有可能な機能で Claude Code を拡張する仕組みである。プラグインプロジェクトの中に skills ディレクトリを作り（各スキルは SKILL.md を持つフォルダとして配置する）、それをマーケットプレイスに配布することで、他の人がそのスキルを発見・インストールできるようになる。プロジェクトに強く紐づいていないスキルほど、この配布方法に向いている。

Enterprise 展開（managed settings）

管理者は組織全体にスキルを展開できる。Enterprise のスキルは最優先度を持ち、同じ名前の personal / project のスキルより優先される（Enterprise → Personal → Project の順）。plugin のスキルは plugin-name:skill-name という名前空間を持つため、この優先順位の序列には含まれず、他のレベルと名前が衝突することはない。managed settings では、たとえば strictKnownMarketplaces のような設定で、プラグインをどこ（GitHub リポジトリや npm パッケージなど）からインストールできるかを制御することもできる。必須の標準・セキュリティ・コンプライアンスを徹底したい場面に向いている。

スキルとサブエージェントの落とし穴

ここは特に注意が必要なポイントとして強調されている。サブエージェントは、自動的にはあなたのスキルを見ることができない。 サブエージェントは、素の状態のクリーンなコンテキストから開始する。

• 組み込みサブエージェント は Explore・Plan・general-purpose（および statusline-setup、claude-code-guide などの補助的なもの）であり、"Verify" という名前の組み込みサブエージェントは存在しない。これらは frontmatter の skills フィールドによるスキルのプリロードを受けない。
• カスタムサブエージェント は、frontmatter の skills フィールドで明示的にリストしたスキルを起動時にプリロードできる。ただし、明示していないプロジェクト・パーソナル・プラグインのスキルも、実行中に Skill ツールを通じて呼び出すこと自体は可能である。
• skills フィールドで指定したスキルは、サブエージェントが起動する その時点で プリロードされる（オンデマンドではない）。

カスタムサブエージェントは、.claude/agents（または ~/.claude/agents）内の markdown ファイルとして作成する。現行バージョンの /agents コマンドはもはや対話式の作成ウィザードを開かず、Claude に作成を依頼するか、ファイルを直接編集するよう促すメッセージを表示するだけになっている。frontmatter に skills フィールドを含めることで、起動時にプリロードしたいスキルを指定する。

---
name: frontend-security-accessibility-reviewer
description: "Use this agent when you need to review frontend code for accessibility..."
tools: Bash, Glob, Grep, Read, WebFetch, WebSearch, Skill...
model: sonnet
skills: accessibility-audit, performance-check
---

このとき、指定するスキルがあらかじめ .claude/skills に実在すること を確認しておく必要がある。この仕組みは、隔離された環境で特定の専門知識を使わせて委譲したい場合、サブエージェントごとに異なるスキルセットが必要な場合、委譲した作業でも標準を守らせたい場合に向いている。

6. Troubleshooting skills（スキルのトラブルシューティング）

学習目標

• skills validator（skills-ref などの検証ツール）を使える。
• 起動しない・読み込まれないといった問題を診断できる。
• 優先順位の衝突を解決できる。
• 依存関係・権限・パスに起因するランタイムエラーをデバッグできる。

validator を使う

Agent Skills のオープンスタンダード側には、SKILL.md の frontmatter を検証するリファレンス実装として skills-ref というツールがある（pip install skills-ref または uv add skills-ref でインストールでき、「agent skills verifier」という名称のコマンドではない）。スキルのディレクトリから実行してもよいし、どこからでも実行できる。この validator は構造上の問題を早期に検出してくれる。ただし、Claude Code 公式のトラブルシューティング手順はこのツールから始めるようには案内しておらず、まずは description の内容やキーワードの一致状況を確認するところから始める。

症状別の診断ガイド

原文で挙げられているトラブルパターンと対処法を、症状別に整理すると次のようになる。

クイックチェックリスト

原文末尾に整理されている、症状ベースの早見表は次の通り。

• 起動しない？ → description とトリガーフレーズを改善する。
• 読み込まれない？ → パス・ファイル名・YAML（frontmatter の記法）を確認する。
• 違うスキルが選ばれる？ → descriptions を明確に区別する。
• 他のスキルに覆われている（shadowed）？ → 優先順位の階層を確認し、リネームする。
• プラグインのスキルが見当たらない？ → キャッシュをクリアして再インストールする。
• ランタイムで失敗する？ → 依存関係・権限・パスを確認する。

まとめ

このコース全体を通じて一貫しているのは、「スキルは万能ではなく、Claude Code の他の機能と役割分担して初めて機能する」 という考え方である。

• スキルは フォルダ＋ SKILL.md（name + description の frontmatter ＋ 指示本文） という単純な構造を持つ。
• 置き場所は personal（~/.claude/skills） と project（.claude/skills） の2種類が基本で、そこに plugins と enterprise（managed settings） が加わり、名前衝突の優先順位は Enterprise → Personal → Project の順になる。Plugins は plugin-name:skill-name という名前空間を持つため、この序列には含まれず他レベルと衝突しない。
• Claude はまず name と description だけ を読み込み、リクエストとの意味的マッチングでスキルを選ぶと、確認プロンプトを介さず自動的に SKILL.md の本文をフルに読み込む（bash コマンド経由でファイルを読む形で実行される）。この「オンデマンド性」こそが、常時読み込まれる CLAUDE.md や、明示的に呼ぶ必要があるスラッシュコマンドとの決定的な違いである。
• 高度な設定として allowed-tools（確認なしで使えるツールの事前承認。範囲を制限したい場合は disallowed-tools）と model（使用モデル指定）があり、複雑なスキルは progressive disclosure（scripts/ / references/ / assets/ への分割、SKILL.md は500行未満を目安に）で整理する。
• サブエージェントは既定では自分のスキルを継承しない。使わせたい場合は、カスタムサブエージェントの frontmatter に skills フィールドで明示的に列挙してプリロードする必要がある（Explore・Plan・general-purpose などの組み込みサブエージェントはそもそもプリロードの対象外）。
• トラブルシューティングでまず確認すべきは description の書き方（起動しない問題の大半はここに帰着する）で、構造的な問題の検証には skills-ref のような validator も使える。それ以外の原因は、体感的にはディレクトリ・ファイル名の構造に帰着することが多い。