miro-board— agent skill

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:

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, "shape": "square"},
            "style": {"fillColor": color},
            "position": {"x": x, "y": y, "origin": "center"},
        },
    )
    response.raise_for_status()
    return response.json()["id"]


def add_frame(board_id: str, title: str, x: float, y: float, width: float, height: float) -> str:
    """Add a frame (container) to the board."""
    response = requests.post(
        f"{BASE_URL}/boards/{board_id}/frames",
        headers=HEADERS,
        json={
            "data": {"title": title, "format": "custom", "type": "freeform"},
            "position": {"x": x, "y": y, "origin": "center"},
            "geometry": {"width": width, "height": height},
        },
    )
    response.raise_for_status()
    return response.json()["id"]


def add_text(board_id: str, content: str, x: float, y: float, font_size: int = 14) -> str:
    """Add a text label to the board."""
    response = requests.post(
        f"{BASE_URL}/boards/{board_id}/texts",
        headers=HEADERS,
        json={
            "data": {"content": content},
            "style": {"fontSize": str(font_size), "textAlign": "center"},
            "position": {"x": x, "y": y, "origin": "center"},
        },
    )
    response.raise_for_status()
    return response.json()["id"]


def add_connector(board_id: str, start_id: str, end_id: str) -> str:
    """Add a connector between two items."""
    response = requests.post(
        f"{BASE_URL}/boards/{board_id}/connectors",
        headers=HEADERS,
        json={
            "startItem": {"id": start_id},
            "endItem": {"id": end_id},
            "style": {"strokeColor": "#333333", "strokeWidth": "2"},
        },
    )
    response.raise_for_status()
    return response.json()["id"]


# ── Board content ──────────────────────────────────────────────────────────────

def build_board():
    board_id = create_board("[Board title]")

    # [Board-type-specific creation code goes here]
    # Example: add_frame, add_sticky, add_text, add_connector calls
    # with x/y coordinates laid out on a grid

    print("Done.")


if __name__ == "__main__":
    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.