Visual Explain
Designvisual-explainVisual Explain is an Agent Skill for design published in the egregore-labs/egregore repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Explain concepts visually using ASCII diagrams, flow charts, tables, and structural maps. Use when asked to explain, compare, or show how something works.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/egregore-labs/egregore/blob/HEAD/.claude/skills/visual-explain/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/visual-explain, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Visual Explain
Explain concepts visually using ASCII diagrams, tables, flow charts, and structural maps. The visual IS the explanation — prose is secondary.
When to invoke
Trigger phrases: "explain visually", "show me a diagram", "draw this out", "chart this", "map this", "visualize this", "show me how this works", "diagram this", "sketch this out".
Also invoke when /visual-explain is used directly.
Visual vocabulary
Use the right format for the right job:
| Concept type | Visual format |
|---|---|
| Flows and pipelines | ASCII arrow diagrams (→, ↓, ──▶) |
| Architecture / components | Box diagrams with labeled connections |
| Comparisons and trade-offs | Tables with columns per option |
| Hierarchies and containment | Tree structures or nested box diagrams |
| Temporal sequences | ASCII sequence diagrams (actor columns + arrows) |
| State changes | Before/after side-by-side diagrams |
| Decision logic | Flowcharts with diamond decision nodes |
Rules
-
Lead with the visual. Always produce the diagram or table FIRST. Prose comes after, if needed at all.
-
Minimal prose. Keep explanatory text to 1-2 sentences per diagram. The visual carries the explanation — prose only clarifies what the visual cannot.
-
Prefer multiple small diagrams over one complex one. Break a system into 2-3 focused visuals rather than cramming everything into a single diagram. Each diagram should have one clear point.
-
Consistent visual language:
[ boxes ]for components, modules, services──▶or→for data flow and control flow───for connections and relationships< diamonds >for decisions( rounded )for inputs/outputs│and─for structure lines
-
System explanations follow this order:
- Structure first (what are the parts, how do they relate)
- Data flow second (what moves between them)
- State changes third (how things evolve over time)
-
Comparisons follow this order:
- Table first (options as columns, criteria as rows)
- Annotate the recommended choice with a brief reason below the table
-
Keep diagrams under 40 lines tall and 72 characters wide. If a diagram exceeds this, split it into multiple diagrams with clear labels.
Examples
Flow diagram
[ User Request ]
│
▼
[ Auth Middleware ] ──▶ [ 401 Unauthorized ]
│
▼
[ Route Handler ]
│
┌────┴────┐
▼ ▼
[ Cache ] [ Database ]
│ │
└────┬────┘
▼
[ Response ]
Comparison table
Option A Option B Option C
──────────────────────────────────────────────────────────
Speed Fast Medium Slow
Cost $$$ $$ $
Complexity High Medium Low
Reliability High High Medium
──────────────────────────────────────────────────────────
✓ Recommended: Option B — best balance of cost and speed.
Sequence diagram
Client Server Database
│ │ │
│── POST /api ──▶│ │
│ │── INSERT ─────▶│
│ │◀── OK ─────────│
│◀── 201 ────────│ │
│ │ │
Hierarchy / tree
egregore/
├── bin/ Shell scripts (graph, notify, telemetry)
├── skills/ Cognitive skill definitions
│ ├── harvest/
│ └── tui-design/
├── memory/ Symlink → shared memory repo
│ ├── people/
│ ├── handoffs/
│ └── knowledge/
└── .claude/
├── commands/ Slash command definitions
└── skills/ Claude Code skill files
Before/after
BEFORE AFTER
┌──────────────────┐ ┌──────────────────┐
│ Monolith │ │ API Gateway │
│ ┌────────────┐ │ │ │
│ │ Auth │ │ └─────────┬─────────┘
│ │ API │ │ │
│ │ DB │ │ ┌───────┼───────┐
│ │ Queue │ │ ▼ ▼ ▼
│ └────────────┘ │ [ Auth ] [ API ] [ Worker ]
└──────────────────┘ │ │ │
└───┬───┘ │
▼ ▼
[ DB ] [ Queue ]