Portable Artifacts

What this branch builds, how to use it, and what it is worth, with working samples.

Branch
feat/visual-artifacts
Repo
claude-skills
Status
PR #38

At a glance

One JSON file becomes a page or video

This branch adds four agent skills that build offline dashboards, diagrams, explainer pages and short videos. The model writes only a small JSON file, and scripts validate, lay out and render it.

  • make-dashboard v2 builds live, offline dashboards from local data files.
  • make-diagram, make-explainer and make-motion add diagrams, pages and videos from JSON.
  • Every page makes no network requests and carries a strict Content Security Policy.

Eval results

Haiku built all 30 eval prompts#

Haiku valid builds
30 of 30
14 dashboard, 8 diagram and 8 explainer runs
make-explainer tests
593
Measured on the branch head with node --test
Skills shipped
4
make-dashboard v2, make-diagram, make-explainer and make-motion
CI checks passing
5 of 5
Measured on PR #38

Four skills

Four skills share one JSON-to-page loop#

  • make-dashboard v2

    Builds one offline dashboard from CSV, Parquet, JSON, DuckDB or SQLite files. Its charts sort, compare and export, and the page reloads when the spec changes.

  • make-diagram

    Draws architecture, flow, sequence and state diagrams from a small JSON topology. Layout is computed at build time, so the model never writes coordinates.

  • make-explainer

    Builds one themed page or slide deck from typed sections. It can embed diagrams, charts and videos made by the other skills.

  • make-motion

    Renders a short MP4 video from a JSON list of scenes. Text, shapes, counters and transitions are all set in the file.

Request flow

A request passes validate and build#

From request to pageflow diagram with 9 nodes and 11 edges.Your requestSTEPClaude Haiku agentSTEPexplainer.json specSTEPvalidate.mjsSTEPbuild.mjsSTEPmake-motion videosSTEPmake-diagram figuresSTEPmake-dashboard chartsOffline HTML pagefix and rerun
From request to page
The agent fills in the JSON spec, and scripts check and render it. The embedded skills supply figures, charts and videos.

Getting started

Install once, then ask in plain words#

  1. Install the skills

    Run one of the install commands in the next section. The skills are added to your agent.

  2. Ask for a page

    Describe what to explain in plain words, or call the skill directly with a slash command.

  3. Validate the JSON

    The skill runs validate.mjs. Each problem prints a JSON path, the problem and the fix. The agent reruns it until the output says valid.

  4. Build the page

    The skill runs build.mjs, which writes one offline HTML page and prints its path. Open that file in any browser.

  5. Check the page (optional)

    Run check.mjs on the page. It looks for console errors and sideways scrolling at desktop and phone width.

Install

Two install routes cover Claude Code and others#

text
/plugin marketplace add abhijitbansal/claude-skills
/plugin install portable-artifacts@claude-skills
npx skills add abhijitbansal/claude-skills --skill make-explainer make-diagram make-dashboard
git clone https://github.com/abhijitbansal/claude-skills
node claude-skills/plugins/portable-artifacts/bin/install.mjs codex
The first two lines install in Claude Code. The third line installs with npx for any agent. The last two lines use the bundled installer.

Commands

Four slash commands each produce a different page#

Each request is one sentence. The skill fills in its own JSON file and builds the output.
RequestWhat it produces
/make-explainer recap of this branch with a test checklistOne offline page that recaps the branch and lists the manual tests.
/make-diagram architecture of the checkout service with its database and queueOne offline diagram of the services, with icons and zoom.
/make-dashboard revenue by region and monthly trend from data/sales.csvOne offline dashboard built from the CSV file, with sortable tables and export.
/make-motion a 6 second title card that counts up to 18One short MP4 video with a title card that counts up to 18.

Eval pass rates

Haiku and Sonnet pass 30; gemma4 passes 15#

Valid builds out of 30 eval prompts per model: 14 make-dashboard, 8 make-diagram and 8 make-explainer prompts. gemma4 built 10, 5 and 0 of them. gemma4 is a small local model, shown for information only.
Data table (3 rows)
modelbuilds
Claude Haiku30
Claude Sonnet30
gemma4 (local)15

Rendered clip

A make-motion video renders from JSON#

A 4 second make-motion video rendered from a JSON spec. The first scene shows the heading One JSON file, one video, and the second counts up to 18.

Narrated clip

A narrated 15 second clip: prompt to dashboard#

Made with make-motion from one prompt at 1920x1080. The follow-up "Add a voiceover that reads each scene aloud" added a Kokoro voiceover, synthesised locally.

Launch clip

10 second launch clip: up to 3x faster#

The product name scales in, a counter runs from 1 to 3, and three feature labels appear one after another. Voiceover by Kokoro.

SQL guard clip

12 second clip explains the make-dashboard SQL guard#

A rejected query card, then three stacked boxes drawn in order: parse with DuckDB, allowlist the tables, locked connection. Voiceover by Kokoro.

Square clip

A square 1080x1080 clip shows quarterly highlights#

A revenue counter to $42.1M and a bar chart of signups by quarter, sized for social feeds. Voiceover by Kokoro.

Versus hand-written

Spec-driven pages cost less and stay consistent#

Hand-written AI pages

Caution
  • The model writes the HTML, CSS and script for every page, which costs more output.
  • Each run can produce a different look, and it often has the generic look of an AI page.
  • A small change can disturb the rest of the page.

Spec-driven pages

Good
  • The model writes only JSON, so the cheapest model passes the eval gates.
  • The same spec always gives the same page, and a change is one edited field.
  • Validation names the JSON path and the fix, so most errors are repaired in one or two runs.

Verdict. A spec keeps the cost low and the output the same from run to run.

Known limits

Five known limits each have a clear workaround#

SeverityRiskMitigation
Low An interactive chart needs a make-dashboard spec. Inline rows give a static chart only. Use a make-dashboard spec when the reader needs the interactive views.
Medium Explainer charts refuse Postgres and MySQL sources, so builds never reach the network. Export the data to CSV or Parquet first.
Low In a slide deck, browser find (Ctrl-F) searches only the current slide. Use page mode when the reader needs to search the whole text.
Low Each static chart ships four drawings, which adds weight to long pages. Keep long pages to a few charts.
Medium make-motion was not re-evaluated on this branch, so it is not pinned to a model. Check each video by hand before sharing it.