write-a-skill

スキルの作成

プロセス

1. 要件を収集する — ユーザーに質問します：

   • スキルが対象とするタスク／ドメインは何ですか？
   • どのような具体的なユースケースに対応する必要がありますか？
   • 実行可能なスクリプトが必要ですか、それとも手順だけで十分ですか？
   • 含めるべき参考資料はありますか？

2. スキルのドラフトを作成する — 以下を作成します：

   • 簡潔な指示を記載した SKILL.md
   • 内容が 500 行を超える場合は、追加の参考ファイル
   • 決定論的な操作が必要な場合は、ユーティリティスクリプト

3. ユーザーとレビューする — ドラフトを提示し、以下を質問します：

   • ユースケースに対応できていますか？
   • 不足している点や不明瞭な点はありますか？
   • もっと詳しくする、または短くするべきセクションはありますか？

スキルの構成

skill-name/
├── SKILL.md           # Main instructions (required)
├── REFERENCE.md       # Detailed docs (if needed)
├── EXAMPLES.md        # Usage examples (if needed)
└── scripts/           # Utility scripts (if needed)
    └── helper.js

SKILL.md のテンプレート

---
name: skill-name
description: Brief description of capability. Use when [specific triggers].
---

# Skill Name

## Quick start

[Minimal working example]

## Workflows

[Step-by-step processes with checklists for complex tasks]

## Advanced features

[Link to separate files: See [REFERENCE.md](REFERENCE.md)]

説明の要件

説明は、エージェントがスキルを読み込むかどうかを判断する際に唯一目にする内容です。ほかのインストール済みスキルと一緒に、システムプロンプトに表示されます。エージェントはこれらの説明を読み、ユーザーのリクエストに応じて関連するスキルを選択します。

目標：エージェントが以下を把握できるよう、十分な情報を提供します。

1. このスキルが提供する機能
2. いつ、なぜこのスキルが起動されるか（具体的なキーワード、状況、ファイル形式）

形式：

• 1024 文字以内
• 三人称で記述
• 最初の文で、そのスキルが何をするかを説明
• 2 文目は「次の場合に使用します：[具体的なトリガー]」とする

良い例：

Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.

悪い例：

Helps with documents.

悪い例では、このスキルをほかのドキュメントスキルと区別できません。

スクリプトを追加する場合

以下の場合は、ユーティリティスクリプトを追加します。

• 操作が決定論的である（検証、フォーマットなど）
• 同じコードを繰り返し生成する
• エラーを明確に処理する必要がある

コードを生成する場合と比べ、スクリプトを使うとトークンを節約でき、信頼性が向上します。

ファイルを分割する場合

以下の場合は、ファイルを個別に分割します。

• SKILL.md が 100 行を超える
• 内容が異なるドメイン（財務と営業のスキーマなど）に分かれている
• 高度な機能を使う機会が少ない

レビューチェックリスト

ドラフトの完成後、以下を確認します。

• 説明にトリガー（「次の場合に使用します：…」）が含まれている
• SKILL.md が 100 行未満である
• 時間の経過で古くなる情報が含まれていない
• 用語が一貫している
• 具体例が含まれている
• 参照先の階層が 1 段だけである