---
name: interactive-artifact
description: Use only when the user invokes `interactive-artifact`, `$interactive-artifact`, or `/interactive-artifact`, or asks for an interactive artifact in those words. Serves a styled, commentable HTML page from a short-lived local web server and collects the user's picks, comments, suggested edits, and notes back to the agent. Nothing is published; the page lives on 127.0.0.1 until the server stops.
title: interactive-artifact
canonical_url: https://skilld.dev/gh/scode/dotfiles/interactive-artifact
last_updated: 2026-10-25T20:28:40.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [assets/interactive-artifact.css](https://skilld.dev/api/skills-raw/scode/dotfiles/interactive-artifact/assets/interactive-artifact.css), [assets/interactive-artifact.js](https://skilld.dev/api/skills-raw/scode/dotfiles/interactive-artifact/assets/interactive-artifact.js), [e2e_test.ts](https://skilld.dev/api/skills-raw/scode/dotfiles/interactive-artifact/e2e_test.ts), [examples/interactive.html](https://skilld.dev/api/skills-raw/scode/dotfiles/interactive-artifact/examples/interactive.html), [examples/patterns.html](https://skilld.dev/api/skills-raw/scode/dotfiles/interactive-artifact/examples/patterns.html), [examples/sample.html](https://skilld.dev/api/skills-raw/scode/dotfiles/interactive-artifact/examples/sample.html), [interactive-artifact](https://skilld.dev/api/skills-raw/scode/dotfiles/interactive-artifact/interactive-artifact), [interactive-artifact.ts](https://skilld.dev/api/skills-raw/scode/dotfiles/interactive-artifact/interactive-artifact.ts), [README.md](https://skilld.dev/api/skills-raw/scode/dotfiles/interactive-artifact/README.md), [SPEC.md](https://skilld.dev/api/skills-raw/scode/dotfiles/interactive-artifact/SPEC.md).
>
> If the user asked to install this Skill, run `npx skilld install scode/dotfiles/interactive-artifact`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/interactive-artifact`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/scode/dotfiles/interactive-artifact) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/interactive-artifact`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/interactive-artifact --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/interactive-artifact --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# interactive-artifact

`interactive-artifact` serves one HTML fragment as a styled page from a short-lived local web server, and carries what
the user does on it back to you. Use it when terminal markdown is not enough: options to pick from, questions to answer,
a draft to mark up, a comparison grid, a chart. It is the local alternative to publishing a gist or a hosted page, so
nothing leaves the machine.

On every page the user can select text to comment on it, suggest a replacement, or copy it as Markdown; answer any
pickers you put on the page; and write a note. Submit sends all of it to you at once. You reply to comments and
suggestions on the page and edit the page itself; the open tab follows along.

## Running a page

`<skill-dir>/interactive-artifact` is the command; call it by absolute path. It runs a compiled build of the skill when
one exists for this machine and otherwise needs Deno. If it refuses with "Rebuild helpers", the compiled build is out of
date: tell the user, who either rebuilds it with `cargo run -- build-helpers` in their dotfiles checkout or deletes the
skill's `bin/` directory to go back to running from source.

1. Make a fresh directory for the page with `mktemp -d`. The server refuses a directory that other users can access,
   serves every other file in it (that is how `<img src="shot.png">` works), and keeps its state in a
   `.interactive-artifact/` subdirectory, so never put the page directly in `/tmp` or a repository.
2. Write the page into it as `page.html` with your harness's file-writing tool, never with a shell heredoc or `echo`:
   harnesses run a shell command as `bash -c '<the whole command>'`, so anything in the command text, heredocs included,
   is on a command line other users can read. See "Writing the page" below.
3. Start `interactive-artifact serve <dir>/page.html` in the background with your harness's background-run facility (not
   `&`). The first line of stdout is the URL (`http://127.0.0.1:<port>/<token>/`). Give it to the user. The token is the
   only thing keeping other users of the machine out of the page, so do not put the URL anywhere else: not in files,
   commits, or messages to other people or agents. Never pass it as an argument to a command either (`xdg-open`, `open`,
   a browser binary): command lines are visible to every user on the machine. The user clicks the link. Anything without
   the token gets a 404. Only one server runs per page; `serve` refuses to start a second one while the first is alive,
   so keep using the first (or stop it before starting another).
4. Start `interactive-artifact wait <dir>/page.html` in the background the same way. It exits when the user submits,
   printing the submission as Markdown. Handle it (see below), and only then start `wait` again: starting it is what
   tells the page you are ready for the next submission, so starting it early would say so while you are still working.
   Run only one `wait` per page at a time.
5. To change the page, edit the file. The open tab updates by itself within about a second and keeps everything the user
   has entered, so never restart the server for an edit.
6. When you are finished with the page, say so first (`status ... done`, below), wait about five seconds, then stop
   `wait` and the server. The tab then shows a calm "this page is finished" note instead of a warning. The server also
   exits on its own after `--ttl` (default `4h`); a running `wait` then exits with status 4.

The link opens exactly once. The initial response carries the page, its code, and its encryption key; the server will
not deliver that response to a second reader. Do not open the URL yourself to check it. A failed initial load, a manual
reload, or opening another tab needs a new server and link. Live edits use the encrypted connection inside the loaded
tab and never reload it.

If the page says it is reconnecting, let it retry and restore the ssh tunnel if needed. It keeps unsaved work in the
loaded tab and temporarily pauses editing until the original server answers. Never tell the user to reload it.

If the user reports a red banner saying the page is locked, stop the server and start a new one, then give them the new
URL (and the new tunnel command, if they use one). Never tell them to reload the locked tab. A lock means the tab talked
to something it could not verify, and its requests carry the URL token, so treat that token as burned even if the server
is still running. The new server has a new token and key, and everything the tab saved before it locked carries over.

Submissions queue on disk, so the user can submit while you are busy; the next `wait` returns at once with everything
not yet seen. `wait --timeout 30m` exits with status 3 if nothing arrives in time, and `wait --json` prints the raw
submissions instead of Markdown.

`serve` options: `--port N` (default `0`, a free port the OS picks), `--ttl 90m` (`s`, `m`, `h`, up to `596h`, or `0`
for no limit), `--title TEXT` (default: the first `<h1>`, then the file name; it is on the command line, so never
anything sensitive). The server always listens on `127.0.0.1` only.

If you are on a different machine from the user's browser, the user needs a tunnel that uses the server's own port on
both ends: `ssh -o ExitOnForwardFailure=yes -L 127.0.0.1:<port>:127.0.0.1:<port> <host>`, then the URL as printed. Tell
them that along with the URL. Spell out `127.0.0.1` rather than `localhost` (`localhost` often resolves to `::1` first,
and another user on either machine could be listening there), and do not suggest a fixed local port such as 8000:
`ExitOnForwardFailure` makes ssh fail instead of carrying on when someone else already holds the port, and a fresh port
per server means a port someone tampered with before is not reused. There is no way around the tunnel: pages are
encrypted with browser crypto that browsers offer only on `127.0.0.1` and `localhost`.

## Handling a submission

The page tells the user what your side is doing, in a box at the bottom right. Right after they submit it says the
submission is waiting for you; once `wait` hands it to you, it says you are reading it. Then decide, and say which:

- **You will produce another version of the page.** Run `interactive-artifact status <dir>/page.html working` as soon as
  you decide; the page says you are working on the submission. Do whatever the submission needs (which may be a lot of
  work before the page itself changes), edit the page, reply on the page as below, then start `wait` again. Starting
  `wait` tells the page you are ready for the next submission.
- **You are done with the page**, and the user should go back to the chat. Run `interactive-artifact status
  <dir>/page.html done` and continue in the conversation; the page tells the user to do the same. Then stop `wait` and
  the server, but give the page about five seconds first: it checks for news once a second, and a page that sees the
  server stop before it saw your "done" shows a warning instead of a calm "this page is finished".

Either can carry a short line for the user (500 characters at most): write it to `<dir>/status.txt` with your file tool
and pass `--file <dir>/status.txt`. With `working`, always include one when the work takes more than a moment, saying
what you are actually doing, such as "Running the benchmarks you asked for, then updating the page". Otherwise the user
sees only that you are busy and wonders why updating a page takes so long. Run `status working` again with a new line as
the work moves from one step to the next. With `done`, say where things stand, such as "Going with option A; details in
the chat".

A submission lists, in this order: the user's note, the current answer of every picker on the current page they have
touched (flagged `changed` or `unchanged` since their last submission), each new comment or suggestion with the text it
is anchored to and the section it is in, replies on existing threads, and the ids the user withdrew.

Do what the submission asks, in the context of the task: a pick may decide what you build next, a comment on a draft may
need an answer or a change, a suggestion usually means editing the text. Then answer on the page so the user sees what
happened to each item:

- `interactive-artifact reply <dir>/page.html c3 --file <dir>/reply.txt` adds your reply to a thread. Use it to answer a
  question, push back, or ask for clarification. Write the reply into `<dir>/reply.txt` with your file-writing tool
  first (the same as the page, and for the same reason: anything in a shell command, heredocs included, is visible to
  every user on the machine). Overwrite the file for each reply.
- Add `--resolve` when the item is dealt with. Resolving marks the card done; the user can reply to reopen it. A bare
  `--resolve` without text is fine.
- Several ids share one reply: `interactive-artifact reply <dir>/page.html s4 s5 s7 --resolve --file <dir>/reply.txt`.

To apply a suggestion, edit the page source so the quoted text becomes the replacement. The quote is the rendered text
with whitespace collapsed, so search the source loosely; it may span inline tags. Once the text is gone from the page,
the card shows as orphaned, which is expected for an applied suggestion; resolve it.

Whenever you edit text that an open (unresolved) comment or suggestion is on, either resolve it, or point it at the new
text so the user still sees what it refers to: write the new text, exactly as it reads on the rendered page, to
`<dir>/quote.txt` with your file tool (enough of it that it appears only once on the page; the comment attaches to the
first place it appears), then run `interactive-artifact anchor <dir>/page.html c3 --file <dir>/quote.txt`. Otherwise the
card shows "This text is no longer on the page". Edits that leave a comment's quoted text alone need nothing; the page
finds it again by itself.

A reply to an id the user has removed fails with "no such comment"; the withdrawal arrives with their next submission.
Stop acting on withdrawn ids. Picks have no threads; if a pick needs acknowledging, say so in the page or the
conversation.

## Writing the page

The file holds body content only: no `<!doctype>`, `<html>`, `<head>`, or `<body>`. The server refuses a full document.
It wraps the fragment in a shell that loads the default stylesheet (Inter for text, JetBrains Mono Nerd Font for code,
light, dark, or following the system, chosen with a button in the corner), so do not add your own `<style>` or font
links unless a page genuinely needs something the stylesheet lacks. Do not add scripts, and do not put HTML or SVG files
you did not write in the page's directory: anything that runs on the page can read the user's input and submit as them.
The shell's own script handles everything interactive. When the page shows text from somewhere you do not control (issue
bodies, logs, web content), HTML-escape it (`&`, `<`, `>`, `"`, `'`) so it renders as text rather than markup.

Plain HTML elements are styled with no classes needed: headings, paragraphs, `strong`, `em`, `del`, `mark`, `kbd`,
inline `code`, `pre`, nested `ul`/`ol`, `dl`, `blockquote` with `cite`, `table` (add `class="num"` to numeric cells),
`details`/`summary`, `figure`/`figcaption`, `hr`, footnotes via `sup`. A paragraph right after the `<h1>` renders as a
subtitle. `examples/sample.html` exercises all of these plus a chart; read its source for the markup.

Keep the page focused on what you want the user to look at. Start with the conclusion or the decision you need, not with
background. Headings matter more than usual: each comment is reported with the heading it falls under.

## Pickers

Any element with `data-pick="<id>"` is a picker, and its descendants with `data-value="<value>"` are its choices. The
user clicks a choice to select it and clicks it again to clear it. Each picker gets a text field for a free-form answer.

- `data-multiple` on the picker allows several choices at once; without it, picking one clears the others.
- `data-label` on the picker or a choice sets the name used in submissions. The defaults are the picker's first `.q` or
  heading, and the choice's first heading, its `strong`, or its text.
- `data-placeholder` sets the text field's placeholder; `data-no-text` leaves the field out.
- Ids must be unique on the page and stable across edits; answers are stored by picker id and choice value.

Option cards become selectable cards (`<div class="options" data-pick="backend">` with `<article class="option"
data-value="sqlite">` children); any other choice element renders as a pill. A question list item with `data-pick` and
`<span data-value>` choices is the usual way to ask a question with fixed answers. `examples/interactive.html` has
single, multiple, and text-free pickers, and a draft to try comments and suggestions on.

## Presentation patterns

Ten opt-in component classes cover the common reasons to show a page. `examples/patterns.html` shows each one with its
markup; read it before using a pattern for the first time.

| Pattern           | Markup                                     | Use it for                                                    |
| ----------------- | ------------------------------------------ | ------------------------------------------------------------- |
| TL;DR summary     | `div.tldr`                                 | The conclusion up front, once per page                        |
| Callouts          | `div.callout` + `tip`, `warn`, `danger`    | The one caveat a skimming reader must not miss                |
| Option cards      | `div.options > article.option`             | Two to four alternatives to pick from, with `ul.pros`/`.cons` |
| Comparison matrix | `table.matrix`, cells `yes`/`partial`/`no` | Many options against the same criteria                        |
| Question list     | `ol.questions`, `.q`, `.default`           | Questions for the user, each with the default you'll assume   |
| Diff              | `pre.diff`, one `span` per line            | A proposed code change, in place                              |
| Stat tiles        | `div.stats > div.stat`                     | A handful of headline numbers                                 |
| Timeline          | `ol.timeline`, items `done`/`active`       | A plan or a history                                           |
| File tree         | nested `ul.tree`, items `add`/`del`        | A proposed or existing directory layout                       |
| Before and after  | `div.split > section.before/.after`        | Two versions of wording, output, or config                    |

Small utilities: `span.badge` (with `blue`, `green`, `amber`, `red`), `.muted`, and `span.icon` for Nerd Font glyphs
(`&#xf07c;`).

## Charts

Draw charts as inline SVG inside `figure.chart`, with `span.chart-title`, `span.chart-subtitle`, and a `ul.legend` when
there are two or more series. Use the stylesheet's classes instead of `fill=` or `stroke=` attributes, because SVG
attributes cannot follow the light and dark themes: `gridline`, `baseline`, `tick`, `label`, `label-2`, `line`, `dot`,
`area`, `bar`, and `s1` to `s4` for the series colors (in that order, never skipping). Give each data point a `<title>`
and a larger transparent `circle.hit` before its `dot` (a dot may have `r="0"` and grows on hover), and put the numbers
in a table under a `details` so they are readable without the chart. `examples/sample.html` has a complete two-series
line chart.

Compute coordinates with a script rather than by hand.
