Miro Management

SKILL.md

---
name: miro-management
description: Manage Miro through the Miro REST API using OAuth 2.0, saved token files, or direct access tokens. Use when the user wants to connect a personal or local Miro integration, complete OAuth authorization, refresh tokens, list boards, inspect board items or members, create or delete common board content such as sticky notes, text, shapes, cards, and connectors, manage webhooks, export board data, preview write payloads safely, or send raw REST API calls in a reusable local workflow.
---

# Miro Management

Use this skill to work with Miro through the REST API.

## Quick start

1. Get the user's Miro app client ID, client secret, and redirect URI if using OAuth.
2. Prefer a local redirect URI such as `http://127.0.0.1:4000/auth/miro/callback`.
3. Use `scripts/miro_api.py` for OAuth, token refresh, board/item operations, exports, and raw API calls.
4. Start with:
   - `auth-url`
   - `serve-oauth-callback`
   - `list-boards`
   - `list-board-items`
5. Never bundle client secrets, refresh tokens, or live access tokens into the skill package.

## Auth modes

### OAuth mode

Use shell environment variables when possible:

```powershell
$env:MIRO_CLIENT_ID = '...'
$env:MIRO_CLIENT_SECRET = '...'
$env:MIRO_REDIRECT_URI = 'http://127.0.0.1:4000/auth/miro/callback'
```

Start the callback helper:

```powershell
python scripts/miro_api.py serve-oauth-callback --port 4000 --token-file .miro/tokens.json
```

Then generate the authorization URL:

```powershell
python scripts/miro_api.py auth-url
```

Open that URL, approve the app, and let the callback helper store the token payload.

### Direct token mode

If the user already has a working Miro access token, skip OAuth and use either:

```powershell
$env:MIRO_ACCESS_TOKEN = '...'
python scripts/miro_api.py list-boards
```

or a saved token file:

```powershell
python scripts/miro_api.py list-boards --token-file .miro/tokens.json
```

## Core workflow

### 1. Confirm access

Use a cheap check first:

```powershell
python scripts/miro_api.py list-boards --token-file .miro/tokens.json
```

### 2. Inspect a board

```powershell
python scripts/miro_api.py get-board --board-id <id> --token-file .miro/tokens.json
python scripts/miro_api.py list-board-items --board-id <id> --token-file .miro/tokens.json
```

### 3. Create or export content

```powershell
python scripts/miro_api.py create-sticky-note --board-id <id> "Hello from OpenClaw" --token-file .miro/tokens.json
python scripts/miro_api.py create-text --board-id <id> "Roadmap" --token-file .miro/tokens.json
python scripts/miro_api.py create-shape --board-id <id> "API Layer" --token-file .miro/tokens.json
python scripts/miro_api.py create-card --board-id <id> "Task" --token-file .miro/tokens.json
python scripts/miro_api.py export-board-items --board-id <id> --format markdown --output-file board-report.md --token-file .miro/tokens.json
```

### 4. Refresh when needed

```powershell
python scripts/miro_api.py refresh-token --token-file .miro/tokens.json
```

## Common commands

- `auth-url` — print the OAuth authorization URL
- `serve-oauth-callback` — run a local callback server and exchange the returned code for tokens
- `exchange-code` — manually exchange a copied authorization code for tokens
- `refresh-token` — refresh access using the stored refresh token
- `whoami` — test token with a lightweight boards call
- `list-boards` — list accessible boards
- `get-board` — get board details
- `create-board` — create a board
- `list-board-items` — list board items
- `export-board-items` — export board items to markdown, csv, or json
- `create-sticky-note` — create a sticky note
- `create-text` — create a text item
- `create-shape` — create a shape item
- `create-card` / `update-card` — create or update a card item
- `create-sticky-note` / `update-sticky-note` — create or update sticky notes
- `create-text` / `update-text` — create or update text items
- `create-shape` / `update-shape` — create or update shapes
- `create-connector` — connect two board items
- `list-board-members` — list board members
- `get-webhooks` / `create-webhook` / `delete-webhook` — manage webhooks
- `create-brainstorm-cluster` — drop a row of idea sticky notes
- `create-kanban-row` — create a lightweight kanban-style row
- `create-architecture-chain` — create connected architecture boxes
- `delete-item` — delete an item by type path + item id
- `preview-write` — preview a write request without sending it
- `raw` — send an arbitrary Miro API request with optional JSON body

## Mutation rules

For write calls:

1. Confirm the target board and item IDs.
2. Summarize the exact body and endpoint before sending when the change is not obviously desired.
3. Keep secrets and tokens outside the skill folder.
4. Prefer exporting API results to files instead of dumping giant payloads in chat.
5. Treat live board writes as real external actions, not harmless local tests.

## References

Read `references/miro-oauth-notes.md` for the Miro OAuth flow, token endpoint, redirect URI rules, and safe local storage guidance.
Read `references/miro-request-examples.md` for starter create/export commands and raw request examples.