Index of every page on this site: llms.txt
All skills
scode avatar

/interactive-artifact

@03a9f7f
Run it yourself

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.

  • 11 files
  • 290.8 KB
  • Updated 4 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/scode/dotfiles/interactive-artifact

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈104 tokens for metadata: the name and description. ≈3.9k when used: this file. ≈5.6k more on demand in 2 files.

Description uses 5.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈418 characters, or 5.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 03a9f7f. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 4 weeks ago

README badge

README badge for scode/dotfiles/interactive-artifact