A Claude Code skill that turns written specs into self-contained interactive HTML mockups — and closes the review loop with anchored comments, general notes, and a one-word submitted trigger that delivers feedback back to Claude.
Inspired by Thariq Shihipar's HTML-as-spec workflow: a rendered mockup communicates aesthetic and functional intent in a way prose can't, and Claude can read it back as input when implementing.
Given a spec markdown file (the kind superpowers:brainstorming produces, or any PRD), the skill generates a single .html file next to it. The HTML is:
- Self-contained — one file, opens from
file://, no build step. Tailwind + marked.js + DOMPurify via CDN. - Four views — Live (the working mockup), Annotated (load-bearing decisions with spec callouts), Comment (inline review surface), Spec (original markdown rendered inline).
- Adaptive mode — UI specs render as clickable mockups; backend/concept specs render as interactive concept diagrams (API explorers, sequence diagrams, state machines, data-flow visualizations).
- Round-trip-capable — every meaningful element is a
data-commentableanchor. The reviewer hovers, clicks+, leaves a comment. A general-notes textarea handles cross-cutting feedback. Submit bundles everything as JSON and ships it back to Claude.
This is a personal Claude Code skill. Clone (or symlink) into your user skills directory:
git clone https://github.com/roeibh/interactive-spec ~/.claude/skills/interactive-spec
# or, if you've already cloned it elsewhere:
# ln -sfn "$(pwd)/interactive-spec" ~/.claude/skills/interactive-specThen restart Claude Code; the skill will appear in your available skills. Verify with:
ls ~/.claude/skills/interactive-spec/SKILL.md(If you'd rather copy than symlink, swap ln -sfn for cp -a — but the symlink keeps you on the repo version as it evolves.)
In any Claude Code session, with a spec in docs/superpowers/specs/ or any markdown file:
> turn this spec into a clickable mockup
The skill detects the spec, classifies it (UI vs concept-viz vs mixed), and writes <spec-name>.html next to it. Open the file and review.
The bare HTML works from file:// — copy/paste or download the feedback JSON when you're done reviewing. For a smoother loop, run the included dev server:
./scripts/serve.sh <spec-directory> [port]
# e.g., from the repo root:
.claude/skills/interactive-spec/scripts/serve.sh docs/superpowers/specs/ 8765Then open http://localhost:8765/<spec-name>.html. You get:
- Auto-reload — editing the HTML rewrites your open tab within a second (Claude does this during
consume-feedbackphase). - Send to Claude Code — the submit modal POSTs your feedback directly to a temp file at
~/.claude/interactive-spec-feedback/<spec-slug>-<timestamp>.json. Switch back to Claude Code, type one word —submitted— and the skill picks up the file, classifies each comment, and updates the spec and/or the HTML in place.
No hooks, no settings.json changes, no copy-paste.
The skill is one skill, two distinct phases:
- Generate phase — produce the HTML from a spec or plan markdown.
- Consume-feedback phase — apply a feedback JSON (pasted inline, dropped as a file, or written to
~/.claude/interactive-spec-feedback/by the server) by updating the spec markdown and/or the HTML.
Claude picks the phase based on the input. See SKILL.md for the full machinery — including how comments get classified (spec change / mockup fix / open question / out of scope) and how decisions-beyond-the-spec get surfaced honestly in the Annotated view.
interactive-spec/
├── SKILL.md # the load-bearing description + process
├── README.md # this file
├── LICENSE # MIT
├── assets/
│ └── base-template.html # the 4-view shell that generated HTMLs extend
├── references/
│ ├── ui-mockup-patterns.md # UI-spec patterns (pages / wizards / tables / mobile / etc.)
│ └── concept-viz-patterns.md # non-UI patterns (API / sequence / state machine / etc.)
├── scripts/
│ ├── serve.py # Python http.server + SSE livereload + POST /submit-feedback
│ └── serve.sh # shell wrapper for serve.py
└── evals/
├── evals.json # canonical test prompts
└── sample-specs/ # 4 example specs + their generated HTMLs
The evals/sample-specs/ directory contains three worked examples spanning the skill's range:
- Onboarding checklist (UI mode) — page + collapsed pill, multi-state mockup
- Webhook delivery service (concept mode) — backend pipeline visualization
- Feature flags system (mixed mode) — admin UI + sync pipeline
Open any of the .html files to see how the skill renders different spec shapes. Or boot the server pointed at evals/sample-specs/ and click around.
brainstorming has an ephemeral visual-companion that drives decisions during the conversation. interactive-spec is the persistent counterpart: produces an artifact after the spec is committed, lives next to it in the repo, and supports the closed comment-and-submit feedback loop across session boundaries.
The natural flow:
brainstorming → spec.md → interactive-spec generate → spec.html
↑ ↓
└──── consume-feedback ────┘
(loop until happy)
↓
writing-plans → implementation
A few choices worth knowing about, in case you're considering modifications:
- HTML is the spec, not a viewer. A rendered mockup beats prose for communicating aesthetic and functional intent. Claude can read it back as input when implementing.
- Be honest about what's decided. If the spec doesn't commit to a sort order, don't silently pick one and render it as if it's spec. Either flag the choice in the Annotated view, or render an ambiguous placeholder. Invented detail that looks decisive is the worst failure mode.
- Polished, not pretty for its own sake. Default to polished. Drop to wireframe only when the spec is explicitly early-stage.
- One file. No build step. A
.htmlnext to a.mdis a first-class artifact; a.htmlthat needsnpm installis a hidden runtime. - Mark commentable elements generously. The feedback loop is only as good as anchor coverage. 15-40 per page is the sweet spot.
- Re-generatable. The spec is the source of truth; the HTML is recoverable from it.
MIT — see LICENSE.