# Html Explanations

> Create standalone HTML for complex explanations, code/diff walkthroughs, plans, reports, handoffs, diagrams, research notes, and concepts.

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

## Install

```sh
agentstack add skill-jesse-merhi-skills-html-explanations
```

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

## About

# HTML Explanations

Use this skill when the user needs to understand something and prose would become a wall of text. Produce a standalone `.html` file that the user can open locally.

Good fits:

- Comparing options, tradeoffs, or approaches
- Explaining code flow, architecture, data flow, or a bug cause
- Explaining a PR, branch, commit, or diff without doing a code review
- Turning implementation plans, status updates, incident reports, or handoffs into visual reports
- Teaching a concept with diagrams, timelines, examples, or controls
- Turning research notes into a scannable explainer
- Making a small interactive demo that clarifies behavior

## Workflow

1. Decide the one thing the page should help the user understand.
2. Pick a format from `references/html-effectiveness-patterns.md`.
3. Create a local standalone HTML file. Use `assets/explanation-template.html` for a small starter, or copy a closer template from `assets/html-effectiveness/examples/`.
4. Keep the final chat reply short: what file you created, a `file://`
   link to open it, what it covers, and how it was verified.

## Output Rules

- Use one self-contained `.html` file with inline CSS and inline JavaScript.
- Do not add a build step or remote runtime dependency.
- Put the answer first in the page: a short headline, a one-paragraph summary, then the visual/interactive body.
- The first screen must be understandable without reading code. Explain
  the decision, bug, or concept in plain English before showing
  implementation details. Put code, dense mechanics, and caveats in
  lower sections or `` blocks unless the user's explicit goal
  is code reading.
- Use real labels from the task: filenames, functions, API names, states, events, dates, and decisions.
- Prefer compact sections, tables, flow diagrams, timelines, side-by-side cards, and toggles over long paragraphs.
- Put long code snippets inside `` blocks or side-by-side panels.
- If styling inline `` and block ``, add a dedicated
  `pre code` rule that resets inline-code backgrounds, borders, padding,
  radius, and font sizing inside code blocks. Inline code pill styles must
  never leak into block code, because they create unreadable pale strips on
  dark code panels.
- If the page explains code, link or label the exact files and symbols used as evidence.
- If the page includes user data or secrets from local files, keep it local and do not add external scripts, fonts, analytics, or image URLs.
- Make it readable on mobile and desktop.

## Page Shapes

Use these as starting points:

- **Code flow**: entrypoint -> important functions -> state/data movement -> result -> risk points.
- **Comparison**: option cards, decision matrix, when-to-use labels, final recommendation.
- **Concept explainer**: short definition, concrete example, diagram, edge cases, small interactive control.
- **Architecture map**: modules as nodes, arrows for calls/data/events, notes on ownership boundaries.
- **Bug explanation**: broken behavior, evidence, cause, smallest fix, verification.
- **PR/diff walkthrough**: what changed, changed flow map, files to read, before/after behavior, tests, open questions.
- **Plan/report**: goal or current state, phases or timeline, blockers, risks, checks, decisions needed, next actions.
- **Incident report**: impact, timeline, trigger, cause, fix, follow-ups, evidence.

## PR And Diff Pages

- Explain the change; do not judge it unless the user asks for review.
- Gather title, body, changed files, commits, key symbols, tests, and visible user/system behavior.
- Group files by changed flow: UI, API, persistence, background job, configuration, tests, docs, or similar.
- Include exact files and symbols to search.
- Put long snippets in expandable sections.
- Use review language only when a review already happened or the user asked for one.

## Plans, Reports, Incidents, And Handoffs

- Pick the report shape first: plan, status, incident, or handoff.
- Mark unknowns plainly; do not let the visual format make uncertain plans look more certain.
- Use absolute dates when timing matters.
- Use checklists only for actionable items.
- If local commands support the report, include the command and result.
- If no verification ran, say that in the page and final reply.

## Verification

Before saying the work is done:

- Open the HTML file in a browser when browser tools are available.
- Check the console for errors if the page has JavaScript.
- Visually inspect every `` block after CSS is applied.
  Confirm code text has strong contrast and is not inheriting inline
  code pill backgrounds, borders, padding, or rounded boxes.
- Read the first viewport as if you are the target user. If it is not
  clear what the recommendation or explanation is before any code
  block, rewrite the top of the page.
- Check at least one narrow viewport if the page is meant to be read on mobile.
- Report anything you did not verify.
- Always include a clickable `file://` URL in the final reply, for example:

```text
file:///absolute/path/to/explainer.html
```

## Source Inspiration

This skill vendors examples from `ThariqS/html-effectiveness` under `assets/html-effectiveness/examples/`. Read `references/html-effectiveness-patterns.md` when choosing a page shape.

When reusing one of those example files:

- Copy the closest HTML file into the task output location.
- Replace the fictional sample data with task-specific facts.
- Keep the existing copyright/SPDX header.
- Keep the vendored `assets/html-effectiveness/LICENSE` available with the skill.
- Preserve the standalone no-build style unless the user asks for something else.

## Source & license

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

- **Author:** [jesse-merhi](https://github.com/jesse-merhi)
- **Source:** [jesse-merhi/skills](https://github.com/jesse-merhi/skills)
- **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-jesse-merhi-skills-html-explanations
- Seller: https://agentstack.voostack.com/s/jesse-merhi
- 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%.