| name | explainer |
| description | Build a standalone HTML explainer/decision-doc for the Próspera Radar project in the house style, token-efficiently. Use when Trey asks for an HTML explainer, walkthrough, decision doc, architecture brief, or visual brief. Author only the body fragment; the shared CSS is inlined by assemble.py so no stylesheet is ever regenerated. |
Próspera Radar explainer skill
House style for the explainers that live in docs/explainers/. The point of this skill
is token efficiency: never hand-write CSS again. Author the body, run the assembler,
the shared stylesheet gets inlined into a portable standalone file.
assemble.py is skill/harness tooling, not production code — same category as the
allowed scripts/phase3_*.py reproducibility harness, so it is not a CLAUDE.md
"no production Python" violation. It uses only the Python stdlib (no deps) and runs
with the system python3.
The loop (3 steps)
- Write a body fragment — raw HTML for inside
<body>, usually one
<div class="wrap"><nav>…</nav><main>…</main></div>. Put it in scratch
($CLAUDE_JOB_DIR/tmp/<name>.body.html) or anywhere. No <html>/<head>/<style>.
- Assemble:
python3 .claude/skills/explainer/assemble.py \
--title "Short title" \
--body "$CLAUDE_JOB_DIR/tmp/<name>.body.html" \
--out docs/explainers/<topic>-YYYY-MM-DD.html
SendUserFile the --out path. It is standalone (CSS inlined) — opens anywhere.
template.body.html is a ready skeleton (nav + sections + footer). Copy it, fill it in.
Conventions
- Location:
docs/explainers/. Name: <topic>-YYYY-MM-DD.html (date = today).
The assembler creates docs/explainers/ on first use (mkdir -p-style).
- Structure: sticky left
<nav> with a TOC (<a class="sec"> for top-level,
plain <a> for sub-items, href="#id" anchors) + scrollable <main>. Number <h2>
with <span class="n">N</span>.
- Always open with a "read this first" framing when the doc carries hard truths, so
the reader calibrates. Use
.big-caveat or a .lead + .callout.
- Provenance tags are load-bearing for this project — every capability/claim should be
visibly tagged for how confident we are that it's actually running. This is a monitoring
and engineering project: distinguish what's live in prod from what's merely deployed,
configured, or aspirational. Reuse the chip vocabulary below consistently:
c-green = live / verified-running-in-prodc-amber = config-defined / deployed-but-unverified / needs-reviewc-red = gap / NOT monitored / known blind spotc-gray = illustrative / examplec-blue = scope choice / convention / by-designc-violet = definition (pairs with .callout.def)
- Voice: sharp, plain, honest. Define jargon inline for non-expert readers. Reflect
what is actually built and running, not what was aspired to. Write the subject matter
freely — Próspera, ZEDE, Honduras, the PACT Act, the ingest pipeline, etc. are the whole
point of these docs.
Component vocabulary (classes in explainer.css)
| Class | Use |
|---|
.lead | opening sentence, larger |
.kicker | small uppercase eyebrow above an h1/h2 |
.callout (.warn/.stop/.good/.def) | highlighted note; .def (violet) for definitions |
.big-caveat | the can't-miss top-of-doc honesty box |
.card | bordered panel; combine with .grid2/.grid3 for side-by-side |
.chip .c-* | inline provenance/status tag |
.flow | monospace box for pipelines / worked traces (preserves whitespace) |
dl.gloss (dt/dd) | glossary list |
ol.steps | auto-numbered circular step markers |
table, td.num/th.num | data tables; .num right-aligns + tabular figures |
.small, .tag | muted fine print / monospace inline label |
You keep full creative freedom — add inline style="" or one-off markup per doc when a
section needs it. The CSS is a floor, not a cage. If you add a component you'll reuse,
put it in explainer.css so the next doc gets it free.
