skill-creator

スキル作成手順

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

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

1. 一意の name を定義します。1～64 文字で、小文字、数字、単一のハイフンのみを使用してください。親ディレクトリ名と完全に一致させる必要があります（例：angular-testing という名前は angular-testing/SKILL.md に配置します）。
2. description を作成します。最大 1,024 文字で、三人称で記述してください。肯定的なトリガー（「次の場合に使用…」）と否定的なトリガー（「次の用途には使用しない…」）を含めてください。
3. 検証スクリプトを実行します： 続行する前に、検証スクリプトを実行して準拠していることを確認してください。 python3 scripts/validate-metadata.py --name "[name]" --description "[description]"
4. スクリプトがエラーを返した場合は、stderr の出力に基づいてメタデータを修正し、成功するまで再実行してください。

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

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

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

1. assets/SKILL.template.md のテンプレートを出発点として使用します。
2. すべての指示を三人称の命令形（例：「テキストを抽出する」「ビルドを実行する」）で記述します。
3. 具体的で手順に沿った形式を適用します：
   • ステップ番号を付ける： ワークフローを厳密な時系列で定義します。分岐条件を明確に示してください（例：「ステップ 2：ソースマップが必要な場合は scripts/build.sh を実行します。不要な場合はステップ 3 に進みます。」）。
   • 具体的なテンプレートを用意する： 出力に特定の構造がある場合は、assets/ にテンプレートを配置し、文章で説明する代わりに、その構造をコピーするようエージェントに指示します。
   • 一貫性のある具体的な用語を使用する： 分野に即した同じ用語を一貫して使用します（例：Angular では、「html」や「view」ではなく、常に「template」を使用します）。
4. 段階的開示を徹底します：
   • メインの SKILL.md は 500 行未満にします。
   • 手順で大きなスキーマ、複雑なルールセット、または大量のコンテキストが必要な場合は、それを references/ 内の階層が 1 つのファイルに移します。
   • 必要な場合にのみ該当ファイルを読むようエージェントに指示します（JiT 読み込み）。例：「適切なエンドポイントを特定するには references/api-spec.md を読みます。」

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

1. 正規表現、複雑な解析、定型文の繰り返しなど、「壊れやすい」タスクを特定します。
2. scripts/ ディレクトリ用に、引数を受け取る単一目的の小規模 CLI スクリプトの概要を作成します。
3. 成功または失敗を標準出力（stdout/stderr）で伝えるようにします。エージェントがユーザーの介入なしに正確に自己修正できるよう、説明的で人間が理解しやすいエラーメッセージを記述してください。

ステップ 5：スキルの構成（任意）

スキルが複雑な場合は、ルーター／サブスキルのパターンを使用して構成します。

1. 高レベルのルータースキルを作成します。
2. 他の特定のスキルフォルダーを参照する条件付きトリガーまたは手順を定義します（例：「クライアントのビルドについては、[クライアントビルドスキルへのパス] を参照してください。サーバーのビルドについては、[サーバービルドスキルへのパス] を参照してください。」）。

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

1. SKILL.md を確認し、エージェントが推測を強いられる箇所（「ハルシネーションの隙間」）がないか調べます。
2. すべてのファイルパスが相対パスであり、スラッシュ（/）を使用していることを確認します。
3. 最終出力を references/checklist.md と照合します。

エラー処理

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