How to build a multi-agent skill with Skill Graph

What Skill Graph does

A normal SKILL.md is one block of instructions, and the agent improvises how to divide the work. A graph skill writes that down: the steps (nodes), what each step hands the next (edges with named contracts), which steps start with a fresh context, what tools and model each step gets, and when work passes or fails.

Skill Graph is the editor for that file. It shows the file as a graph, checks it, lets you step through the plan, and compiles it into an orchestrating skill plus one subagent per step. It never runs a model itself; your agent does that with the files you export.

What you need (and what you don't)

You never have to write YAML. Everything below is done with the mouse on the canvas and in the Inspector, and the studio writes the SKILL.md for you. The editor on the left is there if you prefer typing.

A step does not need references to get its input: everything on its incoming edges reaches it on its own. Contracts, references, gates, models and tools are refinements; the defaults work without them.

Quick start

1. 1Pick a blueprint. Open Blueprints above the editor and choose the closest match, for example PR review or Ship a change. Blank graph gives you three nodes to start from.
2. 2Name it. Click an empty spot on the canvas, then fill in Skill name and When to use it in the Inspector. The description is what makes your agent pick the skill, so say when to use it: “Use when reviewing a pull request…”.
3. 3Shape the steps. Add nodes with + Node and connect them by dragging a node's right-hand handle onto another node. A connection means “this step needs that one's output”.
4. 4Say what each step does. Select a step and write its job in Prompt; every new step starts with a sensible one. Its inputs arrive on their own. To place one at a precise spot, use Insert input above the prompt.
5. 5Fix what the checker finds. The status next to the toolbar turns red when there are errors. Open Issues, click an issue to jump to its node, and fix it until it says Valid.
6. 6Walk through it, then export. Press Walk through plan to see the stages in order, then Export the kit and unzip it into your repository.

The workspace

The studio has four areas. Everything you do in one updates the others immediately.

Drag the dividers between areas to resize them. On a phone, switch between editor, canvas and details with the tabs above the workspace.

Node types

Each node has a type that decides its role in the plan. Steps of the same stage (no path between them) run in parallel.

On the canvas you set a step's label, type and prompt; everything else is under Advanced. The full list of fields, with the names used in the file, is in The file format.

Walking through the plan

Walk through plan plays the stages one at a time: the canvas highlights the steps of the current stage and the Agent plan tab follows along, showing what each step receives, which model and tools it gets, and what it returns. Use the arrows to step back and forth, pause to look closer, and the cross to leave.

The Agent plan tab also shows the load budget: how many tokens the agent reads when the skill triggers (just the plan) compared with one flat file holding every prompt.

Export and install

Export → Claude Code + Cursor kit (.zip) gives you everything below. Unzip it at the root of your repository and commit it; Claude Code and Cursor pick the files up from there.

Single SKILL.md is one self-orchestrating file for agents without subagents; Copy single SKILL.md puts it on your clipboard. Graph source (.md) downloads only the editable file. Exporting is blocked while the graph has errors.

To use it, ask your agent for the task the description names (or invoke the skill by name). It loads the plan, starts the subagents stage by stage and returns the last step's output.

Contracts

A contract names what must travel on an edge, for example tasks_json or findings, so the agent can check each handoff before the next stage starts. Edges work without one; add it where a wrong shape would derail the next step, such as a planner that must return JSON.

To add one, click an edge and type a name in Contract. It is defined for you as you type: as JSON when the name contains “json”, otherwise as Markdown. Below the name you can change its format and describe what a valid payload looks like. All of a skill's contracts are also listed in the Inspector when nothing is selected.

References

A step already receives everything on its incoming edges. A reference says where in the prompt an input belongs, or picks only part of it. The easy way: Insert input above the prompt lists exactly what this step can read, in plain words, and writes the reference at the cursor.

## @node: verifier
You audit findings without having seen how they were produced.

Findings to check:
{{workers.output}}

Keep a finding only if it cites concrete evidence. End with
GATE: PASS if every kept finding does, otherwise GATE: FAIL
and list what failed.

The most useful one is a step's own part of a JSON output. If a planner returns {"research": …, "review": …}, inserting “Only this step's part” into the Research step gives it just its own task instead of the whole plan.

A reference may only read from nodes that run before this one. If the checker says a reference is not upstream, add an edge from that node (directly or through others).

Fresh context

Tick Fresh context (under Advanced → Agent; isolated_context: true in the file) on a step that must judge work without being swayed by how it was produced, typically a verifier or reviewer. Its subagent starts with an empty context and receives only what its incoming edges carry.

On the canvas such a step wears a prior-context bias badge: the share of what its prompt reads that does not come through its own edges. 0% is what you want. Anything higher is flagged as a warning, naming the reference that leaks in, so you can remove it or add the missing edge.

Gates, checks and approvals

Three tools decide whether work passes, from strongest to softest. Checks and gates are under Advanced → Checks; an approval is its own node type.

• check: a command such as npm test that must exit 0. A program, not a model, decides.
• gate: written pass criteria. The step ends with GATE: PASS or GATE: FAIL; with on_fail: retry only the failed work is re-run, with the reason, up to max_retries times.
• approval: a node that stops and asks you before going on.

Mark how much a step can break with risk. wide steps (touching many files) should have a check. irreversible steps (publishing, migrations, deletions, payments) need an approval upstream and on_fail: stop. A missing approval before an irreversible step is an error that blocks export; the other gaps are warnings. A gate without on_fail stops and reports; set on_fail: retry to re-run the failed work.

- id: implement
  type: worker
  tools: [Read, Edit, Write, Bash]
  check: npm test          # a program decides it passed
  on_fail: retry
  max_retries: 2
  risk: wide
- id: approve
  type: approval           # you sign off here
- id: publish
  type: agent
  tools: [Bash]
  risk: irreversible       # needs an approval upstream
  on_fail: stop

Models and tools

Both live under Advanced → Agent. model picks which model runs a step. The menu offers Claude Code's aliases: haiku (fast and cheap, good for focused workers), sonnet (balanced), opus and fable (strongest, good for planners and verifiers). inherit leaves the field out, so the step runs on whatever model your Claude Code session uses. You can also type a full model id in the source.

The menu lists Claude models because the export writes Claude Code subagent files, whose model field only accepts Claude models. The Cursor rule and the single SKILL.md work with any agent and model.

tools follows least privilege: give a step only what it needs. Readers and reviewers usually need [Read, Grep, Glob]; only implementers need Edit, Write or Bash. MCP tools are written mcp__server__tool.

The file format

For people who prefer the editor: a graph skill is a normal SKILL.md. The frontmatter holds name, description, spec: skill-graph/1, a topology (nodes and edges) and contracts. The body holds one ## @node: id section per step with its prompt. Every field of a node:

topology:
  edges:
    - from: goal
      to: splitter
    - from: splitter              # fan out: one edge to each worker
      to: [worker_a, worker_b]
      contract: subtask_json
    - from: [worker_a, worker_b]  # fan in: both feed the verifier
      to: verifier
      contract: findings_array
contracts:
  subtask_json:
    format: json
    description: One key per worker, holding that worker's task.
  findings_array:
    format: markdown
    description: Numbered findings, each with evidence and a confidence.

from and to accept a single id or a list, so one entry can fan out to several workers or fan several in. Each contract has a format (json, markdown or text) and a one-line description.

Errors and warnings

The checker runs on every keystroke. Errors mean the agent could not follow the plan and block exporting. Warnings point at plans that run but are likely to go wrong. Click an issue to select its node.

Saving, sharing and privacy

Your graph is saved automatically in this browser and comes back when you return. Nothing is uploaded: parsing, checking and compiling all happen on your device.

Share copies a link with the whole graph compressed into the part after #, which browsers never send to a server. Very large graphs make long links; the studio warns you when a link may be too long for some apps.

Treat a graph from someone else like code from someone else. A graph opened from a link shows a yellow banner listing its commands, shell access, file edits, MCP tools and the steps with no tool limit (which may use every tool); read them before you export, because your agent will run those commands with those permissions in your repository. Opening a link replaces your saved graph, and Ctrl+Z on the canvas brings it back.

Keyboard and canvas

Troubleshooting

The canvas is empty and the header shows a red message.

The frontmatter could not be read. The file must start with ---, contain valid YAML, and close with another ---. The message names the YAML problem; indentation under topology: is the usual cause.

I lost my view of the graph.

Press the fit button (the frame icon, “Fit graph to view”) at the bottom left of the canvas. Loading a blueprint or opening a file also re-frames the graph.

My agent never picks the skill.

Agents choose skills by their description. Say what the skill does and when to use it, in the words a user would type.

Can I run a graph skill without subagents?

Yes. Use Export → Single SKILL.md: one file in which the agent plays every step itself, in order.

Does this page call a model or need an API key?

No. Skill Graph only checks and compiles your graph in the browser. Your own agent runs the exported files.