playbooks

home / skills / yousufjoyian / claude-skills / vizit

vizit skill

/vizit

This skill visualizes complex explanations in the Vizit panel to help users understand concepts, proposals, or architectures clearly.

npx playbooks add skill yousufjoyian/claude-skills --skill vizit

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
6.8 KB
---
name: vizit
description: Visualize what we're discussing in the Vizit panel to help the user understand
---

# Vizit Skill

Generate a **visual explanation** in the Vizit (A2UI) panel. The user is asking you to help them **understand** something they don't fully grasp — a concept you explained, a proposal you're making, an architecture you described, or a problem they're facing.

**This is NOT a status report or session summary.** The user is saying: **"I don't understand what you just said. Show me visually."**

## Trigger Phrases

- "vizit", "vizit this", "show me in vizit"
- "help me understand", "I don't get it", "visualize this"
- "show me what you mean", "draw it out"

## HARD RULE: Every Vizit MUST End With Copyable Markdown

**NO EXCEPTIONS.** Every single Vizit visualization MUST include a copyable markdown handoff block at the bottom. This is how the user shares context with other AI agents.

If your Vizit output does not have a `<textarea readonly>` block containing a full markdown summary at the bottom, **you have failed the skill**. Go back and add it.

The markdown must be a **complete, self-contained summary** — not a stub. Another AI agent reading ONLY this markdown should fully understand what was visualized.

---

## Core Principle

**Clarify, don't summarize.** The user triggered this because they don't understand something. Your job:

1. **Identify what confused them** — what did you just explain that wasn't clear?
2. **Pick the right visual** — diagrams beat text, flows beat lists, comparisons beat paragraphs
3. **Make it obvious** — if someone glanced at this for 5 seconds, they should get the main idea

## What to Visualize

Look at the **most recent discussion** and identify what needs visual explanation:

| The user is confused about... | Visualization approach |
|---|---|
| How components connect | Architecture diagram with labeled arrows |
| What sequence of steps happens | Numbered flow with descriptions |
| A decision you're proposing | Side-by-side comparison cards (pros/cons) |
| How code works | Annotated pseudo-code or data flow |
| What changed and why | Before/After panels |
| A plan you're proposing | Step-by-step tracker with context per step |
| Relationships between things | Tree, graph, or connection diagram |
| Data or numbers | Chart, gauge, or dashboard |

## Execution Steps

### Step 1: Identify the Confusion Point

Read the last few exchanges. What did the user NOT understand? What did you explain in text that would be clearer as a visual? Be specific — don't visualize everything, visualize the **one thing** that needs clarity.

### Step 2: Get A2UI Log Path

Discover the active terminal's A2UI log path:
```bash
python3 << 'PY'
import json, urllib.request
data = json.loads(urllib.request.urlopen("http://localhost:7690/api/projects").read())
active_proj_id = data.get('activeProjectId')
for p in data.get('projects', []):
    if p.get('id') == active_proj_id:
        term_id = p.get('activeTerminalId')
        for t in p.get('terminals', []):
            if t.get('id') == term_id:
                print(f"/home/yousuf/GoogleDrive/PROJECTS/.triclaude/runtime/terminals/{term_id}/a2ui_input.log")
PY
```

### Step 3: Generate the Visualization

Write HTML to the A2UI log. Rules:

- **Dark theme**: `#0f172a` body, `#1e293b` cards, `#e2e8f0` text
- **Self-contained**: All CSS inline or in `<style>`, no external deps (CDN JS OK for charts)
- **~400px panel width**: Design for narrow panel
- **Padding bottom**: `padding-bottom: 140px` to clear ShortcutBar
- **Visual-first**: The main content should be a diagram, flow, or visual — NOT a wall of text
- **Annotations**: Use callouts, arrows, highlights to draw attention to key parts
- **Interactive OK**: Tabs, toggles, hover effects if they help understanding
- **MANDATORY handoff markdown**: Include a copyable markdown section near the bottom of the visualization so the user can paste it into other AI agents for follow-up discussion

```bash
cat << 'A2UI_EOF' >> $A2UI_LOG
<!-- A2UI:START -->
<!DOCTYPE html>
<html>
<head>
<style>
*{margin:0;padding:0;box-sizing:border-box}
body{background:#0f172a;color:#e2e8f0;font-family:system-ui;font-size:13px;padding:16px;padding-bottom:140px;line-height:1.5}
/* your styles */
</style>
</head>
<body>

<!-- VISUAL EXPLANATION HERE -->
<!-- Pick the right layout for the concept -->

<!-- REQUIRED: COPYABLE MARKDOWN HANDOFF (near bottom) -->
<section style="margin-top:16px;background:#111827;border:1px solid #334155;border-radius:10px;padding:10px">
  <div style="font-size:11px;font-weight:700;color:#93c5fd;margin-bottom:6px;letter-spacing:.04em;text-transform:uppercase">Copy Markdown For Other Agents</div>
  <p style="font-size:11px;color:#93a0b4;margin-bottom:8px">Use this to continue the discussion in another AI tool.</p>
  <textarea readonly style="width:100%;min-height:180px;background:#0b1220;color:#e2e8f0;border:1px solid #334155;border-radius:8px;padding:10px;font:12px/1.45 ui-monospace,Menlo,Consolas,monospace;resize:vertical"># Visualization Title

## What This Shows
- Point 1
- Point 2

## Structure / Flow
1. Step 1
2. Step 2

## Key Takeaway
One-sentence conclusion for another agent.
</textarea>
</section>

</body>
</html>
<!-- A2UI:END -->
A2UI_EOF
```

### Step 4: VERIFY Markdown Block Exists

Before moving on, re-read what you just wrote. Does it contain a `<textarea readonly>` with full markdown? If not, **stop and add it now**.

The markdown inside the textarea must:
- Have a descriptive title
- Summarize everything shown in the visual (tables, flows, verdicts, data)
- Be useful standalone — another agent who never saw the visual should understand the full picture
- Be at least 15 lines (no stubs)

### Step 5: Tell the User

After writing the visualization, tell the user to check the **Vizit** tab, briefly explain what the visual shows, and mention that a **copyable markdown handoff block** is included near the bottom.

## Design Tokens

| Element | Color |
|---------|-------|
| Body bg | `#0f172a` |
| Card bg | `#1e293b` |
| Border | `#334155` |
| Text primary | `#f8fafc` |
| Text body | `#e2e8f0` |
| Text muted | `#94a3b8` |
| Text dim | `#64748b` |
| Blue | `#3b82f6` |
| Green | `#22c55e` |
| Amber | `#f59e0b` |
| Red | `#ef4444` |
| Purple | `#8b5cf6` |

## What NOT to Do

- Don't generate a session status report — that's not what vizit is for
- Don't dump text in cards — use actual visual elements (arrows, flows, diagrams)
- Don't use a fixed template every time — pick the RIGHT visual for the concept
- Don't visualize things that are already clear — focus on the confusion point
- Don't include a save button — this is ephemeral understanding aid, not a saved artifact
- **NEVER omit the markdown handoff block** — this is the #1 most common mistake. If you skip it, the user will have to ask again. Every. Single. Vizit. Must. Have. It.

Overview

This skill creates concise visual explanations in the Vizit (A2UI) panel to help users understand a concept, architecture, flow, or decision they found confusing. It produces a focused, visual-first diagram or annotated flow and always includes a copyable markdown handoff block so other agents can consume the result. The visuals are optimized for a narrow dark-themed panel and emphasize clarity over verbosity.

How this skill works

When you trigger the skill (phrases like “vizit”, “show me in vizit”, or “I don't get it”), the skill inspects the last few exchanges to identify the single point of confusion. It selects an appropriate visual format (architecture diagram, numbered flow, comparison cards, before/after) and writes self-contained HTML+CSS to the A2UI log using the specified dark theme and layout. Every output ends with a required <textarea readonly> containing a complete markdown summary so other agents can continue the conversation.

When to use it

  • When the user says “I don't understand” or asks to “visualize this” after a text explanation
  • To show how components connect in an architecture or system
  • To illustrate a sequence of steps, data flow, or lifecycle
  • To compare options or clarify a proposed decision visually
  • To hand off a clear, copyable summary to another AI agent

Best practices

  • Visualize only the one thing the user found confusing — avoid full summaries
  • Pick a diagram type that makes the relationship obvious at a glance (arrows, numbered steps, side-by-side cards)
  • Design for ~400px panel width with dark theme and ample bottom padding for the ShortcutBar
  • Include concise callouts and labels; minimize body text on the canvas
  • Always include the mandatory copyable markdown handoff near the bottom

Example use cases

  • Draw an annotated architecture diagram to show how services communicate and where a bug occurs
  • Show a numbered flow for a request lifecycle so the user sees the sequence and timing
  • Create a side-by-side pros/cons card to clarify a proposed design choice
  • Render before/after panels to explain a refactor or migration impact
  • Produce an annotated pseudo-code/data-flow diagram when the user is confused about code behavior

FAQ

What exactly appears in the markdown handoff?

A self-contained, multi-line markdown summary: title, what the visual shows, a step-by-step structure or diagram notes, key takeaways, and any decisive recommendation so another agent can act on it.

Can the visualization be interactive?

Yes—simple interactivity (tabs, hover highlights) is allowed if it helps clarify the point, but all assets must be embedded with inline CSS and the panel-sized layout respected.