Miro Management

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 Mir...

Security Scan

The skill appears to implement a legitimate Miro API client, but there are metadata inconsistencies (undeclared env vars / missing primary credential and a Python runtime requirement) that reduce transparency and make it harder to reason about secret handling — review the code and token handling before installing.

Purpose & Capability

The name, description, SKILL.md, reference docs, and the included scripts/miro_api.py consistently implement a Miro REST API client (OAuth flow, token refresh, board/item operations, exports, raw requests). The requested operations and code match the described purpose.

Instruction Scope

Runtime instructions focus on OAuth, token files, and direct tokens and explicitly warn not to bundle secrets. The skill exposes a raw request/preview-write capability which allows sending arbitrary API calls; the SKILL.md recommends confirming payloads before writes. The callback helper (serve-oauth-callback) and raw request functionality merit inspection in the script to ensure they only bind to localhost and do not leak data elsewhere.

Install Mechanism

No install spec (instruction-only) — lowers supply-chain risk. However, the package includes a Python script but the registry metadata lists no required binaries; the skill implicitly requires a Python 3 runtime to run scripts/miro_api.py. This omission is a transparency issue (the platform cannot warn users or provision the runtime automatically).

Credentials

The SKILL.md and script reference environment variables (MIRO_CLIENT_ID, MIRO_CLIENT_SECRET, MIRO_REDIRECT_URI, MIRO_ACCESS_TOKEN) and use local token files, but the registry metadata declares no required env vars or primary credential. The skill legitimately needs Miro credentials, but the metadata omission prevents automated gating and increases risk of accidental secret exposure.

Persistence & Privilege

always:false and normal model invocation settings are appropriate. The skill does not request elevated platform persistence or modify other skills. Note: because it can be invoked autonomously (the platform default), granting it access to live Miro tokens would allow it to perform API actions; restrict automatic invocation if you do not want background writes.

What to consider before installing

This skill appears to be a legitimate Miro API helper, but take these precautions before installing or enabling it: 1) Review scripts/miro_api.py (especially the serve-oauth-callback handler) to confirm it binds only to localhost and doesn't send tokens to unexpected endpoints. 2) Know that the skill expects Miro credentials (client ID/secret, redirect URI, or access token) even though the registry metadata doesn't declare them — don't place secrets inside the skill folder; prefer environment variables or a local token file with restrictive filesystem permissions. 3) Ensure you have a Python 3 runtime available; the metadata doesn't declare this dependency. 4) Be cautious with the 'raw' and 'preview-write' commands: they can send arbitrary API requests. 5) If you want to limit risk, require explicit user invocation (do not allow autonomous invocation) or avoid granting long-lived tokens; prefer short-lived or scoped tokens and review token storage location (.miro/tokens.json) for proper permissions. If you want a higher-assurance decision, request the full, untruncated miro_api.py serve-oauth-callback implementation and confirm no network calls target hosts other than miro.com/api endpoints.

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:

$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:

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

Then generate the authorization URL:

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:

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

or a saved token file:

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

Core workflow

1. Confirm access

Use a cheap check first:

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

2. Inspect a board

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

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

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.