How nicobailon/visual-explainer works
This repository is a Claude Code / agent plugin that produces visually rendered explanations from text prompts and terminal output. It is not an application server or frontend app; it is a packaging and prompt-authoring repo for an agent skill named visual-explainer.
Architectural shape
At a high level, the repo has three layers:
1. Plugin distribution layer
- Root-level plugin metadata in .claude-plugin/
- Marketplace and install plumbing for Claude Code / Pi / Codex
- A root package.json and install-pi.sh for packaging and installation workflows
2. Skill implementation layer
- Everything under plugins/visual-explainer/
- This is the actual agent skill: instructions, commands, references, templates, and sharing script
3. Output delivery layer
- The skill generates self-contained HTML files
- Those files are meant to be opened locally in a browser or deployed to Vercel for sharing
Main subsystems
1) Plugin metadata and packaging
Files:
• .claude-plugin/plugin.json
• .claude-plugin/marketplace.json
• plugins/visual-explainer/.claude-plugin/plugin.json
This layer defines the plugin identity and how it is exposed to a marketplace or agent runtime. The root .claude-plugin directory appears to describe the repo as a plugin catalog entry, while the plugin-specific manifest under plugins/visual-explainer/.claude-plugin defines the actual skill package.
This is the boundary between the repository and the consuming agent platform.
2) Skill behavior and orchestration
File:
• plugins/visual-explainer/SKILL.md
This is the core operating manual for the agent skill. It likely explains:
• when to choose HTML, Mermaid, tables, or slide decks
• how to interpret prompts
• how to structure outputs for readability
• design principles for generated pages
This file is the central control plane for the agent’s behavior. The commands and templates are supporting assets; the skill document is what tells the model how to use them.
3) Slash command entry points
Directory:
• plugins/visual-explainer/commands/
Commands:
• diff-review.md
• fact-check.md
• generate-slides.md
• generate-visual-plan.md
• generate-web-diagram.md
• plan-review.md
• project-recap.md
• share.md
These are task-specific prompts or workflows. They are the user-facing functional entry points. Each command represents a distinct use case:
• architecture or system diagram generation
• visual plan generation
• slide deck generation
• code diff review
• plan/code comparison
• project recap/context snapshot
• document fact-checking
• sharing a generated artifact
Architecturally, these commands are the routing layer: they decide which kind of output should be generated and what format it should take.
4) Reference knowledge base for generation
Directory:
• plugins/visual-explainer/references/
Files:
• css-patterns.md
• libraries.md
• responsive-nav.md
• slide-patterns.md
These are supporting design and implementation references the agent reads while generating content. They act like a constrained knowledge base:
• CSS/layout patterns for polished pages
• supported libraries such as Mermaid or Chart.js
• navigation patterns for long documents
• slide composition patterns for deck mode
This layer is important because the skill is not just “write HTML”; it is “write HTML that follows preferred visual and interaction patterns.”
5) Presentation templates
Directory:
• plugins/visual-explainer/templates/
Files:
• architecture.html
• data-table.html
• mermaid-flowchart.html
• slide-deck.html
These are canonical output templates. They define the visual system for generated artifacts:
• architecture pages for system overviews
• table layouts for structured comparisons
• Mermaid-based diagrams for flowcharts
• slide deck layout for presentation-style output
These templates are the primary rendering boundary. The agent maps a task to one of these output shapes and fills in content.
6) Sharing/deployment script
File:
• plugins/visual-explainer/scripts/share.sh
This script provides the distribution path for a finished artifact. The README says the share workflow deploys the HTML page to Vercel and returns a live URL. That makes sharing a separate concern from generation.
This is a distinct operational boundary:
• generation happens locally
• sharing publishes the generated static HTML externally
Data flow
The repository’s end-to-end flow is:
1. User invokes a command or asks the agent for a visual explanation
- Examples: diagram a flow, review a diff, compare plan vs code
2. Agent consults skill instructions and references
- SKILL.md
- command prompt file
- supporting references
3. Agent selects an output form
- Mermaid diagram
- HTML architecture page
- data table
- slide deck
4. Agent renders a self-contained HTML artifact
- output is saved locally under ~/.agent/diagrams/filename.html according to the README
- no build step is required
5. Browser opens the artifact
- the local HTML becomes the primary presentation surface
6. Optional sharing path
- share.sh deploys the generated page to Vercel
- a public URL is returned for collaboration
Important boundaries
Prompting vs rendering
The repo does not contain an application runtime that renders pages dynamically. Instead, it separates:
• instructions and templates for the agent
• static HTML output for the browser
That means the “engine” is mostly the model + templates, not JavaScript application logic.
Local artifact vs public share
Generated pages are first-class local files. Public sharing is optional and externalized through Vercel. That keeps the core flow offline/local while enabling collaboration as a separate step.
Generic generation vs specialized workflows
The command files split general visual generation into specific workflows:
• diagrams
• plans
• reviews
• recaps
• slides
• fact checking
This reduces ambiguity for the agent and makes each output type more predictable.
Markdown instructions vs HTML templates
The repo uses Markdown for agent instructions and HTML for rendered presentation. Markdown drives the model; HTML is the deliverable.
Technologies and runtime implications
The architecture is lightweight and static:
• Markdown for skill and command definitions
• HTML/CSS for output templates
• Mermaid for diagrams
• likely Chart.js for charts, as hinted in the README references
• browser as the rendering runtime
• Vercel as the optional hosting target
• shell scripting for installation/sharing
There is no evidence of a backend service, database, or long-running process in this repo.
How to draw this repository as an architecture diagram
The most accurate diagram would show:
• A top-level agent platform / Claude Code box
• A plugin package boundary containing:
- plugin metadata
- skill instructions
- command prompts
- reference docs
- templates
- share script
• A local output box for generated HTML files
• A browser box that renders the HTML
• An optional Vercel box for public sharing
The key flows are:
• user prompt → command/skill instructions → template selection → HTML artifact
• HTML artifact → browser
• HTML artifact → share script → Vercel → public URL
Repository intent
The repo is fundamentally a visual-output framework for agents. It packages the knowledge and presentation patterns needed to transform plain-text reasoning into polished, browser-rendered artifacts. The main architectural concern is not business logic, but controlling presentation quality, choosing the right output format, and making the result easy to view or share.
Main entry points: SKILL.md Skill guide · commands Commands · templates Templates · share.sh Share script
Components 14
Plugin distribution
Repository-level packaging and marketplace entrypoints.
- Plugin manifest · Repository-level plugin metadata for marketplace/runtime exposure.
.claude-plugin/plugin.json - Marketplace · Marketplace plumbing for install and discovery.
.claude-plugin/marketplace.json - Package config · Root packaging and dependency metadata.
package.json - Install script · Root installation workflow for Pi or related packaging.
install-pi.sh
Visual explainer skill
The packaged agent skill, prompts, references, and templates.
- Skill manifest · Skill-specific plugin metadata under the visual-explainer package.
plugins/visual-explainer/.claude-plugin/plugin.json - Skill guide · Core operating manual that governs how the skill chooses and structures outputs.
plugins/visual-explainer/SKILL.md - Commands · Task-specific slash-command workflows for visual generation, review, recap, and sharing.
plugins/visual-explainer/commands - References · Supporting guidance for CSS patterns, libraries, navigation, and slide composition.
plugins/visual-explainer/references - Templates · Canonical HTML templates for diagrams, tables, architecture pages, and slide decks.
plugins/visual-explainer/templates - Share script · Deploys a generated artifact for sharing.
plugins/visual-explainer/scripts/share.sh
Output delivery
Local HTML artifacts and optional publishing path.
- HTML artifact · Self-contained local HTML file produced by the skill.
- Browser · Local browser that renders the generated HTML artifact.
- Vercel · Optional public hosting target for shared HTML artifacts.
Other components
- Claude Code · Consuming agent platform that loads the plugin and executes commands.
Connections 15
- Claude Code → Plugin manifest: loads · Platform discovers the repository plugin entry.
- Claude Code → Skill manifest: loads · Platform loads the skill package metadata.
- Plugin manifest → Marketplace: catalogs · Root plugin metadata is paired with marketplace configuration.
- Package config → Install script: packages · Package metadata supports installation and distribution workflows.
- Skill manifest → Skill guide: governs · Skill metadata leads into the primary operating instructions.
- Skill guide → Commands: routes · Skill guide directs task-specific command workflows.
- Skill guide → References: consults · Skill guide uses supporting references for output quality and patterns.
- Commands → Templates: selects · Command prompts map tasks to output templates.
- References → Templates: informs · Reference docs shape the visual patterns used by templates.
- Templates → HTML artifact: renders · Templates are filled to produce a self-contained HTML artifact.
- HTML artifact → Browser: opens · Generated HTML is viewed locally in a browser.
- Commands → Share script: invokes · Share workflow triggers the publishing script.
- Share script → Vercel: deploys · Sharing publishes the artifact to Vercel.
- HTML artifact → Share script: publishes · The generated artifact is handed to the sharing workflow.
- Claude Code → Install script: installs · The consuming environment may use the install workflow.