agentskills

Agent Skills — オープン仕様（agentskills.io）のビジュアル解説

1 — 概要
何か

Agent Skills は、エージェントに「手順・スクリプト・参照資料」を束ねて渡すための シンプルなオープンフォーマット。ルートに SKILL.md があるフォルダが 1 スキル。仕様・ドキュメント・参照実装（skills-ref/）は agentskills/agentskills で公開されている。

SKILL.md 必須エントリ
3 開示の段階
Apache 2 コードライセンス
CC-BY 4.0 ドキュメント
本ページと docs/agent-skills.html の違い: こちらは agentskills.io 公式リポジトリの解説。別資料の「Agent Skills」エンジニアリングスキル集（19 スキル・6 フェーズ）とは別プロジェクト。
2 — スキルフォルダ構成
ディレクトリ

最小構成は SKILL.md のみ。スクリプト・参照・テンプレは任意ディレクトリに分ける。

my-skill/
├── SKILL.md          # 必須: メタデータ + 指示本文
├── scripts/          # 任意: 実行可能コード
├── references/       # 任意: 追加ドキュメント
└── assets/           # 任意: テンプレ・画像など

仕様上、ルート直下に追加のファイルやディレクトリを置いてもよい。参照パスはスキルルートからの 相対パス（深いネストの参照チェーンは避ける）。

3 — Progressive disclosure
コンテキストを段階的に載せる

常に全文を載せるのではなく、タスクに応じて読み込むことで、エージェントの応答を速く保つ。

STEP 1
Discovery
起動時は各スキルの name と description だけを読み、関連しそうかどうかを判定する。
STEP 2
Activation
タスクが説明に合致したら SKILL.md 全文をコンテキストに載せる。
STEP 3
Execution
必要に応じて references/ や scripts/ を読む・実行する。
flowchart LR M[メタデータのみ] -->|マッチ| F[SKILL.md 全文] F --> R[参照ファイル / スクリプト]
目安トークン（仕様の推奨）
段階内容目安
メタデータname + description約 100 トークン
本文SKILL.md の Markdown5000 トークン未満推奨
リソース参照・スクリプト・assets必要なときだけ

メインの SKILL.md は 500 行超えそうなら、詳細を references/ に分割するのが推奨。

4 — SKILL.md フロントマター
フィールド一覧（抜粋）

先頭は YAML。続けて Markdown 本文。必須は name と description。

フィールド必須制約・意味
nameはい最大 64 文字。a-z・数字・ハイフンのみ。連続ハイフン不可。親ディレクトリ名と一致。
descriptionはい1〜1024 文字。何をするかといつ使うか（エージェントが選びやすいキーワード）を書く。
licenseいいえライセンス名または同梱ファイルへの参照。
compatibilityいいえ最大 500 文字。想定プロダクト・パッケージ・ネットワーク要件など。
metadataいいえ任意のキー・値（文字列）。実装側の追加プロパティ用。
allowed-toolsいいえ事前承認ツールのスペース区切り（実験的）。
5 — skills-ref（参照ライブラリ）
Python CLI / API

リポジトリ内 skills-ref/ は 検証・プロパティ読取・プロンプト用 XML 生成向けの参照実装。README では本番利用は想定していない旨が記載されている。

skills-ref validate path/to/skill
skills-ref read-properties path/to/skill   # JSON 出力
skills-ref to-prompt path/to/skill-a path/to/skill-b   # <available_skills> XML
貢献について: CONTRIBUTING では参照ライブラリのコードコントリビューションは当面受け付けていない場合がある。不具合報告やフィードバックは Issue / Discussion へ。
6 — リポジトリ構成
agentskills/agentskills
  • docs/ — Mintlify 製の公式ドキュメント（mint dev でローカルプレビュー）。
  • skills-ref/ — Python パッケージ（uv / pip でインストール可）。
  • ライセンス — コードは Apache 2.0、ドキュメントは CC-BY 4.0（リポジトリ README・CONTRIBUTING に準拠）。
公式