Agents should draw their work. Miro MCP lets them.

---
name: miro-session-map
description: Draw what the current agent session did, or is about to do, as a flowchart on a Miro board - steps, parallel branches, decision gates and where it ended. Use when the user says "map this session", "draw what we just did", "document this process on the board", or wants a visual record of a long agent run before reviewing its output.
---

# Map this session on a Miro board

A long agent session is a process nobody watched end to end. This skill turns it into one
flowchart a human can check in thirty seconds.

## Before drawing

1. Ask for the board URL if you don't have one. If the user gave a frame link
   (`?moveToWidget=<id>`), read that frame first with `canvas_read_as_svg` and draw inside it.
2. Reconstruct the session from evidence, not memory: the conversation, `git log --oneline`,
   `git diff --stat`, files you created, subagents you started, tests you ran. Every node must map
   to something that happened (or, for a plan, something you will do next).
3. Keep it to 8-15 nodes. Merge small steps. If the session had more than 15 real steps,
   draw one frame per phase instead of one crowded diagram.

## Drawing

1. Call `canvas_get_canvas_composer_skill` first (it is required), then
   `canvas_load_format_skill` with `format_name: "diagramming"` and `notation: "flowchart"`.
2. One Mermaid `flowchart LR` inside a `<foreignObject data-type="diagram">`:
   - start and end nodes as stadiums `([...])`
   - work as rectangles, decision gates as `{{...}}` with labeled `Yes` / `No` edges
   - parallel work (subagents, background jobs) as sibling branches from the same node
   - loops that actually happened (a failed test, a re-fetch) as edges back to the gate
3. Label nodes with the concrete thing, not the category: "Subagent: benchmark research", not
   "Research".
4. Under the diagram, add one line with the prompt that produced it, so the board explains itself.

## Miro gotchas

- A diagram widget sizes itself from the Mermaid source and cannot be moved or deleted with the
  canvas tools after creation. Choose its position first, then fit the frame around the rendered
  size.
- Its title chip floats just above it. Leave about 64px of empty space above the diagram.
- Children of a frame use frame-relative coordinates.
- Quote any label that starts with `/` (`a["/api/orders"]`) or Mermaid draws a parallelogram.

## Finish

Report the frame link (`<board>?moveToWidget=<frame id>`) and one sentence on what the map shows
that the transcript hides, such as a gate that failed twice.

---
name: miro-system-map
description: Read the current repository and draw how the system is put together today as a block diagram on a Miro board - runtimes, services, data stores, external APIs and the arrows that write data. Use when the user asks to "draw the current setup", "diagram the architecture", "show me how this repo fits together", or is onboarding onto an unfamiliar or agent-written codebase.
---

# Draw the current system as a block diagram

The goal is the picture a new engineer would draw after a week, produced from the code in ten
minutes. Draw what the code does today, not what the README says it should do.

## Gather facts from the code

1. Entry points: framework routes, API handlers, CLIs, workers, cron jobs.
2. Data: ORM schemas, migrations, connection env vars (names only, never values).
3. Outbound calls: SDK imports and `fetch` targets (email, payments, analytics, LLM providers).
4. Deployment: `vercel.json`/`vercel.ts`, Dockerfiles, IaC, CI workflows.
5. For every arrow you plan to draw, find the line of code that makes the call. If you can't find
   it, leave the arrow out.

## Drawing

1. Call `canvas_get_canvas_composer_skill` first, then `canvas_load_format_skill` with
   `format_name: "diagramming"`, `notation: "flowchart"`.
2. One Mermaid `flowchart LR`:
   - a `subgraph` per place the code runs (for example "Vercel: Next.js", "Worker", "Browser")
   - data stores as cylinders `[(...)]`
   - third-party services in one neutral color, your code in one color, data in a third
   - who calls whom as arrows. Label every arrow that writes or sends data
     ("writes orders", "sends receipts"); leave reads unlabeled
3. 10-15 nodes. If it needs more, draw a top-level map plus one frame per subsystem.
4. Title the frame with a question the diagram answers ("What is <project>, today?").
5. Add the prompt as a caption under the diagram.

## Miro gotchas

- Quote labels that start with `/` or contain brackets: `blog["/blog/[slug]"]`.
- Diagram widgets size themselves, and the canvas tools can't move them after creation. Size the
  frame to the rendered diagram, not to what you authored.
- Leave about 64px above the diagram for its floating title chip.

## Keep it private

A system map lists every endpoint, auth path and data store in one picture. That's the first page of a
threat model. Draw it on a board only your team can open, and never paste it into public docs or posts.

## Finish

Share the frame link and list anything surprising the map exposed, such as a service two
subsystems both write to, or a dependency no one documented.

---
name: miro-flow-trace
description: Trace one request, job or user action through the code and draw it as a UML sequence diagram on a Miro board, including auth branches, retries and error paths. Use when the user asks "what happens when...", "trace this flow", "how does X get from A to B", or needs to review a change to a request path they didn't write.
---

# Trace one flow as a sequence diagram

A sequence diagram answers one question: in what order do these parts talk, and what happens when
something fails? Pick exactly one flow per diagram.

## Trace it in the code

1. Start at the entry point the user named (route, handler, queue consumer, CLI command).
2. Follow the calls in order. For each hop write down the caller, the callee, the message (the
   function or HTTP call) and the file it happens in.
3. Record the branches that matter: auth paths, cache hit or miss, retries, the error the
   caller actually sees. Skip logging and metrics.
4. Participants are components (route handler, auth library, DB), not individual functions.
   Five to seven participants is plenty.

## Drawing

1. Call `canvas_get_canvas_composer_skill` first, then `canvas_load_format_skill` with
   `format_name: "diagramming"`, `notation: "uml_sequence"`.
2. One Mermaid `sequenceDiagram`. Use `alt` / `else` for branches and a nested `alt` for the
   failure case inside a branch. Dashed arrows (`-->>`) for responses. Remember that the
   body is XML, so `->>` not `->>`.
3. Message labels are the real call names from the code (`verifySession`, `POST /orders`),
   so a reviewer can grep for them.
4. Sequence diagrams render tall. Give the frame at least 1,300px of height and check the
   rendered size before placing the caption.

## Keep it private

Auth flows are the part of a system an attacker most wants mapped. Keep these frames on a team-only board,
and leave secrets out of the labels: name an env var if you must, never its value.

## Finish

Share the frame link and name the one step where you'd put a breakpoint or a test if this flow
broke in production.

---
name: miro-change-map
description: Draw what an agent changed as a before-and-after map on a Miro board - which parts were added, removed or rewired, and what that did to the behaviour or the numbers. Use when the user asks "what did you change", "show me before and after", "what's different now", or has to understand a large agent-made change (a refactor, a migration, a new pipeline, a tuned config) without reading all of it.
---

# Map a change as before and after

An agent can change more in an hour than a person can read in a day. The question a human needs
answered is small: what did it look like before, what does it look like now, and what did that do?

## Find the change, don't guess it

1. Work from evidence: `git diff --stat <base>...HEAD`, the files you touched, the config or
   prompts you edited, the benchmark or test output before and after.
2. Name the unit that changed. It is usually a flow (how a request moves), a structure (which
   parts exist and who calls whom) or a setting (the defaults a system runs with).
3. Write the before in three to six steps and the after in three to six steps, in the same
   vocabulary, so the two rows can be compared box by box.
4. If a number moved (accuracy, latency, cost, error rate), put the before and after values in
   the last box of each row. Only use numbers you measured or can point to.

## Drawing

1. Call `canvas_get_canvas_composer_skill` first, then `canvas_load_format_skill` with
   `format_name: "diagramming"`, `notation: "flowchart"`.
2. Draw two separate Mermaid `flowchart LR` diagrams in one frame, "Before" on top and "After"
   below it. (Miro lays out one diagram with two subgraphs side by side, which gets too wide.)
3. Colors: added = green, removed or broken = orange, changed = blue, unchanged = no fill.
4. Put a bold "Before" and "After" label next to each diagram. Diagram titles only show on hover.
5. Title the frame with the question it answers ("What changed when it met real data?") and
   add the prompt as a caption.

## Miro gotchas

- Miro treats every diagram as a 1600x900 box when you resize a frame, even though it renders
  smaller. Leave the frame at least that tall below the lowest diagram's top edge.
- Leave about 64px above each diagram for its floating title chip.

## Finish

Share the frame link and name the one box a reviewer should check first, usually the most
important green or orange one.

---
name: miro-decision-chart
description: Turn the numbers behind a hard technical decision into a chart on a Miro board, with the chosen option highlighted and the decision written underneath. Use when the user asks to "chart these results", "help me decide between", "visualize this benchmark/comparison", or needs to explain a trade-off (accuracy vs cost vs latency) to people who won't read the raw table.
---

# Chart a decision

A decision chart shows the options, the one you picked, and one sentence explaining why, in that
order. It is not a dashboard.

## Get the numbers right first

1. Take numbers only from a source you can point to: a benchmark output file, a query result, a
   design doc, a spreadsheet. Record where each one came from.
2. Choose one primary metric for the bars (accuracy, p50 latency, monthly cost). Secondary
   metrics go in a text label next to each bar, not in extra bars.
3. Sort options by the primary metric. Keep ranges as ranges ("38-40%"), not midpoints.

## Drawing

Miro has no native chart widget, so build a horizontal bar chart from shapes. The canvas SVG
format supports it well:

1. Call `canvas_get_canvas_composer_skill` first and use the Bright Paper palette it returns.
2. One frame. Title = the decision as a question ("Which tool search ships by default?").
   A one-line subtitle states the metric, the dataset and the unit.
3. Per option: a right-aligned `textArea` label, a `rect` bar whose width is proportional to the
   value (fix one scale, such as 14px per percentage point, and use it for every bar), and a
   `textArea` after the bar with the value and the secondary metrics separated by " / ".
4. Every bar in one neutral color, the chosen option in green with a bold label.
5. Under the bars, a light green rounded rect with the decision and the one reason that settled
   it ("four points behind the best at a quarter of the cost").
6. Caption with the source of the numbers.

## Finish

Share the frame link and state which number would change the decision if it moved, so the chart
can be redrawn when that number is re-measured.