仕様

Note

Agent Skills の完全な形式仕様。

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

ディレクトリ構造

スキルは、少なくとも SKILL.md ファイルを含むディレクトリです：

skill-name/
└── SKILL.md          # 必須

スキルをサポートするために、scripts/、references/、assets/ などの 追加ディレクトリ をオプションで含めることができます。

SKILL.md 形式

SKILL.md ファイルは、YAML フロントマターの後に Markdown コンテンツが続く必要があります。

フロントマター（必須）

---
name: skill-name
description: このスキルが何をするか、いつ使用するかの説明。
---

オプションのフィールドを含む場合：

---
name: pdf-processing
description: PDF ファイルからテキストとテーブルを抽出し、フォームに記入し、ドキュメントをマージします。
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---
フィールド必須制約
nameはい最大 64 文字。小文字、数字、ハイフンのみ。ハイフンで始まったり終わったりすることはできません。
descriptionはい最大 1024 文字。空でない。スキルが何をするか、いつ使用するかを説明します。
licenseいいえライセンス名またはバンドルされたライセンスファイルへの参照。
compatibilityいいえ最大 500 文字。環境要件を示します（対象製品、システムパッケージ、ネットワークアクセスなど）。
metadataいいえ追加メタデータのための任意のキー値マッピング。
allowed-toolsいいえスキルが使用してもよい事前承認済みツールのスペース区切りリスト。（実験的）

name フィールド

必須の name フィールド：

  • 1〜64 文字である必要があります
  • 小文字の英数字とハイフン（a-z と -）のみを含むことができます
  • - で始まったり終わったりすることはできません
  • 連続したハイフン（--）を含むことはできません
  • 親ディレクトリ名と一致する必要があります

有効な例：

name: pdf-processing

name: data-analysis

name: code-review

無効な例：

name: PDF-Processing  # 大文字は許可されません

name: -pdf  # ハイフンで始めることはできません

name: pdf--processing  # 連続したハイフンは許可されません

description フィールド

必須の description フィールド：

  • 1〜1024 文字である必要があります
  • スキルが何をするか、いつ使用するかの両方を説明する必要があります
  • エージェントが関連するタスクを特定するのに役立つ特定のキーワードを含める必要があります

良い例：

description: PDF ファイルからテキストとテーブルを抽出し、PDF フォームに記入し、複数の PDF をマージします。PDF ドキュメントを扱う場合や、ユーザーが PDF、フォーム、またはドキュメント抽出について言及する場合に使用してください。

悪い例：

description: PDF の処理を支援します。

license フィールド

オプションの license フィールド：

  • スキルに適用されるライセンスを指定します
  • 短く保つことをお勧めします（ライセンスの名前またはバンドルされたライセンスファイルの名前のいずれか）

例：

license: 専有。LICENSE.txt に完全な条項があります

compatibility フィールド

オプションの compatibility フィールド：

  • 提供されている場合は 1〜500 文字である必要があります
  • スキルに特定の環境要件がある場合にのみ含める必要があります
  • 対象製品、必要なシステムパッケージ、ネットワークアクセスの必要性などを示すことができます

例：

compatibility: Claude Code（または同様の製品）向けに設計

compatibility: git、docker、jq、およびインターネットへのアクセスが必要

ほとんどのスキルには compatibility フィールドは必要ありません。

metadata フィールド

オプションの metadata フィールド：

  • 文字列キーから文字列値へのマップ
  • クライアントは、これを使用して Agent Skills 仕様で定義されていない追加プロパティを保存できます
  • キー名を適度にユニークにして、意図しない競合を避けることをお勧めします

例：

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

allowed-tools フィールド

オプションの allowed-tools フィールド：

  • 事前承認済みのツールのスペース区切りリスト
  • 実験的。エージェントの実装によってこのフィールドのサポートが異なる場合があります

例：

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

本文コンテンツ

フロントマターの後の Markdown 本文にはスキル指示が含まれます。形式の制限はありません。エージェントが効果的にタスクを実行するのに役立つものを何でも書いてください。

推奨セクション：

  • ステップバイステップの指示
  • 入力と出力の例
  • 一般的なエッジケース

エージェントがスキルをアクティブ化することを決定すると、このファイル全体をロードすることに注意してください。長い SKILL.md コンテンツを参照ファイルに分割することを検討してください。

オプションのディレクトリ

scripts/

エージェントが実行できる実行可能コードが含まれます。スクリプトは：

  • 自己完結しているか、依存関係を明確に文書化する必要があります
  • 役立つエラーメッセージを含める必要があります
  • エッジケースを適切に処理する必要があります

サポートされている言語はエージェントの実装によって異なります。一般的なオプションには Python、Bash、JavaScript が含まれます。

references/

エージェントが必要に応じて読むことができる追加のドキュメントが含まれます：

  • REFERENCE.md - 詳細な技術リファレンス
  • FORMS.md - フォームテンプレートまたは構造化データ形式
  • ドメイン固有のファイル（finance.md、legal.md など）

個々の リファレンスファイル に焦点を当ててください。エージェントはこれらをオンデマンドでロードするため、ファイルが小さいほどコンテキストの使用が少なくなります。

assets/

静的リソースが含まれます：

  • テンプレート（ドキュメントテンプレート、設定テンプレート）
  • 画像（図、例）
  • データファイル（検索テーブル、スキーマ）

漸進的開示

スキルは、コンテキストを効率的に使用するために構造化する必要があります：

  1. メタデータ（~100 トークン）：name と description フィールドは、すべてのスキルで起動時にロードされます
  2. 指示（推奨 < 5000 トークン）：完全な SKILL.md 本文は、スキルがアクティブ化されたときにロードされます
  3. リソース（必要に応じて）：ファイル（scripts/、references/、assets/ など）は、必要な場合にのみロードされます

メインの SKILL.md は 500 行未満に保ってください。詳細なリファレンス資料を別のファイルに移動してください。

ファイル参照

スキル内の他のファイルを参照する場合は、スキルルートからの相対パスを使用してください：

詳細については、[リファレンスガイド](references/REFERENCE.md)を参照してください。

抽出スクリプトを実行します：
scripts/extract.py

ファイル参照は SKILL.md から 1 レベル深くに保ってください。深くネストされた参照チェーンを避けてください。

検証

スキルを検証するには、skills-ref 参照ライブラリを使用してください：

skills-ref validate ./my-skill

これにより、SKILL.md フロントマターが有効であり、すべての命名規則に従っているかどうかがチェックされます。