visual-explainer · vercel-labs — Claude Code skill: visual PR and bug walkthroughs
visual-explainer turns bugs, PRs and features into step-by-step infographics with diagrams, syntax-highlighted code and a clear before/after boundary.
MIT 235 installs ★ 2,687 updated 2026-10-16
npx skills add vercel-labs/vgpu --skill visual-explainer -a claude-codeWhat visual-explainer does
The skill builds an explanation from user code to outcome: reads sources, issues or PR diffs, constructs the step sequence and shows exactly where it broke and how the fix corrects it. For personal study it produces a PDF with vector diagrams and selectable code. For PR descriptions it embeds the walkthrough in Markdown: native fenced blocks, before/after tables, Mermaid diagrams or compact SVGs.
A diagram appears only where a relationship is needed — ownership, dependencies, execution order or measured comparison. Code stays text with syntax highlighting; screenshots are forbidden. The skill verifies that the explanation works without images: labels duplicate color, prose contains the substance.
Structure is fixed: problem first with a heading like "Before this PR", a code example, trace to the failure point; then solution under a separate heading, same steps through the changed path and confirmed result with units. For a feature, instead of a bug write "Previous limitation — new behavior".
What it helps with
- explain a bug or feature from user code to outcome
- build a step-by-step PR infographic with diagrams and highlighting
- show where exactly it broke and how the fix corrects it
- produce an educational PDF with vector diagrams and copyable code
Example prompts for the agent
- Explain this PR as an infographic: what broke, where the fix kicks in and what changed for the user
- Make a visual walkthrough of the bug in
gpu-buffer.ts— from the API call to the failure point - Build a PDF that shows how the new
parallel-computefeature works step by step
How to install visual-explainer
1Skills CLI (Vercel)
npx skills add vercel-labs/vgpu --skill visual-explainer -a claude-code2Manually: put the files in place
~/.claude/skills/visual-explainer/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/visual-explainer/
1Skills CLI (Vercel)
npx skills add vercel-labs/vgpu --skill visual-explainer -a codex2Manually: put the files in place
.agents/skills/visual-explainer/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add vercel-labs/vgpu --skill visual-explainer -a cursor2Manually: put the files in place
.cursor/skills/visual-explainer/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install vercel-labs/vgpu .claude/skills/visual-explainer2Manually: put the files in place
.github/skills/visual-explainer/SKILL.md1Skills CLI (Vercel)
npx skills add vercel-labs/vgpu --skill visual-explainer -a gemini-cli2Platform CLI
gemini skills install https://github.com/vercel-labs/vgpu --path .claude/skills/visual-explainerManually: put the files in place
.devin/skills/visual-explainer/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add vercel-labs/vgpu --skill visual-explainer -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about visual-explainer
How to install visual-explainer in Claude Code?
Run npx skills add vercel-labs/vgpu --skill visual-explainer -a claude-code, the skill will appear in ~/.claude/skills/visual-explainer/SKILL.md.
What does visual-explainer do?
Builds a visual explanation of a bug, PR or feature: from user code to outcome, with diagrams, highlighted code and a clear problem/solution boundary. Produces a PDF for personal study or Markdown for a PR description.
When does visual-explainer add diagrams to a PR?
Only when a relationship that prose cannot convey is needed — ownership, dependencies, execution order or measured comparison. It tries Mermaid first, custom SVGs are added per eligibility rules from the README.
Source text
SKILL.md · MIT
--- name: visual-explainer description: >- Use when the user asks to explain a problem, issue, PR, or feature as an infographic. Create a step-by-step visual explanation starting from user code or actions, with a clear problem/solution boundary, syntax-highlighted snippets, and focused diagrams. Support standalone educational PDFs and Markdown-first PR explanations, with optional images only for complex diagrams. Also apply when explicitly invoked by the repository PR writer. --- # Visual explainer Explain the mechanism so a reader unfamiliar with the implementation can follow it from their own code to the outcome. This is the shared visual and narrative style for the repository; it does not grant permission to implement a fix or publish a PR. Follow the active workflow in AGENTS.md. Write in the user's language for personal explanations and the repository's language for PR descriptions unless directed otherwise. ## Establish what is being explained Read the issue or request, relevant source/API docs, and available reproduction or validation evidence. For a PR, identify its base and head and inspect both versions where behavior changed. Distinguish the reported symptom, confirmed cause, proposed solution and implemented result. If the fix is only proposed, label it as proposed throughout; do not present predictions as results. Use one representative example throughout the explanation. Name omitted setup and define terms when the reader first needs them. Do not infer an API from a diagram or an old draft. ## Narrative: problem first, then solution 1. **Make the problem explicit before the first snippet.** Name who encounters it, the trigger, expected behavior and actual outcome. Use a heading such as "The problem — before this PR" and state that the following steps trace the old behavior. For an unfixed issue, say "The current problem". "Summary" or "User code" alone does not establish what is being shown. 2. **Start at user code or an action.** Show a small, representative snippet with syntax highlighting. Explain whether it is valid code exposing a library problem, incorrect usage, or a workaround. If the code is valid, do not imply the user needs to repair it. 3. **Follow the system step by step.** Connect the user call to the necessary internal work, the failure point and its observable consequence. Use short sections, one causal step each. Separate correct mechanisms required for safety or semantics from the actual defect. 4. **Mark the transition to the solution.** Use a separate heading such as "The solution — after this PR" or "Proposed solution". Trace the same example through the changed steps, explain why they fix the problem, and state whether user code changes. For a feature, use "Previous limitation" and "New behavior" instead of inventing a bug. For a refactor, state that observable behavior is unchanged. 5. **Show the result and limits.** Give supported before/after evidence with units, workload, environment and conditions such as warmup. Separate allocations, CPU time and GPU throughput; mock and native results; measured outcomes and expectations. Keep unmet targets and material limitations visible in the human explanation, not only in a technical appendix. Scale the number of steps to the mechanism. A simple change may need only a short before/after. See [the example and counterexamples](references/walkthrough.md) for the intended transitions. ## Visual style - Use a calm technical layout: clear hierarchy, generous spacing, dark ink on a light neutral background, and restrained accents. Blue can identify resources, teal the reused/corrected path, and red the defect. Always use labels as well as color to distinguish states. - Each diagram explains one relationship: ownership, ranges, identity, order, dependencies or a measured comparison. Put it beside the paragraph that explains it. Keep prose outside the graphic; labels should be brief. Arrows must describe an actual flow, dependency or transition. - When an image is warranted (for PRs, apply the eligibility rules below first), prefer small, self-contained SVGs made from shapes, paths and text. Include viewBox, explicit dimensions, title/description, and alt text when embedded. Use an explicit background and sufficient contrast. Avoid scripts, foreignObject, external fonts/resources and raster embeds. - For a PR, target compact or vertical diagrams around 320–480 viewBox units wide with labels around 18–22 units. Inspect them at a narrow ~320px content width and a desktop width. Split wide diagrams rather than assuming vector zoom makes them readable on a phone. - Code stays text, with syntax highlighting. In Markdown, use native language fences; in a PDF, render selectable monospaced text with token colors. Do not use screenshots of code. Mark partial/historical/pseudocode examples in adjacent prose; verify real API snippets against the version they demonstrate. State omitted setup rather than making a partial example look executable by itself. - Keep essential meaning in prose, too: the explanation must work for readers and agents that cannot see the diagrams. For PRs, prefer native Mermaid when a necessary diagram can be expressed clearly that way; custom images must meet the eligibility rules below. ## Choose the output mode Honor the requested format. If the user asks for an infographic for their own understanding and does not name a format, default to an educational PDF. A request to explain a PR is not itself permission to edit that PR; distinguish a personal explanation from a requested PR description. ### Personal explanation: PDF Compose a standalone document with the narrative, highlighted code and diagrams integrated into readable sections. Choose page size and pagination for the content; do not shrink everything onto one poster. Preserve text as text and diagrams as vectors where the tooling permits. Use available PDF guidance/tools (for example ReportLab, Pygments and a PDF renderer), without requiring a machine-specific skill path. Inspect every rendered page for clipping, overlap, tiny labels, broken arrows and code wrapping. Check text extraction as well as the images. Save scratch sources and page previews under `.context/work/<topic>/visual-explainer/`; place the final PDF in the user-requested location or `output/pdf/`. Neither scratch nor personal PDFs are committed by default. Deliver a link to the PDF and any useful preview, with a brief statement of what it explains. An educational PDF stays personal: do not attach it to a PR or turn its pages into images in the PR body. ### PR description: Markdown first, optional complex diagrams Default to native Markdown: paragraphs, headings, numbered steps, bullets, tables and copyable code fences. A before/after comparison belongs in a table or short sections; a linear sequence belongs in a numbered list. Measurements, checklists, key comparisons and snippets stay text. Do not render any of these as PNG/SVG cards, screenshots or text boxes joined by decorative arrows. Color, rounded boxes and a before/after layout do not make a complex diagram. Add an image only when drawing communicates a complex relationship that Markdown cannot explain as clearly: for example, a branching dependency graph with shared ownership, overlapping buffer ranges and lifetimes, or a spatial mapping. Complexity must come from the mechanism, not the number of words. Use native Mermaid if it can express the necessary diagram clearly; otherwise a focused SVG may be appropriate. For each proposed image, explain what relationship needs drawing and why prose, a list, a table or Mermaid would be insufficient. If there is no concrete answer, use Markdown. There is no image quota; a PR with no images is the normal, complete outcome. Apply this rule when reusing existing attachments, too. Replace text-only figures with Markdown instead of preserving them because they are already uploaded. Do not embed a full infographic as a PNG or SVG. These restrictions concern PR descriptions; personal PDFs remain visual documents. After the human walkthrough, the PR writer adds the repository's technical record, validation and required declarations. Its publication and output contract is in [the PR-writing guide](../../../.subharness/tools/pr-writing.ts). Keep new assets in the assigned scratch directory, with meaningful alt text and a list of files needing upload. Reuse verified existing attachment URLs for unchanged figures. The lead uploads new figures as GitHub attachments within the user's authorization; do not commit PR-only images or invent URLs. Published descriptions must have accessible asset URLs, never local paths. ## Verify before delivery - Read the opening through the first snippet: can a newcomer identify the problem and whether the example shows the old/current behavior, a workaround or the solution? - Scan only the headings: is the before/after transition clear? Do not place a new behavior under a heading claiming nothing changes. - Compare each step, diagram and snippet with the evidence. Mark uncertainty; never invent measurements or silently substitute a proposed mechanism for implemented behavior. - For a PR, check every proposed image against the eligibility rule before rendering. If a list, table or prose preserves its meaning just as clearly, replace the image with Markdown. Check that the asset list contains only figures still used; an empty list is valid. - Render and visually inspect any PDF or justified image at its intended reading sizes. XML parsing alone is not visual verification. Report any rendering/inspection limitation rather than claiming it passed. Save rendered previews as scratch evidence, not as replacement PR attachments. - Return the artifact paths, the relevant source revisions and any limitations. Do not rerun expensive product suites merely to illustrate existing evidence.
© vercel-labs · MIT · vercel-labs/vgpu
Similar skills
All skills for Agent setup: memory, context, orchestration →visual-explainer by other authors comes first.