visual-recap
Turn a PR, branch, commit, or git diff into an interactive visual recap with diagrams, file maps, API/schema summaries, annotated diffs, and focused review notes.
Install / Use
npx skills add BuilderIO/skills --skill visual-recapInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Our assessment of visual-recap
visual-recap scores 89/100 on our quality scale, 1541st of 4,698 Development & Engineering skills we index (top 33%).
Its SKILL.md is 33 KB long, well organised into 19 sections and no code examples: a thorough specification that gives an agent plenty to work with.
With 4,394 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so visual-recap is actively maintained.
- Our last check on 2026-10-31 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-09-29. Automated pattern scan on 2026-09-29. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
visual-recap compared with similar skills
All 4 of these similar skills score higher than visual-recap; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| visual-recap (this skill)by BuilderIO | 89 | 4.4k | 54d ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
Frequently asked questions
- How do I install visual-recap?
- Run
npx skills add BuilderIO/skills --skill visual-recap. The install tabs above show the steps for each supported agent. - Which AI agents does visual-recap work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is visual-recap safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is visual-recap still maintained?
- The repository was last updated about 2 months ago, so visual-recap is actively maintained.
Skill content
View source on GitHubname: visual-recap description: >- Turn a PR, branch, commit, or git diff into an interactive visual recap with diagrams, file maps, API/schema summaries, annotated diffs, and focused review notes. metadata: visibility: exported
Visual Recap
/visual-recap creates a visual plan built from a diff, not toward one. It
is the reverse of forward planning: instead of describing the change you are
about to make, you describe the change that was just made, at a higher altitude
than line-by-line review. The same plan data model serves both directions —
schema, API, file, and architecture changes become the same data-model,
api-endpoint, file-tree, and diagram blocks a forward plan would use, only
now they summarize work that exists. A reviewer scans the shape of the change
before spending attention on the literal lines.
Publish As An Agent-Native Plan — Never Inline
The deliverable is ALWAYS a published Agent-Native Plan, created with
create-visual-recap on the Plan MCP connector — NEVER inline chat content (not
Markdown prose, an ASCII sketch, a table, a fenced "wireframe", or a "here's the
recap" summary). A recap's entire value is the hosted, interactive, annotatable
plan; an inline summary is not a degraded recap, it is the thing a recap
replaces. If the plan (or legacy agent-native-plans) tools are not visible,
discover them through the host's tool_search first; if they are still missing,
STOP and give the user the client-specific reconnect step rather than improvising
an inline recap. Before publishing, or whenever a connector or auth error
appears, READ references/connection.md in this skill directory — it is the
single source of truth for the never-inline rule, connector discovery, and the
per-client reconnect steps. Local-files privacy mode (below) is the one
exception.
Local-Files Privacy Mode — read references/local-files.md
When the user wants no hosted Plan database writes — no DB writes, no Plan MCP
publish, fully local/offline/private recaps, or AGENT_NATIVE_PLANS_MODE=local-files
— do not call any hosted Plan tool except the schema-only get-plan-blocks
catalog lookup. Read the diff with the local recap collect-diff / scan /
build-prompt --local-files helpers, author a local MDX folder (set
kind: "recap" and localOnly: true), and preview it with plan local check,
plan local serve --kind recap, and plan local verify --kind recap. Before
using local-files mode, READ references/local-files.md in this skill directory
— it is the single source of truth for the full contract.
When To Use
Build a recap when a PR or commit is large, multi-file, or touches schema, API contracts, or architecture, and a reviewer would benefit from seeing the change mapped to structured blocks before reading the raw diff. A GitHub Action can generate one automatically from a PR diff; an agent can generate one on request ("recap this PR", "show me what this branch changed"). Skip it for small, single-file, or obvious diffs — a recap is review overhead, and a tiny change reviews faster as plain diff.
Recap The Whole Work Unit
When /visual-recap is invoked in a chat thread after work has already happened,
the default scope is the whole current work unit/thread, not only the most recent
user message, tool action, or follow-up fix. Gather the thread-owned changes
across the conversation: original implementation work, later bug fixes, UI
follow-ups, tests, changesets, skill/instruction updates, generated plan/source
artifacts, and any local import/linking fixes needed to make the recap open.
Use the current diff plus conversation context to separate thread-owned changes from unrelated dirty work that existed before the thread. Exclude unrelated pre-existing edits. If the scope is genuinely ambiguous and cannot be inferred, state the assumption or ask a concise question before publishing.
When updating an existing recap after feedback, revise the recap so it still covers the whole thread/work unit plus the new correction. Do not replace a broad recap with a narrow recap of only the latest feedback unless the user explicitly asks for that narrower scope.
Keep The Recap Body Lean
Do not add boilerplate intro, disclaimer, provenance, or summary prose blocks to
the generated plan body. In particular, do not create a rich-text block just to
say the recap is an aid, that the reviewer should still review the diff, how many
files changed, or which ref/working tree generated the recap. The plan title,
brief, and file-tree (which carries the per-file change stats) already carry
that context.
Only add prose blocks when they tell the reviewer something specific about the change that the structured blocks do not: the objective, a real compatibility risk, an important decision visible in the diff, or a grounded review note.
Recaps Must Be Substantial
Lean is not the same as thin. A recap is not a single wireframe plus one
sentence — that under-serves the reviewer as much as boilerplate prose over-serves
them. Alongside the visual/structural headline (wireframes, data-model,
api-endpoint, diagram), a substantial recap also carries the implementation
evidence:
- A short surface/state inventory before authoring: list the changed routes, components, popovers/dialogs, role/access states, empty/error states, and shared abstractions visible in the diff. The final recap must either represent each meaningful item with a block or intentionally omit it because it is tiny, redundant, or not user-visible.
- A
file-treeof the changed files with each entry'schangeflag, so the reviewer sees the footprint of the work at a glance. - The split
diffof the KEY changed files, grouped under a## Key changesrich-textheading in a single horizontaltabsblock (the default orientation, one file per tab), with a one-linesummaryand a fewannotationson each — so the reviewer can drop from the high-altitude shape straight into the load-bearing code. Use horizontal file tabs, not a vertical side rail, so the selected file has enough width for the side-by-side diff.
Skip the diff appendix only for a genuinely tiny change that reviews faster as plain diff (see "When To Use"); for any change worth recapping, the file-tree and key-change diffs belong in the plan.
Canonical Shape And Budgets
A strong recap follows one skeleton, top to bottom:
- UI-impact headline — wireframes first, when the diff changed rendered UI.
- Short outcome narrative (
rich-text): what changed and why, 1-3 paragraphs. data-model/api-endpointblocks for schema and contract changes.file-treeof the changed files withchangeflags.## Key changes— one horizontaltabsblock ofdiff/annotated-code.
Budgets that keep the recap reviewable:
- 3-8 key-change tabs. Fewer than 3 on a large change under-serves the reviewer; more than 8 stops being a summary.
- Keep each diff/annotated-code excerpt focused — prefer under ~150 lines per tab; summarize or link the rest of a long file instead of dumping it.
- Title at most ~70 characters; brief 1-3 sentences.
These budgets are also the cost ceiling: do not exceed them in the name of thoroughness, and do not re-read the full diff after the initial sequential pass — work from the notes taken during that pass.
GOOD. A 25-file auth change: Before/After wireframes of the login surface,
a two-paragraph narrative, a diff-aware data-model of the sessions table, an
api-endpoint for the new refresh route, a file-tree with change flags, and
## Key changes with five focused tabs, each with a one-line summary and a
few annotations on the load-bearing hunks.
BAD. One giant unsegmented diff dump with no summaries or annotations; or a sparse three-block recap of a 40-file change (one wireframe, one sentence, one file list) that forces the reviewer back into the raw diff anyway.
UI Impact Needs Wireframes
When the diff changes rendered UI, layout, density, visual state, interaction affordances, navigation, controls, menus, dialogs, or design tokens, the recap MUST include one or more wireframes. Prose and file diffs are not a substitute for showing what changed visually.
Before choosing wireframes, make a UI coverage pass from the diff:
- Identify the entry surface where the change appears, such as a page header, list row, toolbar, route shell, or menu trigger.
- Identify the interaction surface that opens or changes, such as a popover, dialog, tab, sheet, dropdown, inline editor, or toast.
- Identify the resulting destination or persistent state, such as a public page, read-only view, empty state, error state, loading state, permission-denied state, or saved/shared state.
- Identify access or role variants when permissions change. Owner/admin/editor versus viewer/non-manager differences are visual behavior and need a compact matrix, paired wireframes, or clearly labeled state sequence.
For UI-heavy PRs, a single before/after of the entry surface is not enough. Show the changed entry point, the main changed interaction surface, and the resulting/destination state. Add more states when the diff adds tabs, role-based controls, public/private visibility, invite/manage flows, destructive controls, or empty/error branches.
Choose the smallest visual surface that makes the review clear:
- Use a
Before/Afterwireframe pair when the reviewer benefits from direct comparison, such as a removed or added control, a changed state, layout density, ordering, navigation, or a visible component replacement.references/wireframe.mdowns how to lay that pair out (columns vs. vertical stack by geometry). - Use an after-only wireframe when the change is purely additive or the "before" state would only show absence without adding review value.
- Use more than two wireframes when the UI change is flow-dependent, responsive, or stateful; show the meaningful states in order instead of forcing a single before/after pair.
- For tiny surfaces like menus, popovers, dialogs, toasts, or panels, use the
matching
surface(popover,panel, etc.) and show the focused sub-surface. Do not redraw a full page unless placement in the page is itself part of the change.
Ground each wireframe in the changed UI behavior, component names, file paths, and diff-visible labels/states. If exact pixels are inferred rather than captured, say so in the wireframe caption or a concise annotation. For local/manual recaps, import or update the plan source that holds the wireframes so the rendered recap opens with the UI visual available.
Wireframe Quality — read references/wireframe.md
UI recap/plan wireframes must meet a strict quality bar — full-width chrome,
pinned bottom bars, real product content, before/after comparability, the right
surface preset, --wf-* tokens instead of hex, and no <html>/<style>/font
tags. Before authoring ANY wireframe / <Screen> / WireframeBlock, READ
references/wireframe.md in this skill directory — it is the single source of
truth for HTML wireframe quality, shared word for word with /visual-plan
and /visual-recap. Do not author wireframes from memory.
Use the standard WireframeBlock / <Screen> format so the Plan viewer owns the
surface frame, theme, and sketchy/clean toggle. HTML wireframes are appropriate
when placement precision matters, especially popovers, menus, dialogs, and dense
forms. For HTML
wireframes, keep renderMode unset or wireframe unless a design-only editable
mockup is explicitly required, because renderMode="design" disables the
sketchy rough overlay.
When a browser tool is available, render a UI-impact recap in the Plan viewer and visually inspect it at the current theme before sharing. If any label, annotation, toolbar, or wireframe content overlaps another element, fix the MDX and re-import before reporting the link. Limit this to one render-an
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
