kunalamin/visual-explainer

1. Repository type

- This is not a traditional app; it is an agent skill/plugin package.

- The repo ships prompt files, manifests, reference docs, HTML templates, and a small deploy script that together teach an AI agent how to generate visual explanations.

2. Top-level packaging boundary

- .claude-plugin/ contains the marketplace-facing plugin metadata.

- plugin.json identifies the plugin, and marketplace.json registers it in the catalog.

- This boundary is about distribution and discovery, not runtime behavior.

3. Primary skill boundary

- plugins/visual-explainer/ is the actual skill payload.

- Its own .claude-plugin/plugin.json acts as the skill manifest for the plugin runtime.

- Everything else in this folder is content the agent consumes to decide what to generate.

4. Command entry points

- commands/ contains the slash-command prompts, such as generate-web-diagram, diff-review, plan-review, project-recap, and share.

- These are the main user-facing orchestration endpoints.

- Each command steers the agent toward a particular output shape: diagram, review, recap, slide deck, or shareable page.

5. Behavioral guidance layer

- SKILL.md defines the core workflow and design principles for the agent.

- This file is the central behavioral contract: it explains how the skill should choose layouts, manage complexity, and present information visually.

6. Reference knowledge layer

- references/ contains reusable design and implementation guidance the agent reads before generating output.

- The docs are organized by concern:

- css-patterns.md for layout/theming/animation choices

- libraries.md for supported visualization libraries like Mermaid or Chart.js

- responsive-nav.md for long-form navigation patterns

- slide-patterns.md for slide-deck structure and presentation patterns

- This layer acts like a lightweight knowledge base for consistent output quality.

7. Template rendering layer

- templates/ contains self-contained HTML examples for the output formats:

- architecture.html

- data-table.html

- mermaid-flowchart.html

- slide-deck.html

- These templates are the presentation substrate the agent adapts when generating final pages.

- The repo’s architecture is intentionally browser-native: output is HTML, not a compiled app.

8. Sharing/deployment path

- scripts/share.sh is the only executable helper in the repo.

- It packages or deploys generated HTML to Vercel and returns a shareable URL.

- This is the external publishing boundary for turning local output into a link.

9. Execution flow

- A user invokes a command or directly asks the agent for a visualization/review.

- The agent reads SKILL.md, the relevant command file, and supporting reference docs.

- It then selects an HTML template or Mermaid-based approach, writes the result to ~/.agent/diagrams/..., and opens it in a browser.

- If sharing is requested, the script pushes the HTML to Vercel.

10. Output model

- The system favors static, self-contained HTML pages with optional embedded Mermaid/visual libraries.

- That means the main runtime dependencies are the browser and the agent environment, not a backend service or build pipeline.

- The repo is therefore best diagrammed as a content-driven generator with a browser-rendered output stage.

11. Supported host environments

- The README shows the same skill can be installed into Claude Code, Pi, and OpenAI Codex environments.

- That matters architecturally because the repo is designed to be portable across agent runtimes, with command prompts and skill files copied into each host’s expected directories.

12. Key architecture takeaway

- The repository is a plugin distribution package composed of:

- metadata/manifests for discovery,

- command prompts for entry points,

- reference docs for generation policy,

- HTML templates for rendering,

- a share script for publication.

- There is no monolithic application core; the “engine” is the agent runtime interpreting these files.