Introduction to Agent Skillsコースのカリキュラムを解説

Anthropic Academy(anthropic.skilljar.com)の「Introduction to agent skills」は、Claude Codeの再利用可能な指示ファイルであるSkillsを、作成から共有・トラブルシューティングまで6レッスンで扱う、登録すると無料と表示されるコースです。登録前のコースページで読めるのは、説明文とレッスン見出しだけです。

そこで本記事は、説明文と見出しを手がかりに、各レッスンが扱う内容をClaude Code公式ドキュメントの該当節と対応づけます。あわせて、claude v2.1.289でclaude plugin validateを動かした出力も載せます。

受講に何が必要か

コースページには「Register | FREE」と出ています。受講にはSkilljarのアカウント登録が必要です。

ページに埋め込まれた構造化データでは、isAccessibleForFreeがfalseです。表示は無料、構造化データは非無料という食い違いがあります。動画や演習の中身は、登録前のページには載っていません。

ページ下部の「Data and Privacy」には、Skilljarが集める情報として、コースの進捗・レッスンの完了状況・クイズの点数・学習時間が挙がっています。この情報は修了証の発行に使うとも書かれています。Skilljar全体の一般的な説明なので、このコースにクイズや修了証があるかどうかまでは決まりません。

アカウントについては、Skilljarが記録するのは学習の進捗だけで、Anthropic ConsoleやClaudeのアカウントとは別に管理される、という説明です。有料資格との違いはAnthropic Academyの全コースと認定資格の学習ルートにあります。

説明文が約束する範囲

説明文の冒頭は「同じ指示を繰り返し貼り付ける代わりに、Claudeに一度教える方法を学ぶ」という趣旨です。前半では、SkillsがCLAUDE.md・hooks・subagentsとどう違うか、SKILL.mdのフロントマターの書き方、確実にトリガーされる説明文の作り方、progressive disclosureによるコンテキストの節約を扱うと書かれています。

後半は、allowed-toolsによるツール制限と、コンテキストを消費せずに動くスクリプトです。続いて、リポジトリへのコミット、プラグイン、enterprise managed settingsによる共有と組織展開、カスタムsubagentへの組み込み、トラブルシューティングが並びます。最後の項目は「トリガーされないスキルから、優先順位の衝突、実行時エラーまで」と書かれており、症状の幅が広いことが分かります。

カリキュラム6レッスンと公式ドキュメントの対応

「Curriculum」欄には6つの見出しが並びます。skillsドキュメントの節を各見出しに近い順に対応づけると次のとおりです。

見出しとの対応づけは、見出しの語からの推定です。コース側はレッスンごとの内容を公開していないため、1対1とは限りません。

レッスン1〜3: どこに置き、何を書き、何を許可するか

Skillsは、SKILL.mdを持つディレクトリです。YAMLフロントマターとMarkdown本文の2部で構成され、フィールドはすべて任意です。推奨されているのはdescriptionだけで、省略すると本文の最初の空でない行が使われます。

保存先は、誰のセッションで読み込まれるかを決めます。

同じ名前のSkillがenterprise・personal・projectにまたがるときは、enterpriseがpersonalに、personalがprojectに優先します。deployが~/.claude/skills/とプロジェクトの両方にあれば、/deployが動かすのは個人のほうです。プラグインのSkillは名前空間が付くので、この衝突には加わりません。

descriptionの長さにも上限があります。descriptionとwhen_to_useを合わせた文字列は、Skill一覧の中で1,536字に切られます。いちばん大事な使いどころを先頭に置く、のが推奨です。上限はskillListingMaxDescCharsで変更でき、/skill-doctorでSkill一覧の消費コストを確認できます。

allowed-toolsは、Skillを呼び出したターンの間だけ、列挙したツールを確認なしで使えるようにします。次のメッセージを送ると付与は消えます。ほかのツールが使えなくなるわけではなく、権限設定は引き続き効きます。

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

SKILL.mdが長くなったら、詳細をreference.mdやexamples.mdに分けて本文から参照させます。SKILL.mdは500行以内に収めるのが目安です。Anthropicのengineering blog(2025年10月16日公開)は、この分割をprogressive disclosure(段階的開示)と呼びます。名前と説明、本文、同梱ファイルの順に、必要な分だけ読み込む仕組みです。三層構造はAgent Skillsとは何かに詳しく書いています。

既存の機能とどう使い分けるか

レッスン4が扱う比較を、公式ドキュメントの定義に沿って表にします。

使いどころの目安はこうです。同じ指示や手順を何度もチャットに貼っているとき、またはCLAUDE.mdの一節が「事実」ではなく「手順」に育ったときに、Skillへ切り出します。Skillの本文は使うまで読み込まれません。長い参考資料も、使わない間はほぼコストになりません。

一度読み込まれた本文は、以降のターンも会話に残ります。1行ごとに、継続的なトークンコストがかかるわけです。ファイルは再読込されないので、全体に効かせたい指針は「編集のたびにテストを走らせる」のように、作業全体に当てはまる形で書きます。

subagentとの組み合わせは2方向ある

説明文は「カスタムsubagentへの組み込み」と書いています。この組み合わせは、逆向きの2種類に分かれています。コースがどちらを指すのかは、見出しからは分かりません。

context: forkのSkillは、既定ではバックグラウンドで動きます。結果を同じターンで待ちたいときはbackground: falseを書きます。この設定にはv2.1.218以降が必要です。-pでの非対話実行などでは、書かなくても結果を待ちます。

共有するときの落とし穴

共有の3段階は、プロジェクト(.claude/skills/をコミット)、プラグイン、managed settingsによる組織配布です。企業配布の実務はAgent Skillsのエンタープライズ配布で扱っています。

読み込みの範囲には、見落としやすい例外があります。~/.claude/skills/にあるSkillは、Coworkやクラウドセッションには届きません。ルーティンは起動のたびに新しいクラウドセッションを始めます。個人Skillだけを置いた状態でルーティンから呼ぶと、Skillが見つからないと報告されます。

届けるには、claude.aiアカウントでSkillを有効にします。クラウドセッションなら、リポジトリの.claude/skills/にコミットする手もあります。Desktopのスケジュールタスクはローカルで動くので、~/.claude/skills/を読み込みます。

サブディレクトリのSkillにも注意が要ります。起動時に読まれるのは、起動したディレクトリからリポジトリルートまでの.claude/skills/です。それより下の階層にあるものは、Claudeがそこのファイルを読むか編集するまで読み込まれず、/メニューにも出ません。

レッスン6を症状から引く

説明文が挙げる症状は、Troubleshootingに5項目あります。そのうち4つを、最初に確かめる順に並べます。

5つ目の「個人Skillが消えた」は、v2.1.280より前の挙動です。~/.claude/skills/にmanifest.jsonがあると、そこに挙がったフォルダが.trash/へ移され、読み込まれなくなりました。消えたフォルダは~/.claude/skills/.trash/で見つかります。

自動圧縮のあとの再読み込みにも上限があります。Claude Codeは、呼び出したSkillそれぞれの先頭5,000トークンを保持し、全体で25,000トークンまでです。多数を呼んだセッションでは、古いSkillが丸ごと落ちることがあります。大事な指示はSKILL.mdの先頭に置きます。

フロントマターの壊れ方を手元で確かめる

フロントマターのYAMLが壊れても、エラーにはなりません。Skillは空のメタデータで読み込まれ、/skill-nameは動いても、Claudeはdescriptionと照合できなくなります。見つける手段がclaude plugin validateで、v2.1.233以降で使えます。

claude v2.1.289で、引用符を閉じ忘れたdescriptionを持つSKILL.mdに対して実行した出力は次のとおりです。

claude plugin validate .claude/skills

✘ Found 1 error:
 
  ❯ frontmatter: YAML frontmatter failed to parse: YAML Parse error: Unexpected character. At runtime this skill loads with empty metadata (all frontmatter fields silently dropped).
 
✘ Validation failed

終了コードは1でした。--helpによると、--strictは警告もエラー扱いにして終了コード1を返します。--helpの説明は未知のフィールドも対象と読めますが、実測では通りました。

ただし、フィールド名の綴り違いは別です。disable-model-invocationをdisable-model-invokationと書いたSkillだけを置いて--strictを付けても、結果は「Validation passed」でした。ドキュメントの記述どおり、未知のフィールドは黙って無視されます。

綴りを間違えると、手動専用のつもりのSkillがClaudeに自動で呼ばれる状態になります。綴りはvalidateでは拾えないので、フィールド名の表と見比べる必要があります。

最初の一歩を試す

公式が示す最小のSkillは、未コミットの差分を要約するものです。

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.

!`git diff HEAD`の行は、Claudeが読む前にClaude Codeがコマンドを実行し、出力で置き換えます。Claudeには、最新の差分が埋まった状態で指示が届きます。

まとめ

コースの6レッスンは、Claude Codeが実装するSkillsの機能範囲と、公式ドキュメントの節立てにほぼ重なります。すでにSKILL.mdを書いた人は、レッスン4の使い分けとレッスン6の切り分けから入れば、足りない部分が見つかります。Claude CodeでSkillを書いて動かすなら、保存したあとにclaude plugin validateでフロントマターのYAMLを検査する手があります。