ai-docs

Agent Skills

Properties1
tagsskills, context, progressive-disclosure, api, claude-code, security

8 min read

一行要約

progressive disclosure の3段階とそれぞれのトークンコストが数字で示されている唯一の文書 — Level 1 は skill あたり約100トークン、Level 2 は 5k 未満、Level 3 は読むまでゼロ。だから「skill をいくつ入れても context のペナルティがない」。

要点

3段階の progressive disclosure

Levelいつロードされるかトークンコスト内容
Level 1: Metadata常に（起動時）skill あたり約 100 トークンfrontmatter の name と description
Level 2: Instructionsskill が発火したとき5k トークン未満SKILL.md の本文
Level 3+: Resources必要になったときアクセスするまでゼロ同梱ファイル。参照ファイルは読まれると context に入る。スクリプトは bash で走り、出力だけが context に入る

This lightweight approach means you can install many Skills without context penalty: until a Skill is triggered, only its name and description occupy context. この軽量な仕組みのおかげで、context のペナルティなしに多数の skill を入れられる。skill が起動されるまでは、その名前と description だけが context を占める。

アーキテクチャ — なぜ「実質無制限」なのか

skill は仮想マシン上のディレクトリとして存在し、Claude は普通の bash コマンドでそれを読む。

  • on-demand file access — 数十の参照ファイルを含む skill でも、タスクに必要な1ファイルだけがロードされる。残りはファイルシステム上に留まりトークンゼロ
  • efficient script execution — validate_form.py を走らせても、スクリプトのコード自体は context に入らない。出力（“Validation passed” など)だけがトークンを消費する。Claude に同等のコードをその場で書かせるより遥かに効率的
  • no practical limit on bundled content — 使わなければコストゼロなので、包括的な API ドキュメント、大きなデータセット、大量の例を同梱できる

実際のロードの流れ（pdf-processing skill の例）:

  1. 起動時: system prompt に pdf-processing - Extract text and tables from PDF files... が入る
  2. ユーザー: “Extract the text from this PDF and summarize it”
  3. Claude: bash: cat pdf-processing/SKILL.md → 指示が context に入る
  4. Claude が判断: フォーム記入は不要なので FORMS.md は読まない
  5. Claude が実行

SKILL.md の要件

必須は name と description の2つだけ。

フィールド制約
name最大64文字、小文字・数字・ハイフンのみ、XML タグ不可、予約語 “anthropic” / “claude” 不可
description空でないこと、最大1024文字、XML タグ不可

The description is what Claude matches your request against when determining whether to trigger the Skill, so it must say both what the Skill does and when to use it. description は、skill を起動するかを判断するときに Claude があなたの依頼と突き合わせる対象である。したがって、その skill が何をするかと、いつ使うべきかの両方を述べなければならない。

製品ごとの違い（最も実務的な表）

Claude APIClaude Codeclaude.ai
pre-built skill（pptx/xlsx/docx/pdf）✓✗（ただし Claude API skill は同梱）✓
custom skill の置き場Skills API（/v1/skills）でアップロードファイルシステム（~/.claude/skills/ または .claude/skills/）Settings > Features から zip でアップロード
共有範囲workspace 全体個人 or プロジェクト（plugin でも共有可）個人のみ。組織全体の集中管理は不可
ネットワークアクセスなしフルアクセス（ユーザーの PC の他のプログラムと同じ）ユーザー/管理者の設定次第で full / partial / none
実行時のパッケージインストール不可（プリインストール済みのみ）可（ただしグローバルインストールは非推奨）—

Custom Skills do not sync across surfaces. Skills uploaded to one surface are not automatically available on others. **カスタムの skill は、利用面をまたいで同期されない。**ある面にアップロードした skill が、他の面で自動的に使えるようになることはない。

API での前提条件: code execution ツール（skill はそのコンテナで走る）と beta header skills-2025-10-02。Files API を使うなら files-api-2025-04-14 も。

セキュリティ（独立した節がある）

Use Skills only from trusted sources: those you created yourself or obtained from Anthropic. A malicious Skill can direct Claude to invoke tools or execute code in ways that don’t match the Skill’s stated purpose. skill は信頼できる出所のもの、すなわち自分で作ったか Anthropic から入手したものだけを使え。悪意ある skill は、その skill が掲げた目的と一致しない形で、Claude にツールを呼ばせたりコードを実行させたりできる。

確認すべき点:

  • 同梱ファイルをすべて監査する — SKILL.md、スクリプト、画像、その他のリソース。予期しないネットワーク呼び出し、ファイルアクセスパターン、目的に合わない操作を探す
  • 外部ソースを取りに行く skill は特にリスクが高い — 取得したコンテンツに悪意ある指示が含まれうる。信頼できる skill でも外部依存が時間とともに侵害されうる
  • ツールの悪用（ファイル操作、bash、コード実行）
  • データの露出

Treat like installing software.

Agent Skills は ZDR の対象外。

そのまま使える具体例

frontmatter の最小形:

---
name: pdf-processing
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.
---

skill の骨格:

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---
 
# Your Skill Name
 
## Instructions
[Clear, step-by-step guidance for Claude to follow]
 
## Examples
[Concrete examples of using this Skill]

Level 2 の本文（参照を1階層だけ張る）:

# PDF Processing
 
## Quick start
 
Use pdfplumber to extract text from PDFs:
 
```python
import pdfplumber
 
with pdfplumber.open("document.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```
 
For advanced form filling, see [FORMS.md](FORMS.md).

ディレクトリ構成:

pdf-processing/
├── SKILL.md (main instructions)
├── FORMS.md (form-filling guide)
├── REFERENCE.md (detailed API reference)
└── scripts/
    └── fill_form.py (utility script)

Claude Code での置き場:

~/.claude/skills/<name>/SKILL.md    個人
.claude/skills/<name>/SKILL.md      プロジェクト

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

未取得の派生リンク

グラフビュー

バックリンク