skill-doc-authoring

スキル文書の作成

エージェントが実際に起動して従う、有効な SKILL.md を1つ作成します。これにより、スキルがまったく起動しない（説明が弱い）ことと、起動しても役に立たない（本文が曖昧）ことの2つの失敗を防ぎます。

ファイルの要件

• ディレクトリ名と name: は一致させる必要があります。小文字とハイフンのみを使用し、64文字以内にしてください。
• ファイル名は大文字と小文字を区別し、必ず SKILL.md にしてください。
• フロントマターのキーは name と description の2つだけにしてください。description は1024文字以内にしてください。

skills/<skill-name>/SKILL.md

説明文が起動のトリガーです

エージェントは description だけをもとに、スキルを読み込むかどうかを判断します。三人称で書き、まず機能を説明してから、具体的なユーザーの言い回しや状況を示す 「Use when …」 を続けてください。ユーザーが実際に入力しそうなトリガーワードを含めてください。

• 弱い例：データを扱うワークフローです。
• 強い例：インポート前にCSVのエクスポートデータを検証してクリーンアップします。ユーザーがCSVをアップロードした場合、「dirty data」と言及した場合、または「これをデータベース用に整えて」と依頼した場合に使用します。

近い内容を扱う関連スキルがある場合は、使用しない状況も明記してください。トリガーが重複すると、誤ったスキルが起動する原因になります。

本文の構成

プロジェクトのコンテキストを知らないエージェントに向けて書きます。簡潔に、命令形で、判断しやすい構成にしてください。

# Title
One-line purpose.
## When to use            # + when not to
## Procedure / The loop   # numbered, concrete, with commands
## Quality bar            # how to know it's done right
## Anti-patterns          # the tempting wrong moves

ルール：

• 「エージェントは X を検討するべきです」ではなく、命令形で書いてください（「X を実行する」「Y を確認する」など）。
• 各手順は検証可能にするか、具体的なコマンドや例を示してください。
• 「メモ」「概要」などの補足や、同じ内容の繰り返しは省いてください。エージェントの行動を変えない行は削除してください。
• 長い参考資料（スキーマ、表、スクリプト）は関連ファイルに分け、リンクしてください。SKILL.md は流し読みしやすい状態に保ちます（目安は約200行未満）。

手順

1. ユーザーから実際の手順を抽出します（SOP、実際に行う作業、判断基準）。
2. トリガーを特定します。このスキルが必要になる直前に、ユーザーは何を言う、または何をするでしょうか。
3. 説明文を作成します（トリガーの検証：その言い回しで起動するか。無関係な依頼では起動しないか）。
4. 上記の構成に従って本文を作成します。
5. 次の項目を検証します：ファイル名、name とディレクトリ名の一致、フロントマターのキー、説明文の文字数。
6. 頭の中でドライランします。コンテキストのないエージェントにこのスキルを与え、リクエスト例を2～3件試します。何をすべきか正確にわかるでしょうか。

アンチパターン

• どんなトピックにも当てはまり、何の役にも立たない汎用的なひな型（概要 →「このスキルは…を可能にします」→ 名詞の箇条書き → メモ）。
• いつ起動するかを示さず、分野の説明だけをする description。
• ユーザー固有の手順ではなく、モデルがすでに知っている一般的なベストプラクティスを繰り返すこと。
• スクリプトと短い説明で済む内容を、1つの巨大な SKILL.md にまとめること。