--- 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](workflows/sprint_board.md) | | **Retrospective** | "retro", "retrospective", "what went well" | [workflows/retrospective.md](workflows/retrospective.md) | | **Brainstorm** | "brainstorm", "ideation", "ideas around" | [workflows/brainstorm.md](workflows/brainstorm.md) | | **Story Map** | "user story map", "story mapping", "user journey" | [workflows/story_map.md](workflows/story_map.md) | | **Kanban** | "kanban", "task board", "workflow board" | [workflows/kanban.md](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](references/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](references/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](references/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](references/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="", x=center, y=-100, font_size=48) ``` Centered above the first frame. Always present. ### Column frames ``` miro_create_frame(board_id, title="", 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](references/color-conventions.md) for the named-to-hex translation table. ### Stickies inside a frame ``` miro_create_sticky(board_id, parent_id=, content="...", 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=, end_item_id=, 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//`) 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](workflows/sprint_board.md): 4-column tracker - [workflows/retrospective.md](workflows/retrospective.md): 3-column reflection - [workflows/brainstorm.md](workflows/brainstorm.md): radial idea ring - [workflows/story_map.md](workflows/story_map.md): header + tasks + swimlanes - [workflows/kanban.md](workflows/kanban.md): N-column workflow board Optional power-user path: - [seed-boards.md](references/seed-boards.md): copy + personalize Miroverse templates the user has imported Read the relevant detail file before composing the tool sequence.