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

1. Normalize Input — validate role name as kebab-case.
2. Generate Role Fields — auto-generate fields, delegate to /brainstorming on rejection.
3. Select Skills — find-skills recommendations, user selection, manual additions.
4. Execute CLI — run agent-team role create with approved parameters.
5. Validate Output — verify three managed files match expected template structure.

Step 1: Normalize Input

• role-name must be kebab-case (default: frontend-dev when not provided).
• If the input is not kebab-case, suggest a normalized version and confirm with user.

Step 2: Generate Role Fields

1. Auto-generate the following fields (do not ask user to draft them by default):
   • description
   • system goal
   • in-scope (comma-separated)
   • out-of-scope (comma-separated)
2. Present generated fields for user approval.
3. If user rejects, or AI confidence is low (ambiguous scope, conflicting boundaries, vague goals), delegate to /brainstorming skill for structured refinement.
4. After fields are approved, ask user for target directory (skills or .agents/teams).
5. 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.

Step 3: Select Skills

1. Run find-skills to get recommendation candidates.
2. Show recommendation list and let user select desired skills.
3. Ask for manual additions after selection.
4. Merge selected + manual additions with de-duplication, then confirm final list.
5. Final skills may be empty — will be persisted as skills: [] in references/role.yaml.

If find-skills is unavailable or returns empty, skip recommendations and ask for manual additions only.

Step 4: Execute CLI

CLI Reference

Flag	Type	Required	Default	Description
<role-name>	arg	yes	—	Role name (kebab-case)
--description	string	yes	—	Role description
--system-goal	string	yes	—	Primary objective for system.md
--in-scope	string[]	no	(from description)	In-scope items (repeatable, comma-separated)
--out-of-scope	string[]	no	fallback text	Out-of-scope items (repeatable, comma-separated)
--skills	string	no	""	Final selected skills (comma-separated)
--recommended-skills	string	no	""	Recommended skills from find-skills
--add-skills	string	no	""	Skills to add on top of selection
--remove-skills	string	no	""	Skills to remove from candidate list
--manual-skills	string	no	""	Manual fallback when recommendations unavailable
--target-dir	string	no	skills	Target: skills, .agents/teams, or custom path
--overwrite	string	no	ask	Overwrite mode: ask/yes/no
--repo-root	string	no	.	Repository root path
--force	bool	no	false	Skip global duplicate check

Skills resolution priority: --skills > --recommended-skills > --manual-skills, then --add-skills appended, --remove-skills excluded.

Examples

For open-source publishing (default):

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

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:

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

Step 5: Validate Output

Verify three files against actual template structure:

1. SKILL.md — contains role name, description, and trigger keywords derived from in-scope items.
2. references/role.yaml — must contain:
   • name — role name
   • description — role description
   • system_prompt_file: system.md
   • scope.in_scope — list of in-scope items
   • scope.out_of_scope — list of out-of-scope items
   • constraints.single_role_focus: true
   • skills — list of selected skills (may be empty [])
3. system.md — contains system goal and operating constraints.

If any file is missing or contains unexpected content, report the discrepancy and offer to regenerate.

Overwrite Behavior

• Controlled by --overwrite flag (ask/yes/no).
• On overwrite, backup is created at <parent>/.backup/<role-name>-<timestamp>/.
• Only managed files are overwritten (SKILL.md, references/role.yaml, system.md).

Runtime Skill Discovery (Role Usage Guideline)

Generated roles should follow this behavior at runtime:

1. 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.
2. If a suitable skill is found, ask the user whether to install globally or project-level before installing.
3. If the user does not specify, default to global installation.
4. Install the selected skill and use it to complete the task.
5. After successful use, suggest adding the skill to the role's references/role.yaml for future sessions.
6. If find-skills is unavailable or returns no match, the role should notify the user and proceed with best-effort execution.