role-creator

Original：🇺🇸 English

Translated

Create or update role-specific skill packages with deterministic files. Supports output to skills/ (open-source publishing) or .agents/teams/ (team use). Triggers: 创建角色, 新建 role, create role, 更新 role scope, edit role, update role, add role skill, 修改角色配置. Use when the user asks to create, update, or edit frontend/backend/product (or custom) role skills with auto-generated role fields, guided brainstorming fallback, and curated skills selection.

2installs

Sourcejsonlee12138/agent-team

Added on2026-03-03

NPX Install

npx skill4agent add jsonlee12138/agent-team role-creator

SKILL.md Content

View Translation Comparison →

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

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.

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).

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 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.

Local Skill Resolution

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.

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.

Runtime Skill Discovery (Role Usage Guideline)

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.

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
```
).

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.

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

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.

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).

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 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.

Local Skill Resolution

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.

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.

Runtime Skill Discovery (Role Usage Guideline)

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.

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
```
).

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.

role-creator

NPX Install

Tags

SKILL.md Content

role-creator

Required Workflow

Brainstorming Trigger Policy

Brainstorming Process

Skills Selection UX (After Fields Are Approved)

Local Skill Resolution

Generate Command

Runtime Skill Discovery (Role Usage Guideline)

Overwrite Behavior

Validation

role-creator

NPX Install

Tags

SKILL.md Content

role-creator

Required Workflow

Brainstorming Trigger Policy

Brainstorming Process

Skills Selection UX (After Fields Are Approved)

Local Skill Resolution

Generate Command

Runtime Skill Discovery (Role Usage Guideline)

Overwrite Behavior

Validation