はじめに

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づくりに対する見方が変わる。

参考リンク