miro-board

name	miro-board
description	Generates Miro board content in two modes:
version	1.0.0
tags	["miro","visual","diagramming","collaboration","api"]
metadata	{"skill-author":"Marie-Lynne Block"}

What this skill does

Generates Miro board content in two modes:

• API mode — Python code using the Miro REST API v2 to programmatically create a board with frames, sticky notes, shapes, connectors, and text.
• Prompt mode — A structured natural-language prompt ready to paste into Miro AI (or to use as a manual build guide) when API access is not available.

Supports the following analyst board types:

Board type	Use case
User story map	Epics across top, stories in columns below, personas as swim lanes
Process flow	AS-IS or TO-BE swim-lane diagrams
Stakeholder map	Influence × interest grid
Gap analysis	Current state / gap / target state columns
Impact/effort matrix	2×2 prioritisation quadrant
Retrospective	Start / Stop / Continue (or 4Ls, Mad-Sad-Glad, etc.)
Affinity map	Clustered sticky notes from research data

When to use it

• User wants to create or populate a Miro board from existing content (stories, process notes, stakeholder list, etc.).
• User asks to "make a Miro board", "visualise this in Miro", or "create a [board type] in Miro".
• User has content from another skill output (e.g., write-user-story, stakeholder-map) and wants it on a board.
• User wants a Miro AI prompt to generate a board without writing API code.

Prerequisites (API mode)

• A Miro account with a board created (or the skill will create one).
• A Miro personal access token or OAuth token: developers.miro.com.
• Python with requests installed (uv pip install requests).

Instructions

Step 1 — Identify the board type and content

Ask the user (if not stated):

1. Which board type from the list above?
2. What content to populate it with? (stories, process steps, stakeholder names, etc.)
3. Which mode — API or prompt?

Step 2 — Choose the output mode

API mode — use when:

• User has a Miro access token.
• Content is structured and repeated (many sticky notes, large story maps).
• User wants a reproducible, scriptable board.

Prompt mode — use when:

• User wants to use Miro AI or build manually.
• No API token is available.
• Content is small enough to describe in text.

Step 3 — Generate the output

Follow the board-type instructions below, then produce the output using the format for the chosen mode.

---

Board type instructions

User story map

• Create a frame for the entire board.
• Add epics as a horizontal row of shapes at the top (one shape per epic, left to right in priority order).
• Under each epic, add user stories as a vertical column of sticky notes (blue by default).
• Add persona rows as a left-margin label if multiple personas are in scope.
• Add a release line (horizontal connector) to separate MVP stories from later releases.

Process flow (swim-lane)

• Create one frame per swim lane (actor or system).
• Add process steps as shapes (rectangles for tasks, diamonds for decisions) within each lane.
• Connect steps with connectors to show flow.
• Use colour to distinguish: happy path (green), exception path (orange), manual step (yellow).
• Add a start (circle) and end (circle with border) node.

Stakeholder map

• Create a 2×2 frame with axes: Influence (Y) × Interest (X).
• Quadrant labels: Manage closely (high/high), Keep satisfied (high/low), Keep informed (low/high), Monitor (low/low).
• Add each stakeholder as a sticky note in their quadrant.
• Colour-code by group (business, technical, external).

Gap analysis board

• Create three column frames: Current State | Gap | Target State.
• Add sticky notes per topic row (process, data, technology, people).
• Use red for gaps, green for target state items, grey for current state.
• Add a priority indicator (high/medium/low label) to each gap.

Impact/effort matrix

• Create a 2×2 frame with axes: Impact (Y) × Effort (X).
• Quadrant labels: Quick wins (high/low), Major projects (high/high), Fill-ins (low/low), Thankless tasks (low/high).
• Add each item as a sticky note in the appropriate quadrant.

Retrospective

• Create column frames per category (Start / Stop / Continue, or chosen format).
• Add sticky notes per observation.
• Use voting dots (circles) to indicate team consensus items.
• Add an action items frame at the right with owner and due date per action.

Affinity map

• Create an unsorted frame for raw input sticky notes.
• Create cluster frames for each theme (label at top).
• Move sticky notes into clusters.
• Add a theme label shape above each cluster.

---

Output format — API mode

"""
Miro board creator — [Board type]: [Title]
Requirements: pip install requests
Set MIRO_TOKEN env variable before running.
"""

import os
import requests

TOKEN = os.environ["MIRO_TOKEN"]
HEADERS = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json",
}
BASE_URL = "https://api.miro.com/v2"


def create_board(name: str) -> str:
    """Create a new Miro board and return its ID."""
    response = requests.post(
        f"{BASE_URL}/boards",
        headers=HEADERS,
        json={"name": name, "policy": {"permissionsPolicy": {"collaborationToolsStartAccess": "all_editors"}}},
    )
    response.raise_for_status()
    board_id = response.json()["id"]
    print(f"Board created: {response.json()['viewLink']}")
    return board_id


def add_sticky(board_id: str, content: str, x: float, y: float, color: str = "yellow") -> str:
    """Add a sticky note to the board."""
    response = requests.post(
        f"{BASE_URL}/boards/{board_id}/sticky_notes",
        headers=HEADERS,
        json={
            "data": {"content": content, : },
            : {: color},
            : {: x, : y, : },
        },
    )
    response.raise_for_status()
     response.json()[]


 () -> :
    
    response = requests.post(
        ,
        headers=HEADERS,
        json={
            : {: title, : , : },
            : {: x, : y, : },
            : {: width, : height},
        },
    )
    response.raise_for_status()
     response.json()[]


 () -> :
    
    response = requests.post(
        ,
        headers=HEADERS,
        json={
            : {: content},
            : {: (font_size), : },
            : {: x, : y, : },
        },
    )
    response.raise_for_status()
     response.json()[]


 () -> :
    
    response = requests.post(
        ,
        headers=HEADERS,
        json={
            : {: start_id},
            : {: end_id},
            : {: , : },
        },
    )
    response.raise_for_status()
     response.json()[]




 ():
    board_id = create_board()

    
    
    

    ()


 __name__ == :
    build_board()

The skill fills in build_board() with board-type-specific calls using the content provided by the user.

---

Output format — Prompt mode

## Miro AI prompt: [Board type] — [Title]

> Paste this prompt into Miro AI (board → AI assistant → "Generate board").

---

Create a [board type] Miro board titled "[Title]".

[Board-type-specific layout description]

Content to include:

[Structured list of items, epics, stakeholders, steps, etc.]

Formatting:
- Use [colour] sticky notes for [category].
- Use [colour] sticky notes for [category].
- Group related items in labelled frames.
- Add connectors between [items] to show [relationship].

---

Examples

Example 1 — User story map from epic content

Input: User provides an epic with 6 stories across 2 personas. Expected output (API mode): Python script that creates a board, adds the epic as a header frame, adds 6 sticky notes in columns beneath it, adds 2 persona label texts on the left margin, and draws a release line after story 3.

Example 2 — Stakeholder map (prompt mode)

Input: "Create a Miro stakeholder map for these 8 people: [list with influence/interest ratings]." Expected output (prompt mode): A Miro AI prompt that describes the 2×2 grid, places each person in the correct quadrant, and colour-codes by team.

Example 3 — Gap analysis board

Input: "I have a gap analysis output from the gap-analysis skill. Put it on a Miro board." Expected output: Three-column board (Current State / Gap / Target State) with one row per topic, sticky notes colour-coded by priority, and a legend frame.

Notes

• Miro API coordinates use pixels; (0, 0) is the board centre. Lay items out on a grid with consistent spacing (e.g., 250px between sticky notes, 400px between columns).
• Sticky note colour values accepted by the API: "yellow", "light_yellow", "orange", "light_green", "cyan", "light_pink", "violet", "red", "light_blue", "blue", "dark_blue", "black", "gray", "dark_gray", "white".
• The Miro API rate limit is 100 requests per second per token. For large boards, add a small delay between calls.
• Prompt mode output quality depends on the Miro AI model version in use; review and adjust positions manually after generation.
• Board sharing policy defaults to "all editors can collaborate" — adjust the permissionsPolicy in create_board() if the board is sensitive.