Overview
Steve from Builder.io introduces /visual-plan and /visual-recap — two open-source Claude Code skills that replace static markdown plans with rich, interactive MDX documents featuring wireframes, API specs, schema diagrams, and annotated code. He argues that engineering is entering a new abstraction phase where humans reason at the plan level while agents handle implementation — much like how C abstracted away assembly — and that plans need to be visual, interactive, and shareable to make this paradigm shift work.
1 The Problem with Markdown Plans
Steve opens with a common frustration: plan mode in Claude Code is incredible, but the output is a massive markdown essay dumped in the terminal. He finds his eyes "glazing over" the wall of text, and after implementing, he realizes he missed important small details that weren't clear because there was simply too much to read.
The core issue: markdown is a text-first format. It's great for simple documentation, but when you're trying to reason about architecture, API shapes, database schemas, and UI layouts, text-based plans force you to mentally visualize everything — a cognitive burden that leads to missed details and misunderstandings.
2 The Visual Plan Skill — MDX Components
Steve's solution is a Claude Code skill called visual plan. Instead of generating plain markdown, it produces MDX (Markdown + JSX) with rich visual components:
- Diagrams — architecture and flow visualizations
- Interactive API specs — expandable endpoint definitions with request/response schemas
- Schema design changes — visual database migration representations
- Annotated code — code blocks with highlighted sections and explanations
- Pan-and-zoomable wireframes — interactive UI mockups you can explore
The workflow changes fundamentally: instead of reading a plan and then coding, you now look at a wireframe first, comment on it, iterate, answer open questions visually and interactively, and then have the agent work.
3 Why MDX over HTML and Markdown
The skill was inspired by the idea that HTML is better than markdown for rich content, but Steve identified three problems with raw HTML:
- Slow and verbose to write — even for an AI agent
- Looks bad checked into a repo — large HTML blobs aren't readable in PRs or diffs
- No reusability — every generation produces different HTML "slop," with no consistency across runs
MDX solves all three:
- Reusable components — instead of generating raw HTML, the agent uses pre-defined components like
<Wireframe>,<APISpec>,<SchemaChange> - Clean in repos — MDX files read naturally in code reviews
- Consistency — the same components render the same way regardless of which model or agent generated them
- Customizable — you can add your own components or customize existing ones
4 Engineering's New Abstraction Level
Steve shares a deeper philosophical take: software engineering is entering a new abstraction phase where developers reason at the plan level rather than the code level. He draws a direct parallel to the evolution from assembly to C:
- Assembly → C: Developers stopped thinking in machine instructions and started reasoning about higher-level constructs. The C compiler was trusted to generate correct assembly.
- Code → Plans: Similarly, developers will increasingly reason at the plan level — architecture, wireframes, API shapes — and trust agents to implement correctly.
The key requirement for this shift: plans need to be clear, consumable, and visual. Just as C needed a good syntax to be useful, plan-level reasoning needs better tooling than raw markdown.
5 Visual Recap — The Reverse Skill
Steve also built the reverse companion: visual recap. After the agent finishes work, it generates a rich visual summary of everything it did, using the same component system:
- Wireframes of what was built or changed
- Interactive API spec diffs — before/after views of endpoint changes
- Schema changes — visual representation of database migrations
- Annotated code — key code sections with highlighted changes and explanations
This addresses a gap Steve identifies in current code review: you either get a short description (too vague to catch issues) or a super granular line-by-line diff (too detailed to reason about holistically). Visual recap sits in the middle — interactive, visual, and easy to share with others for comments and feedback.
6 Catching Mistakes Earlier
Steve describes a concrete workflow improvement — catching mistakes at two stages:
Before Implementation
With visual plan, you see wireframes before the agent starts coding. "The text sounded fine, but the wireframe makes me realize — oh wait, no, that's not what I had in mind." You can also review API shapes visually and request changes before any code is written.
After Implementation
With visual recap, you get a snapshot that reveals issues that aren't obvious from raw React and Tailwind code. Steve admits: "It's tedious to hand-test every single thing every time. Having a snapshot at a glance that's clear and I can interactively drill into has been a game-changer compared to just static markdown."
7 Cross-Team Collaboration
Visual plans and recaps unlock a new collaboration pattern: you can share the same visual artifact with different stakeholders, each focused on their area of interest:
- Product managers — review behavior and user flows via wireframes
- Designers — evaluate visual layout and component design
- Engineers — inspect API specs, schema changes, and annotated code
Everyone comments on the same document, and those comments can be passed back to the agent for refinement. This eliminates the translation gap where PMs write requirements in Notion, designers mock in Figma, and engineers interpret both — now everyone reasons about the same visual plan.
8 GitHub Action Integration
Steve built a GitHub Action that automatically runs the visual plan/recap on every pull request. The action:
- Generates a visual snapshot of the changes in the PR
- Posts it as a PR comment with interactive elements you can click into
- Bridges the gap between a short PR description and a granular line-by-line diff
The entire toolchain — skills, the MDX rendering application, and the GitHub Action — is free and open source on GitHub. You can install it via a CLI, fork it, and customize with your own components.
🎯 Key Takeaways
🔑 Key Takeaways
- Markdown plans cause cognitive overload — large text walls in the terminal lead to missed details and misunderstandings that only surface after implementation
- Visual Plan generates interactive MDX — wireframes, API specs, schema diagrams, and annotated code replace static text-based plans
- MDX beats HTML for agent output — reusable components, clean in repos, consistent across models, and customizable by the user
- Engineering is abstracting up — just as C abstracted away assembly, plan-level reasoning will abstract away code-level implementation
- Visual Recap is the reverse skill — generates rich summaries of what the agent built, closing the feedback loop after implementation
- Two-stage error catching — wireframes catch design misunderstandings before coding; recaps catch implementation issues before production
- Same artifact for all stakeholders — PMs, designers, and engineers all review the same visual plan, each focusing on their area
- GitHub Action for PR reviews — automatically generates visual snapshots on every pull request for more consumable code review
- Reusable components ensure consistency — switching agents or models doesn't change the output format, unlike raw HTML generation
- Fully open source and free — skills, MDX editor app, CLI, and GitHub Action all available on GitHub under MIT license
🔗 Resources & Links
- BuilderIO/skills — open-source visual-plan and visual-recap skills for Claude Code + Codex
- BuilderIO/agent-native — visual MDX editor source and Agent Native framework