> ## Documentation Index
> Fetch the complete documentation index at: https://agentskills.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 仕様

> 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)                                      |

<Card>
  **最小例:**

  ```markdown SKILL.md theme={null}
  ---
  name: skill-name
  description: A description of what this skill does and when to use it.
  ---
  ```

  **任意項目を含む例:**

  ```markdown SKILL.md theme={null}
  ---
  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"
  ---
  ```
</Card>

#### `name` field

必須項目 `name`:

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

<Card>
  **有効な例:**

  ```yaml theme={null}
  name: pdf-processing
  ```

  ```yaml theme={null}
  name: data-analysis
  ```

  ```yaml theme={null}
  name: code-review
  ```

  **無効な例:**

  ```yaml theme={null}
  name: PDF-Processing  # uppercase not allowed
  ```

  ```yaml theme={null}
  name: -pdf  # cannot start with hyphen
  ```

  ```yaml theme={null}
  name: pdf--processing  # consecutive hyphens not allowed
  ```
</Card>

#### `description` field

必須項目 `description`:

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

<Card>
  **良い例:**

  ```yaml theme={null}
  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.
  ```

  **悪い例:**

  ```yaml theme={null}
  description: Helps with PDFs.
  ```
</Card>

#### `license` field

任意項目 `license`:

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

<Card>
  **例:**

  ```yaml theme={null}
  license: Proprietary. LICENSE.txt has complete terms
  ```
</Card>

#### `compatibility` field

任意項目 `compatibility`:

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

<Card>
  **例:**

  ```yaml theme={null}
  compatibility: Designed for Claude Code (or similar products)
  ```

  ```yaml theme={null}
  compatibility: Requires git, docker, jq, and access to the internet
  ```

  ```yaml theme={null}
  compatibility: Requires Python 3.14+ and uv
  ```
</Card>

<Note>
  多くのスキルでは `compatibility` は不要です。
</Note>

#### `metadata` field

任意項目 `metadata`:

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

<Card>
  **例:**

  ```yaml theme={null}
  metadata:
    author: example-org
    version: "1.0"
  ```
</Card>

#### `allowed-tools` field

任意項目 `allowed-tools`:

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

<Card>
  **例:**

  ```yaml theme={null}
  allowed-tools: Bash(git:*) Bash(jq:*) Read
  ```
</Card>

### 本文

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

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

```markdown SKILL.md theme={null}
See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
scripts/extract.py
```

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

## Validation

[skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) を使ってスキルを検証できます。

```bash theme={null}
skills-ref validate ./my-skill
```

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