The Problem

Developers often ask AI agents to produce diagrams, diff summaries, or data tables. Agents default to plain‑text ASCII art, which quickly becomes unreadable for anything beyond a few boxes or rows. The result is a wall of characters that cannot be shared or presented.

What This Does

visual‑explainer supplies an Agent Skill that intercepts those requests and returns a self‑contained HTML page instead of raw text. The repository ships the following concrete assets:

  • Prompt templates in prompts/ (diff-review.md, plan-review.md, etc.) that define the slash‑command syntax and the text the agent should generate.
  • HTML skeletons in templates/ (architecture.html, data-table.html, mermaid‑flowchart.html) that embed the generated content, apply dark/light themes, and enable interactive Mermaid diagrams.
  • Supporting docs (README.md, SKILL.md, LICENSE) that describe installation and usage.

When an agent receives a command like /diff-review it loads the corresponding markdown prompt, fills in the diff data, and injects the result into the matching HTML template, producing a single .html file opened in the user’s browser.

How It Is Wired

Entry point – The skill is activated by the agent when a user invokes one of the slash commands listed in prompts/. The agent framework reads SKILL.md to register the skill and the command names.

Prompt → Template flow

  1. Command detection – Agent matches /diff-review, /plan-review, /generate-web-diagram, /project-recap, or /fact-check.
  2. Prompt loading – The agent reads the matching markdown file, e.g. prompts/diff-review.md. The prompt contains placeholders for the data the agent must supply (git diff, plan file, etc.).
  3. Content generation – The agent fills the placeholders with runtime data (git output, plan analysis, etc.). No code in this repo performs the generation; it is delegated to the host agent.
  4. Template rendering – The filled markdown is inserted into the appropriate HTML file from templates/ (e.g., templates/architecture.html for diagram output). The HTML files include a small inline CSS block and a <script> that loads Mermaid.js for flowcharts.
  5. File write & open – The agent writes the final HTML to ~/.agent/diagrams/ (as documented in the README) and launches the default browser.

Side‑effects – The only external effect is file creation in the user’s home directory; there is no network, database, or build step. The skill’s “hub” is the prompt‑template pair; any change to a prompt or template propagates to all commands that use it.

Unmapped wiring – The repository contains no executable scripts, tests, CI configuration, or Dockerfile, so the internal execution path beyond the prompt/template mapping is not present in this codebase.

How To Use It

# Clone the skill into the agent’s skill directory
git clone https://github.com/moses-y/visual-explainer.git ~/.pi/agent/skills/visual-explainer

# Install the prompt‑template extension (required for Pi agents)
cp ~/.pi/agent/skills/visual-explainer/prompts/*.md ~/.pi/agent/prompts/
pi install npm:pi-prompt-template-model

After the agent restarts, the slash commands become available. Running a command, e.g.:

/diff-review main..HEAD

causes the agent to generate ~/.agent/diagrams/diff-review-<timestamp>.html and open it automatically.

Real‑World Use

A development team uses Claude Code with this skill to review pull‑request diffs. Instead of scrolling through a massive terminal diff, the agent produces an HTML page that shows before/after architecture diagrams, a KPI dashboard, and a structured Good/Bad/Ugly code review. The page is then shared with stakeholders via a simple link, improving visibility and decision‑making.

Code Health & Issues

  • Medium – No tests – The repository contains no test files, so functional coverage cannot be verified automatically.
  • Medium – No CI/CD – No .github/, Makefile, or other pipeline definitions are present, meaning builds and checks are not gated.
  • Low – No lockfile – Absence of package-lock.json, yarn.lock, requirements.txt, etc., makes reproducible dependency installation impossible (though the skill claims “no dependencies beyond a browser”).
  • Info – License present – LICENSE file exists (MIT).

No secrets or Dockerfile were detected.

The Bottom Line

visual‑explainer provides a lightweight, browser‑based alternative to ASCII art for AI‑generated diagrams and tables, relying on markdown prompts and static HTML templates. It is well‑documented for agents that follow the Agent Skills spec, but the repo lacks automated testing, CI pipelines, and explicit dependency lockfiles, so teams should add those safeguards before integrating it into production workflows.