Skill: create-agent-role

Source: ludus/skills/create-agent-role/SKILL.md

name: create-agent-role description: Create a ROLE.yaml for an agent in ludus/agents//. Use when onboarding a new agent or formalizing an existing one into the capabilities registry.

Deprecated: This skill has been absorbed into the arena skill's "Scaffold Agent" workflow. Use /arena → option 13 instead. This file is kept as documentation of the ROLE.yaml schema.

Create Agent Role

Creates a ROLE.yaml that machine-describes an agent's wing, escalation path, tools, invocable skills, and competencies. The file feeds ludus staff registry and must be kept in sync with SOUL.md.

Authoritative schema: arena/framework/agents.md §1 (ROLE.yaml).

Step 1 — Read the agent's existing docs

From ludus/agents/<name>/, read in order:

SOUL.md — role purpose, what the agent does/does not do, escalation target
IDENTITY.md — name, wing affiliation cues, persona
TOOLS.md — which CLI binaries are available in the sandbox
AGENTS.md — peers and delegation chain

Extract these answers before writing anything:

Question	Where to find it
What wing does this agent belong to?	IDENTITY.md + SOUL.md (role framing)
Who does it escalate to?	SOUL.md (escalation section)
Does it accept cross-wing work items?	SOUL.md (routing rules)
Which CLI binaries does it use?	TOOLS.md
Which invocable skills does it use?	SOUL.md (workflow, commands)
What broader abilities are undocumented by SKILL.md?	SOUL.md (competencies implied by behavior)

Step 2 — Resolve available skills

Skills listed under skills: must resolve to a SKILL.md. Check all three locations in resolution order (first match wins):

ls ludus/agents/<name>/skills/   # 1. agent-local
ls ludus/skills/                 # 2. ludus shared
ls meta/skills/                  # 3. workspace shared

Any capability that lacks a SKILL.md goes under competencies: instead. Do not invent skill names — only list what exists.

Step 3 — Write the ROLE.yaml

Place the file at ludus/agents/<name>/ROLE.yaml.

wing: <wing-name>          # e.g. leadership, engineering, operations
role: <role-slug>          # e.g. orchestrator, developer, engineering-manager
escalates_to: <target>     # "human" | "<wing>:<role-slug>"
cross_wing: <bool>         # true = appears in org routing table as entry point

tools:                     # Tier 0 — raw binaries, no SKILL.md needed
  - bd
  - gh
  # ...

skills:                    # Tier 1 — each MUST resolve to a SKILL.md
  - intercom               # ludus/skills/intercom/SKILL.md
  # ...

competencies:              # Tier 2 — soft abilities, documented in SOUL.md only
  - task-delegation
  # ...

runs_on: []                # empty = not yet deployed; when deployed, list specific hostnames

Field rules:

Field	Rule
`wing`	Must match a wing key in `infra/inventory/group_vars/all/wings.yaml`
`escalates_to: human`	Reserved for agents that report directly to the CEO
`cross_wing: true`	Use for orchestrators and entry points; false for specialists
`tools`	Binaries only — do not duplicate in `skills:`
`skills`	Only entries with a backing `SKILL.md`. Anything else → `competencies:`
`competencies`	Free-form; no validation. Match phrasing to SOUL.md where possible
`runs_on`	Which production hosts this agent is deployed to; empty = not yet deployed

Step 4 — Validate

Run from ludus/:

uv run ludus staff registry --check

Expected output: OK — N agent(s) validated

If you see VALIDATION ERRORS:

A skill entry has no backing SKILL.md → move it to competencies: or create the SKILL.md
Re-run until clean

Step 5 — Regenerate and commit

uv run ludus staff registry
git add agents/<name>/ROLE.yaml agents/capabilities-registry.yaml
git commit -m "feat: add ROLE.yaml for <name> agent; regenerate capabilities registry"

Both files must be committed together — the registry is the generated snapshot, not a derived artifact to be gitignored. The registry lives at ludus/agents/capabilities-registry.yaml alongside the agent directories.

Common mistakes

Mistake	Fix
Listing a skill that has no SKILL.md	Move to `competencies:` or create the SKILL.md first
Duplicating a tool name in `skills:`	Tools (binaries) belong only in `tools:`, not `skills:`
Copying SOUL.md behavioral directives into ROLE.yaml	ROLE.yaml is for infra tooling — personality stays in SOUL.md
Setting `escalates_to: human` for a non-CEO-facing agent	Only the top-level orchestrator escalates to human
Forgetting to regenerate the registry after writing ROLE.yaml	Always run `ludus staff registry` and commit the updated YAML

name: create-agent-role description: Create a ROLE.yaml for an agent in ludus/agents//. Use when onboarding a new agent or formalizing an existing one into the capabilities registry.​

Create Agent Role

Step 1 — Read the agent's existing docs​

Step 2 — Resolve available skills​

Step 3 — Write the ROLE.yaml​

Step 4 — Validate​

Step 5 — Regenerate and commit​

Common mistakes​