From folio
Use when turning a dense software artifact — a design spec, RFC, ADR, implementation plan, codebase tour, API or protocol design, migration/refactor proposal — or an in-progress feature/app brainstorm from the current Claude Code session into a single self-contained HTML explainer that mixes plain-language framing with diagrams and syntax-highlighted real code. Software topics only; language-, framework-, and stack-agnostic.
How this skill is triggered — by the user, by Claude, or both
Slash command
/folio:software-visual-explainerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
The output exists for one reason: the human actually reads the artifact. Optimize every micro-decision
The output exists for one reason: the human actually reads the artifact. Optimize every micro-decision (density, length, diagram choice, snippet selection) for "I will read this once" comprehension over "I have completely documented the topic." A 60% explanation the reader finishes beats a 100% one they won't open. Don't sacrifice clarity to save tokens — HTML is 2–4× more verbose than markdown and the cost is worth it.
Trigger phrases: "create an explainer", "help me understand X" (code/system topics), "make a visual walkthrough of this feature", "turn this spec into something readable", "single HTML file to explain this", "draw up what we've been discussing", "turn this brainstorm into an explainer".
The input is either a written artifact (a spec, doc, or chunk of code) or the conversation itself (a brainstorm with no doc yet). The moment a brainstorm gets written to a spec, treat that spec as the written artifact and use ordinary document mode.
Output: one fully self-contained HTML file by default, typically docs/explainers/<topic>.html.
For exploration topics with genuinely separate deliverables, a linked web of HTML files is acceptable —
each file its own complete artifact.
code-option-comparison.PR code review (diff annotation) and an undocumented brainstorm are modes within this skill, not
exclusions — see references/content-shape.md.
find_symbol,
get_symbols_overview, find_referencing_symbols); fall back to git grep. Trust the code over
the doc. (Brainstorm mode: verify only existing-code references; proposed code gets the
proposed badge instead.){{LANGUAGE}} in its <script> tag (duplicate the line
for multiple languages). See references/diagrams-and-code.md.templates/template.html. Replace placeholders; preserve the locked palette, fonts,
and component styles. Structure per references/content-shape.md.references/verification.md checklist first.This SKILL.md is the orchestrator. Detail lives in the reference files — read the one you need:
| For… | Read |
|---|---|
| Section order, PR mode, brainstorm mode, density, technical/non-technical mix | references/content-shape.md |
| Mermaid / HTML-box / SVG diagrams, and how code gets highlighted | references/diagrams-and-code.md |
| Copy buttons, tabs, sliders, badges, responsiveness, the locked visual system | references/primitives.md |
| The pre-completion checklist (accuracy, build, a11y, print, brainstorm) | references/verification.md |
| The HTML skeleton to start from | templates/template.html |
templates/template.html is fully self-contained: it embeds the shared core and loads Mermaid +
Prism from a CDN. There is no build step. Write .mermaid blocks and <pre><code class="language-X">,
replace {{LANGUAGE}} in the Prism <script> tag with the language(s) used, and open the file in a
browser — Mermaid renders the diagrams and Prism highlights the code. Nothing to install, no Node.
(The page needs a network connection to reach the CDN; it is not offline-self-contained, by design.)
Do not fork the palette. The template's <style>/<script> are an inline copy of
visual-explainer-core's core.css/core.js. Never hand-edit the theme in one template — change the
canonical core.css/core.js and re-sync (see that skill). Add only software-specific components in
the template's own <style> block.
Ask the user, or default to a sensible spot based on the repo (an existing docs/, notes/, or
wiki/; create docs/explainers/ if nothing fits). Write the full HTML inline with the Write tool;
keep the topic name kebab-case. Don't split a single explainer into multiple files.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Applies a firm's KYC/AML rules grid to parsed onboarding records: assigns risk rating, checks required documents, outputs rule outcomes with citations, and routes for escalation.
Generates daily or weekly digests of activity from connected sources (chat, email, docs, tasks, CRM), highlighting action items, decisions, mentions, and project updates.
npx claudepluginhub jtotty/folio --plugin folio