Stats
Actions
Tags
From Builder Skills
Generates interactive visual recaps from git diffs (PRs, branches, commits) with diagrams, file maps, API/schema summaries, annotated diffs, and review notes.
How this skill is triggered — by the user, by Claude, or both
Slash command
/builder-skills:visual-recapThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
`/visual-recap` creates a visual plan built **from** a diff, not toward one. It
/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.
Use local-files privacy mode when the user explicitly asks for no DB writes,
no hosted Plan app, no Plan MCP publish, fully local files, offline/private
recaps, or when AGENT_NATIVE_PLANS_MODE=local-files is set. This is the only
exception to the hosted publish rule below.
In local-files mode:
npx @agent-native/core@latest recap collect-diff, scan, and
build-prompt --local-files helpers are safe to use because they operate on
local files and do not write to the Plan database.plans/<slug>/: plan.mdx,
optional canvas.mdx, optional prototype.mdx, and optional
.plan-state.json. Set kind: "recap" and localOnly: true in
frontmatter/state when authoring the source.npx @agent-native/core@latest plan local preview --dir plans/<slug> --kind recap after
writing or updating the folder. Report the returned local URL or the
/local-plans/<slug> route if the local Plan app is running with the same
PLAN_LOCAL_DIR.create-visual-recap, create-visual-plan,
import-visual-plan-source, update-visual-plan,
patch-visual-plan-source, get-plan-feedback, export-visual-plan,
set-resource-visibility, or any hosted Plan tool for that recap.Local-files mode prevents recap content from going to the Agent-Native Plan database. It does not by itself make the coding agent's language model local; for that stronger privacy boundary, the host agent/model must also be local or otherwise approved by the user.
The deliverable is ALWAYS a published Agent-Native Plan, created with the
create-visual-recap tool on the Plan MCP connector. The connector is usually
exposed as the plan server, but older installed agents may expose the same
hosted connector as agent-native-plans; both names are valid. NEVER hand the
recap to the user as inline chat content — not Markdown prose, not an ASCII
sketch, not a table, not a fenced "wireframe", not a "here's the recap" summary.
A recap's entire value is the hosted, interactive, annotatable plan; an inline
summary is not a recap, it is the thing a recap replaces. The only supported
output is to publish the plan and return its absolute URL.
Except for the explicit local-files privacy mode above, if neither the plan
nor legacy agent-native-plans Plan MCP tools are available, do NOT improvise an
inline recap as a fallback. Do not report the connector as disconnected just
because it is named agent-native-plans instead of plan. The usual cause is a
connector that did not finish connecting this session (it registers zero tools),
NOT necessarily an auth problem — so do not assume the user must authenticate.
Stop and tell the user how to restore it for their current client: in
Codex/Codex Desktop, run
npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex
and start a new Codex session; in Claude Code, run /mcp and choose
Authenticate/Reconnect, or run the reconnect command with --client claude-code
and restart Claude. Auth is stored per client config/session; --client all
refreshes every local client config that already has the Plan entry, but each
running client still has to reload its MCP tools. Reconnect re-authenticates
WITHOUT reinstalling and finds the entry by URL regardless of connector name.
Never reinstall from scratch just to fix auth. Then publish once the tool is
reachable. Falling back to inline content is a defect, not a degraded mode.
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.
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.
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.
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:
file-tree of the changed files with each entry's change flag, so the
reviewer sees the footprint of the work at a glance.diff of the KEY changed files, grouped under a ## Key changes
rich-text heading in a single horizontal tabs block (the default
orientation, one file per tab), with a one-line summary and a few
annotations on 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.
A strong recap follows one skeleton, top to bottom:
rich-text): what changed and why, 1-3 paragraphs.data-model / api-endpoint blocks for schema and contract changes.file-tree of the changed files with change flags.## Key changes — one horizontal tabs block of diff / annotated-code.Budgets that keep the recap reviewable:
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.
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:
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:
Before / After wireframe 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.md owns how to lay that pair out (columns vs.
vertical stack by geometry).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.
references/wireframe.mdUI 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. A text-match screenshot is not enough; visually inspect the captured image. When no browser is available (for example a headless CI agent), state that in the recap handoff instead.
In local-files privacy mode, report the local preview URL/path from
npx @agent-native/core@latest plan local preview or the /local-plans/<slug> route for a local
Plan app using the same PLAN_LOCAL_DIR. Do not invent a hosted URL and do not
publish just to get an absolute Plan link.
After creating the recap, link the reviewer to the rendered plan with an
absolute URL on the origin whose database actually holds the plan. That
origin is the Plan MCP server you just created the recap through — NOT whatever
dev server you happen to know is running. The create tool returns the correct
link; report THAT. Never make the primary link a local plan.mdx file, a local
mirror folder, or a relative path such as /plans/<id>.
When the recap is posted to a PR for a private repo, the plan link is not a public URL. Make the PR comment/handoff copy explicit: reviewers may need to sign in to Agent-Native Plans with an account that has access to the owning organization before the link loads. Use wording like: "Private repo recap: sign in with access to this org if the plan does not open." Do not imply the link is broken or public when access is gated by repo/org visibility.
A recap lives only in the database of the MCP that created it. A separately
running local dev server (e.g. http://localhost:8081) has its OWN database and
will NOT contain a recap created through the hosted MCP, so a hand-built
localhost link returns "Plan not found". This is the most common recap
mistake — do not guess an origin you have not confirmed shares the MCP's data.
Resolve the URL in this order:
openLink.webUrl, else the
visualUrl in the returned plan.mdx frontmatter, else url/path
resolved against the MCP server's own origin (for the hosted MCP that is
https://plan.agent-native.com). This always points at the database that has
the plan.localhost/dev origin ONLY when the recap was created through a Plan
MCP bound to that same origin — i.e. that MCP's url is
http://localhost:<port>/_agent-native/mcp. Creating through the hosted MCP
and linking to localhost is the exact mismatch that 404s.https://plan.agent-native.com/plans/<id>) and say it was inferred.If the user wants to review on localhost but the recap was created through the
hosted MCP, say so plainly: the local dev server cannot see it. To view a recap
on localhost (e.g. to exercise un-deployed local renderer changes), they must
connect a LOCAL Plan MCP (http://localhost:<port>/_agent-native/mcp) and
re-create the recap through it so it lands in the local database; offer to do
that rather than handing over a localhost URL that will not resolve.
When running in Codex and the Browser/in-app side browser tools are available,
open the returned absolute recap URL there automatically after creation. Still
include the same absolute URL in the final response. Local mirror files like
plans/<slug>/plan.mdx may be mentioned only as secondary source-control
artifacts, not as the main way to open the recap.
Map each kind of change to the block that carries it, derived mechanically from
the actual diff. The names below are the CONCEPTUAL block types, not the JSX
tags — resolve every conceptual name to its exact tag + prop schema with the
get-plan-blocks tool (see "Block reference" below) before authoring.
data-model for the resulting entities,
fields, and relations. Flag what moved per field/entity with
change: "added" | "modified" | "removed" | "renamed", and for a changed type
set was to the prior value (e.g. the old column type) — grounded in the real
migration diff. That diff-aware data-model is the headline; reach for a split
diff of the literal SQL only when the exact statement still matters, not by
default.api-endpoint with the method, path,
params, request, and responses as they are after the change. Flag each changed
param/response with change (and was on a param whose type/shape changed),
and set change on the endpoint root for a wholly added or removed route. Mark
removed endpoints with deprecated: true and explain in prose.
Keep multiple API endpoints in the normal single-column document flow unless
they are an explicit before/after contract comparison.
Author each request/response example as a SINGLE valid JSON value — one
top-level object or array, parseable on its own — so it renders in the
collapsible JSON explorer. Do not put // or /* */ comments, prose,
trailing commas, or two or more concatenated top-level objects inside one
example; a non-parseable body falls back to flat text and loses the explorer.
When an endpoint has several distinct message shapes (for example separate
websocket frame types, or a success body versus an error body), give each its
OWN example with its own label rather than cramming them into one body.rich-text notes beside the
relevant data-model / api-endpoint block. Name the changed field,
endpoint, or behavior and mark whether it is breaking, risky, or non-breaking;
pair that note with a split diff for the literal lines.diff with mode: "split", carrying the real
before / after text and the filename / language. Split mode is the
default for recap code review because before/after legibility is the point;
use mode: "unified" only for a genuinely narrow standalone hunk where
side-by-side would hide the code. Give every diff a one-line summary
saying what the hunk changes and why; it renders as a description above the
code so the reviewer reads intent first. Never leave a diff unlabeled.
For the KEY changed files, attach annotations to the diff so the recap
calls out what each important hunk does — this is the headline affordance for
annotating the key files updated. Each annotation anchors to the AFTER-side
line numbers by default (set side: "before" to point at removed lines). Keep
it to a few high-signal notes per file, not one per line.
When several key files each need a substantial diff, introduce the group with a
rich-text heading block whose markdown is ## Key changes, then place the
diff blocks under it in a reusable tabs block with horizontal orientation
(the default — omit orientation) so the selected file's split diff gets the
full document width. Let that heading label the section — do NOT also set a
title on the tabs block. Keep each tab label to the file path or a short
basename plus directory hint.
If the recap ends with more than one supporting diff, that trailing diff
appendix should be one horizontal tabs block under its own ## Key changes
heading, not a stack of separate diff blocks.annotated-code rather than a one-sided split diff. Carry the real new code
with its filename / language and anchor a few high-signal notes to the lines
that matter so the reviewer reads what the new code does, not code for code's
sake. Keep split diff for true before/after hunks where the removed lines
still carry meaning, and group several annotated walkthroughs in a horizontal
tabs block the same way diffs are grouped.file-tree with each entry's change
flag (added, removed, modified, renamed) and a short note; attach a
snippet only when one tells the reviewer something the path does not.Before / After
wireframes when the comparison clarifies the change; otherwise use after-only
or a short state/flow sequence. Use realistic UI surfaces: for a popover
change, show a popover with its title row, top-right actions, options/fields,
tabs, selected/disabled states, people/lists/rows, and any opened prompt/menu
anchored to the correct trigger. If a route was added, show the route body and
the unavailable/empty state when the diff implements one. If permissions
changed, show what managers can do and what viewers/non-managers see instead.
Keep the body lean: the wireframe carries the UI story, while the file tree
and diff blocks carry implementation evidence.diagram with data.html / data.css
as a two-panel before/after, layered, or swimlane layout, or mermaid for a
quick graph. Use two-dimensional layouts; do not reduce a structural change to
a left-to-right chain. Do not use diagram as a stand-in for rendered UI
controls; UI changes need wireframe blocks.
Author diagram HTML/CSS with the renderer-owned .diagram-* primitives
(.diagram-panel, .diagram-node, .diagram-pill, [data-rough], …) and
the same --wf-* theme tokens references/wireframe.md defines — never
font-family, hex, rgb/hsl literals, or one-off dark/light palettes.rich-text for the "what changed and why" prose:
the objective the diff served, the key decisions visible in it, and the risks a
reviewer should weigh. This is the only place the model writes freely.get-plan-blocks, do not memorize tagsThe conceptual block names above (api-endpoint, data-model, json-explorer,
tabs, …) are NOT the JSX tags you author with, and the exact tags, required
fields, and prop shapes change as the block library evolves. Do not author from
memorized tags — they drift and silently produce a wrong tag (ApiEndpoint
instead of Endpoint, JsonExplorer instead of Json, Tabs instead of
TabsBlock) that errors on import.
Before writing any structured plan content, call get-plan-blocks on the Plan
MCP connector (plan or legacy agent-native-plans). It returns the
authoritative, always-current block
vocabulary generated live from the app's own block registry — the same config
the renderer and MDX round-trip use — so it can never be stale even if this
SKILL.md is an old installed copy:
get-plan-blocks (default format: "reference") → a compact table of every
block's runtime type, exact MDX <Tag>, placement, and key data fields.
This is your map from each conceptual name above to its real tag and props.get-plan-blocks with format: "schema" → the full per-block JSON Schema
plus a worked example for each block, when you need exact field types,
enums, or nesting (e.g. Diff.annotations, Endpoint.params[].in,
DataModel.entities[].fields[]).Author the recap source against the tags and schemas that call returns. The
complete set of valid block-level tags is whatever get-plan-blocks lists;
any other capitalized tag at the block level is rejected on import with an
"Unknown plan block" / "did you mean" error. Lowercase HTML tags inside
rich-text/markdown prose (<div>, <span>, <code>, <br>, …) are always
fine — only capitalized component-style block tags are validated.
A few recap-specific authoring rules the registry table cannot encode:
id (unique across the whole plan) plus the
shared optional summary / editable envelope; give a block a heading by
placing a rich-text block with a Markdown ### heading directly above it
(blocks no longer take a title).Endpoint: prose description is the MDX children (body between the
tags), not an attribute; for a WebSocket upgrade use method="GET". Each
request/response example is a JSON string (the renderer parses it into
the JSON explorer), so keep it a single parseable JSON value.TabsBlock: the whole tabs array (including nested child blocks) is ONE
JSON tabs={[…]} prop — there is NO nested <Tab> element.WireframeBlock: its body is a single <Screen surface ... html=… /> subtree
(nested MDX, not a flat prop); html must be a single-quoted string or static
template literal, never a dynamic html={someVar} expression. See
references/wireframe.md for the HTML rules.Diagram: the whole payload is one data={{ html?, css?, nodes?, edges?, … }}
attribute and requires either html or at least one node; Mermaid is its
own separate block (source text), not a Diagram prop.The recap's center of gravity is the before/after comparison. For document-body comparisons there are two primitives, and they cover the whole need together:
columns — the side-by-side container, for structured comparisons.
Use two columns labeled Before and After, each holding a block (commonly a
data-model, api-endpoint, or rich-text), so the reviewer reads the old
shape against the new shape in one glance. This is the right primitive for
"the schema went from X to Y" or "the endpoint contract changed like this."
Do not use columns simply to compact or group a list of API endpoints.diff — for code. It renders the literal removed and added lines. Use
it for the actual hunks. Use split mode by default for recap code review;
reserve mode: "unified" for genuinely narrow standalone hunks where
side-by-side would hide the code. Key-file diff groups should use horizontal
tabs so split diffs get the full document width.For UI diffs, wireframes are the visual comparison primitive. Use before/after
wireframes when the comparison clarifies the change; use after-only or a state
sequence when that better matches the change. The visual headline must show
exact placement, realistic chrome, and adequate padding before any abstract
explanation. Do not stop at the first visible affordance when the diff adds a
flow; show the entry point, the opened surface, and the resulting state or page
so the reviewer can trace the actual user path. references/wireframe.md owns
the before/after layout choice —
the columns renderer keeps narrow surfaces side by side and auto-stacks wide
desktop/browser frames vertically; never hand-build a side-by-side
wireframe layout in custom-html. For document-body
comparisons, there is no other multi-column primitive — columns plus the
diff block are the whole comparison vocabulary. Do not hand-build side-by-side
layouts in custom-html, and do not stack two data-model blocks vertically
and call it a comparison when columns exists to put them side by side.
Structured blocks are true by construction only if they are derived from the
actual changed lines. The diff, data-model, api-endpoint, and file-tree
blocks MUST be built mechanically from the real diff — real paths, real fields,
real method/path, real before/after text — never inferred, rounded, or invented.
The model writes only the prose: the "why", the narrative, the risk read. A
confidently wrong recap is dangerous in a review context, because a reviewer who
trusts the summary may skip the very line the summary got wrong. When the diff
does not contain a fact, leave it out rather than guess; mark anything the model
inferred (not extracted) as inferred in prose.
.env values, or credential-looking literals. Do not
copy any of these into a diff, file-tree snippet, api-endpoint, or prose
block — redact them (sk-•••, <redacted>). This mirrors the repo's
hardcoded-secret rule: obviously fake placeholders only, never the real value,
in any block, caption, or note.Because a recap is a real, editable plan, the same review loop as forward plans
applies: a reviewer can annotate any block, and the coding agent reads
get-plan-feedback to drive fixes back into the code — annotation → agent →
diff, the same close-the-loop flow forward plans use. After a reviewer annotates
a block, call get-plan-feedback to read the structured feedback, then either
update the recap with create-visual-recap (passing the existing planId to
replace it in place) or apply targeted changes with update-visual-plan. The
loop is live and wired. The one thing not yet automatic is PR-comment-triggered
re-runs: the GitHub Action creates an initial recap per PR, but it does not yet
re-run automatically when new review feedback is posted in GitHub — that
auto-re-run is the remaining fast-follow.
resolutionTarget, and two-axis consumed/resolved state.npx claudepluginhub builderio/skillsTransforms code changes or diffs into structured visual recap plans for high-altitude review, using schema, API, file, and before/after blocks instead of raw diffs.
Creates a visual code review on a Miro board from a PR/MR, local changes, or branch comparison. Produces file-change tables, architecture/security docs, and diagrams, then links them back to the PR/MR.
Visualizes planned code changes as ASCII diagrams with before/after architecture, risk analysis, execution order, and impact metrics. Use for reviewing plans, migrations, or assessing change impacts.