フロントマターのフィールド
必須は 2 つ、残りは任意です。以下の制約はバリデータが実際に適用するもので、名前に大文字が入っているというような、一見些細に見える理由でスキルが弾かれるのはこのためです。
| フィールド | 必須 | 制約 |
|---|---|---|
name | 必須 | 1 to 64 characters. Lowercase a-z, 0-9 and hyphens only. No leading or trailing hyphen, no consecutive hyphens. Must match the parent directory name. |
description | 必須 | 1 to 1024 characters. Must say what the skill does and when to use it, with keywords an agent can match against a task. |
license | 任意 | A license name, or the name of a bundled license file. Recommended to keep it short. |
compatibility | 任意 | Up to 500 characters. Only include it when the skill has real environment requirements, such as a target product, system packages or network access. |
metadata | 任意 | A map of string keys to string values for anything the spec does not define. Use distinctive key names to avoid collisions. |
allowed-tools 実験的 | 任意 | A space separated string of pre-approved tools, for example Bash(git:*) Read. Support varies between agent implementations. |
ディレクトリ構成
必須は SKILL.md だけです。他のディレクトリは慣習であり、大きな資料を必要になるまでエージェントの文脈の外に置くために存在します。
| パス | 必須 | 役割 |
|---|---|---|
SKILL.md | 必須 | Frontmatter plus the instructions themselves. |
scripts/ | 任意 | Executable code the agent can run. |
references/ | 任意 | Documentation loaded on demand, not up front. |
assets/ | 任意 | Templates, images, data files. |
段階的な読み込みと文脈の予算
スキルは 3 段階で読み込まれます。大きなスキル群が実用になるかどうかはここで決まります。第 1 段階は、導入済みのすべてのスキルについて毎回支払うからです。
| 段階 | コスト | 読み込み | 内容 |
|---|---|---|---|
| Metadata | around 100 tokens | Loaded at startup for every installed skill | name and description only |
| Instructions | under 5,000 tokens recommended | Loaded when the skill is activated | the whole SKILL.md body |
| Resources | as needed | Loaded only when the task requires them | files under scripts/, references/ and assets/ |
覚えておく価値のある規則
- Keep SKILL.md under 500 lines and move detail into references/.
- Keep file references one level deep from SKILL.md.
- The name must match the directory name, so renaming a skill means renaming both.
- Most skills do not need compatibility. Add it only when the environment really matters.
公開前に検証する
リファレンス実装のライブラリはフロントマターと命名規則を検査します。これがないと、単に一度も読み込まれないスキルという形で誤りが表面化します。
skills-ref validate ./my-skill出典
このページの制約はすべて、記載日に読んだ公開仕様に基づきます。本番で特定のフィールドに依存する前に、必ず出典を確認してください。
Agent Skills specification 最終確認日: 2026-08-05