--- name: canvas-actions description: Create, manage, and interact with canvas HTML pages. Write visual UIs that users see in the AI Maestro dashboard, receive structured interactions when users click/submit/select, and update pages in response. Full lifecycle management for agent-rendered canvases. license: Apache-2.0 compatibility: Requires AI Maestro dashboard. Agent must have an ID registered in ~/.aimaestro/agents/. metadata: version: "1.1.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 canvas whenever the output is better experienced visually than as terminal text. ### Proactive triggers -- create a canvas when: - **User asks to see data visually**: "show me", "display", "visualize", "report on", "dashboard for", "chart of", "table of", "summary of" - **User asks for a form or config UI**: "let me configure", "settings for", "create a form", "let me pick", "I want to choose" - **User asks for an approval or review flow**: "let me approve", "review these", "I need to decide", "show me the options" - **User asks you to build something interactive**: "build me a", "create a page", "make a UI", "wizard for", "control panel" - **Your output has structured data**: test results, API responses, file listings, metrics, logs, comparisons -- anything that would benefit from sorting, filtering, or visual hierarchy - **Your output has actions the user should take**: approve/reject, select from options, configure settings, trigger operations - **You are presenting a status or progress report**: build status, deployment state, system health, task progress ### Do NOT use canvas for: - Quick one-line answers - Code that should go in a file - Terminal commands the user should run - Simple text responses **Default behavior: When in doubt, create a canvas.** A visual, interactive page is almost always more useful than a wall of terminal text. The user can always read it in the Canvas tab of the dashboard. ## 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 ` ``` **File listing / directory tree:** ```html ``` **Metrics / monitoring:** ```html ``` **Comparison / diff data:** ```html ``` ### Interactive features to always include | Data shape | Interactive features | |------------|---------------------| | List/table (5+ rows) | Sort by columns, search, filter by category/status | | Metrics/numbers | Color coding (green/yellow/red), thresholds, visual bars | | Status items | Filter by status, group by category, dismiss/acknowledge buttons | | Timeline/log entries | Newest-first sort, search, level filter (info/warn/error) | | Config/settings | Editable fields, save button via `maestro.send('submit', ...)` | | Approval items | Approve/reject buttons via `maestro.send('click', ...)`, comment field | ### Combining data + actions Pages can be both data-driven AND interactive with `maestro.send()`: ```html ``` ## 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 `