skill-best-practices

スキル作成手順

以下の手順に従い、agentskills.io の仕様と段階的開示の原則に準拠したスキルを作成します。

同梱パスのルール

同梱パスは、この SKILL.md を含むディレクトリを基準に解決します。別の作業ディレクトリからヘルパーを呼び出す場合は、コマンドが曖昧にならないよう、まず <skill-best-practices-dir> をそのディレクトリに置き換えます。

ステップ 1：メタデータの初期化と検証

1. 一意の name を定義します。1～64 文字で、小文字、数字、単一のハイフンのみを使用します。
2. description を作成します。最大 1,024 文字とし、三人称で記述して、対象外となる条件も含めます。
3. 検証スクリプトを実行する（読み取り専用ヘルパー）： 先に進む前に、検証スクリプトを実行して準拠していることを確認します。 python3 <skill-best-practices-dir>/scripts/validate-metadata.py --name "[name]" --description "[description]"
4. スクリプトがエラーを返した場合は、stderr の出力に基づいてメタデータを修正し、成功するまで再実行します。

ステップ 2：ディレクトリの構成

1. 検証済みの name を使用してルートディレクトリを作成します。
2. 以下のサブディレクトリを作成します。
   • scripts/：小規模な CLI ツールと決定論的なロジック用です。
   • references/：スキーマや API ドキュメントなど、階層が 1 つのコンテキスト用です。
   • assets/：出力テンプレート、JSON スキーマ、静的ファイル用です。
3. README.md や INSTALLATION.md など、人間向けのファイルは作成しないでください。

ステップ 3：コアロジックの作成（SKILL.md）

1. assets/SKILL.template.md のテンプレートを出発点として使用します。
2. すべての指示を三人称の命令形で記述します（例：「テキストを抽出する」「ビルドを実行する」）。
3. 段階的開示を徹底します。
   • メインロジックは 500 行未満に収めます。
   • 手順で大規模なスキーマや複雑なルールセットが必要な場合は、references/ に移します。
   • 必要なときに限り、エージェントに特定のファイルを読むよう指示します。例：「適切なエンドポイントを特定するため、references/api-spec.md を読みます。」

ステップ 4：スクリプトの特定と同梱

1. 「壊れやすい」タスク（正規表現、複雑な解析、繰り返しの定型処理）を特定します。
2. scripts/ ディレクトリ用に、単一目的のスクリプトを設計します。
3. スクリプトが標準出力（stdout/stderr）を使って、成功または失敗をエージェントに伝えるようにします。
4. SKILL.md では、作業ディレクトリに依存する scripts/helper.py のような単独の記述ではなく、エージェントの作業ディレクトリから曖昧さなく指定できるパス（エージェントが実際に入力するパスと同じもの）で同梱ヘルパーを参照します。
5. 各ヘルパーに読み取り専用、ブートストラップ、または変更ありのラベルを付け、下流のエージェントが状態を検査するだけなのか、変更するのかを把握できるようにします。

ステップ 5：最終ロジックの検証

1. SKILL.md を確認し、「ハルシネーションの余地」（エージェントが推測を強いられる箇所）がないか調べます。
2. すべてのファイルパスが相対パスで、スラッシュ（/）を使用していることを確認します。
3. 参照されているすべてのヘルパーのパスがエージェントの作業ディレクトリから曖昧さなく指定でき、ヘルパーの役割（read-only、bootstrap、mutating）が明記されていることを確認します。
4. references/checklist.md を読み、チェックリストの各項目を最終出力と照合します。

エラー処理

• メタデータの失敗： scripts/validate-metadata.py が失敗した場合は、具体的なエラー（例：「STYLE ERROR」）を特定し、一人称または二人称の代名詞を取り除くように該当フィールドを書き直します。
• コンテキストの肥大化： 下書きが 500 行を超える場合は、最も長い手順ブロックを抽出し、references/ 内のファイルに移します。