role-creator

role-creator

固定の契約に従って、ロールスキルパッケージを生成します：

• <target>/SKILL.md
• <target>/references/role.yaml
• <target>/system.md

ターゲットディレクトリの選択肢：

• skills/<role-name>/ — オープンソース公開用（デフォルト）
• .agent-team/teams/<role-name>/ — agent-team でのチーム利用用
• <custom-path>/<role-name>/ — カスタムのローカル出力パス用

必須のワークフロー

1. 入力を正規化 — ロール名が kebab-case であることを検証します。
2. ロールのフィールドを生成 — フィールドを自動生成し、却下された場合は /brainstorming に委任します。
3. スキルを選択 — find-skills の推奨候補、ユーザーによる選択、手動追加を行います。
4. CLI を実行 — 承認されたパラメーターで agent-team role create を実行します。
5. 出力を検証 — 管理対象の 3 つのファイルが、想定されるテンプレート構造に一致することを確認します。

ステップ 1：入力を正規化

• role-name は kebab-case である必要があります。現在の CLI では、位置引数として指定する必要があります。
• 入力が kebab-case でない場合は、正規化した候補を提示し、ユーザーに確認します。

ステップ 2：ロールのフィールドを生成

1. 以下のフィールドを自動生成します（デフォルトではユーザーに作成を依頼しません）。
   • description
   • system goal
   • in-scope（カンマ区切り）
   • out-of-scope（カンマ区切り）
2. 生成したフィールドを提示し、ユーザーの承認を得ます。
3. ユーザーが却下した場合、または AI の確信度が低い場合（スコープが曖昧、境界が矛盾している、目標が不明確など）は、構造化された精緻化のために /brainstorming スキルに委任します。
4. フィールドの承認後、ユーザーにターゲットディレクトリ（skills、.agent-team/teams、またはカスタムパス）を尋ねます。
5. ターゲットが skills または .agent-team/teams の場合、--force を指定しない限り、CLI は ~/.agents/roles/ 内の一致するグローバルロールを確認することを伝えます。一致するものが見つかった場合、CLI はローカルロールの作成を続行するかどうかを尋ねます。

ステップ 3：スキルを選択

1. find-skills を実行して、推奨候補を取得します。
2. 推奨リストを表示し、ユーザーに必要なスキルを選択してもらいます。
3. 選択後、手動で追加するスキルを尋ねます。
4. 最終的なスキル識別子を確認する際は、スキルがリモートソース由来であると分かっている場合、完全なリモート識別子を優先します（例：jsonlee12138/prompts@design-patterns-principles）。
5. 一致するリモートスキルが見つからず、そのスキルがローカルにのみ存在する場合に限り、ローカルの短縮名（例：design-patterns-principles）を使用します。
6. 選択したスキルと手動追加分を重複を除いて統合し、最終リストを確認します。
7. 最終的なスキルリストは空でもかまいません。その場合は references/role.yaml に skills: [] として保存されます。空でない場合は、上記の識別子の優先ルールに従い、skills[{name, description}] として保存します。

find-skills が利用できない場合、または結果が空の場合は、推奨を省略し、手動で追加するスキルのみを尋ねます。このフォールバックの場合も、ユーザーが完全なリモート識別子をすでに指定している場合はそれを優先します。それ以外の場合は、ローカルにのみ存在するスキルに限り、ローカルの短縮名を使用します。

ステップ 4：CLI を実行

CLI リファレンス

フラグ	型	必須	デフォルト	説明
<role-name>	arg	はい	—	ロール名（kebab-case）
--description	string	はい	—	ロールの説明
--system-goal	string	はい	—	system.md の主な目標
--in-scope	string[]	いいえ	（説明から取得）	対象範囲内の項目（繰り返し指定可、カンマ区切り）
--out-of-scope	string[]	いいえ	代替テキスト	対象範囲外の項目（繰り返し指定可、カンマ区切り）
--skills	string	いいえ	""	最終的に選択されたスキル（カンマ区切り）
--recommended-skills	string	いいえ	""	find-skills による推奨スキル
--add-skills	string	いいえ	""	選択内容に追加するスキル
--remove-skills	string	いいえ	""	候補リストから削除するスキル
--manual-skills	string	いいえ	""	推奨を利用できない場合の手動指定用フォールバック
--target-dir	string	いいえ	skills	出力先：skills、.agent-team/teams、またはカスタムパス
--overwrite	string	いいえ	ask	上書きモード：ask/yes/no
--repo-root	string	いいえ	.	リポジトリのルートパス
--force	bool	いいえ	false	グローバルな重複チェックをスキップ

スキルの解決優先順位：--skills > --recommended-skills > --manual-skills。その後、--add-skills を追加し、--remove-skills を除外します。

例

オープンソース公開向け（デフォルト）：

agent-team role create frontend-dev \
  --description "Frontend role for UI implementation" \
  --system-goal "Ship accessible and maintainable UI work" \
  --in-scope "Build components,Improve accessibility" \
  --out-of-scope "Database migrations,Backend API ownership" \
  --skills "ui-ux-pro-max,better-icons"

チーム利用向け（agent-team との連携）：

agent-team role create frontend-dev \
  --target-dir .agent-team/teams \
  --description "Frontend role for UI implementation" \
  --system-goal "Ship accessible and maintainable UI work" \
  --in-scope "Build components,Improve accessibility" \
  --out-of-scope "Database migrations,Backend API ownership" \
  --skills "ui-ux-pro-max,better-icons"

スキルが空の場合の例：

agent-team role create product-manager \
  --description "Product role for roadmap and PRD work" \
  --system-goal "Define clear product requirements and priorities"

ステップ 5：出力を検証する

実際のテンプレート構造に照らして、次の 3 つのファイルを確認します。

1. SKILL.md — ロール名、生成された説明のフロントマター、および references/role.yaml と system.md へのリンクが含まれていること。
2. references/role.yaml — 次の内容が含まれていること：
   • name — ロール名
   • description — ロールの説明
   • system_prompt_file: system.md
   • scope.in_scope — 対象範囲内の項目のリスト
   • scope.out_of_scope — 対象範囲外の項目のリスト
   • constraints.single_role_focus: true
   • skills — name と description を持つオブジェクトとして選択済みスキルを記載（または空の []）
3. system.md — システム目標と運用上の制約が含まれていること。

いずれかのファイルが見つからない場合、または現在のテンプレートに照らして想定外の内容が含まれている場合は、差異を報告し、再生成を提案します。

上書きの動作

• --overwrite フラグ（ask/yes/no）で制御します。
• 現在の CLI は、上書き時にバックアップディレクトリを作成しません。
• 管理対象ファイル（SKILL.md、references/role.yaml、system.md）のみが上書きされ、ロールディレクトリ内のその他のファイルは保持されます。
• 生成後、ルートレベルの旧式の role.yaml があれば削除されます。

実行時のスキル検出（ロール利用ガイドライン）

生成されたロールは、実行時に次の動作に従う必要があります。

1. ロールが references/role.yaml に記載されていないスキルを必要とするタスクを受け取った場合、find-skills を呼び出して該当するスキルを検索します。
2. 適切なスキルが見つかった場合、プロジェクトレベルでのインストールを試みるか、すでに利用可能なローカルまたはプロジェクトのキャッシュ済みスキルのみを使用できます。
3. ワーカー／実行時の解決では、グローバルインストールは禁止されています。
4. スキルをローカルで引き続き利用できない場合は、理由と次の推奨手順を含む警告を出してから、可能な範囲で実行を続けます。
5. スキルを正常に使用した後、今後のセッションに備え、ロールを再生成してスキルをロールの references/role.yaml に追加するよう提案します。
6. find-skills を利用できない場合、または一致するスキルが見つからない場合は、ユーザーに通知し、可能な範囲で実行を続けます。