Bundle an opt-in 'visual-explainer' skill (diagram-first HTML design docs instead of verbose Markdown)

[ashwin-pc]

Summary

Bundle a visual-explainer skill with pi-web, opt-in (off by default), that makes the agent emit a single self-contained, preview-safe HTML design doc (dense, diagram-led, Mermaid) instead of a verbose Markdown file whenever the user asks for an explanation / design / HLD / walkthrough / proposal.

This skill was built and validated against pi-web specifically, so it belongs here (or as a pi-web-recommended package). It's currently a global skill at ~/.pi/agent/skills/visual-explainer/.

Why this fits pi-web (not just "a generic skill")

Its core constraints are pi-web behaviors I had to design around:

• Preview-safety. pi-web previews HTML artifacts in <iframe sandbox=""> (src/markdown/render.ts), which disables JS. The skill therefore forbids JS-gated content (no scroll-reveal/opacity:0, no JS-only tabs), keeps Mermaid source in the DOM as a fallback, and drives light/dark from @media (prefers-color-scheme) so theming works with no JS. A naive "fancy" HTML explainer renders blank in the preview.
• Pairs with Vend bundled Mermaid to standalone artifacts via /api/vendor/ (offline diagrams) #27 (vend bundled Mermaid at /api/vendor/ for offline diagrams) and Allow scripts in the HTML artifact preview iframe (sandbox="allow-scripts") so diagrams render in-session #28 (sandbox="allow-scripts" so diagrams render in-session). With those, the in-chat preview renders diagrams directly.

What the skill does

SKILL.md description:

Produces a single, self-contained, responsive HTML artifact (a dense, content-first technical document with Mermaid diagrams and minimal prose) instead of a verbose Markdown file. Use this whenever you would otherwise write a long-form Markdown document to explain, teach, or propose something… Do NOT use it for quick inline answers, code edits, or deliverables that must literally be Markdown (README.md, issue/PR/commit text, files explicitly requested as .md).

Structure (small, freeform assets):

visual-explainer/
├── SKILL.md                      # triggers, principles, preview-safe workflow
├── assets/
│   ├── template.html             # design system + preview-safe theming + Mermaid wiring
│   ├── example-hld.html          # canonical dense HLD exemplar
│   └── example-architecture.html # richer interactive style (open-in-tab only)
└── references/
    ├── design-system.md          # tokens, dense type scale, semantic Mermaid palette, theming
    ├── components.md             # HLD block catalog (header+thesis, cards, before/after stack,
    │                             #   legend, semantic classDefs, y/x + decision + phasing tables, schema)
    └── checklist.md              # quality bar incl. the JS-disabled preview check

Proposed integration (opt-in)

Option A — bundle in-repo + opt-in toggle (preferred)

1. Add skills/visual-explainer/ to the repo and to package.json files.
2. Mirror the existing extension bundling for skills: pi-web already builds
   additionalExtensionPaths() from resolveBundledExtensionPaths({ bundledExtensionsDir })
   and passes it to new DefaultResourceLoader({ additionalExtensionPaths }) in
   makeAgentSession() (server.ts ~L1704). Add the analogous bundledSkillsDir +
   additionalSkillPaths and pass it to the loader (or inject the bundled dir into the
   agent's skills settings array when the toggle is on).
3. Gate behind a PiWebSettings flag (e.g. skills.visualExplainer: boolean, default
   false), surfaced as a checkbox in /settings. Toggling reloads resources via the
   existing reload path (/reload / resourceLoader.reload()), and the skill then shows
   up in the skill command list (server.ts ~L1012 getSkills()).

Net: ships with pi-web, discoverable in /settings, off until the user enables it.

Option B — standalone pi package

Publish as an npm/git pi package (pi.skills per docs/packages.md) and document
pi install. Less discoverable from the web UI; doesn't give a built-in /settings toggle.

Skill contents

I can paste the full SKILL.md + assets/references into this issue or a gist for copy-in.
(Per this workspace's contribution rules I'm filing an issue rather than opening a PR.)

Acceptance criteria

• skills/visual-explainer/ is bundled in the published package (files).
• A /settings toggle enables/disables it; default off.
• When enabled, the agent auto-loads it for explanation/design requests and it appears
  in the skill command list; when disabled, it does not load.
• No behavior change for users who leave it off.

Related

• Vend bundled Mermaid to standalone artifacts via /api/vendor/ (offline diagrams) #27 — vend bundled Mermaid to artifacts (offline diagrams)
• Allow scripts in the HTML artifact preview iframe (sandbox="allow-scripts") so diagrams render in-session #28 — allow scripts in the artifact preview iframe (render diagrams in-session)