| name | viz-render |
| description | Render markdown or Mermaid content as formatted HTML in the browser. Triggers when the user asks to view, render, or preview a document as HTML; when the user asks to visualize, diagram, chart, or draw architecture, flows, sequence/class/state/ER diagrams; when resolving plan files from ~/.claude/plans/; or proactively when about to output a table with 4+ rows or 3+ columns, a structured comparison, an audit, a feature matrix, or any formatted content exceeding ~50 lines in the terminal. |
Viz Render Skill
Render markdown documents, Mermaid diagrams, or plan files as formatted HTML
with syntax highlighting, math formulas, Mermaid, scroll animations, and dark
mode. One skill, one script, three input shapes.
When to Use
- User asks to "view as HTML", "render in browser", "preview as a web page"
- User asks for a diagram (flowchart, sequence, architecture, ER, state, …)
- User references a plan by name (resolve from
~/.claude/plans/)
- Content contains complex tables, Mermaid, or math formulas
- Proactive: terminal output would contain a table with 4+ rows or 3+ columns
- Proactive: comparison, audit, feature matrix, or status report as ASCII
- Proactive: conversation output would exceed ~50 lines of structured content
When NOT to Use
- Short content (<20 lines) that renders fine in terminal
- User explicitly wants terminal/text output
- User is asking to edit or modify the content, not view it
- Simple diagrams (2–3 nodes with obvious relationships)
Input Shapes → Workflow
Shape A: file path
User gave an absolute/relative path to a markdown file.
bash "${CLAUDE_PLUGIN_ROOT}/lib/render.sh" "{file_path}" "doc-{name}"
Shape B: plan name (bare name, no path separator, no .md)
List available plans or resolve by name against ~/.claude/plans/:
INPUT="$ARGUMENTS"
PLANS_DIR="$HOME/.claude/plans"
if [ -z "$INPUT" ]; then
echo "Available plans in $PLANS_DIR:"
ls -t "$PLANS_DIR"/*.md 2>/dev/null | head -20 | xargs -n1 basename | sed 's/\.md$//' | sed 's/^/ - /'
elif [ -f "$INPUT" ]; then
DOC_FILE="$INPUT"; DOC_NAME=$(basename "$DOC_FILE" .md)
bash "${CLAUDE_PLUGIN_ROOT}/lib/render.sh" "$DOC_FILE" "doc-$DOC_NAME"
else
DOC_FILE="$PLANS_DIR/$INPUT.md"
[ -f "$DOC_FILE" ] && bash "${CLAUDE_PLUGIN_ROOT}/lib/render.sh" "$DOC_FILE" "doc-$INPUT" \
|| { echo "Plan not found: $INPUT.md"; ls -t "$PLANS_DIR"/*.md 2>/dev/null | head -10 | xargs -n1 basename | sed 's/\.md$//' | sed 's/^/ - /'; }
fi
Shape C: inline content or Mermaid code
Write the content (or Mermaid wrapped in a ```mermaid fence) to a
temp markdown file, then render.
For inline markdown, write to /tmp/viz-doc-{timestamp}.md.
For bare Mermaid code, wrap as:
# {Diagram Title}
```mermaid
{mermaid code}
```
…write to /tmp/viz-diagram-{name}.md, then:
bash "${CLAUDE_PLUGIN_ROOT}/lib/render.sh" "/tmp/viz-diagram-{name}.md" "diagram-{name}"
Generating Mermaid From Scratch
When the user requests a diagram without providing the code:
- Pick a diagram type (see
references/diagram-types.md for syntax)
- Keep it focused: 5–15 nodes, descriptive labels <30 chars, no-space IDs
- If requirements are too broad, suggest splitting into multiple diagrams
Output
The render script prints the output HTML path (under /tmp/viz/{project}/)
and opens it in the default browser. Report the path to the user.
Recipes (interactive HTML artifacts)
If the markdown file starts with frontmatter viz: <recipe>, the render
script swaps the generic viewer for a recipe-specific interactive template.
Recipes treat markdown as the canonical source: the HTML reads from it on
load and exports a roundtrippable markdown back to the clipboard on Export.
Use a recipe when the user wants an output they will iterate on (mark items
as done/wontfix, filter, edit fields), not just read.
Available recipes:
- pr-review — severity-grouped finding cards with status badges,
inline-editable metadata, and severity filters. See
references/recipes/pr-review.md for the markdown structure spec.
Workflow:
- Author the markdown with the recipe's frontmatter and structure.
bash "${CLAUDE_PLUGIN_ROOT}/lib/render.sh" <file.md> <output-name>- User edits in HTML → clicks Export → updated markdown is on clipboard.
- User pastes back to chat → agent overwrites the source
.md → re-render.
Markdown without viz: frontmatter falls through to the generic viewer
unchanged.
The recipe Save endpoint listens on port 18090 by default. If that port is
held by another process, render.sh auto-selects the next free port (trying
up to 5 candidates) so the recipe still opens over http:// — no manual
override needed. Set VIZ_PORT=<port> only to pin a specific base port.
Recipe Round-trip Monitoring
A recipe's "儲存" button writes the edited markdown back to the source .md
via the viz server (/api/save), but nothing wakes you to read it — the
user otherwise has to come back to chat and tell you, or click 複製 and paste.
To close the loop automatically, arm a Monitor on the source file right
after rendering: the user edits, clicks 儲存, the file's mtime changes, and
the Monitor wakes you to read it back — no copy-paste, no "I'm done" ping.
Prerequisite: the recipe must open on http://127.0.0.1:<port>/... (the
URL render.sh prints). If render.sh fell back to file:// (server
unavailable — all candidate ports held), the 儲存 button is hidden and
monitoring is useless; tell the user to use 複製/Export instead.
After a successful recipe render, note the absolute source path (the path
you passed to render.sh — for plan-name inputs it is
~/.claude/plans/<name>.md), then arm the Monitor:
Monitor:
description: recipe edits on <source-path>
timeout_ms: 300000
command: |
f="<source-path>"; prev=$(stat -f %m "$f" 2>/dev/null || echo 0); idle=0
while true; do
sleep 1
cur=$(stat -f %m "$f" 2>/dev/null || echo 0)
if [ "$cur" != "$prev" ]; then
echo "recipe-saved: $f mtime=$cur"; prev="$cur"; idle=0
else
idle=$((idle + 1))
[ "$idle" -ge 120 ] && { echo "recipe-watch-idle: $f — say resume-watch to restart"; exit 0; }
fi
done
recipe-saved event: Read the source file, diff against what you
last knew, and report the updated content to the user. They need not type
anything.recipe-watch-idle (120s no change) or Monitor timeout (300s): tell
the user monitoring stopped. Restart = re-arm the same Monitor on the
same source path, on an explicit "resume watch" from the user. Do not
auto-restart indefinitely — idle usually means they stopped editing.
stat -f %m is macOS; viz targets macOS (open, stat -f).
References
