К основному содержанию
скилл CX Codex

visual-explainer · vercel-labs — скилл для Claude Code: визуальные объяснения

Скилл visual-explainer превращает баги, PR и фичи в пошаговые инфографики с диаграммами, подсвеченным кодом и чётким разделением на «было» и «стало».

MIT 235 установок ★ 2 687 обновлён 2026-10-16

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add vercel-labs/vgpu --skill visual-explainer -a claude-code
Открыть на GitHub

Что делает visual-explainer

Скилл собирает объяснение от пользовательского кода до итога: читает исходники, issue или diff PR, строит последовательность шагов и показывает, где именно сломалось и как это исправили. Для личного разбора выдаёт PDF с векторными диаграммами и текстовым кодом. Для описания PR встраивает объяснение в Markdown: нативные fence-блоки, таблицы до/после, Mermaid-диаграммы или небольшие SVG.

Диаграмма появляется только там, где нужна связь — ownership, зависимости, порядок или сравнение результатов. Код остаётся текстом с подсветкой синтаксиса, скриншоты запрещены. Скилл проверяет, что объяснение читается и без картинок: метки дублируют цвет, проза содержит суть.

Структура фиксирована: сначала проблема с заголовком вроде «До этого PR», пример кода, трассировка до точки отказа; затем решение под отдельным заголовком, те же шаги через изменённый путь и подтверждённый результат с единицами измерения. Для фичи вместо бага пишется «Было ограничение — стало возможно».

Какие задачи решает

  • объяснить баг или фичу от кода пользователя до результата
  • собрать пошаговую инфографику для PR с диаграммами и подсветкой
  • показать, где именно сломалось и как fix это чинит
  • сделать образовательный PDF с векторными схемами и копируемым кодом

Примеры запросов агенту

  • Объясни этот PR как инфографику: что было сломано, где fix срабатывает и что изменилось для пользователя
  • Сделай визуальное объяснение бага в gpu-buffer.ts — от вызова API до точки отказа
  • Собери PDF, который покажет, как работает новая фича parallel-compute пошагово

Как установить visual-explainer

1Через Skills CLI (Vercel)

npx skills add vercel-labs/vgpu --skill visual-explainer -a claude-code

2Вручную: положить файлы

~/.claude/skills/visual-explainer/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/visual-explainer/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о visual-explainer

Как установить visual-explainer в Claude Code?

Выполни npx skills add vercel-labs/vgpu --skill visual-explainer -a claude-code, скилл появится в ~/.claude/skills/visual-explainer/SKILL.md.

Что делает visual-explainer?

Строит визуальное объяснение бага, PR или фичи: от пользовательского кода до итога, с диаграммами, подсвеченным кодом и чётким разделением на проблему и решение. Выдаёт PDF для личного разбора или Markdown для описания PR.

Когда visual-explainer добавляет диаграммы в PR?

Только если нужно показать связь, которую текст не передаёт — ownership, зависимости, порядок выполнения или сравнение результатов. Сначала пробует Mermaid, кастомные SVG добавляет по правилам eligibility из README.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →

Сначала — visual-explainer от других авторов.

visual-explainer nicobailon Скилл visual-explainer для Claude Code и Codex строит наглядные автономные HTML-страницы вместо длинных текстовых ответов. Превращает архитектуру, дифы кода и планы миграций в интерактивные схемы. CX Codex +1 885установок plannotator-visual-explainer backnotprop Скилл plannotator-visual-explainer для Claude Code создаёт HTML-визуализации планов, PR-разборов, архитектурных диаграмм и слайдов в тёмной теме Plannotator. CX Codex +1 15 100установок visual-testing-advanced proffesor-for-testing Скилл visual-testing-advanced настраивает продвинутое визуальное регрессионное тестирование интерфейса, сравнение скриншотов по пикселям и адаптивную проверку верстки. CX Codex +1 163установок visual-storyteller Michael Galpert Субагент visual-storyteller собирает визуальные истории из данных: инфографику, слайды презентаций и иллюстрации для онбординга. CX Codex ★ 1 013звёзд репо image-gen krishagel Скилл image-gen для Claude Code создаёт изображения, инфографику и диаграммы через Nano Banana 2. Генерирует визуал по текстовому описанию и редактирует готовые картинки. CX Codex +1 4установок markdown-viewer-skills podo Скилл markdown-viewer-skills для Claude Code и Codex выбирает движок для UML, сетевых схем, графиков и инфографики в Markdown. Создаёт схемы для документации. CX Codex +1 202установок canvas-design Composio Плагин canvas-design помогает создавать визуальные работы в PNG и PDF. Он пригодится для постеров, арт-объектов и других статичных дизайнов. ★ 2 003звёзд репо

Из того же набора3

Спонсоры проекта

Компании, которые помогают держать аналитику открытой