skill-creator

スキル作成手順

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

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

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

ステップ 2：ディレクトリを構成する

1. 検証済みの name を使ってルートディレクトリを作成します。
2. 次のサブディレクトリを作成します。
   • scripts/：小規模な CLI ツールや決定論的な処理用。
   • references/：スキーマや API ドキュメントなど、階層の浅いコンテキスト用。
   • 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）を使って、成功または失敗をエージェントに伝えるようにします。

ステップ 5：ロジックを最終検証する

1. SKILL.md を見直し、「ハルシネーションにつながる曖昧な点」（エージェントが推測せざるを得ない箇所）がないか確認します。
2. すべてのファイルパスが相対パスであり、スラッシュ（/）を使っていることを確認します。
3. 最終出力を references/checklist.md と照合します。

エラー処理

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