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 階層以内に収まっている