grim:dev:workbench-artifact git:20260906.eb17afbB

Immutable. This exact content is served forever at /api/v1/blob/c7f6348f70fe64a7.

---
name: grim:dev:workbench-artifact
description: "Workbench Artifact: Create minimal skill-paired browser artifacts with a file-backed data layer, two-way sync, and tiny local server routes."
disable-model-invocation: true
---

# Workbench Artifact

## Purpose
Use this skill when creating or modifying a Workbench Artifact.

Workbench Artifacts combine:
- a normal `SKILL.md`;
- a tiny local browser artifact;
- a text-file data layer agents can patch directly;
- two-way sync between browser UI and files;
- optional host callbacks for Browser, Codex, annotation tools, or an artifact shell.

Keep the default implementation minimal:
- no framework;
- no database;
- no build step;
- no generated manifest;
- no browser-only source of truth.

## Canonical Paths
- Shared standard: `skills/artifacts/artifacts/references/workbench-skills.md`
- Skill source: `skills/artifacts/workbench-artifact/SKILL.md`
- Sample artifact: `skills/artifacts/workbench-artifact/artifact/index.html`
- Default state template: `skills/artifacts/workbench-artifact/artifact/state.json`
- Per-project state: `<project-root>/workbench/workbench-artifact/state.json`
- Served URL: `http://127.0.0.1:8765/workbench-artifact/` (after `node artifacts/server.js --root <project-root>`)

## Minimal Sync Sample
This skill ships the smallest complete sync loop:
- `index.html`
- `styles.css`
- `app.js`
- `state.json`
- generic server route in `artifacts/server.js`

The sample uses:

```text
GET  /api/workbenches/workbench-artifact/state
POST /api/workbenches/workbench-artifact/state
```

Browser edits write the per-project `state.json`.

Agent edits to `state.json` reload automatically in the browser.

State and media live in `<project-root>/workbench/<workbench-name>/`, flat, no nested folders. The artifact's own `state.json` is only the default template that seeds a fresh project.

## The Sync Server
The two-way sync is powered by a small local server: `artifacts/server.js`. It is plumbing — start it for the user, never make the user run it.

- Start one server per project: `node artifacts/server.js --root <project-root> [--port N]`
- Root defaults to the current working directory; the port auto-picks the next free one if 8765 is busy.
- It serves each workbench's app code from the Tome, reads/writes the per-project `workbench/` folder, watches files for hot reload, and exposes the state APIs above.
- Two terminals pointed at two roots = two fully independent workbenches side by side.
- The `workbench/` folder is a sibling of `docs/` — same philosophy: project-owned durable files.
- Media dropped into the folder appears in the workbench on the next poll, zero code edits.

To open a workbench (or any local web app) on your phone over home WiFi, follow the LAN sharing guide in `grim:artifacts` — bind the server to `0.0.0.0` and hit the Mac's LAN IP from the phone.

## Optional WebMCP Host Bridge

Consider WebMCP as an optional pathway from an artifact through its host browser to the agent, alongside annotation tools and host callbacks.
- Expose the artifact's existing validated actions and visible state when the browser and agent support it.
- Keep normal UI operation and file-backed two-way sync independent of WebMCP.
- Add it only when useful for the particular workbench; a 3D workbench does not require it.
- Verify current browser/host support before implementation: https://developer.chrome.com/docs/ai/webmcp

## New Workbench Checklist
1. Create `skills/<slug>/SKILL.md`.
2. Create `skills/<slug>/agents/openai.yaml`.
3. Create `skills/<slug>/artifact/index.html`.
4. Create `skills/<slug>/artifact/styles.css`.
5. Create `skills/<slug>/artifact/app.js`.
6. Create `skills/<slug>/artifact/state.json`.
7. Add the workbench to `artifacts/server.js`.
8. Add or update `skills/registry.yaml`.
9. Add 128 and 1024 PNG icons under `assets/`.
10. Validate JSON and JavaScript.
11. Serve and inspect the route.

## Verification
- `python3 -m json.tool skills/artifacts/workbench-artifact/artifact/state.json`
- `node --check skills/artifacts/workbench-artifact/artifact/app.js`
- `node --check artifacts/server.js`
- `node artifacts/server.js --root <project-root>`
- open `http://127.0.0.1:8765/workbench-artifact/`