miro-workflow

name	miro-workflow
version	0.1.0
description	Compose Miro boards from natural-language requests by combining tools from miro-mcp-server. Use when the user asks to set up a sprint board, retrospective, brainstorming session, user story map, kanban, or any structured Miro layout. Do NOT use for single-tool calls (create one sticky), questions about Miro the product, read-only board inspection, generic diagrams not tied to Miro (use /diagram), or sprint scoping and feature documents (use /feature-scoping).
allowed-tools	["mcp__miro__miro_list_boards","mcp__miro__miro_create_board","mcp__miro__miro_get_board","mcp__miro__miro_update_board","mcp__miro__miro_create_frame","mcp__miro__miro_update_frame","mcp__miro__miro_get_frame","mcp__miro__miro_get_frame_items","mcp__miro__miro_create_sticky","mcp__miro__miro_update_sticky","mcp__miro__miro_create_sticky_grid","mcp__miro__miro_create_text","mcp__miro__miro_update_text","mcp__miro__miro_create_shape","mcp__miro__miro_update_shape","mcp__miro__miro_create_flowchart_shape","mcp__miro__miro_create_connector","mcp__miro__miro_update_connector","mcp__miro__miro_list_connectors","mcp__miro__miro_create_card","mcp__miro__miro_update_card","mcp__miro__miro_create_mindmap_node","mcp__miro__miro_list_mindmap_nodes","mcp__miro__miro_create_group","mcp__miro__miro_get_group_items","mcp__miro__miro_bulk_create","mcp__miro__miro_list_items","mcp__miro__miro_get_board_summary","mcp__miro__miro_get_board_content","mcp__miro__miro_copy_board","mcp__miro__miro_find_board"]

Miro Workflow Skill

Compose Miro boards from natural-language requests using the miro-mcp-server tools. The MCP exposes 91 atomic tools; this skill is the map.

---

Scope

If the request is a single-tool call ("create one sticky note"), a question about Miro the product, or read-only inspection ("what's on this board?"), exit and let Claude handle it directly. The skill's job is composition, not single-call wrapping. Routing happens via the description field, not this section.

---

The 5 workflows

Each workflow is a documented composition with default spatial values. Pick one based on intent:

Workflow	Trigger Phrases	Detail File
Sprint Board	"sprint planning", "sprint board", "sprint kickoff"	workflows/sprint_board.md
Retrospective	"retro", "retrospective", "what went well"	workflows/retrospective.md
Brainstorm	"brainstorm", "ideation", "ideas around"	workflows/brainstorm.md
Story Map	"user story map", "story mapping", "user journey"	workflows/story_map.md
Kanban	"kanban", "task board", "workflow board"	workflows/kanban.md

If the request doesn't match any of these, fall back to direct tool calls and ask the user what layout they want.

Optional: seed boards

Before falling back to from-scratch construction, check if the user has imported a Miroverse template into their account that matches the requested workflow. See seed-boards.md for the lookup pattern. Seed boards are an optional power-user path; they produce more polished output but require one-time setup. The from-scratch workflows below work without any setup.

---

Workflow selection guide

Goal: track sprint work?     → sprint_board (4 columns: Backlog, In Progress, Review, Done)
Goal: reflect on the team?   → retrospective (3 frames: Went Well, Could Improve, Action Items)
Goal: generate ideas?         → brainstorm (radial: central topic, 6 stickies in a ring)
Goal: map a product?         → story_map (header row + tasks + release swimlanes)
Goal: ongoing task flow?     → kanban (configurable column count)

Pick the workflow that matches the verb in the request (track, reflect, generate, map, manage). When in doubt, ask once.

---

Universal pre-flight (always run first)

Before any workflow:

1. Call miro_list_boards to confirm the user's boards.
2. If the user named an existing board, get its ID. If not, create a fresh board with miro_create_board.
3. Save the board_id for every subsequent call.

Do NOT skip pre-flight. Without board_id, every other call fails.

---

Spatial defaults (summary)

Full math in spatial-defaults.md. Quick reference:

Element	Default size	Default gap
Frame (column)	800 × 600	50px between frames
Sticky note	~200 × 200 (Miro auto-sizes)	40px between stickies
Connector	n/a	uses item IDs, not coords
Title text	font_size: 48	100px above first frame

Origin (0, 0) is top-left in the board; the first frame sits at (0, 0) and successive frames stack to the right at x = previous_x + 800 + 50.

---

Color conventions

Full table in color-conventions.md. Quick map:

Color	Used for
yellow	default, neutral content, tasks
green	positive (Went Well), Done, MVP
pink	concerns (Could Improve), Review
blue	In Progress, headers, activities
gray	Backlog, future, low priority

Match the prompt-defined colors in prompts/prompts.go for consistency with users who fire the MCP prompts directly.

---

Anti-patterns

These come up often. Avoid them.

1. Stickies floating outside frames. Always pass parent_id (the frame ID) when creating stickies inside a column. Otherwise the sticky lands at canvas root and looks orphaned.
2. Wrong coordinate origin for parented items. When parent_id is set, coordinates are frame-relative (NOT canvas-absolute). The frame's top-left is (0, 0) and the item's CENTER is placed at the given (x, y). So for an 800×600 frame, a sticky at (40, 40) will overflow the frame's left and top edges by ~half the sticky's size. To stay fully inside an 800×600 frame: x ∈ [100, 700], y ∈ [114, 486]. Center horizontally at x = 400.
3. Frame color requires CSS hex, not a named color. The Miro API returns 2.0703 invalid hex string for named colors ("green", "blue", etc.) on frames. Pass hex like "#A6E5BB". Stickies, in contrast, accept named values like "light_green", "yellow", "light_pink". See color-conventions.md for the named→hex translation table.
4. Missing board_id. Every create/update call needs it. Re-confirm after miro_create_board.
5. Sticky text > 280 chars. Miro truncates. Break into multiple stickies if longer.
6. Hand-rolled flowchart connectors with raw shapes. Use miro_create_flowchart_shape (auto-sized for diagrams) instead of miro_create_shape when building flowcharts.
7. Bulk creates without ordering. miro_bulk_create is fast but doesn't guarantee item order in the response. Don't assume index N = the Nth created item.
8. Skipping the title text. Every workflow board gets a title at the top (font_size: 48). Without it, boards look unfinished.

---

Troubleshooting

Common errors when calling the miro-mcp-server tools, with cause and fix.

Error	Cause	Fix
401 Unauthorized	MIRO_ACCESS_TOKEN missing or expired	Tell the user to set the env var; restart the MCP host
404 Not Found on board_id	Wrong board ID, or board outside the user's team	Re-run miro_list_boards to confirm the ID; ask the user which team
429 Too Many Requests	Too many tool calls in a short window	Use miro_bulk_create instead of individual calls; back off 5s and retry
400 Bad Request on sticky create	Invalid color name or parent_id not found	Check color is one of: yellow, green, blue, pink, gray, orange, cyan; confirm parent frame exists before creating children
Connector create fails with "item not found"	Bulk-create response order isn't guaranteed; the connector ran before the item ID was stable	Always create items, await the response, collect IDs, THEN create connectors in a second pass
Sticky text shows "..." (truncated)	Text exceeds Miro's ~280 char limit	Split the content into multiple stickies; keep each under 280 chars
Frame title doesn't appear	title was passed as empty string	Always provide a title; Miro renders the title bar regardless
Items overlap visually	Used canvas-absolute coords instead of frame-relative when parent_id was set	Use (0, 0) to mean "frame's top-left" when parented; not the canvas origin
Board URL returns 403	Board is in a team the user isn't a member of	Confirm the user's team via miro_list_boards; recreate the board in their team

If an error doesn't match anything above, return the raw error message to the user with the relevant tool name and the params you sent. Don't fabricate a diagnosis.

---

Bulk creation guidance

When a workflow needs more than ~5 items of the same type (e.g., 12 stickies in a sprint board), prefer miro_bulk_create over individual calls. Single round-trip, lower rate-limit pressure. Trade-off: response order isn't guaranteed, so don't rely on indices for downstream connector calls; use returned IDs.

For workflows that need connectors between items, create items first (collect IDs), then connectors in a second pass.

---

Common building blocks

All 5 workflows share these pieces:

Title

miro_create_text(board_id, content="<Workflow Name>", x=center, y=-100, font_size=48)

Centered above the first frame. Always present.

Column frames

miro_create_frame(board_id, title="<Column>", x=N*850, y=0, width=800, height=600, color="#A6E5BB")

N is the column index (0, 1, 2, ...). 850 = 800 frame + 50 gap. Frame color is a CSS hex string per anti-pattern #3 above; see color-conventions.md for the named-to-hex translation table.

Stickies inside a frame

miro_create_sticky(board_id, parent_id=<frame_id>, content="...", color="<color>", x=relative_x, y=relative_y)

parent_id is critical. Inside the frame, (0, 0) is the frame's top-left.

Connectors between items

miro_create_connector(board_id, start_item_id=<id_a>, end_item_id=<id_b>, shape="curved")

Use IDs from prior creation calls. Connectors don't need coordinates.

---

Output expectation

After completing any workflow, return:

1. The board URL (formed from board_id: https://miro.com/app/board/<id>/)
2. A one-line summary: "Created [workflow name] with [N frames, M stickies, K connectors]"
3. Any items skipped due to errors (with reason)

Never close out without the URL; that's the user's primary deliverable.

---

Pairing with MCP prompts

The miro-mcp-server ships 5 MCP prompts (create-sprint-board, create-retrospective, create-brainstorm, create-story-map, create-kanban) that produce procedural instructions identical to these workflows. The skill's job is to fire when the user phrases a request naturally (without invoking a slash-prompt). Both routes converge on the same compositions; that's intentional.

If the user explicitly fires /create-retrospective, defer to the prompt. The skill is for the implicit ask.

---

Best practices

✅ Do

• Run miro_list_boards first to confirm the user's workspace.
• Set parent on stickies that belong inside frames.
• Use color conventions consistently (green = positive, pink = concern, etc.).
• Bulk-create when N ≥ 5 same-type items.
• Return the board URL at the end.

❌ Don't

• Skip the title text.
• Use canvas-absolute coordinates for items inside frames.
• Create connectors before the items they connect exist.
• Assume bulk-create response order.
• Fire 91 tool calls when 5 will do.

---

Detailed workflow files

For each workflow (from-scratch construction):

• workflows/sprint_board.md: 4-column tracker
• workflows/retrospective.md: 3-column reflection
• workflows/brainstorm.md: radial idea ring
• workflows/story_map.md: header + tasks + swimlanes
• workflows/kanban.md: N-column workflow board

Optional power-user path:

• seed-boards.md: copy + personalize Miroverse templates the user has imported

Read the relevant detail file before composing the tool sequence.