/miro

name: miro
description: "Discover Miro boards, read board items for planning and summaries, prepare guarded board writes, and run Enterprise board export workflows through SecretRef-backed API requests."
user-invocable: true
requires:
  bins:
    - node
credentials:
  - id: miro-access-token
    kind: bearer
    required: true
    secret_ref:
      source: store
      id: MIRO_ACCESS_TOKEN
    scope: "api.miro.com/v2 boards:read boards:write"
    how_to_obtain: "Create a Miro OAuth app or access token with the narrowest needed board scopes. Set `MIRO_ACCESS_TOKEN` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set MIRO_ACCESS_TOKEN \"<token>\"` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set MIRO_ACCESS_TOKEN \"<token>\"`."
  - id: miro-discovery-access-token
    kind: bearer
    required: false
    secret_ref:
      source: store
      id: MIRO_DISCOVERY_ACCESS_TOKEN
    scope: "api.miro.com/v2 boards:export"
    how_to_obtain: "Enterprise admins can enable eDiscovery in Miro Enterprise Integrations. Set `MIRO_DISCOVERY_ACCESS_TOKEN` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set MIRO_DISCOVERY_ACCESS_TOKEN \"<token>\"` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set MIRO_DISCOVERY_ACCESS_TOKEN \"<token>\"`."
  - id: miro-oauth-client-id
    kind: oauth
    required: false
    secret_ref:
      source: store
      id: MIRO_CLIENT_ID
    scope: "https://miro.com/oauth/authorize"
    how_to_obtain: "Create a Miro app. Set `MIRO_CLIENT_ID` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set MIRO_CLIENT_ID \"<client-id>\"` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set MIRO_CLIENT_ID \"<client-id>\"`. Do this before token exchange."
  - id: miro-oauth-client-secret
    kind: oauth
    required: false
    secret_ref:
      source: store
      id: MIRO_CLIENT_SECRET
    scope: "https://api.miro.com/v1/oauth/token"
    how_to_obtain: "Set the Miro app client secret as `MIRO_CLIENT_SECRET` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set MIRO_CLIENT_SECRET \"<client-secret>\"` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set MIRO_CLIENT_SECRET \"<client-secret>\"`. Never paste it into prompts or helper arguments."
  - id: miro-oauth-code
    kind: oauth
    required: false
    secret_ref:
      source: store
      id: MIRO_OAUTH_CODE
    scope: "one-time OAuth authorization code"
    how_to_obtain: "After approving the Miro authorize URL, set the one-time code as `MIRO_OAUTH_CODE` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set MIRO_OAUTH_CODE \"<code>\"` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set MIRO_OAUTH_CODE \"<code>\"`. Exchange it immediately."
  - id: miro-refresh-token
    kind: oauth
    required: false
    secret_ref:
      source: store
      id: MIRO_REFRESH_TOKEN
    scope: "https://api.miro.com/v1/oauth/token refresh_token"
    how_to_obtain: "The helper captures this from Miro OAuth token responses with `captureResponseFields`; do not set it manually unless recovering a known stored token."
metadata:
  hybridclaw:
    category: productivity
    short_description: "Miro board discovery, item reads, guarded board writes, and Enterprise board exports."
    tags:
      - miro
      - whiteboard
      - boards
      - sticky-notes
      - diagrams
      - export
    related_roadmap:
      - R21.102
    issue: 1040
    stakes_tiers:
      green:
        - board-list
        - board-metadata-read
        - board-item-read
        - export-status-read
      amber:
        - sticky-note-create-update
        - text-create-update
        - shape-create-update
        - connector-create-update
        - frame-create-update
        - enterprise-export-create
        - enterprise-export-link
      red:
        - board-delete
        - item-delete
        - permission-share-change
    escalation:
      writes: confirm-each
      route: f14
    cost_measurement:
      system: UsageTotals
      sub_limit_key: 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 secr