# Explainer

> Generate dense, visual-first HTML explainers in a signature dark aesthetic — diagrams carry the design, prose is captions only. Every section has a custom inline-SVG visualization: pipeline DAGs, archetype grids, hub-and-spoke diagrams, decision trees, risk matrices, gantt timelines, layer cakes, palette swatches, side-by-side comparisons. Dark theme with mint/violet/amber/cyan/coral accents, mon…

- **Type:** Skill
- **Install:** `agentstack add skill-angelopvtac-explainer-pack-explainer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Angelopvtac](https://agentstack.voostack.com/s/angelopvtac)
- **Installs:** 0
- **Category:** [Data & Analytics](https://agentstack.voostack.com/c/data-and-analytics)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Angelopvtac](https://github.com/Angelopvtac)
- **Source:** https://github.com/Angelopvtac/explainer-pack/tree/main/skills/Explainer

## Install

```sh
agentstack add skill-angelopvtac-explainer-pack-explainer
```

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

## About

# Explainer

A signature visual-first HTML format. Dense, dark-themed, diagram-driven reference documents that compress complex systems into scannable visual sections. Each section is a custom inline-SVG diagram with a one-line caption — never a paragraph.

## The rule

If a section is mostly prose, the skill is being misused. Every section must have a visualization that carries the meaning. Prose is captions. Captions are one sentence. If the meaning needs three sentences, the diagram is wrong.

## Canonical example

See `examples/sample-explainer.html` in the pack — a complete, self-contained explainer demonstrating sections, SVG diagrams, and the aesthetic. That is the bar.

## Workflow Routing

| Workflow | Trigger | File |
|----------|---------|------|
| **Generate** | "make an explainer", "build a visual doc", "explainer for X" | `Workflows/Generate.md` |
| **Revise** | "revise section N of the explainer", "update the X section in {path}", "fix section N in explainer" | `Workflows/Revise.md` |

## Tools

- `Tools/verify.ts` — pre-open gate. Checks HTML5 shape, `viewBox` on every renderable ``, no duplicate `id`s, and prose-creep per section. Run before opening.
- `Tools/render.ts` — substitutes `{{KEY}}` placeholders in `Boilerplate.html` from a JSON object (HTML-escaped by default; `raw_` prefix for raw HTML). Accepts `--theme=` to pick a theme from `Themes/`. Default: `anthropic`.

## References

- `References/Philosophy.md` — visual-first rules, anti-patterns, when to use what
- `References/Aesthetic.md` — CSS tokens, typography, spacing, color semantics
- `References/Components.md` — catalog of 15 reusable diagram patterns with code
- `References/Boilerplate.html` — ready-to-clone base template; CSS is structure-only and references token names (`var(--bg)`, `var(--accent)`, etc.) supplied by the selected theme

## Themes

Five baked-in themes, each a single CSS file in `Themes/`. The structural rules (single chrome accent, color is semantic and lives in the data layer only, chrome retreats, diagrams over prose) are universal — themes only change the surface, ink, accent, data palette, font stack, and a few component-level details.

| Theme | Identity | Sample |
|---|---|---|
| `anthropic` | Default. Warm-tinted near-black, clay accent. | `examples/samples/anthropic.html` |
| `fragapane` | Soft organic dark. Dusty rose accent, sentence-case kickers, generous whitespace, un-italic captions. | `examples/samples/fragapane.html` |
| `ft` | Light. FT salmon paper, brand-red accent, density-heavy. Print inverts to dark. | `examples/samples/ft.html` |
| `bloomberg` | Terminal. Pure black, brand yellow, mono-everywhere (the only theme that intentionally breaks the "mono for code only" rule). | `examples/samples/bloomberg.html` |
| `riso-zine` | Light. Off-cream paper, fluorescent riso red, geometric display sans (Space Grotesk). Optional `.halftone` texture utility. | `examples/samples/riso-zine.html` |

Pick at generation time with `--theme=` on `render.ts`, or pass the theme into the Generate workflow.

## Output destination

Default: `./explainers/{slug}.html` (relative to the current working directory). Slug is kebab-case.

To override the default, set the environment variable `EXPLAINER_OUT_DIR` to an absolute or `~/`-prefixed path (e.g. `~/explainers`, `~/Documents/explainers`). The skill resolves this at write time.

After writing, the workflow opens the file with the OS-native opener (`xdg-open` on Linux, `open` on macOS, `start` on Windows) when available; otherwise it prints the absolute path.

## Examples

**Example 1: Architecture reference**
```
User: "Make an explainer for our auth pipeline"
→ Invokes Generate workflow
→ Outlines 8 sections (pipeline DAG, schema, decision tree, etc.)
→ Writes ./explainers/auth-pipeline.html
→ Opens in browser
```

**Example 2: Decision comparison**
```
User: "Build a visual doc comparing Postgres / SQLite / DuckDB for our use case"
→ Invokes Generate workflow
→ Produces side-by-side comparison + 2×2 fit matrix + tier fan-out
→ Writes ./explainers/db-comparison.html
```

## Gotchas

- **Prose creep.** The most common failure: a section sneaks in 3–4 sentences because the diagram felt thin. If the meaning needs prose, the diagram is wrong — redesign the diagram, don't expand the caption.
- **Light theme drift.** Reviewers sometimes ask for "a lighter version." Refuse. The aesthetic is fixed; deviation breaks the format's identity.
- **External assets.** No ``, ``, ``, or CDN fonts. The doc must work offline and self-contained forever. System monospace + sans-serif stacks only.
- **Generic labelled rectangles.** If your "diagram" is boxes with text inside connected by arrows, you've drawn a PowerPoint slide, not an explainer. Each diagram must carry a structural insight from geometry, color, spatial relationships — not from reading text inside boxes.
- **Fewer than 6 sections.** The format expects density. If you can't justify 6 sections each carrying a real diagram, the topic probably wants a markdown doc instead.

## Source & license

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

- **Author:** [Angelopvtac](https://github.com/Angelopvtac)
- **Source:** [Angelopvtac/explainer-pack](https://github.com/Angelopvtac/explainer-pack)
- **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-angelopvtac-explainer-pack-explainer
- Seller: https://agentstack.voostack.com/s/angelopvtac
- 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%.