skill-creator

スキル作成手順

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

Step 1: メタデータの初期化と検証

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

Step 2: ディレクトリの構成

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

Step 3: コアロジックの作成（SKILL.md）

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

Step 4: スクリプトの特定と同梱

1. 「壊れやすい」タスク（正規表現、複雑な解析、または繰り返しの定型処理）を特定します。
2. scripts/ ディレクトリ用の単一目的スクリプトを設計します。
3. 成功または失敗をエージェントに伝えるため、スクリプトが標準出力（stdout/stderr）を使用するようにします。

Step 5: 最終ロジックの検証

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

エラー処理

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