feat: add miro-agent skill with CLI, MCP, and browser tool routing

[mirowolff]

Summary

• Adds skills/miro-agent/ — a skill that routes Miro board interactions to the optimal tool (MCP, miroctl CLI, or agent-browser)
• Includes full + quick references for all three tools, a preflight script, and a tool selection guide
• Includes an end-to-end test playbook (see below)

DEPENDENCY: oAuth flow in CLI

Files

File	Purpose
SKILL.md	Routing rules, preflight, tool matrix, gotchas, error handling
agents.md	Maintenance instructions for keeping the skill updated
reference/miroctl.md + miroctl-quick.md	CLI reference (full + index with line pointers)
reference/miro-mcp.md + miro-mcp-quick.md	MCP reference (full + index with line pointers)
reference/agent-browser.md + agent-browser-quick.md	Browser reference (full + index with line pointers)
reference/tool-selection.md	Overlap resolution and fallback chains
scripts/preflight.sh	Checks miroctl install/auth and agent-browser availability
scripts/test-playbook.md	End-to-end test suite

Test Playbook

The playbook (scripts/test-playbook.md) validates the skill end-to-end on a fresh board:

Test Setup

Creates a temporary board via miroctl boards create, runs preflight, verifies MCP connectivity.

Part 1 — CLI tests (18 tests):

• Frame two-step creation (create + update for position/size/style)
• Sticky note, shape, text, card creation
• Connector between items
• Tag create + attach
• Image upload from local file
• Embed creation
• Screenshot capture via agent-browser + upload
• Image from URL
• Document file upload (PDF)
• Item deletion
• List/filter items by type
• Get specific item
• Boards list with --all (offset-based pagination)
• Minimum limit validation (--limit 5 should fail with 400)

Part 2 — MCP tests (13 tests):

• context_explore — discover board structure
• context_get — AI summary of frame contents
• board_list_items — filtered by type
• doc_create / doc_get / doc_update — full document lifecycle
• diagram_get_dsl + diagram_create — flowchart creation
• table_create / table_sync_rows / table_list_rows — table lifecycle with filtering
• image_get_data / image_get_url — image retrieval

Cleanup:

Deletes the test board and temp files.

What to watch for: Tool routing correctness, quick ref usage (not loading full refs), frame two-step pattern, sleep after upload, board ID quoting, --all caveat on cursor-based endpoints, minimum limit enforcement, MCP→CLI fallback behavior.