Maestro, agents, and skills

Maestrly can split work across several agents. A conversation can delegate to subagents, Maestro can coordinate a pool of agents for you, and skills add focused procedures any agent loads when a task needs them. Start small: one conversation and a few well-written agents and skills go further than a large configuration you have not tested.

Standard and Maestro conversations

A Standard conversation runs one model directly. Switch its mode in the composer (⇧Tab cycles them): Agent reads, edits files, and runs commands; Design builds navigable UI prototypes with mock data; Plan investigates with restricted tools and proposes a plan; Ask answers without changing code.

Maestro puts an orchestrator model in charge. It coordinates read-only and routes executable work, tests, and review to the agents in its Agent Pool. Maestro needs a project. Choose Maestro under Conversation experience when you create a conversation, or Use Maestro in the mode menu of a Standard conversation; the history is kept. Use model directly leaves Maestro again.

Configure Maestro

Open Settings → Maestrly Chat → Maestro:

Strategy: Balanced, Best quality, Fast, or Economy.
Orchestrator profile: the model that coordinates.
Agent Pool: each agent has a name, a description, Agent instructions, a Capability (Worker or Read-only), Specialties, and Execution candidates and fallbacks. Candidates are provider and model pairs tried in order, so one pool can mix providers and accounts. An agent without candidates inherits the orchestrator profile. Import agents adds your agent definitions to the pool.
Save global default, or Save as new to keep a named strategy you can reuse.
The Configuration assistant proposes changes from a description, such as "replace this model across the pool"; review them, then Apply to draft.

In a conversation, Maestro controls lets you Save conversation override or Use global. Settings are frozen at the start of each turn, so changes apply on the next one. While a run is active, send your message to the Current run or the Next turn, and follow it in Live Maestro status.

Agents and subagents

An agent definition is a Markdown file: frontmatter plus the instructions the agent follows.

---
name: test-writer
description: Writes focused unit tests for one module and runs them.
tools: read, grep, glob, edit, write, bash
---
Follow the project's test conventions. Cover edge cases and report what you ran.

Put project agents in .agents/agents/ or .claude/agents/, and personal ones in ~/.agents/agents/ or ~/.claude/agents/. A project agent wins over a global one with the same name.
Optional fields: tools (without it, the agent gets read-only tools), category, and provider, model, and effort together for a fixed execution profile.
Two agents are built in: explore, a read-only search agent, and general-purpose, a worker with full tools. A definition with the same name replaces them.

During a turn, the main agent can hand a self-contained task to a subagent, which works in its own context and returns a report. Turn delegation on or off with + → Subagents → Allow subagents in this conversation. Since 0.9.3, independent subagent tasks run in parallel in Claude and Codex conversations. A subagent card opens Subagent execution, with its transcript, model, duration, and Estimated cost.

To route work yourself, type # and pick an agent in the composer, such as #explore. Asking in words ("use test-writer to…") also counts.

Subagent execution profiles

The Subagents section of Settings → Maestrly Chat → Models & agents sets provider, model, effort, and speed for subagents: a rule for All subagents, plus the rules you add with Add a rule for a category and Add a rule for an agent. Each rule can chain fallback models, tried in order when the previous one fails or is unavailable. The most specific rule wins (agent, then category, then default), and conversation rules beat global ones. Same as the conversation uses the delegating conversation's model, reasoning, and speed. Since 0.20.0, every model there shows as a chip and picking one saves it at once. A name in an agent rule with no definition file becomes a virtual agent based on general-purpose that you can call with #. Change a conversation's profiles from + → Subagent execution profiles.

Code and plan reviews

Since 0.19.0, a review is one independent, read-only pass that you steer, instead of an automatic loop. Review in the header of a project conversation, or /code-review in the composer, reviews the conversation's current changes: the committed difference from the default branch, staged and unstaged changes, and new files. Review plan in the drawer's Plan tab reviews a plan waiting for your decision.

The review moves through five stages:

Scope shows what will be reviewed and asks who reviews: This conversation's model, or Another model with its own effort and Fast setting. A different model tends to catch what the conversation's model misses. Nothing runs until you choose Start review.
Investigate: reviewers work in parallel and read-only, three for code (logic, integration, and security and tests) and two for plans (feasibility and completeness). You follow what each one reads and the findings it raises.
Verify: a verifier confirms each finding, discards it with a reason, or merges duplicates. Discarded findings stay visible.
Decide: one finding at a time, with its lines, evidence, and a suggestion. For code, choose Fix, Discuss, or Dismiss; for plans, Comment on the plan or Dismiss. J/K move between findings.
Hand off: for code, Send to the agent an editable message built from your decisions, with the full report attached, or Save the report only. For plans, your comments land on the plan's lines as a revision request, or you approve the plan as written.

From Start review until you hand off or discard the review, the conversation is paused: no turn runs and nothing can be sent. A receipt then stays in the conversation, and when the agent has finished, Check the fixes (or Check the revision) runs one more verifier pass over what you sent. A code review uses up to four runs of the reviewing model and a plan review up to three, counted in the conversation's usage. One review runs per conversation at a time; code reviews are not offered in multi-repository or archived conversations, and an open review is lost if the app closes before the hand-off. The earlier review loops were removed; older conversations keep their messages as history.

Plans

In Plan mode the agent proposes a plan in the drawer's Plan tab, and the sidebar shows Plan waiting for review. Read the plan, Edit it, see its Changes, comment on a section or leave a general comment, then Request revision, Approve, or Discard plan. To carry an approved plan elsewhere:

Implement in new conversation starts a Standard conversation in Agent mode with the model, effort, and Fast mode you choose. Same checkout works on this branch, including uncommitted changes; New worktree creates a branch from the current commit, without them. The current conversation keeps its model and mode. If the new one cannot start, it offers Retry start.
Implement with Maestro creates a Maestro conversation on the same branch, with the configuration, pool, and orchestrator profile you choose.

Send tasks to new conversations

In Agent, Design, or Ask mode, ask in your own words, such as "Open one conversation for each of these tasks and start development with Opus, high effort" or "Send another agent to review this." A message that asks explicitly starts the conversations directly. When your latest message does not ask in so many words, the chat lists what the agent wants to start and asks you to confirm with Start or Don't start. Text the agent read in files, web pages, or tool output can never answer for you; "don't open conversations" is respected, and no more than the number you state are started. By default each task gets its own worktree and branch from the current commit; uncommitted changes are not included.

Each new conversation gets a self-contained task, is marked Started from another conversation, and appears in the reply with an Open link. Up to 20 can start per request, and repeating the request does not create duplicates. It is not available in Plan or Maestro mode, in bot conversations, or in multi-repository conversations. Nothing is pushed, opened as a pull request, or merged automatically. To send work to another workspace, see Projects and Git.

To have the result brought back, say so ("open another agent to review this and bring me the result"). When the new conversation's first turn ends, its final answer arrives here as a message marked Result from …, and the agent continues with it.

Talk to other conversations

The agent can also read and message conversations that already exist, in any project or standalone chat. Ask in your own words: "What did the review conversation conclude?" or "Tell the Atlas conversation that the API changed, and bring me its answer."

The agent finds conversations by name, reads their latest answer and recent messages, and can wait for one to finish its turn.
A message it sends starts a turn in the other conversation, shown as Message from … with a link back. The receiving agent keeps its own mode, permissions, and model, so a message from an Ask chat cannot edit files anywhere it could not already. A busy conversation gets the message when its turn ends.
The first message to an unrelated conversation asks you to confirm with Send or Don't send. Conversations started from this one, the one that started it, and ones that already exchanged messages with it need no confirmation.
The other conversation's answer comes back here, as Result from …, only when you ask for it. A conversation that was given work can also report back, marked Report from …, when it is done or blocked.
Turns started by another conversation can only read and message linked conversations, never start new ones or create projects, and stop after three agent-to-agent turns since you last typed. The agent then tells you instead of continuing.

This works in Agent, Design, and Ask modes, not in Plan or Maestro mode, bot conversations, or subagents.

Skills

A skill is a folder with a SKILL.md and optional scripts/, references/, and assets/, loaded when the agent needs it. Global skills live in ~/.agents/skills, project skills in the project's .agents/skills; Maestrly also reads .claude/skills and .codex/skills.

Settings → Maestrly Chat → Skills: All lists global skills (New skill, View SKILL.md, Open folder); Groups bundles skills (New group); Library searches skills.sh, with Install and Install by slug/URL.
In a conversation, the Skills menu shows Skills in this conversation: choose an Active set (All skills, No skills, or a group) and set each skill to Inherit, On, or Off.
Invoke a skill yourself with / and its name. In its frontmatter, disable-model-invocation: true leaves it to you, and user-invocable: false leaves it to the agent.
Saved prompts in the Prompts tab can become skills with Convert to skill.

A good skill has a narrow trigger and a repeatable procedure: when it applies, what it needs, the steps and checks, and what a finished result contains. Write agent instructions as operating rules, and keep the actual task in the chat. Do not repeat the same rule in an agent and several skills.

Plugins add skills named <plugin>:<skill> and subagents named <plugin>-<agent> that work with every model. See Plugins.

Test before reuse

Run a new or changed agent or skill in a small conversation and check that it:

uses only the tools the task needs;
asks before sensitive or irreversible actions;
stays inside the requested project and files;
runs the expected checks and reports results faithfully;
stops clearly when blocked.

Security

Agent and skill instructions can make tools read data or take actions. Treat imported agents and library skills as untrusted until you have read them, and install only from sources you trust. Do not put secrets in instructions. Subagents and Maestro workers act under the conversation's permission mode, so a broad mode applies to all of them. Behavior can change with the model: after switching provider or model, test again.

Next: Tools and MCP.