# Interactive Html

> Turn a folder of static HTML into a live commenting surface and act as the agent that responds. Inject a client library, start a local server, watch an on-disk inbox; when the user highlights text, picks an element, drags a region, or asks a question, read it and edit the HTML in response. If the user has no HTML yet, generate a polished self-contained page from their description first, then star…

- **Type:** Skill
- **Install:** `agentstack add skill-machbuilds-interactive-html-interactive-html`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [machbuilds](https://agentstack.voostack.com/s/machbuilds)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [machbuilds](https://github.com/machbuilds)
- **Source:** https://github.com/machbuilds/interactive-html/tree/main/skills/interactive-html

## Install

```sh
agentstack add skill-machbuilds-interactive-html-interactive-html
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Interactive HTML

Turn any folder of HTML into a place the user can leave inline comments
(text selections, element selections, page-level notes), then **you are the
agent** that responds: comments land in an on-disk inbox, you read them, edit
the HTML, and the page auto-reloads with a walkthrough of what changed.

Because *you* (the current session) do the edits, there is no separate agent
process and no cold-start — the loop is as fast as you can make an edit.

## Runtime location

This skill is self-contained: its runtime ships in this same directory. The
installer bakes the absolute path below in at install time, so every command
here is runnable as written.

```
IH_HOME = __IH_HOME__
```

## When to invoke

- "make this page interactive" / "make these pages interactive" → **Setup flow** (existing HTML)
- "let me comment on this page" / "add feedback to this page" → **Setup flow**
- "build me a page about …" / "create an html page" / "design a page for …" → **Generate flow**, then offer the loop
- "make an interactive page from this" / "I have this content, make it an interactive page" → **Generate flow** → **Setup flow** back-to-back, no second confirmation
- "stop the interactive server" / "shut it down" → **Stop flow**
- "make these pages static again" / "remove the comment layer" → **Removal flow**

## Setup flow

1. **Pick the target directory.** Default to the current working directory
   (the project the user is in). If they name a folder, use that. If it has no
   `*.html`, see the Create-then-setup flow.

2. **Launch** — inject the client tags and start the server in one step, in the
   background (do NOT block the session):

   ```
   python __IH_HOME__/cli/ih.py  --no-watch --no-open
   ```

   `--no-watch` is important: it starts the server only, because **you** are the
   agent — we do not want a second `claude -p` agent competing with you. The
   launcher prints the page URLs (it auto-bumps off a busy port).

3. **Tell the user the URL(s)** it printed, e.g. `http://localhost:5050/index.html`.

4. **Monitor the inbox** so new comments notify you immediately:

   ```
   Monitor on path: /.ih/comments.jsonl
   ```

   Do NOT poll — let the Monitor notification arrive.

## Responding to a comment batch

When a new line appears in `/.ih/comments.jsonl`:

- Read the new batch. Each comment has a stable `id`, a `kind`
  (`text` / `element` / `region` / `general`), an `intent`
  (`change` / `question`), and an `anchor` with a CSS `selector`, `tag`,
  `quote`, and `html_snippet`. **Locate the element by its visible text
  or `html_snippet`** — match on content, not on runtime-only attributes.
  `kind: "region"` comments add `anchor.multi` (selectors for every element
  the user circled) and `anchor.region` (the drawn rectangle, page
  coordinates) — treat the set as the target area.

- **`intent: "question"` comments are questions, not edit requests.** Do
  NOT modify the page for them. Answer in the update's `answers` array
  (schema below) — concretely, citing the relevant part of the page. The
  client shows your answer in its Q&A tab, anchored to where they asked.

- For `intent: "change"` comments, edit the relevant `*.html` file(s).
  Keep edits minimal and focused on what was asked.

- Wrap each logical change in `">…`, or
  add a `data-ih-change="ch-"` attribute to an existing wrapping element.
  Exactly one anchor per change — the page uses these for the walkthrough.

- **Append** one batch object to `/.ih/updates.json`. It is a JSON array
  (newest last) — read it, append, write the whole array back:

  ```json
  {
    "batch_id": "u-",
    "timestamp": "",
    "in_response_to_batch": "",
    "changes": [
      {
        "id": "ch-",
        "anchor": "ch-",
        "in_response_to": [""],
        "title": "short, concrete label",
        "description": "one or two sentences for the record"
      }
    ],
    "answers": [
      {
        "id": "a-",
        "in_response_to": [""],
        "text": "your answer, plain prose"
      }
    ]
  }
  ```

  Omit `changes` or `answers` when empty. An answers-only update doesn't
  reload the page — the client surfaces it in the Q&A tab in place.

The server detects the write and pushes an SSE event; the page reloads with
scroll preserved and offers a tour (or, for answers-only updates, shows the
Q&A tab without reloading). The page's busy banner clears when a change's or
answer's `in_response_to` matches a submitted comment id.

Rules:
- Edit only HTML files and `.ih/updates.json`.
- Every `id` under `changes` must have a matching `data-ih-change` in the HTML,
  and every new `data-ih-change` must appear in updates.json. Answers need no
  HTML anchor.
- Questions never modify the page unless the question explicitly asks for an
  edit too.

## Generate flow (when the user has no HTML yet)

When the user asks you to **build a page** ("build me a page about X", "make
a page from this content", "make an interactive page from this"), generate
the HTML first, then run the Setup flow on it.

### 1. Gather just enough context

If the user gave content or a clear description, don't interrogate them —
infer and build. Only ask when genuinely ambiguous, and at most once:

- **Purpose & audience** — who reads this and what should they do/feel?
- **Visual feel** — light or dark, dense or spacious, serious or playful?
- **Structure** — report, landing page, dashboard, docs, portfolio?

Default when unstated: light theme with `prefers-color-scheme` dark
support, spacious, content-first.

### 2. Write the page

One self-contained `*.html` file. Inline CSS in a `` block. No
external dependencies — no CDNs, no Google Fonts, no frameworks. The file
must render perfectly from `file://` and offline. Save to the current
directory unless the user names one. Filename from the content
(`q3-report.html`, not `page1.html`).

#### Quality baseline (always)

- **Semantic HTML5** — ``, ``, ``, ``,
  ``, ``; one ``; heading levels never skip.
- **System font stack** — `-apple-system, BlinkMacSystemFont, "Segoe UI",
  system-ui, sans-serif` (and a mono stack for code). Crisp everywhere,
  zero network requests.
- **Design tokens as CSS custom properties** — colors, spacing scale, and
  radii defined once in `:root`, used everywhere. Makes later edits (and
  your agent edits via interactive comments) surgical.
- **Responsive by default** — readable at 375px, 768px, 1024px, 1440px.
  Prefer intrinsic layouts (max-width, flex/grid with minmax, `clamp()`
  for type) over breakpoint thickets.
- **Dark mode is mandatory, not optional.** Every page ships both modes:
  define all colors as tokens in `:root`, flip them in a single
  `@media (prefers-color-scheme: dark)` block, and never hardcode a color
  outside the tokens. A page that breaks in either mode is not done.
- **Reduced motion** — wrap animations in `prefers-reduced-motion: no-preference`.
- **Diagrams are inline SVG.** When the content describes structure, flow,
  sequence, comparison, or architecture, draw it — don't describe it in a
  paragraph. Inline `` only (no external images, no Mermaid script
  dependency). Use `currentColor` for strokes/text and the CSS tokens for
  fills so every diagram adapts to dark mode automatically. Label axes and
  nodes; a diagram that needs the surrounding prose to be understood has
  failed.
- **Accessibility** — visible focus states (`:focus-visible`), ARIA only
  where semantics don't already cover it, alt text, 44px minimum touch
  targets, AA contrast.
- **Real content** — never lorem ipsum. If the user's content is thin,
  write plausible, specific copy from context and mark anything invented
  with an HTML comment ``.

#### Design judgment (apply, don't recite)

- **Users scan, they don't read.** Strong visual hierarchy: prominence =
  importance. Clear sections. Front-load key terms in headings.
- **Don't make them think.** Self-evident beats clever. Use conventions —
  logo/title top-left, nav where people expect it.
- **Omit ruthlessly.** Cut half the words, then cut again. No happy talk,
  no filler introductions, no "Welcome to…".
- **One focal point per screen.** If everything shouts, nothing is heard.
- **Group related things visually; contain nested things.** Whitespace is
  the grouping tool, borders are the fallback.
- **Make clickable things look clickable** without hover — shape, color,
  placement.

#### Anti-slop list (never)

- Purple-to-blue gradient heroes as a default aesthetic
- Generic three-column "feature" grids with icon + blurb
- Decorative blobs, waves, or floating geometric shapes
- "Get Started" / "Learn More" buttons that lead nowhere
- Cookie-cutter testimonial sections with invented names
- Emoji as a substitute for visual design
- Drop-shadow rounded cards as the only component idea
- Center-everything layouts with no hierarchy
- Stock-photo placeholder rectangles

### 3. Self-QA before delivering (mandatory)

Run this checklist against the file you just wrote. Fix failures before
handing the file off — do not deliver a page that fails any of these:

- [ ] **Both color modes** — mentally render light and dark: every text/
      background pair stays readable, no hardcoded colors outside tokens
- [ ] **Heading hierarchy** — exactly one ``, no skipped levels
- [ ] **No placeholder content** — zero lorem ipsum; invented facts are
      marked ``
- [ ] **Zero network requests** — no CDN links, no Google Fonts, no
      external images; the page works from `file://` with WiFi off
- [ ] **375px sanity** — nothing overflows horizontally; touch targets
      ≥44px
- [ ] **SVGs in both modes** — diagrams use `currentColor`/tokens, legible
      on dark backgrounds
- [ ] **Focus visible** — interactive elements have a `:focus-visible`
      state

### 4. Chain into the comment loop

After saving:

1. Tell the user the file path you wrote.
2. Offer to open it (`open ` on macOS).
3. **If the original ask was "make an interactive page…"**, proceed
   immediately into the **Setup flow** above on the file's directory —
   don't make the user re-ask.
4. **Otherwise** offer: *"Want to iterate on it by commenting on the page
   itself? Say make it interactive and I'll start the comment loop."* If
   they accept, run Setup on the file's directory.

### Revision etiquette

When the user iterates later (in chat or via comments on the page):

- Edit the existing file; never regenerate from scratch unless asked —
  regeneration destroys their accumulated tweaks.
- Keep edits scoped to what was asked. The design tokens make global
  changes (colors, spacing) one-line edits.
- If a request conflicts with the quality baseline (e.g. "add a purple
  gradient hero"), do what they asked — the baseline is a default, not a
  veto over the user.

## On startup in a directory that already has `.ih/`

1. Read `.ih/comments.jsonl` for comment ids.
2. Read `.ih/updates.json` and union every `changes[*].in_response_to` —
   those are already handled.
3. If unhandled comments remain, tell the user the count and offer to process.
4. Either way, start the server (Setup step 2) and the Monitor (step 4).

## Stop flow

1. Find the port (the launcher printed it; default 5050). Confirm with
   `curl -s http://localhost:/_ih/info`.
2. `lsof -ti: | xargs kill`
3. Confirm `lsof -i:` is silent.

The server also self-retires on parent-death or idle timeout, so if you simply
end the session it cleans itself up.

## Removal flow

Strip the client tags for a clean, server-independent copy:

```
python __IH_HOME__/cli/inject.py  --remove
```

This leaves the `.ih/` directory in place; delete it manually if unwanted.

## Headless alternative (no live session)

When no Claude session is driving the page (e.g. an automated/background run),
use the standalone watcher instead of this skill — it dispatches batches to an
agent CLI:

```
python __IH_HOME__/cli/ih.py                   # full loop, claude -p agent
python __IH_HOME__/cli/ih.py  --agent builtin  # bundled agent (ANTHROPIC_API_KEY)
```

## Gotchas

- The injected tags reference `/client/ih.css` and `/client/ih.js`, served by
  the server from the repo's `client/` folder. Pages only work through the
  server, not opened as `file://`.
- `.ih/updates.json` is append-only and order matters — append, don't prepend.
- `anchor` values in updates.json must match a real `data-ih-change` in the
  HTML, or the walkthrough warns "anchor not found".

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [machbuilds](https://github.com/machbuilds)
- **Source:** [machbuilds/interactive-html](https://github.com/machbuilds/interactive-html)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-machbuilds-interactive-html-interactive-html
- Seller: https://agentstack.voostack.com/s/machbuilds
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.