From amq-squad
Author custom amq-squad roles that are not in the built-in persona catalog, then wire them into a team. Covers writing a role file (Markdown with optional YAML frontmatter, .yaml, or .json), the required binary, and adding the role via `team init`/`new team`/`new profile` with `--role-file` or an inline path in `--roles`, plus the inline `--roles X --binary X=<cli>` shortcut. Use when someone wants a role like researcher, sre, scribe, or data-scientist that the catalog does not ship. For built-in personas (cto, qa, fullstack, ...) and general team design, use `amq-team-setup`; for live coordination use `amq-squad`.
How this skill is triggered — by the user, by Claude, or both
Slash command
/amq-squad:amq-squad-role-creator [role-id] [codex|claude][role-id] [codex|claude]This skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Use this skill to add a **custom role** — one that is not in the built-in
Use this skill to add a custom role — one that is not in the built-in
persona catalog (cpo, cto, senior-dev, fullstack, frontend-dev, backend-dev, mobile-dev, junior-dev, qa, pm, designer). Custom roles are first-class team
members: they appear in team.json, team-rules.md, the bootstrap prompt,
status/history, and launch/resume exactly like built-ins.
Requires amq-squad v1.5.0+. Check with amq-squad version.
There are two ways to add a custom role. Pick by how much role guidance you want.
For a role that only needs an id + CLI, with the generic custom-role fallback
text seeded into its role.md:
amq-squad new team --roles researcher --binary researcher=codex
amq-squad new team --roles researcher,reviewer --binary researcher=codex,reviewer=claude
amq-squad new profile discovery --roles researcher --binary researcher=codex
amq-squad team init --roles cto,researcher --binary researcher=codex
Rules:
--roles/--personas entry that is not a built-in persona is a custom role.a-z, 0-9, -, _)
and must have an explicit --binary <role>=<cli> entry (there is no
catalog default to fall back to). Built-in roles keep their catalog defaults
unless overridden.custom role "researcher" requires --binary researcher=<cli>.When you want a real persona description, peers, and skills, author a role file
and pass it with --role-file (comma-separated) or inline in --roles:
amq-squad new team --role-file ./roles/researcher.md --roles cto
amq-squad team init --roles "cto,./roles/researcher.md"
amq-squad new profile discovery --role-file ./roles/researcher.md,./roles/sre.yaml
What happens:
id: field, a # Role: <name> heading,
or the filename).binary: field; --binary overrides it.
If neither is present the command fails with the same binary guidance as above..amq-squad/roles/<id>.md. At launch,
up / agent up seeds that agent's role.md from it verbatim (and never
overwrites later user edits).--role-file is added to the team even if it is not
also listed in --roles.Markdown with YAML frontmatter (recommended — frontmatter for metadata,
body becomes role.md verbatim):
---
id: researcher
label: Research Engineer
binary: codex
peers: [cto, qa]
skills:
- /deep-research
---
# Role: Research Engineer
## Description
Owns deep technical investigation, prototypes, and written findings. Turns
open questions into evidence the team can act on.
## Peers
- cto
- qa
## Skills
- /deep-research
## System Prompt
Stay within the research scope; hand implementation to developer roles. Use the
amq-squad protocol for handoffs.
## Priming Template
At launch, state your role and handle, summarize relevant context, then wait
for instruction.
Plain Markdown, no frontmatter (whole file is role.md; id from the
# Role: heading or filename; supply the binary with --binary):
# Role: Scribe
## Description
Captures decisions and keeps the team's written record.
amq-squad new team --roles "cto,./roles/scribe.md" --binary scribe=claude
Metadata-only YAML or JSON (no body; role.md is rendered from the
fields):
id: sre
label: Site Reliability Engineer
binary: claude
description: Owns reliability, on-call, and incident response.
skills:
- /run
peers:
- cto
- backend-dev
{ "id": "analyst", "label": "Analyst", "binary": "codex",
"description": "Owns reporting and data pulls.", "peers": ["pm"] }
| Field | Meaning |
|---|---|
id (or role) | role slug + default handle (lowercase a-z 0-9 - _) |
label | human title shown in listings and role.md |
binary | codex or claude (any non-control value is accepted) |
description | one-line summary seeded into the rendered role.md |
skills | list of slash commands for this role |
peers | list of role ids this role talks to most |
body (JSON only) | optional verbatim role.md content |
codex/claude), and whether you need rich
guidance (file) or just an id (inline)../roles/<id>.md (frontmatter + body is the
sweet spot). Keep the # Role:, ## Description, ## Peers, ## Skills,
## System Prompt, ## Priming Template sections so it matches what the
binary renders for built-ins.amq-squad new team --role-file ./roles/<id>.md --roles cto --dry-run --json
Confirm the member shows the right role, handle, and binary.--dry-run), or add --sync to also write
the CLAUDE.md/AGENTS.md pointer stubs..amq-squad/roles/<id>.md later to refine the persona; re-running
team init --force re-stages it, and launch never clobbers an agent's
already-seeded role.md.amq-squad new team --role-file ... --dry-run --json succeeds and the plan
lists the custom member with the expected binary..amq-squad/roles/<id>.md exists and team.json
includes the member.amq-squad up --dry-run shows a launch command for the custom role.amq-team-setup.amq-squad.amq-cli.npx claudepluginhub omriariav/amq-squad --plugin amq-squadProvides CDSS development patterns for drug interaction checking, dose validation, clinical scoring (NEWS2, qSOFA), and alert classification integrated into EMR workflows.