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. 验证输出 — 确认三个受管理文件符合预期的模板结构。

步骤 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，请说明 CLI 会检查 ~/.agents/roles/ 中匹配的全局角色，除非传入 --force。如果找到匹配项，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>	参数	是	—	角色名称（kebab-case）
--description	字符串	是	—	角色描述
--system-goal	字符串	是	—	system.md 的主要目标
--in-scope	字符串[]	否	（根据描述生成）	范围内的项目（可重复，逗号分隔）
--out-of-scope	字符串[]	否	回退文本	范围外的项目（可重复，逗号分隔）
--skills	字符串	否	""	最终选定的技能（逗号分隔）
--recommended-skills	字符串	否	""	find-skills 推荐的技能
--add-skills	字符串	否	""	在所选技能基础上添加的技能
--remove-skills	字符串	否	""	从候选列表中移除的技能
--manual-skills	字符串	否	""	无法获取推荐时使用的手动回退选项
--target-dir	字符串	否	skills	目标：skills、.agent-team/teams 或自定义路径
--overwrite	字符串	否	ask	覆盖模式：ask/yes/no
--repo-root	字符串	否	.	仓库根目录路径
--force	布尔值	否	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：验证输出

根据实际模板结构验证以下三个文件：

1. SKILL.md — 包含角色名称、生成的描述 frontmatter，以及指向 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 不可用或未找到匹配项，角色应告知用户，并尽力继续执行。