ai-docs

Equipping agents for the real world with Agent Skills

Properties1
tagsskills, agents, context, progressive-disclosure, mcp, code-execution

8 min read

一行要約

Skill の設計思想は progressive disclosure（名前と説明 → SKILL.md 本体 → 参照ファイル、の3段階）であり、これによって「skill に束ねられる context の量は事実上無制限になる」というのが最大の主張。

要点

何を解こうとしているか

Claude is powerful, but real work requires procedural knowledge and organizational context. Claude は強力だが、実際の仕事には手続き的な知識と組織固有の文脈が要る。

モデルの賢さではなく、手順知識と組織固有の文脈が足りない、という問題設定。

Instead of building fragmented, custom-designed agents for each use case, anyone can now specialize their agents with composable capabilities. ユースケースごとに断片的な専用エージェントを作るのではなく、誰もが組み合わせ可能な能力によってエージェントを専門化できるようになった。

Skill は「エージェントが動的に発見してロードできる、指示・スクリプト・リソースを整理したフォルダ」。

Building a skill for an agent is like putting together an onboarding guide for a new hire. エージェントのために skill を作ることは、新しく入る人のためのオンボーディング資料をまとめることに似ている。

skill の解剖

  • SKILL.md を含むディレクトリ
  • SKILL.md は name と description を必須メタデータとする YAML frontmatter で始まらなければならない
  • 起動時、エージェントは全 skill の name と description を system prompt に事前ロードする

pay special attention to the name and description of your skill. Claude will use these when deciding whether to trigger the skill. skill の name と description には特に注意を払え。Claude は skill を起動するかどうかの判断にこれらを使う。

progressive disclosure（中核の設計原則）

the core design principle that makes Agent Skills flexible and scalable Agent Skills を柔軟かつスケールさせている、中核の設計原則

段階何がロードされるかいつ
1name と description起動時（全 skill 分）
2SKILL.md 全文関連があると判断されたとき
3参照されている追加ファイル必要になったとき

Like a well-organized manual that starts with a table of contents, then specific chapters, and finally a detailed appendix. よく整理されたマニュアルが、目次から始まり、次に個別の章、最後に詳細な付録へと進むのと同じである。

context window との関係 — なぜ「事実上無制限」なのか

Agents with filesystem and code execution tools don’t need to read the entirety of a skill into their context window when working on a particular task. This means that the amount of context that can be bundled into a skill is effectively unbounded. ファイルシステムとコード実行のツールを持つエージェントは、特定のタスクに取り組む際に skill の全体を context window へ読み込む必要がない。つまり、skill に同梱できる context の量には事実上上限がない。

ここが核心。skill はファイルシステム上に置かれ、エージェントはファイルツールで必要な部分だけ読む。だから skill の総量は context window に縛られない。

code execution との関係

PDF skill の例が具体的でわかりやすい。

  • コアの SKILL.md から reference.md と forms.md を参照する形で追加ファイルを束ねる
  • 作者はコアを痩せさせておき、「フォームを埋めるときにだけ Claude が forms.md を読む」ことを信頼する
  • PDF を読んで全フォームフィールドを抽出する Python スクリプトを事前に書いて同梱する。Claude は、スクリプト自体も PDF 自体も context にロードせずにこれを実行できる

スクリプトを同梱することは、単なる利便ではなく context 戦略である、という点がこの記事の重要な含意。

他の手段との違い

対象違い
単体で作り込んだエージェント（monolithic agent）skill は composable / scalable / portable な形でドメイン知識を装備させる
MCPskill は MCP を補完する。MCP が接続とツールを与えるのに対し、skill はより複雑なワークフローを教える

単純さそのものが価値

Skills are a simple concept with a correspondingly simple format. This simplicity makes it easier for organizations, developers, and end users to build customized agents. skill は単純な概念であり、形式もそれに見合って単純である。この単純さゆえに、組織・開発者・エンドユーザーがカスタマイズしたエージェントを作りやすくなっている。

セキュリティ上の注意

Skill はスクリプトを含み、それがエージェントによって実行されうるため、原典はセキュリティに独立した節を割いている。信頼できない skill を導入することは、信頼できないコードを実行することと同義という前提で扱う必要がある。

そのまま使える具体例

skill ディレクトリの構造（PDF skill の形）:

pdf/
├── SKILL.md         # コアは痩せさせる。name と description が最重要
├── reference.md     # 必要時にだけ読まれる
├── forms.md         # フォームを埋めるときにだけ読まれる
└── scripts/
    └── extract_fields.py   # 実行するだけ。スクリプトも PDF も context に載らない

frontmatter の最小要件:

---
name: pdf
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

原典で言及されている関連文書

未取得の派生リンク

グラフビュー

バックリンク