Agent skill
Visual explanation
Your agent picks the view by the shape of the answer, draws it from the real code, and puts each picture beside the sentence it supports.
Install the global Vite+ CLI before running this command. Without it, replace vp dlx with pnpm dlx.
Pick visual-explanation from the list.
How a Comark document becomes HTML
Parsing and rendering are two separate calls, and the plugins do their work in the first. That's why a block's problems are known before any HTML exists.
A plugin can join at three points: its Markdown rules while the text becomes tokens, markdownItPost on the tokens, and post on the tree. The last arrow is the renderer, which only maps each node to a component.
In code, the diagram is three lines:
# How a Comark document becomes HTML
Parsing and rendering are two separate calls, and the plugins do their work in the first. That's why a block's problems are known before any HTML exists.
```mermaid
flowchart LR
md[Markdown] --> tokens[Tokens]
tokens --> tree[Node tree]
tree --> doc[Nodes and issues]
doc --> html[HTML]
```
A plugin can join at three points: its Markdown rules while the text becomes tokens, `markdownItPost` on the tokens, and `post` on the tree. The last arrow is the renderer, which only maps each node to a component.
In code, the diagram is three lines:
```ts
const document = await parseMarkdown(source, { plugins }); // <1>
if (document.meta.issues.length) refuse(document.meta.issues); // <2>
const html = await renderHtmlFromDocument(document, { components }); // <3>
```
1. Every plugin runs here, in the order of `plugins`.
2. Each issue is one sentence naming the block and the fix, so a host can refuse a document before it renders.
3. Components only draw: `screenshot` maps to the figure's HTML, and nothing is parsed again.What it does
Section titled "What it does"The skill answers one question about how something works with the smallest view that shows it:
- a sequence diagram for the order of events
- a call tree for who calls whom
- a file tree for where code lives
- a marked screenshot for something on screen
Every label comes from the real source, so you can check the picture instead of trusting it.
When to use it
Section titled "When to use it"Ask "Show me how a document becomes HTML" or "Explain how the cache invalidates, with a diagram." Your agent loads the skill when you ask to see how a system, a flow, or a change works. To be sure, say "Use the visual-explanation skill."
Choose by what you want:
- To see how something works: this skill.
- To apply an idea afterwards and check that you can: Teach lesson.
- To see what a change did to a screen: Before/after evidence.
It's working if
Section titled "It's working if"- The title is the question, or its answer.
- The page reads top to bottom in under a minute, and a sentence beside each view says what to look at.
- Every function, file, and state in the view exists in the code.
- A diagram has about eight nodes or fewer, and its labels read at the page's width.
- A second view appears only to answer the question the first one raises.
The skill draws on the show-me skill by Dex Horthy at Humanlayer.