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段階である

次の手順

スキルを作成したら、setup-roblox-skills を実行してプロジェクトのルーティングブロックに登録します。これにより、Claude がその目的、ユースケース、トリガーワードを把握できます。