はじめに
X（Twitter）で面白い投稿を見かけた。
「AnthropicのSkillsガイドPDFをそのままClaude Codeに投げて、オリジナルのskill-creatorを作ると精度と品質が爆上がりする」というものだ。
自分もAgent Skillsを本格的に使い始めてから数ヶ月が経つ。この投稿を見て、「試してみよう」という気持ちになったのは事実だ。ただ、実際にやってみて気づいたことがある。この情報は半分正しいのだが、重要な部分が抜けている。
そもそもAgent Skillsとは何か、なぜコンテキスト管理に有効なのかを整理したうえで、skillをより高品質に作るために公式が提供しているskill-creatorを使うべき理由を述べる。
Agent Skillsとは何か
まず「コンテキスト」を理解する
Claude CodeなどのAIエージェントには、コンテキストウィンドウと呼ばれる「一度に処理できる情報量の上限」がある。人間で例えると、「今この瞬間に頭の中に入れておける情報の枠」だ。
コンテキストには以下がすべて含まれる。
- 会話履歴（これまでのやり取り）
- システムプロンプト（エージェントへの基本指示）
- 読み込んでいるファイルやドキュメント
- ツールの定義情報
- インストール済みのskillsの情報
コンテキストが埋まると、古い情報が押し出されたり、処理が遅くなったり、応答の品質が下がったりする。コンテキストは有限の資源であり、節約することが品質維持に直結する。
Agent Skillsはコンテキストをどう節約するか
Agent Skillsはプログレッシブ・ディスクロージャー（段階的開示）という設計原則に基づいている。
通常の方法でClaude Codeに「毎回この手順でPDFを処理してほしい」と伝えようとすると、詳細な指示をシステムプロンプトや会話内に毎回書く必要がある。これは大量のコンテキストを消費する。
Agent Skillsを使うと、情報の読み込みが3段階に分かれる。
第1段階（常時ロード）：name と description のみ
→ コンテキストへの影響は最小限
第2段階（skill起動時のみ）：SKILL.md の本文
→ 関連するタスクが来たときだけ読み込む
第3段階（必要に応じて）：scripts/, references/, assets/ 内のファイル
→ Claudeが判断して必要なものだけ参照
「PDFを扱うタスクのときだけPDF操作の詳細手順が読み込まれる」という仕組みだ。関係のない作業中はコンテキストを圧迫しない。
Anthropicのエンジニアリングブログでも言及されているように、この設計によってskillにバンドルできる情報量は事実上無制限になる。コンテキストウィンドウの節約と、豊富な専門知識の両立を実現している。
Agent Skillsの基本構造
skillは以下のようなフォルダ構成だ。
my-skill/
├── SKILL.md # 必須：YAMLフロントマター + Markdown指示
├── scripts/ # 任意：Pythonスクリプト等
├── references/ # 任意：詳細ドキュメント
└── assets/ # 任意：テンプレートやフォント等
SKILL.md の最低限の構成はこれだけだ。
---
name: my-skill-name
description: このskillが何をするか、いつ使うかを記述する
---
# My Skill
ここにClaudeへの指示を書く
フロントマターの description がClaudeがskillを使うかどうかを判断する唯一の手がかりだ。ここの書き方が品質を大きく左右する。
よく見かける誤解：「PDFだけ渡せばskill-creatorが作れる」
話題の投稿が参照しているのは、AnthropicがHubSpotで公開している「The Complete Guide to Building Skills for Claude」というPDFだ。
このPDFは優れた教材だ。skillの概念・設計原則・フォルダ構成ルール・MCP連携パターンなどが体系的にまとめられており、「skillとは何か」を学ぶには十分な内容だ。
しかし、このPDFだけを元にskill-creatorを作ろうとすると、重要な部分が抜け落ちる。
PDFがカバーしていない領域
実際にAnthropicが公開している公式skill-creator（anthropics/skillsリポジトリ）と比較すると、PDFには以下の内容がほぼ記載されていない。
evalパイプライン（品質評価の仕組み）
公式skill-creatorの中核は、skillを作ったあとにその品質を測定・改善するための本格的なevalループだ。PDFのテスト解説は「手動でクエリを試す」「スクリプト化する」程度にとどまっている。
サブエージェントによる自動評価
公式では以下の3つのサブエージェントが連携する。テスト実行自体はskill-creator本体がサブエージェントをspawnする形で行われる。
-
grader：アサーション（期待する動作）に対して各実行を評価 -
comparator：どちらのバージョンが良いかをブラインドA/B比較 -
analyzer：ベンチマーク結果から見えにくいパターンを抽出
descriptionの「undertrigger問題」とその対策
公式SKILL.mdには明確に記載されている知見がPDFには書かれていない。
Claudeはskillをundertriggerする（使うべき時に使わない）傾向がある。だからdescriptionを少し"pushy"に書くべきだ。
たとえば「ダッシュボードの作り方」ではなく、「ダッシュボードの作り方。ユーザーがダッシュボード、データ可視化、社内メトリクスに言及したときは必ずこのskillを使うこと」のように、積極的なトリガー条件を書くことが推奨されている。
descriptionの最適化フロー
公式では、skill作成後に「should-triggerクエリ」と「should-not-triggerクエリ」を20個ずつ作り、専用スクリプトでdescriptionを体系的に最適化するフローが存在する。PDFにはこのフローがない。
SKILL.mdのサイズ制限に関する矛盾
PDFのChapter 5では「SKILL.mdは5,000語以内にせよ」と書かれている（SKILL.mdの実際の長さについては別途500行という指標もある）。
ところが、公式skill-creator自身のSKILL.mdは、evalループの詳細手順・環境別の挙動の違い・スキーマ仕様など膨大な内容を含んでおり、5,000語を超えていることが確認されている。
これはAnthropicが「5,000語」をハードな制限ではなく、パフォーマンスが下がったときのトラブルシューティング上の目安として書いていたからだ。プログレッシブ・ディスクロージャーの設計上、SKILL.mdに詰め込める量は事実上無制限のため、PDFがその点を「上限ルール」のように書いてしまったのは不正確だった。
正しいアプローチ：公式skill-creatorを使う
なぜ公式skill-creatorが優れているか
公式skill-creator（anthropics/skillsリポジトリのskills/skill-creator/）は、PDFの内容をカバーしたうえで、以下を追加している。
充実したテスト・評価サイクル
skillを作った後、以下のループを回す。
テストケース設計 → 並列実行（with_skill / without_skill）
→ grader評価 → benchmark集計 → HTMLビューアで確認
→ ユーザーフィードバック → skillを改善 → 繰り返し
単に「動くか確認する」レベルではなく、skillありとなしで定量的に比較できる点が大きな違いだ。
フォルダ構成の実例
公式skill-creatorのフォルダ構成は以下だ。
skill-creator/
├── SKILL.md
├── agents/
│ ├── grader.md
│ ├── comparator.md
│ └── analyzer.md
├── eval-viewer/
├── references/
│ └── schemas.md
├── scripts/
│ ├── aggregate_benchmark.py
│ ├── run_eval.py
│ ├── improve_description.py
│ └── package_skill.py
└── assets/
agents/ と eval-viewer/ はPDFには記載のない独自のディレクトリだ。skillが「作って終わり」ではなく「測定して改善する」ものであるという哲学が構造に表れている。
環境ごとの使い分けが明示されている
公式SKILL.mdには、Claude.ai / Claude Code / Cowork それぞれで何ができて何ができないかが明記されている。PDFにはこの環境差異の記載がない。（出典: skill-creator SKILL.md）
| 機能 | Claude Code | Claude.ai | Cowork |
|---|---|---|---|
| サブエージェント並列実行 | ✅ | ❌ | ✅ |
| descriptionスクリプト最適化 | ✅ | ❌ | ✅ |
| evalビューアのブラウザ起動 | ✅ | ❌ |
--staticフラグで代替 |
| パッケージング（.skillファイル生成） | ✅ | ✅ | ✅ |
使い方
Claude Codeに公式skill-creatorをインストールするには、anthropics/skillsリポジトリからskill-creatorをダウンロードし、Claude Codeのskillsディレクトリに配置する。インストール後は以下のように使える。
Use the skill-creator skill to help me build a skill for [作りたいskillの内容]
PDFの正しい使い方
PDFには得意な用途がある。以下の場面では依然として優秀なリファレンスだ。
- skillの概念・設計原則を学ぶ教材として（プログレッシブ・ディスクロージャーの理解など）
- MCP連携パターンの参考として（Sequential, Multi-MCP, Iterativeなど5つのパターンが整理されている）
- 配布・GitHubでのホスト方法の参考として
- 組織レベルでのデプロイ方法（Admin workspace-wide展開）の参考として
おすすめは「PDFで概念を学んでから、公式skill-creatorで実装する」という使い分けだ。
PDFだけをClaude Codeに渡してskill-creatorを作らせると、evalパイプラインやサブエージェント構成が抜けた「不完全なskill-creator」ができあがる。公式のものと比べると、品質の測定・改善サイクルが大幅に弱くなる。
まとめ
| 観点 | PDFのみ | 公式skill-creator |
|---|---|---|
| skillの概念理解 | ✅ 十分 | ✅ |
| フォルダ構成・命名規則 | ✅ 十分 | ✅ |
| MCP連携パターン | ✅ 詳しい | 記載なし |
| descriptionのundertrigger対策 | ❌ 記載なし | ✅ |
| evalパイプライン | ❌ 概念のみ | ✅ 本格的 |
| with/without比較評価 | ❌ | ✅ |
| ブラインドA/Bテスト | ❌ | ✅ |
| 環境別の挙動の違い | ❌ | ✅ |
| SKILL.mdサイズ制限 | △ 5,000語と記載（実態と乖離） | 数値制限なし |
PDFは「skillを理解するための本」、公式skill-creatorは「skillを作り、測定し、改善するためのツール」だ。どちらか一方ではなく、両方を組み合わせて使うのが最も効果的だ。
「PDFを投げるだけ」から一歩踏み込んで、公式のevalループを回してみると、skillづくりに対する見方が変わる。