write-a-skill

スキルの作成

プロセス

1. 要件を収集する — ユーザーに次の点を確認します。

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

2. スキルの草案を作成する — 次のものを作成します。

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

3. ユーザーと一緒に確認する — 草案を提示し、次の点を尋ねます。

   • ユースケースに対応できていますか？
   • 不足している点や分かりにくい点はありますか？
   • 詳細を増やしたり減らしたりすべきセクションはありますか？

スキルの構成

skill-name/
├── SKILL.md           # Instruções principais (obrigatório)
├── REFERENCE.md       # Docs detalhados (se necessário)
├── EXAMPLES.md        # Exemplos de uso (se necessário)
└── scripts/           # Scripts utilitários (se necessário)
    └── helper.js

SKILL.md テンプレート

---
name: skill-name
description: "Descrição breve da capacidade. Use quando [triggers específicos]."
---

# Skill Name

## Quick start

[Exemplo mínimo funcional]

## Workflows

[Processos passo-a-passo com checklists para tasks complexas]

## Advanced features

[Link para arquivos separados: Veja [REFERENCE.md](REFERENCE.md)]

Description の要件

エージェントがどのスキルを読み込むか判断するときに確認するのは、description だけです。description は、インストール済みのほかのすべてのスキルと一緒に system prompt に表示されます。エージェントはこれらの description を読み、ユーザーの依頼に基づいて関連するスキルを選びます。

目的：エージェントが次の点を把握するために、必要十分な情報を記載します。

1. このスキルが提供する機能
2. どのようなときに使用するか（具体的なキーワード、状況、ファイルの種類）

形式：

• 最大 1024 文字
• 三人称で記述する
• 1 文目：何をするか
• 2 文目：「次の場合に使用します：[具体的なトリガー]」

良い例：

Extrai texto e tabelas de arquivos PDF, preenche forms, faz merge de documents. Use quando trabalhar com arquivos PDF ou quando o usuário mencionar PDFs, forms ou extração de documentos.

悪い例：

Ajuda com documentos.

悪い例では、エージェントがこのスキルをほかのドキュメント用スキルと区別する手がかりがありません。

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

次のような場合は、ユーティリティスクリプトを追加します。

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

スクリプトを使うとトークンを節約でき、生成されたコードより信頼性が高まります。

ファイルを分割する場合

次のような場合は、ファイルを分けます。

• SKILL.md が 100 行を超える
• 内容に異なるドメインが含まれる（finance と sales のスキーマなど）
• 高度な機能が必要になることがまれである

確認チェックリスト

草案の作成後、次の点を確認します。

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