仕様

Agent Skills 形式の完全仕様。

このドキュメントは Agent Skills 形式を定義します。

​

ディレクトリ構造

スキルは、最低限 SKILL.md を含むディレクトリです。

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Optional: additional files or directories

​

SKILL.md 形式

SKILL.md は YAML frontmatter と Markdown 本文で構成します。

​

Frontmatter

Field	Required	Constraints
name	Yes	Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen.
description	Yes	Max 1024 characters. Non-empty. Describes what the skill does and when to use it.
license	No	License name or reference to a bundled license file.
compatibility	No	Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.).
metadata	No	Arbitrary key-value mapping for additional metadata.
allowed-tools	No	Space-delimited list of pre-approved tools the skill may use. (Experimental)

最小例:

SKILL.md

---
name: skill-name
description: A description of what this skill does and when to use it.
---

任意項目を含む例:

SKILL.md

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

​

name field

必須項目 name:

• 1-64 文字
• 小文字の英数字とハイフン（a-z と -）のみ
• 先頭・末尾に - は不可
• -- は不可
• 親ディレクトリ名と一致

有効な例:

name: pdf-processing

name: data-analysis

name: code-review

無効な例:

name: PDF-Processing  # uppercase not allowed

name: -pdf  # cannot start with hyphen

name: pdf--processing  # consecutive hyphens not allowed

​

description field

必須項目 description:

• 1-1024 文字
• スキルの機能と利用タイミングを説明する
• エージェントが関連タスクを判定しやすい具体的キーワードを含める

良い例:

description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

悪い例:

description: Helps with PDFs.

​

license field

任意項目 license:

• スキルに適用されるライセンスを指定
• 短い表現を推奨

例:

license: Proprietary. LICENSE.txt has complete terms

​

compatibility field

任意項目 compatibility:

• 指定する場合は 1-500 文字
• 特定環境要件がある場合のみ記載を推奨
• 対応製品、必要パッケージ、ネットワーク要件などを示せる

例:

compatibility: Designed for Claude Code (or similar products)

compatibility: Requires git, docker, jq, and access to the internet

compatibility: Requires Python 3.14+ and uv

多くのスキルでは compatibility は不要です。

​

metadata field

任意項目 metadata:

• 文字列キーと文字列値のマップ
• 仕様で定義されていない追加情報を保持できる

例:

metadata:
  author: example-org
  version: "1.0"

​

allowed-tools field

任意項目 allowed-tools:

• 事前承認されたツールのスペース区切りリスト
• Experimental。実装ごとに対応状況が異なる

例:

allowed-tools: Bash(git:*) Bash(jq:*) Read

​

本文

frontmatter 以降の Markdown 本文にスキル指示を記述します。形式の制約はありません。

推奨セクション:

• 手順
• 入出力例
• 典型的なエッジケース

長い内容は参照ファイルへ分割してください。

​

Optional directories

​

scripts/

エージェントが実行できるコードを配置します。スクリプトは以下を満たすべきです。

• 自己完結、または依存関係を明記
• 分かりやすいエラーメッセージ
• エッジケースへの対応

​

references/

必要時に読み込む追加ドキュメントを配置します。

• REFERENCE.md
• FORMS.md
• 分野別ファイル（finance.md、legal.md など）

​

assets/

静的リソースを配置します。

• テンプレート
• 画像
• データファイル

​

Progressive disclosure

スキルはコンテキスト効率を意識して設計してください。

1. Metadata: 起動時に name と description を全スキル分読み込み
2. Instructions: 有効化時に SKILL.md 本文全体を読み込み
3. Resources: scripts/、references/、assets/ などを必要に応じて読み込み

SKILL.md は 500 行未満を目安にし、詳細は別ファイルへ分割してください。

​

File references

スキル内の他ファイル参照は、スキルルートからの相対パスを使用します。

SKILL.md

See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
scripts/extract.py

SKILL.md から 1 段程度の浅い参照構造を推奨します。

​

Validation

skills-ref を使ってスキルを検証できます。

skills-ref validate ./my-skill

このコマンドは SKILL.md frontmatter の妥当性と命名規則をチェックします。