miro

Files (3)

• SKILL.md
• index.cjs
• miro.cjs

SKILL.md (first lines)

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

```bash
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.

## Command Contract

Run the colocated helper with Node:

```bash
node skills/miro/miro.cjs --help
```

Plan a request without contacting Miro:

```bash
node skills/miro/miro.cjs --format json plan "Summarize sticky notes on this Miro board"
```

Build the OAuth authorize URL:

```bash
node skills/miro/miro.cjs --format json oauth authorize-url \
  --client-id "<miro-client-id>" \
  --redirect-uri "http://127.0.0.1:1455/oauth2/callback" \
  --scope boards:read \
  --scope boards:write
```

After the operator approves the URL and stores the callback code with
`hybridclaw secret set MIRO_OAUTH_CODE "<code>"`, exchange it without exposing
the code or resulting tokens:

```bash

From HybridAIOne/hybridclaw, MIT.

More from HybridAIOne/hybridclaw