--- name: canvas-actions description: Create and update interactive HTML pages (canvases) that the user sees in the AI Maestro dashboard, and handle what they click, submit or select. Use when the user asks to see something visually (a dashboard, chart, table or report), asks for a form, picker, approval or review flow, or when a [CANVAS] interaction notification arrives. Not for one-line answers, code or terminal commands. license: Apache-2.0 compatibility: Requires AI Maestro dashboard. Agent must have an ID registered in ~/.aimaestro/agents/. metadata: version: "1.2.0" homepage: "https://agentactions.org" repository: "https://github.com/agentmessaging/agent-actions" --- # Agent Canvas Create visual, interactive HTML pages that users see in the AI Maestro dashboard. Embed live data, receive structured actions when users interact, and update pages in response. ## When to use this skill Use a canvas when the user asks for something visual or interactive, or needs to act on the result. ### Create a canvas when: - **The user asks to see data visually**: "show me", "display", "visualize", "dashboard for", "chart of", "table of" - **The user asks for a form or config UI**: "let me configure", "settings for", "create a form", "let me pick", "I want to choose" - **The user asks for an approval or review flow**: "let me approve", "review these", "I need to decide", "show me the options" - **The user asks you to build something interactive**: "build me a", "create a page", "make a UI", "wizard for", "control panel" - **The user must act on your result**: approve or reject, choose among options, configure settings, trigger an operation - **A [CANVAS] notification arrives**: a user interacted with one of your pages (see Receiving Interactions) ### Do NOT use canvas for: - Quick answers, summaries or status updates the user did not ask to see as a page - Code that should go in a file - Terminal commands the user should run - Ordinary command output (test results, logs, file listings): report it in text **Default: answer in text.** A canvas is for when the user wants a page or needs to act; it costs the user a switch to the Canvas tab. ## Architecture: Data-Driven Interactive Pages **CRITICAL: Canvas pages must be data-driven, not static HTML.** Never hardcode data into HTML elements. Always embed data as JSON in a ` ``` ### Why this pattern matters | Approach | Result | |----------|--------| | Static HTML `` with hardcoded rows | Dead page. User can only read. No sorting, no filtering, no search. | | Embedded JSON + JS rendering | **Interactive page.** User can sort columns, filter by status, search by name. Same data, 10x more useful. | ### Data block rules 1. **Always use ` ``` ## Your Canvas Directory Every agent has a canvas directory where HTML files are stored: ``` ~/.aimaestro/agents//canvas/ ├── dashboard.html # Your pages go here ├── reports/ │ └── weekly.html # Subdirectories supported └── interactions/ # User actions land here (auto-created) └── 2026-05-18T15-30-00-000Z-uuid.json ``` Find your agent ID: ```bash # From environment (set by AI Maestro) echo $AIM_AGENT_ID # Or find it in the registry cat ~/.aimaestro/agents/registry.json | jq '.agents[] | select(.name == "your-agent-name") | .id' ``` ## Creating Canvas Pages Write self-contained HTML files to your canvas directory. The dashboard renders them in a sandboxed iframe with the Canvas tab. ```bash cat > ~/.aimaestro/agents/$AIM_AGENT_ID/canvas/page.html << 'HTMLEOF' Page Title
HTMLEOF ``` ### maestro.send() API Use `maestro.send(action, element, data)` to send user interactions back to your agent. The `maestro` object is automatically injected by the dashboard; you don't need to define it. ```javascript maestro.send(action, element, data) ``` | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `action` | string | Yes | What happened (see Standard Actions below) | | `element` | string | No | Which UI element was acted on (id, name, or label) | | `data` | object | No | Arbitrary key-value payload | ### Standard Actions | Action | Use case | Example | |--------|----------|---------| | `click` | Button press, link activation | `maestro.send('click', 'deploy-btn', { env: 'prod' })` | | `submit` | Form submission | `maestro.send('submit', 'config-form', { name: 'api', timeout: 30 })` | | `change` | Input value changed | `maestro.send('change', 'search-input', { value: 'query text' })` | | `select` | Option selected | `maestro.send('select', 'priority', { value: 'high' })` | | `toggle` | Boolean switch | `maestro.send('toggle', 'dark-mode', { enabled: true })` | | `dismiss` | Modal/alert dismissed | `maestro.send('dismiss', 'alert-42', { acknowledged: true })` | | `navigate` | Tab/page switch in canvas | `maestro.send('navigate', 'settings-tab', { tab: 'advanced' })` | | `custom` | Anything else | `maestro.send('custom', 'drag-drop', { from: 'A', to: 'B' })` | Custom actions beyond this list are fine. The `action` field is freeform. ## Canvas Rules HTML must be **self-contained**: - Inline all CSS (in `