[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6AD4F578H583C5SNG2A81WM":3,"skill-same:01M6AD4F578H583C5SNG2A81WM":83},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":31,"publishedAt":54,"linkOnly":55,"markdownContent":56,"markdownBody":57,"frontMatter":58,"refName":59,"commitSha":60,"skillDirectory":61,"forksCount":62,"repositoryHtmlUrl":63,"repositoryHomepageUrl":64,"ownerHtmlUrl":65,"ownerBlogUrl":66,"ownerDescription":67,"updatedAt":68,"install":69,"resources":82},"01M6AD4F578H583C5SNG2A81WM","create-canvas",null,"Author, validate, and debug canvas extensions that the agent can open in the GitHub Copilot app's side panel. Use when creating, reviewing, or troubleshooting a canvas extension — including its actions, inputs, rendered content, and the surrounding extension wiring (tools, hooks, lifecycle).","github\u002Fgh-aw","github","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F9919?v=4","01M6AC83DS133TPXFSP1DHNCC6","GitHub","01M6AD3VCZ4WKQSFSRTPN7N9DN",5633,"MIT","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fcreate-canvas\u002FSKILL.md",[18,23,26],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":27,"categoryName":28,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,9],"create canvas","create","canvas","Tools","when","side panel","author","wiring","extensions","panel","app","hooks","use","open","lifecycle","github copilot app","actions","content","debug","copilot","validate","github copilot","2026-11-10 10:12:30",false,"---\nname: create-canvas\ndescription: Author, validate, and debug canvas extensions that the agent can open in the GitHub Copilot app's side panel. Use when creating, reviewing, or troubleshooting a canvas extension — including its actions, inputs, rendered content, and the surrounding extension wiring (tools, hooks, lifecycle).\n---\n\n# Extension Canvas Authoring\n\nUse this skill when creating or debugging an extension canvas that integrates with the runtime canvas model.\n\nThe host app no longer participates in extension canvas registration. Extensions declare canvases directly to the runtime via the Copilot SDK on `joinSession`; the runtime routes provider callbacks (`canvas.open`, `canvas.action.invoke`, etc.) straight to the declaring connection; the host app just renders whatever URL the provider returns.\n\n## Authoring workflow (do this in order)\n\n1. **Decide the scope.** Project (`.github\u002Fextensions\u002F\u003Cname>\u002F`) is committed to the repo and shared with the team. User (`$COPILOT_HOME\u002Fextensions\u002F\u003Cname>\u002F`) is local to the current user. Session (`$COPILOT_HOME\u002Fsession-state\u002F\u003CsessionId>\u002Fextensions\u002F\u003Cname>\u002F`) is loaded only for the current session — ideal for a throwaway canvas for one conversation. Unless the request makes it obvious, ask before creating files — the choice changes who sees the extension, whether it's committed, and the resulting `extensionId`.\n\n2. **Scaffold via tool, don't hand-write the skeleton.**\n   ```\n   extensions_manage({ operation: \"scaffold\", kind: \"canvas\", name: \"\u003Cname>\", location: \"project\" | \"user\" | \"session\" })\n   ```\n   The canvas scaffold produces an `extension.mjs` with `joinSession({ canvases: [createCanvas({...})] })`, a working loopback HTTP server per instance, an example action, and `onClose` cleanup. Edit from there.\n\n3. **Edit the file.** Implement your `open`, `actions[]`, optional `onClose`, and (if needed) tools\u002Fhooks alongside.\n\n4. **Reload.** Call `extensions_reload`. Stale canvas instances flip to `stale`, then back to `ready` once the provider reconnects.\n\n5. **Verify.** Call `extensions_manage({ operation: \"list\" })` and `extensions_manage({ operation: \"inspect\", name: \"\u003Cname>\" })`. If the extension is marked failed, `inspect` surfaces the log file path and a tail — that log is the primary debugging surface.\n\n6. **Drive it.** Run the validation checklist below via `list_canvas_capabilities`, `open_canvas`, and `invoke_canvas_action`.\n\n## Extension shape\n\nA canvas extension is a Copilot CLI extension running as a forked Node process that speaks JSON-RPC over stdio to the CLI.\n\n- Entry file **must** be named `extension.mjs` (ES modules only; TypeScript is not supported).\n- Discovery scans only immediate subdirectories of `.github\u002Fextensions\u002F` (relative to git root), `$COPILOT_HOME\u002Fextensions\u002F`, and `$COPILOT_HOME\u002Fsession-state\u002F\u003CsessionId>\u002Fextensions\u002F`.\n- The runtime auto-derives a stable `extensionId` of `${source}:${name}` (e.g. `project:my-extension`); session-scoped extensions embed the session id as `session:\u003CsessionId>:\u003Cname>`.\n- `@github\u002Fcopilot-sdk` is resolved automatically by the CLI — do **not** add a `package.json` or `node_modules` for it.\n- `stdout` is reserved for JSON-RPC. **Never `console.log`.** Use `session.log(message, { level, ephemeral })`.\n- Tool names must be globally unique across all loaded extensions — collisions cause the second extension to fail.\n\n## `joinSession` signature\n\n```js\nimport { joinSession, createCanvas, CanvasError } from \"@github\u002Fcopilot-sdk\u002Fextension\";\n\nconst session = await joinSession({\n    canvases: [createCanvas({ \u002F* ... *\u002F })],\n    tools: [\u002F* optional *\u002F],\n    hooks: {\u002F* optional *\u002F},\n    onPermissionRequest: async (request) => ({ kind: \"approve-once\" }), \u002F\u002F optional\n});\n\u002F\u002F session.sessionId, session.workspacePath (string | undefined),\n\u002F\u002F session.send, session.sendAndWait, session.log, session.on, session.rpc\n```\n\n## Canvas API (`canvas.d.ts`)\n\n```js\nimport { createCanvas, CanvasError, joinSession } from \"@github\u002Fcopilot-sdk\u002Fextension\";\n\nconst canvas = createCanvas({\n    id: \"main\",                  \u002F\u002F unique within this extension\n    displayName: \"My canvas\",    \u002F\u002F human-readable label shown in host chrome\n    description: \"Short summary the agent sees in the system-prompt canvas catalog.\",\n    inputSchema: { \u002F* JSON Schema for open input (optional) *\u002F },\n    actions: [\n        {\n            name: \"do_thing\",        \u002F\u002F unique within this canvas; MUST NOT start with `canvas.`\n            description: \"...\",\n            inputSchema: { \u002F* JSON Schema (optional) *\u002F },\n            handler: async (ctx) => {\n                \u002F\u002F ctx: { sessionId, extensionId, canvasId, instanceId, actionName, input, host }\n                \u002F\u002F Return raw result; throw CanvasError(\"code\", \"message\") for errors.\n                return { \u002F* ... *\u002F };\n            },\n        },\n    ],\n    open: async (ctx) => {\n        \u002F\u002F ctx: { sessionId, extensionId, canvasId, instanceId, input, host }\n        \u002F\u002F Idempotent: same instanceId may arrive again after provider reconnect.\n        return {\n            url: \"http:\u002F\u002F127.0.0.1:\u003Cloopback-port>\u002F\", \u002F\u002F optional for native canvases\n            title: \"...\",   \u002F\u002F optional, shown in host chrome\n            status: \"...\",  \u002F\u002F optional, shown in host chrome\n        };\n    },\n    onClose: async (ctx) => {\n        \u002F\u002F Optional. Fire-and-forget; return value ignored.\n    },\n});\n```\n\nRuntime rules:\n- Action names starting with `canvas.` are reserved and rejected at declaration time.\n- Every `actions[]` entry must have a `handler`; missing handlers fall through to `CanvasError.noHandler()`.\n- Canvas-level `inputSchema` is validated before `open`; action-level `inputSchema` is validated before dispatch. Failure returns `canvas_input_invalid` with Ajv details.\n- Return raw values from action handlers; throw `CanvasError(\"code\", \"message\")` for errors.\n- `ctx.canvasId` (not `ctx.id`) is the canvas identifier in handler context.\n\n## Loopback server pattern\n\n```js\nimport { createServer } from \"node:http\";\nimport { createCanvas, joinSession } from \"@github\u002Fcopilot-sdk\u002Fextension\";\n\nconst servers = new Map(); \u002F\u002F instanceId → { server, url }\n\nasync function startServer(instanceId) {\n    const server = createServer((req, res) => {\n        res.setHeader(\"Content-Type\", \"text\u002Fhtml; charset=utf-8\");\n        res.end(renderHtml(instanceId));\n    });\n    await new Promise((r) => server.listen(0, \"127.0.0.1\", r));\n    const port = server.address().port;\n    return { server, url: `http:\u002F\u002F127.0.0.1:${port}\u002F` };\n}\n\nawait joinSession({\n    canvases: [\n        createCanvas({\n            id: \"my-canvas\",\n            displayName: \"My canvas\",\n            description: \"...\",\n            open: async (ctx) => {\n                let entry = servers.get(ctx.instanceId);\n                if (!entry) {\n                    entry = await startServer(ctx.instanceId);\n                    servers.set(ctx.instanceId, entry);\n                }\n                return { title: \"My canvas\", url: entry.url };\n            },\n            onClose: async (ctx) => {\n                const entry = servers.get(ctx.instanceId);\n                if (entry) {\n                    servers.delete(ctx.instanceId);\n                    await new Promise((r) => entry.server.close(() => r()));\n                }\n            },\n        }),\n    ],\n});\n```\n\nBind embedded servers to **loopback only** (`127.0.0.1`). The host only embeds loopback URLs. Push state updates to the iframe with Server-Sent Events (`\u002Fevents`).\n\n## ID model — three distinct identifiers\n\n- **`canvasId`** — the canvas *type* declared by the extension. Accepted by `list_canvas_capabilities` and `open_canvas`; not by `invoke_canvas_action`.\n- **`extensionId`** — auto-derived `${source}:${name}` (e.g. `project:triage-board`). Only pass it to disambiguate when two extensions declare the same `canvasId`.\n- **`instanceId`** — caller-invented handle for one running panel (slug or UUID). Two panels of the same canvas need two `instanceId`s. Validated against `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$` — max 128 chars, alphanumeric first character, then only `[A-Za-z0-9._-]`.\n\nExample: `open_canvas({ canvasId: \"triage-board\", instanceId: \"triage-1\" })` then `invoke_canvas_action({ instanceId: \"triage-1\", actionName: \"refresh\" })`.\n\n## Agent-side canvas tools\n\n```\n\u002F\u002F Open a canvas panel\nopen_canvas({ canvasId: \"my-canvas\", instanceId: \"my-canvas-1\", input?: {...} })\n\u002F\u002F Returns { instanceId, url? } — no extensionId needed unless two providers share the canvasId.\n\n\u002F\u002F Discover a canvas type's actions and input schema\nlist_canvas_capabilities({ canvasId: \"my-canvas\" })\n\n\u002F\u002F Invoke an action on an open panel\ninvoke_canvas_action({ instanceId: \"my-canvas-1\", actionName: \"do_thing\", input?: {...} })\n```\n\nRe-opening the same `instanceId` focuses the existing panel (the host emits `session.canvas.opened` with `reopen: true` and reloads the iframe without invoking the provider again).\n\n## Injecting instructions\n\n- **`additionalContext` from hooks** (everyday path). `onSessionStart` → once-per-session guidance; `onUserPromptSubmitted` → per-turn nudges. The runtime appends it as a `developer`-role message.\n- **`systemMessage` on `joinSession`** (system-prompt path):\n  - `{ mode: \"append\", content }` — append to the SDK foundation.\n  - `{ mode: \"customize\", sections: {...} }` — override individual sections (`identity`, `tone`, `safety`, `custom_instructions`, `runtime_instructions`, etc.) with `replace` \u002F `remove` \u002F `append` \u002F `prepend` \u002F transform-callback actions.\n  - **Do NOT use** `{ mode: \"replace\", content }` from an extension — it discards the entire SDK-managed prompt including safety guardrails.\n\n## State model\n\n**`instanceId` identifies the panel, not the data.** Never key persistent state by `instanceId` alone — iframes reload, extensions restart, and a fresh `instanceId` may be opened for the same logical content.\n\nPick the right storage scope:\n- **Per session \u002F workspace** — write artifact files into `session.workspacePath` (returned by `joinSession`). Lives alongside session artifacts, cleaned up with the session.\n- **Per user \u002F global** — write under `$COPILOT_HOME\u002Fextensions\u002F\u003Cextension-name>\u002Fartifacts\u002F`. Follows the user across sessions.\n- **Per artifact \u002F document** — key under a stable `documentId` or file path passed via `input`.\n- **In-repo, committed artifacts** — architecture diagrams, ADRs, design docs that belong in the repo. Write to a sensible repo path.\n- **Per panel (`instanceId`)** — only ephemeral UI state that genuinely should not survive a reload.\n\nResolve the owning ID in `open()` from `input`, load persisted state for that ID, and render. Two `instanceId`s for the same `documentId` should show the same content.\n\n## App theme tokens\n\nThe runtime mirrors the canvas theme contract onto your canvas document:\n- Root\u002Fbody attributes: `data-color-mode`, `data-dark-theme`, `data-light-theme`, `data-theme-source`, `data-theme-tone`, `data-visual-mode`, `pointer-on-hover` class.\n- Semantic tokens: `--background-color-default`, `--border-color-default`, `--text-color-default`, `--text-color-muted`, `--color-focus-outline`.\n- Type ramp: `--font-sans`, `--font-mono`, `--font-weight-semibold`, `--text-body-medium`, `--leading-body-medium`.\n- True-color: `--true-color-red`, `--true-color-red-muted`, `--true-color-blue`, `--true-color-blue-muted`.\n\n```css\nbody {\n    margin: 0;\n    background: var(--background-color-default, #ffffff);\n    color: var(--text-color-default, #1f2328);\n    font-family: var(--font-sans, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif);\n    font-size: var(--text-body-medium, 14px);\n    line-height: var(--leading-body-medium, 20px);\n}\n```\n\nOnly depend on the attributes, classes, and variables documented above — others are app-internal and can change.\n\n## Validation checklist\n\n1. **Discovery** — confirm your canvas appears in the `\u003Ccanvases>` section of the system prompt, then verify `list_canvas_capabilities({ canvasId })` returns your `actions[]`.\n2. **Open** — call `open_canvas({ canvasId, input? })`. Confirm you receive `{ instanceId, url? }` and no error.\n3. **Action** — call `invoke_canvas_action({ instanceId, actionName, input? })` and confirm correct response payload.\n4. **Input validation** — call `open_canvas` with input that fails `inputSchema`. Expect `canvas_input_invalid`.\n5. **Reserved verb rejection** — call `invoke_canvas_action(instanceId, \"canvas.open\", ...)`. Expect `canvas_reserved_action_name`.\n\n## Debugging\n\n1. `extensions_manage({ operation: \"list\" })` — is the extension loaded? Marked `failed`?\n2. `extensions_manage({ operation: \"inspect\", name: \"\u003Cname>\" })` — surfaces log file path and tail. Primary debugging surface.\n3. After editing, **always** `extensions_reload` before re-running RPC calls.\n4. To force iframe reload, call `open_canvas` again with the same `instanceId`.\n5. If not discovered at all, verify the file is named exactly `extension.mjs` and lives in an immediate subdirectory of `.github\u002Fextensions\u002F`, `$COPILOT_HOME\u002Fextensions\u002F`, or the session's extensions dir.\n\n## Sharing extensions via Gist\n\nUse `share_extension` \u002F `install_extension` tools. Gist format:\n- Flat file structure (subdirs encoded as `\\` in gist keys, decoded on install).\n- A `copilot-extension.json` manifest: `{ \"name\": \"\u003Cextension-name>\", \"version\": 1 }`.\n- `node_modules\u002F`, `dist\u002F`, `build\u002F`, `.git\u002F`, hidden dirs (except `.github\u002F`) skipped during share.\n- Per-file cap: ~1 MB; total cap: ~5 MB.\n\n## Common pitfalls\n\n- **`console.log` corrupts JSON-RPC.** Use `session.log()` for user-visible messaging.\n- Do not declare action names starting with `canvas.`.\n- Do not forget to wire a `handler` on every `actions[]` entry.\n- Bind servers to **loopback only**.\n- `open` may be re-invoked on provider reconnect — treat it as idempotent and rehydrate from durable storage.\n- Return raw values from action handlers; throw `CanvasError(\"code\", \"message\")` for errors.\n- The canvas context field is `ctx.canvasId`, not `ctx.id`.\n- Tool names must be globally unique across all loaded extensions.\n- `extension.mjs` only — `.ts` is not supported. The `@github\u002Fcopilot-sdk` import is auto-resolved; do not add a `package.json` for it.\n\n## Session object quick reference\n\n```js\nawait session.log(\"message\", { level?: \"info\"|\"warning\"|\"error\", ephemeral?: boolean });\nawait session.send({ prompt: \"...\", attachments?: [{ type: \"file\", path: \"...\" }] });\nconst response = await session.sendAndWait({ prompt: \"...\" });\nconst unsub = session.on(\"tool.execution_complete\", (event) => { \u002F* ... *\u002F });\n\u002F\u002F session.workspacePath — path to session workspace (string | undefined)\n\u002F\u002F session.sessionId — current session ID\n```\n\nKey event types: `assistant.message`, `tool.execution_start`, `tool.execution_complete`, `user.message`, `session.idle`, `session.error`, `permission.requested`, `session.shutdown`.\n","# Extension Canvas Authoring\n\nUse this skill when creating or debugging an extension canvas that integrates with the runtime canvas model.\n\nThe host app no longer participates in extension canvas registration. Extensions declare canvases directly to the runtime via the Copilot SDK on `joinSession`; the runtime routes provider callbacks (`canvas.open`, `canvas.action.invoke`, etc.) straight to the declaring connection; the host app just renders whatever URL the provider returns.\n\n## Authoring workflow (do this in order)\n\n1. **Decide the scope.** Project (`.github\u002Fextensions\u002F\u003Cname>\u002F`) is committed to the repo and shared with the team. User (`$COPILOT_HOME\u002Fextensions\u002F\u003Cname>\u002F`) is local to the current user. Session (`$COPILOT_HOME\u002Fsession-state\u002F\u003CsessionId>\u002Fextensions\u002F\u003Cname>\u002F`) is loaded only for the current session — ideal for a throwaway canvas for one conversation. Unless the request makes it obvious, ask before creating files — the choice changes who sees the extension, whether it's committed, and the resulting `extensionId`.\n\n2. **Scaffold via tool, don't hand-write the skeleton.**\n   ```\n   extensions_manage({ operation: \"scaffold\", kind: \"canvas\", name: \"\u003Cname>\", location: \"project\" | \"user\" | \"session\" })\n   ```\n   The canvas scaffold produces an `extension.mjs` with `joinSession({ canvases: [createCanvas({...})] })`, a working loopback HTTP server per instance, an example action, and `onClose` cleanup. Edit from there.\n\n3. **Edit the file.** Implement your `open`, `actions[]`, optional `onClose`, and (if needed) tools\u002Fhooks alongside.\n\n4. **Reload.** Call `extensions_reload`. Stale canvas instances flip to `stale`, then back to `ready` once the provider reconnects.\n\n5. **Verify.** Call `extensions_manage({ operation: \"list\" })` and `extensions_manage({ operation: \"inspect\", name: \"\u003Cname>\" })`. If the extension is marked failed, `inspect` surfaces the log file path and a tail — that log is the primary debugging surface.\n\n6. **Drive it.** Run the validation checklist below via `list_canvas_capabilities`, `open_canvas`, and `invoke_canvas_action`.\n\n## Extension shape\n\nA canvas extension is a Copilot CLI extension running as a forked Node process that speaks JSON-RPC over stdio to the CLI.\n\n- Entry file **must** be named `extension.mjs` (ES modules only; TypeScript is not supported).\n- Discovery scans only immediate subdirectories of `.github\u002Fextensions\u002F` (relative to git root), `$COPILOT_HOME\u002Fextensions\u002F`, and `$COPILOT_HOME\u002Fsession-state\u002F\u003CsessionId>\u002Fextensions\u002F`.\n- The runtime auto-derives a stable `extensionId` of `${source}:${name}` (e.g. `project:my-extension`); session-scoped extensions embed the session id as `session:\u003CsessionId>:\u003Cname>`.\n- `@github\u002Fcopilot-sdk` is resolved automatically by the CLI — do **not** add a `package.json` or `node_modules` for it.\n- `stdout` is reserved for JSON-RPC. **Never `console.log`.** Use `session.log(message, { level, ephemeral })`.\n- Tool names must be globally unique across all loaded extensions — collisions cause the second extension to fail.\n\n## `joinSession` signature\n\n```js\nimport { joinSession, createCanvas, CanvasError } from \"@github\u002Fcopilot-sdk\u002Fextension\";\n\nconst session = await joinSession({\n    canvases: [createCanvas({ \u002F* ... *\u002F })],\n    tools: [\u002F* optional *\u002F],\n    hooks: {\u002F* optional *\u002F},\n    onPermissionRequest: async (request) => ({ kind: \"approve-once\" }), \u002F\u002F optional\n});\n\u002F\u002F session.sessionId, session.workspacePath (string | undefined),\n\u002F\u002F session.send, session.sendAndWait, session.log, session.on, session.rpc\n```\n\n## Canvas API (`canvas.d.ts`)\n\n```js\nimport { createCanvas, CanvasError, joinSession } from \"@github\u002Fcopilot-sdk\u002Fextension\";\n\nconst canvas = createCanvas({\n    id: \"main\",                  \u002F\u002F unique within this extension\n    displayName: \"My canvas\",    \u002F\u002F human-readable label shown in host chrome\n    description: \"Short summary the agent sees in the system-prompt canvas catalog.\",\n    inputSchema: { \u002F* JSON Schema for open input (optional) *\u002F },\n    actions: [\n        {\n            name: \"do_thing\",        \u002F\u002F unique within this canvas; MUST NOT start with `canvas.`\n            description: \"...\",\n            inputSchema: { \u002F* JSON Schema (optional) *\u002F },\n            handler: async (ctx) => {\n                \u002F\u002F ctx: { sessionId, extensionId, canvasId, instanceId, actionName, input, host }\n                \u002F\u002F Return raw result; throw CanvasError(\"code\", \"message\") for errors.\n                return { \u002F* ... *\u002F };\n            },\n        },\n    ],\n    open: async (ctx) => {\n        \u002F\u002F ctx: { sessionId, extensionId, canvasId, instanceId, input, host }\n        \u002F\u002F Idempotent: same instanceId may arrive again after provider reconnect.\n        return {\n            url: \"http:\u002F\u002F127.0.0.1:\u003Cloopback-port>\u002F\", \u002F\u002F optional for native canvases\n            title: \"...\",   \u002F\u002F optional, shown in host chrome\n            status: \"...\",  \u002F\u002F optional, shown in host chrome\n        };\n    },\n    onClose: async (ctx) => {\n        \u002F\u002F Optional. Fire-and-forget; return value ignored.\n    },\n});\n```\n\nRuntime rules:\n- Action names starting with `canvas.` are reserved and rejected at declaration time.\n- Every `actions[]` entry must have a `handler`; missing handlers fall through to `CanvasError.noHandler()`.\n- Canvas-level `inputSchema` is validated before `open`; action-level `inputSchema` is validated before dispatch. Failure returns `canvas_input_invalid` with Ajv details.\n- Return raw values from action handlers; throw `CanvasError(\"code\", \"message\")` for errors.\n- `ctx.canvasId` (not `ctx.id`) is the canvas identifier in handler context.\n\n## Loopback server pattern\n\n```js\nimport { createServer } from \"node:http\";\nimport { createCanvas, joinSession } from \"@github\u002Fcopilot-sdk\u002Fextension\";\n\nconst servers = new Map(); \u002F\u002F instanceId → { server, url }\n\nasync function startServer(instanceId) {\n    const server = createServer((req, res) => {\n        res.setHeader(\"Content-Type\", \"text\u002Fhtml; charset=utf-8\");\n        res.end(renderHtml(instanceId));\n    });\n    await new Promise((r) => server.listen(0, \"127.0.0.1\", r));\n    const port = server.address().port;\n    return { server, url: `http:\u002F\u002F127.0.0.1:${port}\u002F` };\n}\n\nawait joinSession({\n    canvases: [\n        createCanvas({\n            id: \"my-canvas\",\n            displayName: \"My canvas\",\n            description: \"...\",\n            open: async (ctx) => {\n                let entry = servers.get(ctx.instanceId);\n                if (!entry) {\n                    entry = await startServer(ctx.instanceId);\n                    servers.set(ctx.instanceId, entry);\n                }\n                return { title: \"My canvas\", url: entry.url };\n            },\n            onClose: async (ctx) => {\n                const entry = servers.get(ctx.instanceId);\n                if (entry) {\n                    servers.delete(ctx.instanceId);\n                    await new Promise((r) => entry.server.close(() => r()));\n                }\n            },\n        }),\n    ],\n});\n```\n\nBind embedded servers to **loopback only** (`127.0.0.1`). The host only embeds loopback URLs. Push state updates to the iframe with Server-Sent Events (`\u002Fevents`).\n\n## ID model — three distinct identifiers\n\n- **`canvasId`** — the canvas *type* declared by the extension. Accepted by `list_canvas_capabilities` and `open_canvas`; not by `invoke_canvas_action`.\n- **`extensionId`** — auto-derived `${source}:${name}` (e.g. `project:triage-board`). Only pass it to disambiguate when two extensions declare the same `canvasId`.\n- **`instanceId`** — caller-invented handle for one running panel (slug or UUID). Two panels of the same canvas need two `instanceId`s. Validated against `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$` — max 128 chars, alphanumeric first character, then only `[A-Za-z0-9._-]`.\n\nExample: `open_canvas({ canvasId: \"triage-board\", instanceId: \"triage-1\" })` then `invoke_canvas_action({ instanceId: \"triage-1\", actionName: \"refresh\" })`.\n\n## Agent-side canvas tools\n\n```\n\u002F\u002F Open a canvas panel\nopen_canvas({ canvasId: \"my-canvas\", instanceId: \"my-canvas-1\", input?: {...} })\n\u002F\u002F Returns { instanceId, url? } — no extensionId needed unless two providers share the canvasId.\n\n\u002F\u002F Discover a canvas type's actions and input schema\nlist_canvas_capabilities({ canvasId: \"my-canvas\" })\n\n\u002F\u002F Invoke an action on an open panel\ninvoke_canvas_action({ instanceId: \"my-canvas-1\", actionName: \"do_thing\", input?: {...} })\n```\n\nRe-opening the same `instanceId` focuses the existing panel (the host emits `session.canvas.opened` with `reopen: true` and reloads the iframe without invoking the provider again).\n\n## Injecting instructions\n\n- **`additionalContext` from hooks** (everyday path). `onSessionStart` → once-per-session guidance; `onUserPromptSubmitted` → per-turn nudges. The runtime appends it as a `developer`-role message.\n- **`systemMessage` on `joinSession`** (system-prompt path):\n  - `{ mode: \"append\", content }` — append to the SDK foundation.\n  - `{ mode: \"customize\", sections: {...} }` — override individual sections (`identity`, `tone`, `safety`, `custom_instructions`, `runtime_instructions`, etc.) with `replace` \u002F `remove` \u002F `append` \u002F `prepend` \u002F transform-callback actions.\n  - **Do NOT use** `{ mode: \"replace\", content }` from an extension — it discards the entire SDK-managed prompt including safety guardrails.\n\n## State model\n\n**`instanceId` identifies the panel, not the data.** Never key persistent state by `instanceId` alone — iframes reload, extensions restart, and a fresh `instanceId` may be opened for the same logical content.\n\nPick the right storage scope:\n- **Per session \u002F workspace** — write artifact files into `session.workspacePath` (returned by `joinSession`). Lives alongside session artifacts, cleaned up with the session.\n- **Per user \u002F global** — write under `$COPILOT_HOME\u002Fextensions\u002F\u003Cextension-name>\u002Fartifacts\u002F`. Follows the user across sessions.\n- **Per artifact \u002F document** — key under a stable `documentId` or file path passed via `input`.\n- **In-repo, committed artifacts** — architecture diagrams, ADRs, design docs that belong in the repo. Write to a sensible repo path.\n- **Per panel (`instanceId`)** — only ephemeral UI state that genuinely should not survive a reload.\n\nResolve the owning ID in `open()` from `input`, load persisted state for that ID, and render. Two `instanceId`s for the same `documentId` should show the same content.\n\n## App theme tokens\n\nThe runtime mirrors the canvas theme contract onto your canvas document:\n- Root\u002Fbody attributes: `data-color-mode`, `data-dark-theme`, `data-light-theme`, `data-theme-source`, `data-theme-tone`, `data-visual-mode`, `pointer-on-hover` class.\n- Semantic tokens: `--background-color-default`, `--border-color-default`, `--text-color-default`, `--text-color-muted`, `--color-focus-outline`.\n- Type ramp: `--font-sans`, `--font-mono`, `--font-weight-semibold`, `--text-body-medium`, `--leading-body-medium`.\n- True-color: `--true-color-red`, `--true-color-red-muted`, `--true-color-blue`, `--true-color-blue-muted`.\n\n```css\nbody {\n    margin: 0;\n    background: var(--background-color-default, #ffffff);\n    color: var(--text-color-default, #1f2328);\n    font-family: var(--font-sans, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif);\n    font-size: var(--text-body-medium, 14px);\n    line-height: var(--leading-body-medium, 20px);\n}\n```\n\nOnly depend on the attributes, classes, and variables documented above — others are app-internal and can change.\n\n## Validation checklist\n\n1. **Discovery** — confirm your canvas appears in the `\u003Ccanvases>` section of the system prompt, then verify `list_canvas_capabilities({ canvasId })` returns your `actions[]`.\n2. **Open** — call `open_canvas({ canvasId, input? })`. Confirm you receive `{ instanceId, url? }` and no error.\n3. **Action** — call `invoke_canvas_action({ instanceId, actionName, input? })` and confirm correct response payload.\n4. **Input validation** — call `open_canvas` with input that fails `inputSchema`. Expect `canvas_input_invalid`.\n5. **Reserved verb rejection** — call `invoke_canvas_action(instanceId, \"canvas.open\", ...)`. Expect `canvas_reserved_action_name`.\n\n## Debugging\n\n1. `extensions_manage({ operation: \"list\" })` — is the extension loaded? Marked `failed`?\n2. `extensions_manage({ operation: \"inspect\", name: \"\u003Cname>\" })` — surfaces log file path and tail. Primary debugging surface.\n3. After editing, **always** `extensions_reload` before re-running RPC calls.\n4. To force iframe reload, call `open_canvas` again with the same `instanceId`.\n5. If not discovered at all, verify the file is named exactly `extension.mjs` and lives in an immediate subdirectory of `.github\u002Fextensions\u002F`, `$COPILOT_HOME\u002Fextensions\u002F`, or the session's extensions dir.\n\n## Sharing extensions via Gist\n\nUse `share_extension` \u002F `install_extension` tools. Gist format:\n- Flat file structure (subdirs encoded as `\\` in gist keys, decoded on install).\n- A `copilot-extension.json` manifest: `{ \"name\": \"\u003Cextension-name>\", \"version\": 1 }`.\n- `node_modules\u002F`, `dist\u002F`, `build\u002F`, `.git\u002F`, hidden dirs (except `.github\u002F`) skipped during share.\n- Per-file cap: ~1 MB; total cap: ~5 MB.\n\n## Common pitfalls\n\n- **`console.log` corrupts JSON-RPC.** Use `session.log()` for user-visible messaging.\n- Do not declare action names starting with `canvas.`.\n- Do not forget to wire a `handler` on every `actions[]` entry.\n- Bind servers to **loopback only**.\n- `open` may be re-invoked on provider reconnect — treat it as idempotent and rehydrate from durable storage.\n- Return raw values from action handlers; throw `CanvasError(\"code\", \"message\")` for errors.\n- The canvas context field is `ctx.canvasId`, not `ctx.id`.\n- Tool names must be globally unique across all loaded extensions.\n- `extension.mjs` only — `.ts` is not supported. The `@github\u002Fcopilot-sdk` import is auto-resolved; do not add a `package.json` for it.\n\n## Session object quick reference\n\n```js\nawait session.log(\"message\", { level?: \"info\"|\"warning\"|\"error\", ephemeral?: boolean });\nawait session.send({ prompt: \"...\", attachments?: [{ type: \"file\", path: \"...\" }] });\nconst response = await session.sendAndWait({ prompt: \"...\" });\nconst unsub = session.on(\"tool.execution_complete\", (event) => { \u002F* ... *\u002F });\n\u002F\u002F session.workspacePath — path to session workspace (string | undefined)\n\u002F\u002F session.sessionId — current session ID\n```\n\nKey event types: `assistant.message`, `tool.execution_start`, `tool.execution_complete`, `user.message`, `session.idle`, `session.error`, `permission.requested`, `session.shutdown`.\n",{"name":5,"description":7},"main","8541229759617347888641eba917d3b0ad66a984",".github\u002Fskills\u002Fcreate-canvas",626,"https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw","https:\u002F\u002Fgh.io\u002Fgh-aw","https:\u002F\u002Fgithub.com\u002Fgithub","https:\u002F\u002Fgithub.com\u002Fabout","How people build software.","2026-11-14 06:33:26",{"source":8,"skillName":5,"commands":70,"prompt":80,"zipAvailable":81},[71,74,77],{"tool":72,"command":73},"npx","npx skills add github\u002Fgh-aw --skill create-canvas",{"tool":75,"command":76},"bunx","bunx skills add github\u002Fgh-aw --skill create-canvas",{"tool":78,"command":79},"pnpm","pnpm dlx skills add github\u002Fgh-aw --skill create-canvas","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fcreate-canvas\u002FSKILL.md",true,[],[84,108,126,151,175,192],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":94,"publishedAt":54},"01M6ADC942STTXHFV410J4DH0X","GitHub Agentic Workflows","GitHub Agentic Workflows (`gh-aw`) is a GitHub CLI extension for writing Agentic Workflows in markdown and compiling them to GitHub Actions.","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002FSKILL.md",[90,93],{"categoryNo":91,"categoryName":92,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000011","运维与部署",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},[9,95,96,97,98,99,100,101,102,103,104,105,48,106,107],"agentic","agentic workflows","github agentic workflows","workflows","github cli","gh","extension","for","compiling","cli","writing","github actions","markdown",{"skillNo":109,"name":110,"nameZh":6,"description":111,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":112,"categories":113,"keywords":114,"publishedAt":54},"01M6ADC6ZXSA46N9XD6VNAP1MS","windows-compatibility","Cross-platform path handling and command patterns","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.squad\u002Ftemplates\u002Fskills\u002Fwindows-compatibility\u002FSKILL.md",[],[115,116,117,118,119,120,121,122,123,124,125],"windows","windows compatibility","compatibility","bugs","path","high","platform","cross-platform","patterns","command","git",{"skillNo":127,"name":128,"nameZh":6,"description":129,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":130,"categories":131,"keywords":132,"publishedAt":54},"01M6ADC44957SVQF96R5YY247P","versioning-policy","Semver versioning rules for Squad SDK and CLI — prevents prerelease version incidents","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.squad\u002Ftemplates\u002Fskills\u002Fversioning-policy\u002FSKILL.md",[],[133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,102,149,104,150],"policy","versioning policy","versioning","incident","gate","implementation","version","Rules","workspace","pr","ci","npm","semver","release","squad","resolution","incidents","sdk",{"skillNo":152,"name":153,"nameZh":6,"description":154,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":155,"categories":156,"keywords":159,"publishedAt":54},"01M6ADC1PHMEAEVR87F8PDR89X","tiered-memory","Three-tier agent memory model (hot\u002Fcold\u002Fwiki) for context reduction per spawn","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.squad\u002Ftemplates\u002Fskills\u002Ftiered-memory\u002FSKILL.md",[157,158],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},[160,161,162,163,102,164,165,166,167,168,169,170,171,172,173,174],"tiered memory","memory","memory-management","model","cold","proposal","runtime","three","spawn","management","context","wiki","agent memory","performance","design",{"skillNo":176,"name":177,"nameZh":6,"description":178,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":179,"categories":180,"keywords":184,"publishedAt":54},"01M6ADBZTDGFM0E25EWRQEMYEH","test-discipline","Update tests when changing APIs — no exceptions","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.squad\u002Ftemplates\u002Fskills\u002Ftest-discipline\u002FSKILL.md",[181],{"categoryNo":182,"categoryName":183,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量",[185,186,187,188,36,120,189,136,190,191],"test discipline","discipline","test","sync","tests","quality","update",{"skillNo":193,"name":147,"nameZh":6,"description":194,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":195,"categories":196,"keywords":197,"publishedAt":54},"01M6ADBX5MJP4Z7CG4XTV8ZVT8","Squad's command catalog and interactive menu. Invoke via \u002Fsquad (slash command) or natural language (\"squad commands\", \"what can squad do\", \"show me squad options\"). Presents categorized operations (Install & Upgrade, Team Management, Issues & PRs, Plugins & Skills, Model & Cost, Sessions & State) as an interactive picker. Routes to the right squad CLI command or the Squad coordinator agent.","https:\u002F\u002Fgithub.com\u002Fgithub\u002Fgh-aw\u002Fblob\u002Fmain\u002F.squad\u002Ftemplates\u002Fskills\u002Fsquad\u002FSKILL.md",[],[147,198,199,200,201,202,203,204,205,206,207,208,209,124,163,210,211,212,213,214,215,216,104],"show","interactive menu","invoke","coordinator","as","commands","upgrade","options","me","natural language","do","install","team","show me","plugins","issues","state","squad commands","sessions"]