Miro

Miro

Use this skill for Miro board work through the REST API: board discovery, metadata lookup, board item reads for summaries or planning, guarded creation and updates for common board items, and Enterprise board export jobs when the operator has Discovery access.

Scope

• list accessible boards and fetch board metadata
• read board items by type for audit-safe context capture and summaries
• fetch specific sticky note, text, shape, connector, and frame items
• create or update sticky notes, text items, shapes, connectors, and frames only after preview and explicit operator grant
• create and inspect Enterprise board export jobs, including result/task lookup and export-link creation where the API supports it
• download completed Enterprise export links into local workspace artifacts
• classify missing credential, upstream auth/scope, rate-limit, and API errors
• refuse deletes and permission/share changes in this v1 skill

Credential Rules

Store Miro tokens in HybridClaw runtime secrets. Never paste a raw Miro token into the prompt, a helper argument, a shell environment dump, or a log.

Recommended setup order:

1. Browser admin: open the active HybridClaw admin URL ending in /admin/secrets and set the needed MIRO_* secrets.
2. Browser /chat or TUI fallback: /secret set MIRO_ACCESS_TOKEN "<oauth-or-access-token>" plus any needed Discovery or OAuth client secrets.
3. Local console fallback:

hybridclaw secret set MIRO_ACCESS_TOKEN "<oauth-or-access-token>"
hybridclaw secret set MIRO_DISCOVERY_ACCESS_TOKEN "<enterprise-discovery-token>"
hybridclaw secret set MIRO_CLIENT_ID "<miro-client-id>"
hybridclaw secret set MIRO_CLIENT_SECRET "<miro-client-secret>"

Use MIRO_ACCESS_TOKEN for normal board APIs. Required Miro scopes depend on the operation:

• board discovery and item reads: boards:read
• sticky notes, text, shapes, connectors, and frames: boards:write

Use MIRO_DISCOVERY_ACCESS_TOKEN only for Enterprise board export APIs that require boards:export. Enterprise export requires a Miro Enterprise plan, Company Admin role, and enabled eDiscovery.

For Miro OAuth app authorization, use the helper to build the authorize URL, store the callback code as MIRO_OAUTH_CODE, and then exchange the code through the gateway. The exchange request uses <secret:MIRO_CLIENT_ID>, <secret:MIRO_CLIENT_SECRET>, and <secret:MIRO_OAUTH_CODE> placeholders and captures access_token into MIRO_ACCESS_TOKEN and refresh_token into MIRO_REFRESH_TOKEN with captureResponseFields.

Do not try to verify either secret with bash, environment inspection, or by asking the model whether a secret exists. The model cannot inspect the gateway secret store. If the operator says the secret was set, build the helper request and pass the httpRequest object to the built-in http_request tool. Only say a secret is missing if the gateway or helper error explicitly says MIRO_ACCESS_TOKEN or MIRO_DISCOVERY_ACCESS_TOKEN is missing, unavailable, not set, or unresolved.

Default Workflow

1. Start with list-boards unless the board id is already known.
2. Fetch board metadata with get-board before summarizing ownership, sharing, or last-modified context.
3. Read board items with list-items, filtered by --type when the task is about a specific surface such as sticky notes, text, shapes, connectors, or frames.
4. For large boards, page with the returned cursor and keep summaries bounded to relevant item types and regions named by the operator.
5. For any board write, run approval-plan or --request first, show the preview, then wait for explicit approval.
6. Pass --operator-grant approve-miro-board-write only after approval for the exact board id, operation, and payload.
7. For Enterprise exports, use approval-plan export-create before creating an export job and approval-plan export-link before minting a download link. Pass --operator-grant approve-miro-export only after approval for the exact org id, board id or task id, and export format.
8. After export-results returns an exportLink, use capture-export to save the ZIP/PDF/HTML/SVG export under .generated-miro and return the helper's artifacts[] output.
9. Do not delete items, delete boards, or change board permissions through this skill.