# Explainer > Builds a self-contained, interactive HTML explainer for a subject. - **Type:** Skill - **Install:** `agentstack add skill-tyom-skills-explainer` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [tyom](https://agentstack.voostack.com/s/tyom) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [tyom](https://github.com/tyom) - **Source:** https://github.com/tyom/skills/tree/main/skills/explainer ## Install ```sh agentstack add skill-tyom-skills-explainer ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Explain Visually Produce a single self-contained HTML file that explains a subject so well the reader can rebuild a mental model of it and explain it back. Beauty serves clarity. Interactivity serves understanding. Explain, don't decorate — teach before you summarize. Every claim is grounded in the real source material. The subject is arbitrary: a code repo, a library, a protocol or spec, a pull request, an HTTP API, a data model, a config format, a build pipeline, an algorithm, or a pure concept. The skill is technology-agnostic — adapt the sections and demos to whatever the subject actually is. ## Workflow ### 1. Investigate the source Read the actual material before writing a word of explanation. Do not explain from priors or from the name alone. When the argument is a **remote GitHub repo** (a URL or `owner/repo`, not a local path), get it onto disk first: `git clone --depth 1` into a tmp directory and explore there. If the repo is large, don't clone the whole thing — use the `ungit` command (when available) to pull only the specific files or directories you need as LLM-friendly context. When the URL already points at a path _within_ the repo (a subdirectory or file), the subject is that part, not the whole repo — definitely use `ungit` to fetch just that path into tmp rather than cloning everything. - For a **repo/codebase**: read the README, the manifest (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, etc.), the entry points, the module/folder layout, and the public surface (exported functions, types, routes, CLI). Note the language, the dependency count and what they are, the rough size, the version, the licence. - For a **spec/protocol/API**: read the document; extract the message/endpoint vocabulary, required vs optional fields, state machines, and error cases. - For a **PR/change**: read the diff and the surrounding code it touches; identify what changed, why, and the blast radius. - For a **concept**: gather the canonical definition, the failure mode it addresses, and at least one concrete worked example. Capture concrete, checkable facts as you go — names, paths, signatures, commands, versions, counts, field types, default values. These are the backbone of trust; positioning language is not. Define the audience. Default to a **smart reader who is new to this specific thing** but technically literate. Define jargon before using it; if a term needs heavy domain context, replace it with plain language or teach it visually. ### 2. Outline the teaching path Write the path before building. Decide: - what the reader must be able to explain back when done - the order that gets them there with the least backtracking - which ideas need a diagram, and which need a **live interactive demo** - what to omit (restraint is a feature) - which concrete source facts support each section **Content dimensions to cover** (include the ones that apply; skip what's irrelevant rather than padding): - **What it is** — the one-sentence identity, then what it _is not_ (the scope boundary). A clear "is / is not" pairing prevents the most common misunderstanding. - **Why it exists** — the problem or the old painful way, stated concretely. - **The mental model** — the one reusable idea the reader keeps. - **Architecture** — when the subject has structure: the parts, their responsibilities, how they connect, and the direction data/control flows. Name the real files/modules/services. - **Dependencies & footprint** — what it stands on (runtimes, libraries, services), how many, and the version/size/licence facts that set expectations. - **Data model** — the core types/entities/schemas/messages, their fields, and any state machines or lifecycles they walk. Show the real shapes. - **A concrete example** — one real, end-to-end path through the subject taken from the source. - **Lifecycle / end-to-end flow** — follow one unit (a request, a record, a build, a turn) from entry to exit. - **What to do next** — the action the reader takes after understanding. Across the piece, show at least one **transformation** — before/after, problem/solution, vague/clear, hidden/visible, or input/output. Contrast is what makes an idea land. ### 3. Build the HTML One self-contained `.html` file that opens in any browser with no build step. Inline the JS. **Prefer Tailwind via CDN for layout, spacing, typography, colour, and responsive behaviour** — reach for utility classes first. Use hand-rolled CSS (in a `` block) only for what Tailwind handles poorly: font imports and theme tokens, SVG/diagram styling, keyframe animations, syntax-highlighting classes, complex selectors or pseudo-elements, and fine refinements. Keep the two consistent — drive custom CSS from the same colour/spacing tokens Tailwind uses. The CDN script and a webfont are the only external assets allowed; nothing else the file can't live without. Structure: - A **hero fact sheet** as the opening screen (always — see below). - A sticky table of contents / section nav for anything longer than a couple of screens, so the artifact is navigable, not just scrollable. - One clear idea per section, with a simple concrete title (not a slogan); split into more sections before cramming one. - Slide-like sections on desktop; readable stacked sections on mobile. #### The hero fact sheet Every explainer opens with the same recognisable pattern — it sets the subject and earns trust before any prose. Build it from these stacked parts, top to bottom: 1. **Eyebrow chips** — a row of 1–3 small pill/tag chips for the categorical identity: subject kind + the most load-bearing classifiers. For code: `python package`, `v0.1.0 · MIT`. For non-code: the equivalent (e.g. `RFC · proposed standard`, `REST API · v2`, `concept`). Keep them mono and muted. 2. **The name**, as a restrained display title (`md:text-6xl`/`7xl`). 3. **A one-to-two-sentence plain-language identity** — what it is and who it's for, in prose, with a key identifier or two highlighted inline (mono/accent). No marketing. 4. **The grounding-fact grid** — a single horizontal row of **4–6 cells** (responsive: wrap to 2–3 columns on mobile), each a large coloured number/value over a small muted label. These are the checkable facts that set expectations at a glance. Pick the ones that actually matter for the subject: - code/repo: dependency count, public-surface or type count, file/module count, lines of code, test count, language/runtime version, licence. - spec/protocol: message/endpoint count, required-field count, version, status, error-code count. - API: endpoint count, auth model, rate limit, version, response format. - dataset: row/record count, column/field count, size on disk, format, licence. - concept: a small number of defining quantities or the canonical "N parts / N rules / N states." 5. **A meta line** directly under the grid (small, muted, mono) for the remaining provenance-ish facts that don't deserve a cell: package name, author/maintainer, optional extras, source URL, commit/date. Every value in the fact sheet must be a real, verified fact from the source — never a guess or a placeholder. If you can't verify a count, either compute it or leave that cell out; do not pad the grid to hit six. Use **diagrams** to show structure and flow: architecture layers, sequence/lifecycle, state machines, data shapes. Diagram text must be centred, aligned, and fully contained inside its shapes — use explicit font sizes, `text-anchor`, `dominant-baseline`, and padding so labels never drift, clip, or touch borders. Never reach for `overflow: hidden` on a content container to hide a layout problem instead of fixing it. #### Make it interactive where it earns understanding This is what separates a beautiful read from a thing the reader actually _gets_. Wherever a mechanism can be operated rather than described, let the reader operate it. Build the interactivity as a faithful, self-contained reimplementation of the real logic (a small JS port), and say so. Match the patterns to the subject: - **Transformer / encoder / parser** → an input the reader picks or edits, showing the exact output the real code would produce. Annotate the rules being applied. - **Reducer / state machine / algorithm** → a **navigable step-through** built to the higher bar in [`step-throughs.md`](step-throughs.md) (pure fold, both-direction nav, keyboard, diff highlight, semantic render, scenario selector) — the transitions are the lesson, not the final state. - **Architecture** → clickable layers/nodes that expand to reveal each part's job, public surface, and source file. - **API / protocol** → pick an endpoint or message and see the request/response or wire bytes; toggle options and watch the payload change. - **Data model** → toggle between fields, walk a record through its lifecycle states, or filter a schema. - **Config / flags** → flip options and render the resulting effective behaviour. Keep demos honest: port the real rules, use realistic sample data drawn from the source, and don't fake outputs. Provide a few curated scenarios rather than a blank canvas — guided beats open-ended for teaching. Every interactive control needs a visible, discoverable affordance (a labelled button, a select, a hover hint). Interactivity is a strong default, not a mandate for trivial subjects. A two-paragraph concept may need none. Anything with a transformation, a state machine, or composable parts almost always benefits. #### Provenance End with a short note on what the artifact was generated from (which files/docs were read) and that any live demos are faithful ports of the real logic. This earns the reader's trust and dates the explanation. ### 4. Verify Open the file in a real browser and check it before finishing — drive it directly, don't offload verification to another skill. **Decide the verification tool up front and confirm it's actually available before calling it** — don't trial-and-error through broken tool calls and error recovery. Use the first that's present: 1. **Chrome DevTools MCP** (or any other connected browser-automation MCP) — preferred. Check it's connected before reaching for anything else. 2. **System Chrome/Chromium, headless from the CLI** — confirm the binary first (`command -v`, or the known app path like `/Applications/Google Chrome.app/...`), then drive it with `--screenshot` / `--dump-dom`. Do **not** hand-wire Playwright or resolve npm module paths by hand; that `ERR_MODULE_NOT_FOUND` / CJS-vs-ESM rabbit hole burns tokens for nothing. If neither is available, leave the file for the user to open and say so, rather than thrashing. - Check desktop and a narrow mobile viewport. - Click every interactive control and confirm it behaves and updates correctly. - For a step-through demo: run the verify checklist in [`step-throughs.md`](step-throughs.md) (both-direction parity, diff highlight, keyboard, safe endpoints). - Fix overflow, overlap, clipped or drifting text, unreadable scale, cramped spacing, broken responsive layout, and any dead control. The artifact fails if the reader cannot explain the subject back, if a demo is broken, or if any text overlaps, clips, or overflows. ## Style - Choose a visual register that fits the subject. A codebase or protocol reads well in a focused **IDE-dark, mono-forward** theme; a product concept can take a warmer editorial palette. Commit to one coherent system of fonts, colour tokens, and spacing rather than mixing registers — express it through a small Tailwind config (`tailwind.config` inline, or CSS variables the utilities reference) so the whole document shares one palette. - Use a display face for headings and a monospace face for code, identifiers, and wire/data. Keep code visually distinct from prose. - Think in grids, line height, margins, and hierarchy. Whitespace is structure. - Keep hero titles restrained; avoid the largest sizes unless the title is very short. - On mobile: natural-height sections, single-column grids, compact display type, readable body text, diagrams that fit without dominating. A mobile hero should feel native, not like a cropped desktop slide. - Syntax-highlight code by hand with custom CSS classes (comment / keyword / string / function / literal) so snippets read like an editor, not a blob. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [tyom](https://github.com/tyom) - **Source:** [tyom/skills](https://github.com/tyom/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-tyom-skills-explainer - Seller: https://agentstack.voostack.com/s/tyom - 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%.