@frebreco/canvas 0.3.0-next.6 → 0.3.0-next.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frebreco/canvas",
-  "version": "0.3.0-next.6",
+  "version": "0.3.0-next.8",
   "description": "A multiplayer canvas for coding agents that run on your machine.",
   "license": "MIT",
   "type": "module",
@@ -18,6 +18,7 @@
   "files": [
     "bin",
     "src",
+    "skills",
     "README.md",
     "LICENSE"
   ],

package/skills/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "canvas",
+  "description": "Skills canvas gives the agents it runs.",
+  "skills": "./"
+}

package/skills/code-tour/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: code-tour
+description: Give a code tour on the canvas board — a guided walk through how part of the codebase works, as one files frame people click through. Use when asked for a tour or walkthrough of code, how a feature works across files, or to onboard someone to an area.
+---
+
+A code tour is one files frame on the board whose list holds, in reading order: a guide (a
+markdown scratch file), then the **stops** — project files at the lines that matter — and
+optionally a diagram at the end. People click through it at their own pace; the thread only
+points at it.
+
+## Steps
+
+1. **Find the stops.** Read the code until you can tell the story from entry point to effect.
+   Pick 4–10 stops in the order a newcomer needs them, usually where it starts → the core → the
+   edges. A stop is one file at a tight line range (roughly 5–40 lines): the function, the branch,
+   the type that carries the idea. Only files git tracks can be shown; a stop in an ignored file
+   gets described in the guide instead. Done when each stop's range is read from the file as it
+   is now, and the stops tell the story without gaps.
+
+2. **Write the guide**, `tour-<topic>.md`: a one-paragraph overview, then one short section per
+   stop, numbered and titled like its list entry — what to look at in those lines, why it
+   matters, and how it hands over to the next stop. Name functions and types; quote lines
+   sparingly, the frame shows them. End with open questions or pitfalls if you found any.
+
+3. **Draw it**, when the flow branches or spans several components: `tour-<topic>.html`, a
+   single self-contained page (inline CSS and SVG or script) with boxes named like the stops.
+   Skip it for a straight line of calls.
+
+4. **Open the tour.** `view_board` first; retarget an existing tour frame on the same topic with
+   `update_frame` rather than opening a second one. Otherwise one `open_frame` of type `file`
+   whose `files` list is the whole tour, the guide first:
+
+   ```json
+   {
+     "type": "file",
+     "title": "Tour: login",
+     "files": [
+       { "display": "0 Guide.md", "name": "tour-login.md", "content": "…" },
+       { "display": "1 Route/login.ts", "path": "src/routes/login.ts", "start_line": 12, "end_line": 30 },
+       { "display": "2 Session/session.ts", "path": "src/auth/session.ts", "start_line": 5, "end_line": 22 },
+       { "display": "3 Diagram.html", "name": "tour-login.html", "content": "…" }
+     ]
+   }
+   ```
+
+   Number the display names like the guide's sections, so people can match them; folders are
+   worth it only for chapters of a long tour. Done when every stop in the list has its section
+   in the guide and every section its stop.
+
+5. **Reply briefly**: the tour's frame, how many stops, and the story in one or two sentences.
+   The guide carries the explanation; the thread stays short.
+
+## Walking people through it
+
+When people ask to be walked through the tour ("next", "show stop 3"), `update_frame` the tour
+frame to that stop's `path`, `start_line` and `end_line`, and explain it in your reply. Changing
+the frame makes you its occupant for the turn, so everyone following scrolls with you.
+
+## Revising
+
+Follow-up questions often deserve a stop or a section. `write_board_file` with the guide's path
+rewrites it in place. `update_frame` with `files` replaces the whole list, so send every entry,
+the new one in its place. Name the guide and diagram there by their `canvas:scratch/` paths:
+`content` would create new copies.

package/src/server/agents.ts

@@ -46,6 +46,7 @@ import type {
   SessionSnapshot,
 } from "../shared/protocol";
 import { fromAcp, pendingChanges, settingsOf } from "./agent-config";
+import { SKILLS_DIR } from "./skills";
 import { trimEvent } from "./trim-event";
 
 interface AgentDefinition extends AgentInfo {
@@ -78,6 +79,8 @@ export function detectAgents(): ReadonlyArray<AgentDefinition> {
         claudeCode: {
           options: {
             allowedTools: BOARD_TOOL_NAMES.map((name) => `mcp__${BOARD_SERVER_NAME}__${name}`),
+            // canvas's own skills; the host's stay available beside them.
+            plugins: [{ type: "local", path: SKILLS_DIR, skipMcpDiscovery: true }],
           },
         },
       },
@@ -93,6 +96,8 @@ export function detectAgents(): ReadonlyArray<AgentDefinition> {
           model: opencodeModel,
           // Shell commands ask, so a person approves anything the agent runs.
           permission: { bash: "ask" },
+          // canvas's own skills; the host's stay available beside them.
+          skills: { paths: [SKILLS_DIR] },
         }),
       },
     },

package/src/server/board-mcp.ts

@@ -24,6 +24,7 @@ import type { McpServer } from "@agentclientprotocol/sdk";
 import { BOARD_SERVER_NAME, BOARD_TOOLS, boardInstructions } from "../shared/board-tools";
 import type { FileContent } from "../shared/protocol";
 import type { Scratch } from "./scratch";
+import type { Skill } from "./skills";
 
 export interface BoardCall {
   readonly callId: string;
@@ -38,6 +39,8 @@ export interface BoardMcpOptions {
   readonly scratch: Pick<Scratch, "create" | "write" | "read" | "list" | "remove">;
   /** Send a call to the host's browser; false if none is connected. */
   readonly relay: (call: BoardCall) => boolean;
+  /** canvas's skills, named in the priming. */
+  readonly skills?: ReadonlyArray<Skill>;
   readonly timeoutMs?: number;
 }
 
@@ -133,7 +136,7 @@ export class BoardMcp {
               : LATEST_PROTOCOL,
           capabilities: { tools: { listChanged: false } },
           serverInfo: { name: BOARD_SERVER_NAME, version: "0.0.0" },
-          instructions: boardInstructions(sessionId),
+          instructions: boardInstructions(sessionId, this.options.skills),
         });
       case "ping":
         return reply({});

package/src/server/server.ts

@@ -13,6 +13,7 @@ import { AgentManager, detectAgents } from "./agents";
 import { BoardMcp } from "./board-mcp";
 import { Files } from "./files";
 import { Scratch } from "./scratch";
+import { canvasSkills } from "./skills";
 import { Store } from "./store";
 import { Terminals } from "./terminals";
 
@@ -51,6 +52,7 @@ export async function serve(options: ServeOptions) {
       host.send(JSON.stringify({ t: "board-call", ...call } satisfies ServerToClient));
       return true;
     },
+    skills: canvasSkills(),
   });
   process.on("exit", () => boardMcp.stop());
 

package/src/server/skills.ts

@@ -0,0 +1,32 @@
+/**
+ * The skills canvas gives every agent session, shipped in `skills/` beside
+ * `src/` (finding 12). The folder is a Claude Code plugin (its manifest points
+ * `skills` at itself) and an opencode skills path at once; `agents.ts` hands
+ * it to each agent, which lists the skills beside the host's own.
+ *
+ * Claude drops skill descriptions from its listing once the host has many
+ * skills, so the board priming names them too (`boardInstructions`).
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+export const SKILLS_DIR = resolve(import.meta.dir, "../../skills");
+
+export interface Skill {
+  readonly name: string;
+  readonly description: string;
+}
+
+/** Every skill in `dir`, from its `SKILL.md` frontmatter. */
+export function canvasSkills(dir: string = SKILLS_DIR): ReadonlyArray<Skill> {
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+    .map((entry) => {
+      const text = readFileSync(join(dir, entry.name, "SKILL.md"), "utf8");
+      const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? "";
+      const field = (key: string) => new RegExp(`^${key}: (.+)$`, "m").exec(frontmatter)?.[1];
+      return { name: field("name") ?? entry.name, description: field("description") ?? "" };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+}

package/src/shared/board-tools.ts

@@ -267,7 +267,10 @@ export const BOARD_TOOLS: ReadonlyArray<{
 ];
 
 /** The agent's standing context, sent as MCP server instructions. */
-export function boardInstructions(frameId: string): string {
+export function boardInstructions(
+  frameId: string,
+  skills: ReadonlyArray<{ readonly name: string; readonly description: string }> = [],
+): string {
   return `You are running inside canvas: a shared, multiplayer board that people are looking at together, live. Its frames are coding-agent sessions, files of this project, browser previews and terminals. You are the agent in frame ${frameId}; people write prompts into it and read your replies there. Several people may prompt you.
 
 Frames that sit close together form a cluster: people keep related work together that way, and your own cluster is your workspace. Within a cluster frames sit in rows; frames in a row share a height.
@@ -284,5 +287,14 @@ The ${BOARD_SERVER_NAME} tools let you see and change the board: ${BOARD_TOOL_NA
 - Scratch files hold what exists only to be shown on this board: a write-up, a diagram, an HTML visualisation. Pass the text as \`content\` (with a \`name\`) to open_frame or update_frame, or use write_board_file; canvas keeps them outside the project, as canvas:scratch/<name>. Don't write such files into the project for the board. Anything else — a temp file for your own work, a script, test data — goes wherever it would without canvas.
 - Any agent may read (read_board_file) and overwrite (write_board_file) any scratch file; view_board lists them.
 - To show several files for one topic, prefer one file frame with a list (files) over a frame per file: people click through it at their own pace. You decide the tree: display paths, folders, order, line ranges. A write-up (a scratch file) at the top and a visualisation at the bottom fit in the same list.
-- Markdown and HTML files render. HTML runs its scripts, but relative links and assets (CSS, images, other scripts) don't load, so inline them.`;
+- Markdown and HTML files render. HTML runs its scripts, but relative links and assets (CSS, images, other scripts) don't load, so inline them.${skillsSection(skills)}`;
+}
+
+/** canvas's own skills: the agent lists them, but may have dropped their descriptions. */
+function skillsSection(
+  skills: ReadonlyArray<{ readonly name: string; readonly description: string }>,
+): string {
+  if (skills.length === 0) return "";
+  const list = skills.map((skill) => `- ${skill.name}: ${skill.description}`).join("\n");
+  return `\n\ncanvas also gives you skills for work on the board. When one fits the request, load it with your skill tool before you start:\n${list}`;
 }