---
name: write-skill
description: エージェントのスキルを書きます。ユーザーが新しいスキルを作りたい、書きたいときに使います。
---

# エージェントのスキルを作る

## 進め方

1.  必要なことを確認する - ユーザーに次のことを聞きます：
    -   このスキルは、どのような仕事や分野を対象にしていますか？
    -   具体的にどのような場面（ユースケース）で使いますか？
    -   実行できるスクリプト（プログラム）が必要ですか？ それとも手順の指示だけで十分ですか？
    -   参考にする資料などはありますか？

2.  スキルの下書きを作る - 次のものを用意します：
    -   短くてわかりやすい指示を書いた SKILL.md
    -   内容が500行を超える場合に使う、より詳しい説明を書いた別の参考ファイル
    -   決まった手順で処理を行う必要がある場合に使う、便利なスクリプト

3.  ユーザーと確認する - 下書きを見せて、次のことを聞きます：
    -   これで使いたい場面をカバーできていますか？
    -   足りないことや、わかりにくいところはありませんか？
    -   もっと詳しく書いた方がよい部分や、逆に短くした方がよい部分はありますか？

## スキルの構成（ファイルやフォルダの作り方）

```text
skill-name/
├── SKILL.md        # 主な指示（必ず作ります）
├── REFERENCE.md    # 詳しい説明（必要な場合のみ）
├── EXAMPLES.md     # 使い方の例（必要な場合のみ）
└── scripts/        # 便利なスクリプト（必要な場合のみ）
    └── helper.js
```

## スキルスイート（複数のスキルをまとめる方法）

**スキルスイート**とは、関連するいくつかの「サブスキル（細かい作業手順）」を1つのフォルダにまとめたものです。複雑な作業や、大きなシステム全体（例：`iris` スキル）を1つの名前でまとめたいときに使います。

### 構成（フォルダの作り方）

```text
skill-suite-name/
├── SKILL.md        # サブスキルの一覧（インデックス）となるファイル（必須）
├── sub-skill-1.md  # サブスキルの具体的な手順
├── sub-skill-2.md  # サブスキルの具体的な手順
└── scripts/        # 共通で使うスクリプトなど（必要な場合のみ）
```

### argument-hint

スキルスイートの場合、フロントマターの `argument-hint` は次のようにします。

```yaml
argument-hint: "<subskill> [<arguments...>]"
```

### 主な SKILL.md の書き方

スキルスイートの主となる `SKILL.md` は、サブスキルへの案内板（インデックス）として機能します。どのファイルにどんな手順が書かれているかを、次のような表形式で整理します。

| サブスキル名 | ファイル名 | 説明 |
| :--- | :--- | :--- |
| **sub-skill-1** | [sub-skill-1.md](./sub-skill-1.md) | このサブスキルが何をするかの簡単な説明。 |
| **sub-skill-2** | [sub-skill-2.md](./sub-skill-2.md) | このサブスキルが何をするかの簡単な説明。 |

## SKILL.md のテンプレート

```md
---
name: スキル名
description: スキルでできることの簡単な説明。［特定のきっかけ］のときに使います。
argument-hint: <必須の引数> [任意の引数]  # （必要な場合のみ）
---

# スキル名

## クイックスタート（すぐに始める方法）

［最も簡単な動く例］

## ワークフロー（手順）

［複雑な作業のための、チェックリスト付きの段階的な手順］

## 高度な機能

［別のファイルへのリンク：[REFERENCE.md](REFERENCE.md) を見てください］
```

## 引数ヒント（argument-hint）のルール（任意）

フロントマターにある `argument-hint` は省略可能です。そのスキルを実行するときにどのような情報（引数）を渡せばよいかを示すものです。

-   **必ず指定するもの**（必須）は、山かっこ `<...>` で囲みます。
-   **指定しなくてもよいもの**（任意）は、角かっこ `[...]` で囲みます。

**例**:

```yaml
argument-hint: <document> [target-language]
```

## 説明文（description）のルール

説明文（description）は、エージェントがどのスキルを読み込むか決めるときに**唯一確認する情報**です。インストールされているすべてのスキルと一緒に、システムプロンプトの中に表示されます。エージェントは説明文を読み、ユーザーの要望に合ったスキルを選びます。

**目標**: エージェントが次の2つのことを判断できるだけの、十分な情報を与えること：

1.  このスキルで何ができるか
2.  どのようなとき（特定のキーワード、文脈、ファイルの種類など）にこのスキルを使うべきか

**書き方**:

-   最大1024文字まで
-   三人称（客観的な視点）で書くこと
-   最初の文：何ができるか
-   2番目の文：「［特定のきっかけ］のときに使います。」

**良い例**:

```text
PDFファイルからテキストや表を抜き出し、フォームに入力し、文書を結合します。PDFファイルを扱うときや、ユーザーがPDF、フォーム、または文書の抽出について言及したときに使います。
```

**悪い例**:

```text
文書の処理を助けます。
```

悪い例では、エージェントが他の文書用スキルと区別することができません。

## スクリプトを追加するタイミング

次のような場合は、便利なスクリプトを追加してください：

-   処理のやり方が決まっているとき（データの確認や、形式を整える処理など）
-   同じようなコードが何度も繰り返し作られてしまうとき
-   エラーが起きたときの処理をきちんと書く必要があるとき

スクリプトを使うと、エージェントがコードをその場で作るよりも、トークン（文字数のカウント）を節約でき、動きも安定します。

## ファイルを分けるタイミング

次のような場合は、ファイルを別々に分けてください：

-   SKILL.md が100行を超えるとき
-   内容が全く違う分野に分かれているとき（お金の計算方法と、商品の売り方のルールの違いなど）
-   高度な機能を使う機会がほとんどないとき

## 確認リスト

下書きを作ったあと、次のことを確認してください：

-   [ ] 説明文に「［特定のきっかけ］のときに使います」という言葉が入っているか
-   [ ] SKILL.md が100行未満になっているか
-   [ ] 古くなってしまう情報（日付や期限など）が入っていないか
-   [ ] 言葉の使い方が統一されているか
-   [ ] 具体的な例が載っているか
-   [ ] 別のファイルを参考にする場合、フォルダの深さが1つまでになっているか（何重にも深くリンクしない）
