# Respond Html > Render a structured HTML artifact instead of a chat reply β€” for plans, proposals, comparisons, audits, recommendations, mockups, and process/data visualizations. Single self-contained file saved under an html-answers/ directory, opened in browser, with inline βœ…/πŸ’¬/❌ reactions + comment box on every section, decision-block, and callout. Live stats in sticky toolbar. One button copies all feedback… - **Type:** Skill - **Install:** `agentstack add skill-davidsimoes-claude-skills-shared-respond-html` - **Verified:** Yes β€” security-reviewed for prompt injection and unsafe behavior - **Seller:** [davidsimoes](https://agentstack.voostack.com/s/davidsimoes) - **Installs:** 0 - **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [davidsimoes](https://github.com/davidsimoes) - **Source:** https://github.com/davidsimoes/claude-skills-shared/tree/main/respond-html ## Install ```sh agentstack add skill-davidsimoes-claude-skills-shared-respond-html ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # /respond-html β€” Structured HTML Artifacts For Reading & Feedback When a chat reply would be a wall of prose with implicit structure (sections, comparisons, decisions, tradeoffs), the artifact wins. The user scans the rendered HTML, reacts inline (βœ…/πŸ’¬/❌ + comment per section/decision-block/callout), hits πŸ“‹ Copy feedback, pastes the markdown back to chat. The skill makes that the default path, not a special occasion. ## What this skill is An **orchestrator** with one new template. It: 1. **Classifies** the request by content type. 2. **Delegates** to the right existing skill when one fits (`/dataviz` data mode, `/dataviz` process mode, `/frontend-design`), or **renders** with the response-artifact template when none of those fit (the gap this skill fills: plans, proposals, comparisons, audits, recommendations, structured analysis). 3. **QAs** the output with `/chrome-validate all` β€” non-optional. No "looks good" without evidence. 4. **Opens** the file in the user's browser via `open`. ## Phase 0 β€” Classify content type Use `references/content-type-detection.md` for the full decision tree. Quick form: | Signal | Route | |---|---| | Input is JSON/CSV/JSONL/TSV, or user says "analyze this data" / "EDA" / "profile this dataset" | `/dataviz` **data mode** | | User describes a workflow, pipeline, architecture, state machine, "how X works"; numbered steps; sequence diagrams | `/dataviz` **process mode** | | User asks for a UI component, page, app interface, prototype, "mock up X", "design a screen for X" | `/frontend-design` (apply its aesthetics rules) + this skill's template if the output is also a reading artifact | | **Plan** ("show me a plan for X", "approach to X", roadmap) | **response-artifact template** | | **Proposal** ("propose X", "recommend an approach", "what would you do") | **response-artifact template** | | **Comparison** ("compare A vs B", "which is better", "tradeoffs of X") | **response-artifact template** | | **Audit** ("review this", "audit X", "what's wrong with Y") | **response-artifact template** | | **Recommendation / structured analysis** | **response-artifact template** | | Ambiguous | One-line classification with reasoning, then ask. Default lean: response-artifact (it handles the widest range). | Announce the classification in one line before proceeding: *"Classifying as a **plan** with 3 options β†’ response-artifact template."* ## Phase 0.5 β€” Pick the gravity tag After content-type, pick the **gravity tag** that matches the artifact's stakes + verdict + shape. The gravity tag deterministically chooses the font pair and accent β€” no rotation, no "what did I use last time." See `references/aesthetics.md` for the 8-row mapping table and the 3-step picker. Eight tags: `stern` Β· `decisive` Β· `balanced` Β· `distinctive` Β· `editorial` Β· `measured` Β· `light` Β· `multidimensional`. Extend the announcement: *"Classifying as a **plan** with 3 options, gravity **decisive** β†’ Crimson Pro + Manrope + jade."* The chosen gravity tag goes into the artifact's eyebrow (e.g. "Plan Β· decisive"). ## Phase 1 β€” If delegating, hand off cleanly When the route is `/dataviz` or `/frontend-design`: - **Invocation**: use the Skill tool with the exact skill name (`skill: "dataviz"` or `skill: "frontend-design:frontend-design"`) and pass the user's original request plus any context already gathered as `args`. For /dataviz, prefix the args with `data:` or `process:` to bypass /dataviz's autodetect β€” your Phase 0 classification is authoritative; double-classifying invites silent conflict. - **Output path divergence**: /dataviz defaults to `data/{slug}_{hash6}_report.html` in the current working directory; /frontend-design typically produces code in chat or scaffolds a framework project, not a single HTML file. Phase 3 (chrome-validate) and Phase 4 (`open`) below assume the project-aware path resolved in Phase 2 exists β€” when delegating, you must either: - (a) pass an `output:` arg to /dataviz (supported β€” /dataviz writes there verbatim and suppresses its own Phase 6 `open`), OR - (b) use whatever path the target skill actually produces (read its SKILL.md or its emitted summary) and substitute that path into Phase 3 + 4. - For /dataviz, prefer (a) β€” concrete syntax: `data: output:/abs/path/index.html` or `process: output:/abs/path/index.html`. /frontend-design has no equivalent output-arg yet, so (b) is the only option there. - Don't duplicate work β€” let the target skill own the render. - After the target skill finishes, run the chrome-validate gate (Phase 3) yourself against whatever file path the target produced. Stop here. Do not also produce a response-artifact. **Maturity note**: when the route is unambiguous (a `.csv` file β†’ /dataviz, an explicit "mock up a button" β†’ /frontend-design), delegate without asking. Surface only when the request genuinely straddles modes (e.g., "show me the data AND a plan") β€” see Compound requests in `references/content-type-detection.md`. The response-artifact path (own template, Phase 2 below) is the well-trodden flow; delegation is less battle-tested but should not be avoided when clearly correct. ## Phase 2 β€” If rendering, build the artifact **Inputs**: the user's request + whatever context was gathered (files read, conversation, prior decisions). **Output path** (project-aware): 1. **Look at `pwd`**. If it's inside one of your standard project roots (e.g. `~/dev//`), write to `/.html-answers//index.html`. 2. **Otherwise scan the content** for project-name keywords that match your dev directories (e.g. `ls ~/dev/`). If a clear match, use that project's `.html-answers/`. 3. **Fallback** for cross-cutting / no-specific-project content: a generic shared dir like `~/dev/html-answers//index.html` (configure to taste). `` is a 3-5 word kebab-case summary of the topic (e.g., `compare-deploy-targets`, `audit-inbox-triage`, `q3-roadmap-plan`). State the chosen path inline before rendering: *"Detected the `acme-migration` project β€” saving to `~/dev/acme-migration/.html-answers/vercel-plan/`."* If you're unsure (no `pwd` match, no clean keyword hit), surface a single AskUserQuestion with 2-3 plausible roots before rendering. The path determines where TTL cleanup later sweeps from (see Phase 5). **Template**: `templates/response-artifact.html`. Replace the placeholder tokens listed at the top of the file. See `references/response-artifact-spec.md` for what goes in each section and how to choose font pair + accent. **Aesthetics come from the gravity tag picked in Phase 0.5** β€” no rotation, no random pick. - The gravity row in `references/aesthetics.md` specifies the body serif, heading sans, and accent. Use exactly that combo. - Never use any font on the never-list (Inter, Roboto, Arial, Helvetica, Space Grotesk, Open Sans, Lato, Merriweather). - Two artifacts of the same gravity will share the aesthetic. That's correct β€” they're the same shape. - If the gravity feels wrong while drafting, change the tag, not the font pair. **Sections must include** (in order): 1. **BLUF** β€” bottom-line-up-front, 1-3 sentences. The single most important thing. 2. **Context / problem statement** β€” what we're answering and why. 3. **Body sections** β€” the actual content. Use callouts (`decision`, `tradeoff`, `risk`, `recommendation`) and decision-blocks (question + options + recommendation) where they earn their keep. Each section, decision-block, and callout becomes a **reactable unit** in the feedback model β€” the user can βœ…/πŸ’¬/❌ each one independently. 4. **Open questions / next steps** β€” what's unresolved, what the user needs to decide. **Don't** dump raw chat transcripts into HTML. Synthesize. The artifact's value is the structure β€” TOC, callouts, scannable hierarchy, AND the inline reaction model. If you just paste prose into `` tags you've added zero value over the chat reply. **Feedback model** (handled by the template's JS β€” no manual work needed): - Every section, decision-block, and callout gets βœ…/πŸ’¬/❌ buttons + comment box auto-injected. - Sticky toolbar at the top shows live counts. - One button copies grouped-by-section markdown to clipboard for the user to paste back. - See `references/response-artifact-spec.md` for the snippet library and ID conventions. ## Phase 2.5 β€” Strategic content gate (only for plan/proposal/audit/recommendation) Trigger condition (NOT a gravity tag β€” that's the visual layer; this is the content-type layer): - The **content type** from Phase 0 is plan / proposal / audit / recommendation, AND - The artifact contains at least one **decision-block** OR a **recommendation callout** that selects between options (testable: grep the rendered HTML for `class="decision-block"` or `class="callout recommendation"`). Pure-prose explainers without a recommend-an-option element don't trigger the gate. When both are true, invoke `/fresh-eyes` on the rendered output BEFORE the chrome-validate gate. The hostile-audit pass catches what chrome-validate doesn't: stale claims, missing options, premise-not-questioned, scope drift from the original ask. Skip `/fresh-eyes` for visualization-shaped output (data, process diagrams, UI mockups) where the artifact is descriptive not prescriptive β€” chrome-validate alone covers those. Also skip for short single-decision artifacts (gravity `light`) β€” over-auditing wastes context. Strategic path: `Phase 2 (render) β†’ Phase 2.5 (/fresh-eyes) β†’ Phase 3 (chrome-validate) β†’ Phase 4 (open)`. ## Phase 3 β€” Chrome-validate gate (non-optional) After writing the file, run `/chrome-validate all` against the artifact. See `references/chrome-validate-handoff.md` for the exact invocation β€” note the `file://` rejection issue with `claude-in-chrome` and the `python3 -m http.server` workaround documented there. Surface the GATE/STATUS/EVIDENCE block to the user. Do not say "ready" until every gate is PASS. On FAIL: - Show the user the failing gate + the evidence - Propose a fix (don't auto-apply changes that affect content/design β€” show the failure first, ask what to do) - Once fixed, re-run the gate The gate exists because untested HTML accumulates silent regressions (broken images, off-by-default CSS, dead links). The discipline is borrowed from `pre-send-qa-gate.md` Phase 3, reduced to a single tool call. ## Phase 4 β€” Open and report ```bash open /index.html ``` …where `` is whichever path Phase 2 resolved (project-aware). Final line to the user: ``` Ready at file:///index.html β€” opening now. ``` Plus a one-line summary of what the artifact contains (so the user knows what to look at without opening it first). ## Phase 5 β€” Cleanup (passive, runs via /close) Artifacts strictly older than 30 days get swept by the `/close` skill's end-of-session ritual. Exemption is file-based (not reaction-based β€” reactions live in browser localStorage, not on disk): - A `.keep` file in the artifact dir β†’ that slug is pinned forever - A `.keep` file in the parent `.html-answers/` dir β†’ ALL slugs in that project are pinned - A `feedback.md` file in the artifact dir β†’ that slug is pinned (use this when you've exported feedback via πŸ“‹ Copy feedback) You don't invoke this β€” it's a side-effect of `/close`. Just be aware: - Pre-existing artifacts in the output path are at risk of cleanup after 30 days if not pinned. - To preserve reactions across the TTL, **export feedback markdown** (πŸ“‹ Copy feedback button) and save as `/feedback.md`. That's the durable record β€” the in-browser localStorage is NOT readable from disk. ## When NOT to use this skill - The answer fits in 1-3 short sentences (just reply). - The user explicitly asked for chat, code, or a different format ("just tell me", "in chat is fine"). - The task is a single-file code edit, debug, or shell operation. - The user is mid-flow on something else and wants a quick aside. When the user invokes the skill but the request doesn't actually fit it, say so once and offer the alternative: *"This looks like a one-line answer β€” reply in chat instead?"* ## Anti-patterns - **Dumping raw conversation into HTML.** Synthesize. The artifact must add structural value over the chat reply, not duplicate it. - **Generic AI aesthetics.** Inter, Roboto, Arial, Space Grotesk, purple-on-white gradients, candy-color CTAs. See `references/aesthetics.md` for the gravity-tag mapping table and the "never" list. - **Skipping chrome-validate.** That's the gate. A render that hasn't been validated is not ready. - **Auto-fixing chrome-validate failures without showing the user first.** Failures often surface real issues they want to weigh in on (a missing section, wrong content, broken link to a doc that doesn't exist yet). Show, then fix. - **Deploying anywhere public by default.** This skill is local-only. If the user wants to share, they'll say so β€” push or deploy then. Don't auto-deploy. - **Opening multiple files.** Always `open` exactly the `index.html`. The browser-spam pattern is annoying and breaks the user's flow. - **Speculative additions.** Don't add charts, animations, or sections he didn't ask for. The template is reading-optimized for a reason. ## What this skill does NOT do - Doesn't visualize raw data β€” that's `/dataviz` data mode. - Doesn't render workflow diagrams β€” that's `/dataviz` process mode. - Doesn't design new UI components β€” that's `/frontend-design`. - Doesn't deploy or share publicly β€” local only. - Doesn't replace the chat reply for trivial answers. ## Related skills - `/dataviz` β€” data mode for JSON/CSV analysis; process mode for workflows/architectures. /respond-html delegates to it. - `/frontend-design` β€” bold UI/component design. /respond-html borrows the aesthetics rules and delegates UI-mockup requests. - `/chrome-validate` β€” the QA gate. Always runs after a render. - `/dataviz` and `/respond-html` partially overlap on "process mode" vs "plan/proposal". Rule: if the content is **how something works** (steps, actors, branches) β†’ `/dataviz` process. If the content is **what we should do** (options, recommendations, tradeoffs) β†’ `/respond-html`. ## References - `references/content-type-detection.md` β€” full decision tree, edge cases, examples. - `references/response-artifact-spec.md` β€” section-by-section spec, snippet library (callouts, decision-blocks, tables), TOC generation. - `references/aesthetics.md` β€” gravity-tag β†’ font/accent mapping (8 rows), never-list, vibe check. - `references/chrome-validate-handoff.md` β€” exact invocation, evidence-block format, what to do on FAIL. - `templates/response-artifact.html` β€” the template skeleton. Read it once before your first render to understand the placeholder tokens. ## Known limitations (v0.3.1) Documented gaps rather than silent failures β€” the user should know what's unsupported: - **Delegation paths to /dataviz and /frontend-design are documented but lightly tested.** The response-artifact path (own template) is the well-trodden flow. When delegating, output-path management and aesthetic-rule propagation depend on the orchestrator (Claude) being careful β€” see Phase 1. - **/frontend-design is a plugin skill without `user-invocable: true` or trigger phrases.** Invocation must go via the Skill tool with the exact name `frontend-design:frontend-design`. Output is typically code in chat or scaffolded frameworks, NOT a single HTML file at a known path β€” Phase 3 (`/chrome-validate`) doesn't apply cleanly when delegating to frontend-design. - **`claude-in-chrome` MCP may reject `file://` URLs** depending on the harness version β€” the chrome-validate workaround is to spin up `python3 -m http.server` and validate against `http://localhost:/`. See `references/chrome-validate-handoff.md`. - **Reactions persist locally in browser localStorage** keyed by pathname. They survive reload but don't migrate across origins (file:// vs localhost), and don't survive across browsers/devices. There's no server-side persistence β€” the user's expected to react in a single session, copy as markdown, paste back to chat. - **Aesthetic … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source β€” we do not rehost the code. - **Author:** [davidsimoes](https://github.com/davidsimoes) - **Source:** [davidsimoes/claude-skills-shared](https://github.com/davidsimoes/claude-skills-shared) - **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:** no - **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-davidsimoes-claude-skills-shared-respond-html - Seller: https://agentstack.voostack.com/s/davidsimoes - 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%.