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

.. code-block:: text

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

   .. code-block:: bash

      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:

   .. code-block:: bash

      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.