К основному содержанию
скилл CX Codex

maestro-graph — скилл для Claude Code и Codex

Скилл maestro-graph для Claude Code и Codex, который проводит задачу по заранее написанному графу: спускает агентов на каждый узел, собирает их результаты и переходит к следующему шагу.

MIT ★ 238 обновлён 2026-10-17

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add ReinaMacCredy/maestro --skill maestro-graph -a claude-code
Открыть на GitHub

Что делает maestro-graph

Граф задаёт цепочку шагов в markdown-файле; maestro-graph крутит её, запуская детерминированные узлы сам и отдавая вам агентские и человеческие точки решения. Узел может читать дерево проекта (если профиль только на чтение) или писать в него и получать отзыв перед следующим шагом. Свой граф пишешь из reference — встроенные пресеты покрывают обзор кода, циклы исправления и советы коллегии.

Процесс линеен: спустил узел, дождался результата, перешёл к следующему. Независимые узлы крутятся параллельно. Если узел должен вернуть JSON-объект по схеме, maestro-graph парсит его из ответа агента — если сломается, переспрашивает дважды, потом падает. При превышении лимита (число узлов, циклов, ветвлений) граф останавливается с пометкой partial — переспустишь с новым лимитом.

Проектный граф требует явного доверия командой maestro graph trust, домашние и встроенные графы спускаются сразу. Каждый переход логируется в journal — смотришь через maestro trace.

Какие задачи решает

  • оркестрировать несколько агентов по фиксированному сценарию
  • запустить обзор кода по чек-листу с остановками на решениях
  • направить исправления ошибок через цикл проверки
  • собрать мнения нескольких профилей перед финальным выводом
  • повторить граф с другими параметрами без переписывания логики

Примеры запросов агенту

  • Запусти граф review-gate для этого PR с range=main..feature и tier=full
  • Проведи исправление через fix-loop с scope=async и check=npm run test
  • Напиши свой граф в my-graph.md и запусти maestro graph run --file my-graph.md brief="проверь архитектуру"

Как установить maestro-graph

1Через Skills CLI (Vercel)

npx skills add ReinaMacCredy/maestro --skill maestro-graph -a claude-code

2Вручную: положить файлы

~/.claude/skills/maestro-graph/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/maestro-graph/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о maestro-graph

Как установить maestro-graph в Claude Code?

Выполни в терминале npx skills add ReinaMacCredy/maestro --skill maestro-graph -a claude-code, затем открой ~/.claude/skills/maestro-graph/SKILL.md.

Что такое maestro-graph и зачем он нужен?

Это скилл, который автоматизирует цепочку агентских действий по графу: читает узлы, спускает агентов, собирает результаты и движется дальше. Подходит для повторяющихся процессов вроде обзора кода или циклов исправлений.

Как написать свой граф вместо встроенного пресета?

Создай markdown-файл с описанием узлов по образцу из references/authoring.md, запусти maestro graph run --file <путь> [параметры]. Если граф пригодится снова, скопируй его в .maestro/graphs или ~/maestro/graphs.

Исходный текст

SKILL.md · MIT
---
name: maestro-graph
description: Drive a pre-known multi-agent path as a maestro graph - run it by name or from a file you just wrote, pull each agent node with graph next, spawn it as a sub-agent under its maestro-<profile> definition, hand the result back with graph result, repeat until the verdict. A sub-agent node reads or writes as its profile allows, and the chat running the graph reviews every diff a writing node leaves; a node whose result another seat must accept is opened as a pane instead. Author a new graph from the reference when no preset fits.
review-date: 2026-11-28
---
<!-- maestro-skill-version: dev -->

# maestro-graph

Use when a task is a pre-known path with several agent steps: a review gate,
a research sweep, a judge panel, a fix loop. The path is one markdown graph
file; maestro holds the run, executes the deterministic nodes itself and
hands you only the agent and human nodes to spawn. maestro never starts a
model (Hub d78), so the loop below is yours on every harness. Design,
diagnosis and the SLP seat protocol stay outside graphs.

## Pick or write the graph

- `maestro graph list` shows every graph across the repo
  (`<repo>/.maestro/graphs`), the room (`~/maestro/graphs`) and the shipped
  set; a nearer file shadows a farther one by name. `maestro graph show
  <name>` prints one.
- A shipped preset fits: run it by name. `review-gate` takes `range=<git
  range>`, `tier=light|full`, `intent=<what the change is for>` and, on a
  re-run, `justified=<file:line reason per line>`; `fix-loop` takes `scope=<what to fix>` and
  `check=<command that must pass>` and drives a writing fixer for at most
  three rounds; `council` takes `brief=<neutral brief>` and
  `tier=lens|debate|debate-with-proof|high-risk` and runs the maestro-council
  protocol with you (the Lead) answering the draft and verdict nodes.
- Nothing fits: write a graph for the task from
  [references/authoring.md](references/authoring.md) and run it with
  `--file <path>`. Keep a good one by copying the file into a graphs
  directory (Hub d100; there is no save verb).

## The pull loop (executor subagent)

```text
maestro graph run <name>|--file <path> [key=value ...] [--limit k=v] --json > run.json
loop:
  envelope = read run.json (or maestro graph next <run> --json > run.json)
  if envelope.done: stop; the verdict, LIMIT stop or failed node is in it
  for each node in envelope.nodes (all at once, they are independent):
    kind human  -> stop and ask the user the prompt; feed the answer back
    kind agent  -> spawn a sub-agent with the node's profile and brief
  for each returned sub-agent:
    maestro graph result <run> <ref> --file <path>|--text "<result>"
  maestro graph next <run> --json
```

- A sub-agent node reads or writes as its profile allows: review lenses
  are read-only, `fixer` and `delegate` write. Review every diff a writing
  node leaves before the next node reads the tree. A node whose result
  another seat must accept is opened as a pane with
  `maestro work add --to <peer>` and its result handed back with
  `graph result` as before.
- `run` returns the first envelope, so the first `next` is implicit.
- Redirect every `--json` envelope to a file and read the fields you need
  out of it (`jq`, or one `python3 -c` line); never let it land inline. An
  envelope carrying several node briefs and their schemas routinely passes
  a harness output cap, and a truncated envelope costs a second read of the
  same bytes before the loop can continue.
- Every node in `nodes` is ready now; spawn them in parallel. Nodes that
  depend on one of them appear on a later `next`, as soon as their own
  inputs are in: only a `join` waits for a whole fan-out (Hub d82).
- `ref` is the node id, or `node@key` for one instance of a foreach.
- A node with a `schema` must return JSON of that shape. Write the
  sub-agent's answer to a file and pass `--file`; maestro extracts the
  first JSON block from prose or a fence. `PARSE_FAILED` with `retry:
  true` means re-ask that sub-agent for JSON matching the schema carried
  in the error (two retries); the third failure marks the node failed and
  the run ends with `failed`.
- `stopped: "LIMIT"` ends the run at a structural limit (`nodes`, `loops`,
  `fanout`, Hub d84) with `partial` state; rerun with `--limit <k>=<N>`
  when the cap, not the graph, was wrong.
- `GRAPH_UNTRUSTED` on a repo graph's function node: review the file the
  error names, then run the `maestro graph trust` command it gives and
  `graph next` again. Home and shipped graphs never ask.
- `maestro trace <run>` is the journal: every node transition and round.

## Spawning an agent node

The profile is a definition `maestro install` rendered for both harnesses
(Hub d83): `~/.claude/agents/maestro-<profile>.md` and
`~/.codex/agents/maestro-<profile>.toml`.

- Claude Code: the `Agent` tool with `subagent_type: "maestro-<profile>"`,
  `model: "opus"` (graph nodes are judgment and writing roles), and the
  node's `brief` verbatim as the task. A profile whose `harness` is codex
  (challenger, verifier, auditor, reviewer-correctness-codex) opens
  as a Codex pane with `--profile maestro-<profile>` instead; the Agent tool
  rejects its model.
- Codex: `spawn_agent` with agent type `maestro-<profile>` and the node's
  `brief` verbatim.

Send the `brief`, never the bare `prompt`: the brief is the prompt plus, when
a schema is declared, one sentence naming the required keys and any optional
keys, then the schema as a JSON block (Hub d843), so the agent answers in the declared
shape instead of its harness habit. It already
carries the run state the graph author placed in it. Add only what the harness needs to return
the answer (for example, "write your JSON answer to <path>"). Never merge
two nodes into one spawn and never run a function node's command yourself;
maestro already did.

## Executor team

`graph run` reports `executor` in every envelope (Hub d88): `subagent`
from a plain session, `claude -p`, `codex exec` or a desktop app; `team`
when the driver is a role pane of a running SLP team. Under `team` the
Lead is the driver and each agent node is one Peer work item (Hub d89);
the Lead is never a node and maestro still spawns nothing.

```text
Team Supervisor: maestro work add "run graph <name> <key=value ...>" \
                   --acceptance "the run's verdict"
Lead:            maestro work take <item>
                 maestro graph run <name> [key=value ...] --json
loop:
  envelope = the JSON just returned (or maestro graph next <run> --json)
  if envelope.done: maestro work return <item> "<verdict JSON>"; stop
  for each node in envelope.nodes without a work field:
    kind human -> answer it yourself: maestro graph result <run> <ref> --text "<answer>"
    kind agent -> maestro work add "<node.brief>" --to peer-<node.profile> \
                    --acceptance "one JSON object matching the schema in the brief" --json
                  maestro graph result <run> <ref> --work <new item id>
  for each node with a retry field (its item's body failed the schema):
    open a fresh item with node.brief and rebind exactly as above; two
    retries, the third failure fails the node
  for each node with a work field whose workState is RETURNED:
    read it (maestro status <item>), then maestro work accept <item>
    (or maestro work note <item> "<gap>" --rework for one retake)
  maestro graph next <run> --json
Team Supervisor: maestro work accept <item>
```

- One pane per profile: `--to peer-<profile>` opens the Peer lazily on the
  first item and sends later nodes of that profile to the same pane; each
  `work add` wakes the pane with `[from lead][<id> OPEN]`, so no hand prompt.
- A bound node stays in `nodes` with `work` and `workState` until its item
  is DONE; `next` then parses the item's returned body like any result
  (schema and all) and issues what depended on it. A body that fails the
  schema unbinds the node and lists it with `retry: {error, schema, work}`,
  twice at most (d843); a cancelled item fails the node.
- Bound nodes count toward `limits.fanout`; keep the fan-out under the
  number of Peers you are willing to open.
- Prompts to a Peer must open with a lowercase plain sentence; a brief that
  opens "You are ..." is swallowed as a slash command. The node prompts in
  the shipped presets already do.
- The graph runtime writes no SLP state: every `work add`, `accept` and
  `return` above is yours (A7).

## Hand-off

The verdict is the run's evidence on its work item (`maestro work show
<run>`); quote it in the return that asked for the gate. A graph that
misbehaved is a finding for the handback, not a card.

© ReinaMacCredy · MIT · ReinaMacCredy/maestro

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
maestro josstei Плагин maestro для Claude Code и Codex ведёт задачи по этапам: задаёт вопросы по проектированию, составляет план, подключает параллельных субагентов и проводит ревью. CX Codex ★ 489звёзд репо project-supervisor-orchestrator davila7 Субагент project-supervisor-orchestrator для Claude Code координирует сложные процессы с несколькими специализированными агентами. Он проверяет полноту данных и запускает агентов по очереди. CX Codex 1 563установок suede-graph-flo-xr JasonColapietro Скилл suede-graph-flo-xr сравнивает и отсеивает планы реализации до внесения правок в код. Запускает граф рассуждений, выбирает один вариант и тестирует сборку в изолированном дереве Git. CX Codex +1 ★ 121звёзд репо graph Yeachan-Heo Скилл graph запускает многошаговые пайплайны как ориентированные графы и после сбоя продолжает работу по журналу с незавершённых узлов. CX Codex +1 285установок multi-agent-patterns NeoLabHQ Скилл multi-agent-patterns для Claude Code помогает спроектировать систему из нескольких агентов. Включается, когда задачу можно разбить на части или одному агенту не хватает контекста. CX Codex +1 1 400установок maestro-e2e raphaelbarbosaqwerty Скилл maestro-e2e для написания и отладки E2E-тестов на Maestro: логины, регистрация, навигация, диалоги разрешений. Работает с iOS, Android, Flutter, React Native и вебом. CX Codex +1 543установок

Из того же набора10

Весь набор →
maestro-questionnaire Скилл maestro-questionnaire превращает нерешённый вопрос в Markdown-опросник для человека, у которого есть нужные ответы. Подходит для сбора информации асинхронно или на встрече. CX Codex +1 ★ 238звёзд репо maestro-coach Скилл maestro-coach для Claude и Codex, который разбирает непонятный вопрос по шагам и объясняет концепт за решением на реальном коде вашего репозитория. CX Codex +1 ★ 238звёзд репо maestro-bundle Скилл maestro-bundle управляет жизненным циклом связок SPEC, NOTES и VERIFY в фреймворке Maestro и передаёт контекст между сессиями агентов. CX Codex +1 ★ 238звёзд репо maestro-verify Скилл maestro-verify сверяет проверки с критериями приёмки, фиксирует вердикт и помогает закрыть рабочий пакет. Нужен перед передачей результата или закрытием задачи. CX Codex +1 ★ 238звёзд репо maestro-design Скилл maestro-design для разрешения блокирующих вопросов перед началом разработки: выбор архитектуры, моделирование, прототипирование и фиксация решений. CX Codex +1 ★ 238звёзд репо maestro-work Скилл maestro-work для Claude Code задаёт общий порядок работы плейбуков: бриф, правила для исполнителя и формат передачи результата. Он включается при делегировании задачи и ведении её записи в Maestro. CX Codex +1 ★ 238звёзд репо maestro-council Скилл maestro-council проводит совет по решению, которое дорого откатывать: изолированные участники, проверка общей посылки, перекрёстный допрос и один обязательный вердикт. CX Codex +1 ★ 238звёзд репо maestro-improve Скилл maestro-improve превращает накопленные уроки в минимальные правки доктрины и правил проекта. Помогает фиксировать опыт сессий без потери истории. CX Codex +1 ★ 238звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой