visual-plan
Turn ordinary text plans into rich interactive visual plans with diagrams, file maps, annotated code, open questions, and UI/prototype review when useful.
Install / Use
npx skills add BuilderIO/skills --skill visual-planInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
DesignSupported Platforms
Our assessment of visual-plan
visual-plan scores 92/100 on our quality scale, 61st of 260 Design skills we index (top 24%).
Its SKILL.md is 32 KB long, well organised into 17 sections with 1 code example: 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-plan is actively maintained.
- Our last check on 2026-10-05 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-plan compared with similar skills
All 4 of these similar skills score higher than visual-plan; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| visual-plan (this skill)by BuilderIO | 92 | 4.4k | 54d ago | SKILL.md |
| x402by browser-use | 100 | 121.0k | 3d ago | SKILL.md |
| algorithmic-artby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
| pptxby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
| designby nextlevelbuilder | 100 | 149.0k | 6d ago | SKILL.md |
Frequently asked questions
- How do I install visual-plan?
- Run
npx skills add BuilderIO/skills --skill visual-plan. The install tabs above show the steps for each supported agent. - Which AI agents does visual-plan 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-plan 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-plan still maintained?
- The repository was last updated about 2 months ago, so visual-plan is actively maintained.
Skill content
View source on GitHubname: visual-plan description: >- Turn ordinary text plans into rich interactive visual plans with diagrams, file maps, annotated code, open questions, and UI/prototype review when useful. metadata: visibility: exported
Agent-Native Plans
Agent-Native Plans is structured visual planning mode for coding agents. Build the plan you would normally write in Markdown, but as a scannable document with editable blocks mixed in: inline diagrams, code snippets, open questions, and an optional top visual review area (wireframe canvas, live prototype, or both in tabs). Architecture and backend plans stay document-only; UI and product plans start with the top canvas/prototype (the Visual Surface Choice section owns that rule).
/visual-plan is the packaged command and main entry point. Choose the review
mode from the task: UI-first when the work is primarily product UI and review
should start with screens, prototype-first when review should start with a
functional live prototype, design-first when review needs full-fidelity branded
screens, or visual-intake when the user explicitly wants a questionnaire before
planning. When a Codex, Claude Code, Markdown, or pasted plan already exists,
/visual-plan uses that source plan as the starting point and builds the review
surface from it instead of starting over.
When To Use
Create or adapt a visual plan whenever the plan would be better as a reviewable artifact than a chat paragraph. This includes modest work such as a single UI surface with states, a small workflow, a before/after product change, or a component/API/data-shape decision that needs alignment, plus larger multi-file, ambiguous, long-running, risky, or UI-heavy work. Use it when architecture / data flow / UI direction / options / open questions would benefit from inline diagrams or structured blocks, when the user needs to react to a direction before you implement, or when an existing text plan needs a richer review surface.
Plan Discipline
- Gate thoughtfully. A visual plan is a richer review surface, not only a tool for giant projects. Use it when the user needs to see, compare, comment on, or approve a direction before code, even for a modest UI/state/workflow change. Skip it for truly trivial, unambiguous work — typos, one-line fixes, a single well-specified function, anything whose diff you could describe in one sentence — and just make the change. Never pad a plan with filler and never ship a single-step plan.
- Research before you draft. Read the real files, actions, schema, and
patterns first; name actual files, symbols, and data shapes instead of
inventing them. Check existing
actions/before proposing endpoints and prefer named client helpers over raw fetch. Delegate wide exploration to a sub-agent. Lead with reuse: for each step, name what it reuses — existing actions, schema, components, helpers — before what it adds, so the plan explains the genuinely new delta instead of redescribing what already exists. - Decide the hard-to-reverse bets first. For non-trivial backend, data, or API work, sketch where the feature is headed, then call out the decisions that are expensive to undo once data or callers depend on them — wire format, public ids, data-model shape, auth and ownership boundaries — and get those right in the plan even if most of the feature ships later. Then scope to the smallest first cut that proves the approach without foreclosing it, stating both what is in and what is explicitly deferred.
- Keep examples at the right altitude. When the user's idea is a broad framework, product, or operating-model change, do not collapse it into the first concrete example, provider, or sync path they mention. Separate the core abstraction from motivating examples and app/provider adapters. Use examples to make the plan legible, but label them as examples unless they are the whole requested scope.
- Publish standalone plans. If the user pasted, referenced, or already has a Codex / Claude Code / Markdown plan, treat it as source material, but rewrite the published plan as a clean standalone proposal. Preserve the source plan's useful intent and codebase facts, label inferred visuals as inferred, and avoid revision language such as "preserve the prior plan", "do not drop the old idea", "unlike the previous version", or "this revision changes...". A reader who never saw the chat or earlier drafts should understand the plan.
- Make the first read concrete. If the plan is meant to be shared with someone outside the chat, or if the concept is abstract, lead near the top with one concrete product example before mode tables, architecture, or roadmaps. For UI-capable concepts, that usually means a top-canvas app state that shows the real user workflow in product terms. Do not rely on phrases that only make sense in conversation, and do not frame the plan as "not the old idea"; state the positive model directly.
- Planning is read-only. Make no source edits while building or reviewing the plan. Start editing only after the user approves the direction.
- Clarify vs. assume. Do not ask how to build it — explore and present the
approach and options in the plan. Ask a clarifying question only when an
ambiguity would change the design and you cannot resolve it from the code; use
the host agent's normal ask-user-question flow and batch 2-4 high-leverage
questions before finalizing. Do not call
create-visual-questionsfor ordinary clarification or preflight; reserve it for the visual-intake mode when the user explicitly asks for a visual intake questionnaire. Otherwise state the assumption explicitly and proceed, and keep anything unresolved in the plan's single bottomquestion-formOpen Questions block. For complex plans, do a final open-question pass before handoff: if a decision would affect architecture, scope, UX, data shape, or rollout, either decide it in the plan with rationale or put it in that bottom form with a recommended default. - The plan is the approval gate. After surfacing it, ask the user to review and approve before you write code, and name which files/areas the work touches. Presenting the plan and requesting sign-off is the approval step — do not ask a separate "does this look good?" question.
- The document is the source of truth, not the chat. When scope shifts,
update the plan with
update-visual-planrather than only changing course in chat, and make the updated document stand alone. Do not describe the update as a correction to an earlier draft inside the plan itself. Re-read the approved plan before major steps.
Create A Structured Agent-Native Plan — Never Inline
The deliverable is ALWAYS a structured Agent-Native Plan, not a chat-only plan.
The hosted Plan MCP connector (plan server, or legacy agent-native-plans) is
the default collaboration and commenting surface; it is not a reason to reject
the planning pattern as an external dependency or rented layer. Plans are
portable source artifacts (plan.mdx, optional canvas.mdx /
prototype.mdx, JSON, and HTML export), and ownership-sensitive workflows can
use local-files mode or a self-hosted/custom Plan app URL without abandoning the
skill's review discipline. Do not advise the user to skip /visual-plan because
the default surface is hosted; choose the right Plan mode for the user's
ownership, privacy, sharing, and branding needs.
By default, create the plan via the Plan MCP connector and NEVER hand it over as
inline chat content — no Markdown prose, ASCII sketch, table, or fenced
wireframe. 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 plan. 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 (after Tool Guidance) is the exception.
Core Workflow
This section describes the default hosted Plan MCP workflow. If
AGENT_NATIVE_PLANS_MODE=local-files is set, or the user asks for fully local
files/no hosted Plan writes, use Local-Files Privacy Mode instead; carry
forward only the code-research and plan-composition guidance here.
- Follow the host agent's normal planning flow: inspect the codebase, delegate wide exploration when useful, gather the info needed, and ask native clarifying questions as needed before generating the plan. If a source plan already exists, gather its exact text from the user's paste, a referenced file, or recent visible agent context; do not invent source text.
- Call
get-plan-blocksfor the authoritative block catalog — do not author from memorized tags. Then call the mode-matched create tool:create-visual-planfor document-first plans (architecture, backend, data, refactor, API),create-ui-planfor UI-first plans,create-prototype-planfor prototype-first plans,create-plan-designfor design-first plans,create-visual-questionsonly when the user explicitly asks for a visual intake questionnaire. When a source plan already exists, pass it asplanTextand preserve the original plan's useful intent while producing a standalone plan document, not a revision memo. - For UI/product plans, compose the top canvas first with the primary
wireframes and annotated states, then write the document with native blocks
(see
references/canvas.mdandreferences/document-quality.md). For broad product architecture plans with a user-facing implication, add a concrete "what this looks like in the app" visual before the abstract architecture or mode tables. Keep the document close to the standalone Markdown plan the agent would normally output. If an existing plan was provided, carry forward the right facts and decisions without referring to the previous draft or explaining how this version differs. For non-visual plans, skip the top visual surface (Visual Surface Choice below owns the rule) and putdiagram,data-model,api-endpoint,diff,file-tree,code, andannotated-codeblocks directly next to the relevant prose. Wide document layout is renderer-owned and intentionally allowlisted: only literal code-review surfaces (diff,annotated-code) andtabsblocks with vertical orientation or diff-like children break out wider than prose. Keepapi-endpoint,openapi-spec,data-model,json-explorer,wireframe, question, andcustom-htmlblocks in normal document flow unless their own renderer says otherwise. - Surface the returned Plans link or inline MCP App and ask the user to review. Always include the actual URL in chat so the next step is a click in CLI or other text-only hosts. When the host exposes an embedded browser/preview panel and a tool can open arbitrary URLs there, open the returned plan URL automatically for convenient review — a convenience and smoke test, never the only handoff or the access model. Plans should load out of the box for the local agent and local browser session; if a signed-in embedded browser cannot read a local plan that an anonymous/tool check can read, fix the app/action ownership or access path rather than patching one plan by hand. For high-stakes plans (architecture, backend, data, multi-file, or risky), also kick off the self-review pass in Self-Review Before Handoff while the user reads, instead of blocking the handoff on it.
- For hosted plans, call
get-plan-feedbackbefore editing, after review, after any long pause, and before the final response. TreatanchorDetails, re
Truncated for display — read the full file on GitHub.
Related Skills
x402
121.0kSet up Browser Use Cloud payments with x402 — pay per request from a crypto wallet (USDC on Base mainnet), no signup or API key.
algorithmic-art
177.9kCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems.
pptx
177.9kUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an em…
design
149.0kComprehensive design skill: brand identity, design tokens, UI styling, logo generation (55 styles, Gemini, Atlas Cloud, or MuAPI AI), corporate identity program (50 deliverables, CIP mockups), HTML presentations (Chart.js), banner design (22 styles, social/ads/web/print), icon design (15 styles, SVG…
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.
