Visual Explainer
Make explanations easier to understand with one consistent HTML design system.
This is a daily-use presentation skill, not a replacement for domain expertise.
Standing preferences
- Prefer HTML whenever a diagram, spatial layout, comparison, or small interaction
makes the answer clearer. A short explanation can merit a small HTML document.
- Use a restrained dark interface with one cyan accent. Keep the same palette,
type scale, spacing, and diagram treatment across documents and agents.
- Use this order: Visual overview -> Details -> Next steps. A short document
can have one diagram, a paragraph of detail, and one next step. Do not pad it.
- Use visuals to explain relationships, behavior, decisions, and changes. A page
of styled prose and tables alone is insufficient when a diagram would help.
- Respect a user's explicit requested format, project brand, or theme. Skip HTML
for a single fact, a simple command, casual chat, or a task needing no visual.
- These preferences persist; do not ask the user to choose a new theme each time.
Load the shared assets
Resolve this SKILL.md's containing directory, following its symlink if needed.
All assets below are relative to that directory and work in installed copies too.
- Read design-system.md.
- Copy explainer.html to the output path first.
It is the document, not an example to imitate: replace only its subject
matter, diagrams, links, and next steps; retain its stylesheet, design
tokens, accessibility, and three section anchors in order. Do not write the
HTML from scratch and do not rewrite the stylesheet — a page that drifts
from the template drifts from every other page.
- Read diagrams.md when a diagram is useful. Use
mermaid-config.json for Mermaid rendering.
The assets here own the style. Do not invent a new palette or ask theme-factory
to pick one for each document. Change the shared assets when the user changes
their standing preference; do not patch only a generated report.
Choose the explanation before choosing the layout
Ground all claims in the user's context, actual files, or cited sources. Name
unknowns explicitly; do not invent components, metrics, transitions, or APIs to
make a diagram look complete. Separate observed and proposed behavior.
| What the reader needs to understand |
Useful visual |
| Steps, branching, or a user's journey |
Flowchart or user-flow diagram; include failure/retry paths when relevant |
| Who talks to whom, and in what order |
UML-style sequence diagram, including waits and error responses |
| System scope and external dependencies |
C4 context view: people, system boundary, external systems, labeled relationships |
| Applications and data stores inside a system |
C4 container view; label technologies and responsibilities |
| Components within one application |
C4 component view; do not mix abstraction levels |
| Types, ownership, or inheritance |
UML class diagram; ER diagram for tables and cardinality |
| Lifecycle or allowed transitions |
State diagram |
| Old versus proposed behavior |
Paired diagrams or a labeled before/after comparison |
| Options and tradeoffs |
Comparison matrix plus a visual showing the decision or consequences |
| Time or dependencies |
Timeline, dependency graph, or Gantt when dates are supported |
| Numeric evidence |
An appropriately scaled chart with units, sources, and uncertainty |
Use the smallest number of visuals that answers the question. Prefer one
readable overview over a huge graph. Split dense diagrams into a context view
and focused detail views. Label edges with verbs; color alone never conveys meaning.
Build the document
- Lead with a concrete title and one sentence answering the user's question.
- Visual overview: put the main diagram or explanatory visual near the top,
with a plain-language caption. Keep the overview readable without interaction.
- Details: explain the diagram, evidence, tradeoffs, and exceptions. Use
native details/summary for optional depth. Tables are for genuine comparisons.
- Next steps: list a small number of specific actions, owners or prerequisites
when known. For a pure explanation, offer one useful check or experiment.
- Add source links next to claims and a date when the subject changes over time.
Label assumptions and proposals visibly. Never fabricate citations.
- Save to a task-appropriate output directory, normally
artifacts/<slug>.html
inside an authorized project. Without a project, use a local output directory
under the current user's home. Do not put task reports or private content in
the skill library. Preserve existing outputs by choosing a new filename.
Useful interaction includes expandable detail, diagram zoom, meaningful filters,
or a before/after toggle. Every control must work and remain keyboard accessible.
Keep navigation and essential content usable if scripting is disabled or stripped
by a host. Do not add dashboard controls or decorative animations without a purpose.
Diagrams must arrive rendered
Mermaid source is an authoring format, not the final visual. Render it to SVG
locally and inline the SVG, or write a small accessible inline SVG directly.
Retain the editable Mermaid source beside the HTML or escaped inside a details
element. Never deliver a blank Mermaid container or source text as the only diagram.
Use the pinned CLI recipe and sample sources in diagrams.md.
If the renderer is unavailable, draw the needed SVG directly and keep any Mermaid
source for future editing. Do not block a simple explanation on installing a stack.
Do not use CDN scripts, remote fonts, runtime fetches, iframes, or external CSS.
Verify and deliver
- Run
python scripts/check_html.py <output.html> from this skill's directory
(Windows: py -3; macOS/Linux: python3). It must pass before delivery: it
checks structure, the design tokens, and the section order — not a visual
review or a full security audit. A token failure means the stylesheet was
rewritten instead of reused; restore the template's stylesheet rather than
patching the check.
- Glance test: read only the finished page — no chat, no source documents —
and state the answer in one sentence. If the page needs the chat to be
understood, redraw the overview before delivering. For a substantial plan or
report, have a fresh agent with no context on the work read only the page
and answer as a stranger: what is being decided, and could they act on it?
Rework anything it cannot explain; at most three rounds.
- If the user explicitly requested different project branding, the token check
is expected to fail — note the override in your reply instead of forcing the
shared tokens back.
- Inspect a screenshot or browser view when making a new layout or diagram.
Check wide and narrow screens, readable labels, no clipped content, and controls.
Prefer a local headless browser; if unavailable, disclose that visual inspection
was not performed. Reusing the unchanged template does not require a new theme review.
- Ensure no sample-specific content remains, source claims are supported, and
all diagrams show real or clearly labeled proposed relationships.
- Return the local clickable HTML path with the answer. When a hosted link is
requested or authorized by the user's established workflow, use
postplan-upload
with this finished HTML. That upload produces a public URL; local HTML generation
alone does not authorize publishing private project material.
- If hosting fails, preserve and link the local HTML. Never claim an upload or
rendering succeeded without checking its result.
Integration and maintenance
postplan-upload owns the hosting command and delivery result. This skill owns
the visual design and diagram choices. Planning/review/domain skills own their
subject matter and can use this presentation without repeating the style rules.
Keep this skill in default-profile.toml alongside postplan-upload. Both the
OneDrive library and standalone Git installations carry its complete asset tree.
After changing it, update the repository and propagate installed copies using
the repository's documented sync procedure; do not copy a machine's credentials.
1---2name: visual-explainer3description: >-4 Explain ideas, plans, architecture, code changes, comparisons, audits, and5 workflows with consistent standalone HTML and useful diagrams. Use proactively6 for most answers where a visual improves understanding, even short answers;7 trigger for explain how it works, show the flow, compare options, diagram,8 UML, Mermaid, C4, HTML report, visual explanation, or a clickable plan.9 Uses a restrained dark theme, one cyan accent, and visual overview, details,10 next steps. Works with postplan-upload for hosted delivery.11license: MIT12metadata:13 source: https://skillmd.com/skills/hongyime/visual-explainer14 version: "1.0.0"15 platform: "Codex, Antigravity (agy), OpenCode, Muse on Windows, macOS, Linux (Debian)"16---1718# Visual Explainer1920Make explanations easier to understand with one consistent HTML design system.21This is a daily-use presentation skill, not a replacement for domain expertise.2223## Standing preferences2425- Prefer HTML whenever a diagram, spatial layout, comparison, or small interaction26 makes the answer clearer. A short explanation can merit a small HTML document.27- Use a restrained dark interface with one cyan accent. Keep the same palette,28 type scale, spacing, and diagram treatment across documents and agents.29- Use this order: **Visual overview -> Details -> Next steps**. A short document30 can have one diagram, a paragraph of detail, and one next step. Do not pad it.31- Use visuals to explain relationships, behavior, decisions, and changes. A page32 of styled prose and tables alone is insufficient when a diagram would help.33- Respect a user's explicit requested format, project brand, or theme. Skip HTML34 for a single fact, a simple command, casual chat, or a task needing no visual.35- These preferences persist; do not ask the user to choose a new theme each time.3637## Load the shared assets3839Resolve this SKILL.md's containing directory, following its symlink if needed.40All assets below are relative to that directory and work in installed copies too.41421. Read [design-system.md](references/design-system.md).432. Copy [explainer.html](templates/explainer.html) to the output path first.44 It is the document, not an example to imitate: replace only its subject45 matter, diagrams, links, and next steps; retain its stylesheet, design46 tokens, accessibility, and three section anchors in order. Do not write the47 HTML from scratch and do not rewrite the stylesheet — a page that drifts48 from the template drifts from every other page.493. Read [diagrams.md](references/diagrams.md) when a diagram is useful. Use50 [mermaid-config.json](assets/mermaid-config.json) for Mermaid rendering.5152The assets here own the style. Do not invent a new palette or ask theme-factory53to pick one for each document. Change the shared assets when the user changes54their standing preference; do not patch only a generated report.5556## Choose the explanation before choosing the layout5758Ground all claims in the user's context, actual files, or cited sources. Name59unknowns explicitly; do not invent components, metrics, transitions, or APIs to60make a diagram look complete. Separate observed and proposed behavior.6162| What the reader needs to understand | Useful visual |63|---|---|64| Steps, branching, or a user's journey | Flowchart or user-flow diagram; include failure/retry paths when relevant |65| Who talks to whom, and in what order | UML-style sequence diagram, including waits and error responses |66| System scope and external dependencies | C4 context view: people, system boundary, external systems, labeled relationships |67| Applications and data stores inside a system | C4 container view; label technologies and responsibilities |68| Components within one application | C4 component view; do not mix abstraction levels |69| Types, ownership, or inheritance | UML class diagram; ER diagram for tables and cardinality |70| Lifecycle or allowed transitions | State diagram |71| Old versus proposed behavior | Paired diagrams or a labeled before/after comparison |72| Options and tradeoffs | Comparison matrix plus a visual showing the decision or consequences |73| Time or dependencies | Timeline, dependency graph, or Gantt when dates are supported |74| Numeric evidence | An appropriately scaled chart with units, sources, and uncertainty |7576Use the smallest number of visuals that answers the question. Prefer one77readable overview over a huge graph. Split dense diagrams into a context view78and focused detail views. Label edges with verbs; color alone never conveys meaning.7980## Build the document81821. Lead with a concrete title and one sentence answering the user's question.832. **Visual overview:** put the main diagram or explanatory visual near the top,84 with a plain-language caption. Keep the overview readable without interaction.853. **Details:** explain the diagram, evidence, tradeoffs, and exceptions. Use86 native details/summary for optional depth. Tables are for genuine comparisons.874. **Next steps:** list a small number of specific actions, owners or prerequisites88 when known. For a pure explanation, offer one useful check or experiment.895. Add source links next to claims and a date when the subject changes over time.90 Label assumptions and proposals visibly. Never fabricate citations.916. Save to a task-appropriate output directory, normally `artifacts/<slug>.html`92 inside an authorized project. Without a project, use a local output directory93 under the current user's home. Do not put task reports or private content in94 the skill library. Preserve existing outputs by choosing a new filename.9596Useful interaction includes expandable detail, diagram zoom, meaningful filters,97or a before/after toggle. Every control must work and remain keyboard accessible.98Keep navigation and essential content usable if scripting is disabled or stripped99by a host. Do not add dashboard controls or decorative animations without a purpose.100101## Diagrams must arrive rendered102103Mermaid source is an authoring format, not the final visual. Render it to SVG104locally and inline the SVG, or write a small accessible inline SVG directly.105Retain the editable Mermaid source beside the HTML or escaped inside a details106element. Never deliver a blank Mermaid container or source text as the only diagram.107108Use the pinned CLI recipe and sample sources in [diagrams.md](references/diagrams.md).109If the renderer is unavailable, draw the needed SVG directly and keep any Mermaid110source for future editing. Do not block a simple explanation on installing a stack.111Do not use CDN scripts, remote fonts, runtime fetches, iframes, or external CSS.112113## Verify and deliver114115- Run `python scripts/check_html.py <output.html>` from this skill's directory116 (Windows: `py -3`; macOS/Linux: `python3`). It must pass before delivery: it117 checks structure, the design tokens, and the section order — not a visual118 review or a full security audit. A token failure means the stylesheet was119 rewritten instead of reused; restore the template's stylesheet rather than120 patching the check.121- Glance test: read only the finished page — no chat, no source documents —122 and state the answer in one sentence. If the page needs the chat to be123 understood, redraw the overview before delivering. For a substantial plan or124 report, have a fresh agent with no context on the work read only the page125 and answer as a stranger: what is being decided, and could they act on it?126 Rework anything it cannot explain; at most three rounds.127- If the user explicitly requested different project branding, the token check128 is expected to fail — note the override in your reply instead of forcing the129 shared tokens back.130- Inspect a screenshot or browser view when making a new layout or diagram.131 Check wide and narrow screens, readable labels, no clipped content, and controls.132 Prefer a local headless browser; if unavailable, disclose that visual inspection133 was not performed. Reusing the unchanged template does not require a new theme review.134- Ensure no sample-specific content remains, source claims are supported, and135 all diagrams show real or clearly labeled proposed relationships.136- Return the local clickable HTML path with the answer. When a hosted link is137 requested or authorized by the user's established workflow, use `postplan-upload`138 with this finished HTML. That upload produces a public URL; local HTML generation139 alone does not authorize publishing private project material.140- If hosting fails, preserve and link the local HTML. Never claim an upload or141 rendering succeeded without checking its result.142143## Integration and maintenance144145`postplan-upload` owns the hosting command and delivery result. This skill owns146the visual design and diagram choices. Planning/review/domain skills own their147subject matter and can use this presentation without repeating the style rules.148149Keep this skill in `default-profile.toml` alongside `postplan-upload`. Both the150OneDrive library and standalone Git installations carry its complete asset tree.151After changing it, update the repository and propagate installed copies using152the repository's documented sync procedure; do not copy a machine's credentials.