role-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

role-creator

Generate a role skill package in a fixed contract:

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

Target directory options:

```
skills/<role-name>/
```
— for open-source publishing (default)
```
.agents/teams/<role-name>/
```
— for team use with agent-team

按照固定契约生成角色skill包：

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

目标目录选项：

```
skills/<role-name>/
```
— 用于开源发布（默认）
```
.agents/teams/<role-name>/
```
— 供agent-team团队使用

Required Workflow

必选工作流

Normalize role input:
- ```
role-name
```
  must be kebab-case (default:
```
frontend-dev
```
  when not provided).
Auto-generate role fields first (do not ask user to draft them by default):
- ```
description
```
- ```
system goal
```
- ```
in-scope
```
  (comma-separated output)
- ```
out-of-scope
```
  (comma-separated output)
If user rejects the auto result, or AI confidence is low, run the full brainstorming process below.
After fields are approved, run skills selection flow.
Ask user for target directory (
```
skills
```
or
```
.agents/teams
```
).
If target is
```
.agents/teams
```
and the role already exists in global
```
~/.claude/skills/
```
, ask if user wants to copy from there instead of generating.
Execute generator script to write files deterministically.

标准化角色输入：
- ```
role-name
```
  必须使用短横线命名法（未提供时默认值为
```
frontend-dev
```
  ）。
首先自动生成角色字段（默认不要求用户手动起草）：
- ```
description
```
- ```
system goal
```
- ```
in-scope
```
  （逗号分隔输出）
- ```
out-of-scope
```
  （逗号分隔输出）
如果用户拒绝自动生成的结果，或AI置信度较低，则运行下方完整的头脑风暴流程。
字段获得批准后，运行skill选择流程。
询问用户目标目录（
```
skills
```
或
```
.agents/teams
```
）。
如果目标目录是
```
.agents/teams
```
，且该角色已存在于全局
```
~/.claude/skills/
```
中，询问用户是否要从该位置复制内容而非重新生成。
执行生成脚本确定性写入文件。

Brainstorming Trigger Policy

头脑风暴触发规则

Default flow: auto-generate role fields first.
Enter full brainstorming when either condition is met:
- User says the auto-generated role fields are not acceptable.
- AI detects low confidence (ambiguous scope, conflicting boundaries, or vague goals).

默认流程：优先自动生成角色字段。
满足任意以下条件时进入完整头脑风暴：
- 用户表示自动生成的角色字段不可接受。
- AI检测到置信度较低（范围模糊、边界冲突或目标不明确）。

Brainstorming Process

头脑风暴流程

Explore context — scan existing role skills under
```
skills/*/
```
and
```
.agents/teams/*/
```
, templates, and recent commits for patterns.
Ask clarifying questions — one question per message; prefer multiple choice; focus on role purpose and scope boundaries.
Confirm fields — present the final
```
description
```
,
```
system_goal
```
,
```
in_scope
```
,
```
out_of_scope
```
for user approval before generation.

上下文探索 — 扫描
```
skills/*/
```
和
```
.agents/teams/*/
```
下的现有角色skill、模板以及最近提交，寻找模式。
提出澄清问题 — 每条消息仅提一个问题，优先使用选择题，聚焦于角色用途和范围边界。
字段确认 — 在生成前展示最终的
```
description
```
、
```
system_goal
```
、
```
in_scope
```
、
```
out_of_scope
```
供用户批准。

Skills Selection UX (After Fields Are Approved)

技能选择用户体验（字段获批后）

Run
```
find-skills
```
first to get recommendation candidates.

Show recommendation list in checkbox format (primary) with numbered indices:

text

Recommended skills:
1. [ ] skill-a
2. [ ] skill-b

Reply in either format:
- Edit checkboxes to [x]/[ ]
- Or send numbers, e.g. 1,2

Parse precedence:
- Checkbox parsing is primary.
- Numeric parsing (
```
1,3,5
```
  ) is fallback.
- If both checkbox and numeric forms are present, checkbox result wins.

Ask for manual additions after selection:

text

Any additional skills to add manually? (comma-separated, optional)

Merge selected skills and manual additions with de-duplication, then confirm final list.
Final skills may be empty and should be persisted as
```
skills: []
```
in
```
references/role.yaml
```
.

find-skills

is unavailable or returns empty, skip recommendations and ask for manual additions only.

首先运行
```
find-skills
```
获取推荐候选。

以带编号索引的复选框格式展示推荐列表（优先）：

text

Recommended skills:
1. [ ] skill-a
2. [ ] skill-b

Reply in either format:
- Edit checkboxes to [x]/[ ]
- Or send numbers, e.g. 1,2

解析优先级：
- 优先解析复选框。
- 兜底解析数字格式（
```
1,3,5
```
  ）。
- 如果同时存在复选框和数字格式，以复选框结果为准。

选择完成后询问是否要手动添加：

text

Any additional skills to add manually? (comma-separated, optional)

合并选中的skill和手动添加的内容并去重，然后确认最终列表。
最终skill列表可以为空，应在
```
references/role.yaml
```
中存储为
```
skills: []
```
。

如果

find-skills

不可用或返回空结果，跳过推荐环节，仅询问手动添加内容。

Local Skill Resolution

本地Skill解析

After the final skills list is confirmed, resolve each plain skill name against local directories:

For each skill in the final list that is a plain name (no
```
/
```
), scan local paths:
- ```
skills/*/
```
  ,
```
.agents/teams/*/
```
  ,
```
.claude/skills/*/
```
  ,
```
~/.claude/skills/*/
```
If a local copy is found, ask the user whether to replace it with a full scoped path:
text
```
Skill 'vitest' found locally at skills/vitest/.
Use find-skills to look up its full remote path (e.g. antfu/skills@vitest)?  [y/N]
```
- y → run
```
find-skills
```
  for that skill name, present matches, let user pick the scoped path to replace the plain name.
- N (default) → keep the plain name as-is.
Skills that already have a scoped path (containing
```
/
```
) are kept unchanged.
Update the final list with any replacements before passing to the generator script.

最终skill列表确认后，针对每个纯skill名称在本地目录中进行解析：

对于最终列表中属于纯名称（不含
```
/
```
）的每个skill，扫描本地路径：
- ```
skills/*/
```
  ,
```
.agents/teams/*/
```
  ,
```
.claude/skills/*/
```
  ,
```
~/.claude/skills/*/
```
如果找到本地副本，询问用户是否要用全限定路径替换它：
text
```
Skill 'vitest' found locally at skills/vitest/.
Use find-skills to look up its full remote path (e.g. antfu/skills@vitest)?  [y/N]
```
- y → 对该skill名称运行
```
find-skills
```
  ，展示匹配结果，让用户选择限定路径替换纯名称。
- N（默认） → 保留原纯名称不变。
已经带有全限定路径（包含
```
/
```
）的skill保持不变。
传入生成脚本前使用所有替换内容更新最终列表。

Generate Command

生成命令

For open-source publishing (default):

bash

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"

For team use (agent-team integration):

bash

agent-team role create frontend-dev \
  --target-dir .agents/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"

Empty skills example:

bash

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

Minimum required CLI version: includes
role create
subcommand.

用于开源发布（默认）：

bash

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集成）：

bash

agent-team role create frontend-dev \
  --target-dir .agents/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"

空skill示例：

bash

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

最低要求CLI版本：包含
role create
子命令。

Runtime Skill Discovery (Role Usage Guideline)

运行时Skill发现（角色使用指南）

Generated roles should follow this behavior at runtime:

When a role receives a task that requires a skill not listed in its
```
references/role.yaml
```
, it should invoke
```
find-skills
```
to search for a matching skill.
If a suitable skill is found, ask the user whether to install globally or project-level before installing.
If the user does not specify, default to global installation.
Install the selected skill and use it to complete the task.
After successful use, suggest adding the skill to the role's
```
references/role.yaml
```
for future sessions.
If
```
find-skills
```
is unavailable or returns no match, the role should notify the user and proceed with best-effort execution.

This ensures roles are self-sufficient and can dynamically extend their capabilities without manual reconfiguration.

生成的角色在运行时应遵循以下行为：

当角色收到的任务需要用到
```
references/role.yaml
```
中未列出的skill时，应调用
```
find-skills
```
搜索匹配的skill。
如果找到合适的skill，询问用户是全局安装还是项目级安装后再执行安装。
如果用户未指定，默认全局安装。
安装选中的skill并使用它完成任务。
成功使用后，建议将该skill添加到角色的
```
references/role.yaml
```
中供后续会话使用。
如果
```
find-skills
```
不可用或无匹配结果，角色应通知用户并尽力执行任务。

这确保角色具备自足能力，可以动态扩展能力，无需手动重新配置。

Overwrite Behavior

覆盖行为

If the target directory exists, the script asks for confirmation before overwrite.

On confirmation, it creates a backup at:

<parent>/.backup/<role-name>-<timestamp>/

Then it overwrites managed files only (
```
SKILL.md
```
,
```
references/role.yaml
```
,
```
system.md
```
).

如果目标目录已存在，脚本在覆盖前会请求确认。
确认后会在以下位置创建备份：
- ```
<parent>/.backup/<role-name>-<timestamp>/
```
然后仅覆盖受管理的文件（
```
SKILL.md
```
、
```
references/role.yaml
```
、
```
system.md
```
）。

Validation

验证

After generation, verify the output files exist and contain expected content:

Check all three managed files exist in
```
<target>/<role-name>/
```
:
- ```
SKILL.md
```
  — contains role name, description, and trigger keywords
- ```
references/role.yaml
```
  — contains
```
description
```
  ,
```
system_goal
```
  ,
```
in_scope
```
  ,
```
out_of_scope
```
  ,
```
skills
```
- ```
system.md
```
  — contains system goal and scope instructions
Verify field values in
```
references/role.yaml
```
match the approved inputs (description, system goal, scopes, skills list).
If any file is missing or contains unexpected content, report the discrepancy and offer to regenerate.

生成完成后，校验输出文件是否存在且包含预期内容：

检查
```
<target>/<role-name>/
```
下三个受管理文件是否都存在：
- ```
SKILL.md
```
  — 包含角色名称、描述和触发关键词
- ```
references/role.yaml
```
  — 包含
```
description
```
  、
```
system_goal
```
  、
```
in_scope
```
  、
```
out_of_scope
```
  、
```
skills
```
- ```
system.md
```
  — 包含系统目标和范围说明
验证
```
references/role.yaml
```
中的字段值与获批的输入（描述、系统目标、范围、skill列表）一致。
如果任何文件缺失或包含非预期内容，报告差异并提供重新生成的选项。