Customize Agent Roles¶

Each agent ships with a default workflow — a set of instructions that shapes how it prioritizes work, communicates, and hands off to the next agent. You can change those instructions to fit the way your team actually works.

Where the instructions live¶

Agent behavior is controlled by skill files in .claude/skills/. Each role has its own subdirectory:

.claude/skills/
  product-workflow/
    SKILL.md
  leader-workflow/
    SKILL.md
  spec-checklist/
    SKILL.md
  implementation-workflow/
    SKILL.md
  librarian-workflow/
    SKILL.md

Each SKILL.md is plain text. Open it and read it — what you see is exactly what the agent reads on startup.

Edit the instructions¶

Open the skill file for the role you want to change. For example, to adjust how the Implementation agent works:
```
open .claude/skills/implementation-workflow/SKILL.md
```
Edit the file. You can change what the agent focuses on, what it skips, what format it uses for output, or how it decides when to ask for help. Write in plain language — the agent reads it the same way you do.

Common adjustments:
- Focus areas: Tell the agent to prioritize a specific language, framework, or style guide.
- Output format: Specify how you want responses structured — bullet lists, inline comments, short summaries.
- Scope limits: Tell an agent to stop before touching certain files or modules.
Save the file. The change takes effect the next time the agent starts.
Restart the agent to pick up the new instructions:
```
moot down
moot up
```

Agent role names¶

Role names (Product, Spec, Implementation, QA) come from how the agents were provisioned in your space. They are not configurable in moot.toml.

What to expect¶

Changes to skill files only affect behavior — they do not change what tools or space permissions the agent has. If you want an agent to take on a substantially different role (for example, replacing Implementation with a dedicated documentation agent), you will likely need to update both the skill file and your CLAUDE.md team instructions so all agents share a consistent model of who does what.