explain-visually

Files (5)

• SKILL.md
• brand_defaults.md
• modality_guide.md
• render_html_to_png.py · scripts/
• style_library.md

SKILL.md (first lines)

# Explain Visually

> ℹ️ **First, set expectations:** before anything else, print one short line with this skill's version and its most recent change - the top entry of `metadata.changelog` above - e.g. `explain-visually vX.Y - recent: <summary>`. Then proceed.

## Purpose

Explain a topic back to the reader **with the right picture for each part of it**. Where `/one-pager` distills text into a dense page and a diagram skill builds ONE brand-locked diagram for posting, this skill is a **comprehension tool**: it breaks a topic into the facets that most need to be *seen*, chooses the best **visual modality** per facet (flowchart, timeline, sequence, schema/ER, state machine, chart, comparison, mind map, or a conceptual illustration), renders each one in a **style you control**, and bundles the set onto a single page so you grasp the whole thing at once.

Two properties define it:

1. **Self-contained, no research.** It explains **what was already discussed or provided** - the current conversation, a paste, or a file. It does NOT browse, query knowledge bases, or pull external facts. If the discussion didn't establish a fact a visual needs, it marks `[NEEDS: ...]` and asks - it never invents.
2. **Style is a dial.** The locked brand is the *default* (`brand-dark`), but you can switch the whole visual language (`clean-light`, `blueprint`, `whiteboard`, or a `custom` brief). Every diagram in a run shares the chosen style.

The deliverable is a **single bundled page (+ PDF)** assembled by `/one-pager`, plus the individual visual PNGs kept for reuse.

## When to use

**Right tool when:**
- "Explain this to me visually" / "show me how this works" / "diagram what we just discussed" / "make this make sense"
- The topic has **internal structure worth seeing** - a process, a sequence, a system, an evolution, a set of trade-offs
- You want **several complementary visuals** (not one), each picked for what it shows best
- You want to **control the look** rather than accept the locked brand

**Wrong tool when:**
- You need ONE brand-locked diagram to **post** -> a diagram skill
- You need a multi-slide **deck** -> `/presentation`
- You need a dense **text** brief (mostly prose/stats, few diagrams) -> `/one-pager` directly
- A single generative infographic is enough -> `/create-explanatory-image`
- You need it to **research** a topic it doesn't already have material on -> this skill refuses; gather the material first (it is self-contained by design)

## What makes this distinct

| Approach | Trade-off |
|----------|-----------|
| a diagram skill | ONE human-composed diagram, brand-locked, for posting. No modality selection, no style control, single artifact. |
| `/create-explanatory-image` | ONE generative image, iterates to correctness. Great for a metaphor; not multi-modal, not assembled. |
| `/one-pager` | Dense single page from a brief - text-first. This skill is its **visual front-end**: it produces the *pictures*, then hands them to `/one-pager`. |
| **`/explain-visually` (this skill)** | Decomposes a topic into facets, picks the **right visual per facet**, renders in a **style you control**, bundles to one page. Mostly free (Mermaid); only conceptual-illustration facets cost ~USD 0.067 each. ~1-3 min. |

## State Dependencies

| Source | Location | Purpose |
|--------|----------|---------|
| Modality guide | `modality_guide.md` | Facet -> visual modality -> engine; per-modality Mermaid templates; node budget - read every time |
| Style library | `style_library.md` | The 4 styles + custom: Mermaid theme vars, render-wrapper HTML, illustration prompt fragment, `/one-pager` theme mapping - read every time |
| Brand defaults | `brand_defaults.md` (this skill) | Read **only when `--style brand-dark`** - **§0 first** (swappable defaults; the workspace's own design doc wins). Exact palette/fonts the brand-dark preset cites |
| Render script | `scripts/render_html_to_png.py` | Themed Mermaid HTML -> PNG via Playwright |

## Prerequisites & cold start

Script paths in this file are relative to **this skill's directory** — run them from there,
or prefix with the directory the skill was injected into.

| Requirement | Needed for | Missing → |
|---|---|---|
| `python3` + Playwright/Chromium | rendering every Mermaid visual | Report the install command (`pip install playwright && playwright install chromium`); **do not claim visuals that were never rendered**. |
| Network access at render time | Mermaid + Google Fonts load via CDN | See `style_library.md` for offline vendoring; without either, the render fails visibly rather than silently producing an unstyled diagram. |
| `GEMINI_API_KEY` (fallback `GOOGLE_API_KEY`) | conceptual-illustration facets only | Not fatal — proceed as if `--no-illustrations` was passed and say so in the delivery report. Held by the `/create-explanatory-image` child skill, which fails naming the key. Pure-Mermaid runs cost USD 0. |

## Headless mode (`--autonomous`)

This skill is **callable as one line** by a schedule, an orchestrator, or another agent
(the fleet's playbook-call convention). Invoked that way there is nobody to answer a gate,
so `--autonomous` must be passed and both gates are skipped. In that mode:

- The self-contained rule hardens: with no operator to ask, a bare topic with no material
  behind it is a **failed run** — report it and produce nothing. It is never a licence to
  research or to fill the topic from general knowledge.
- `[NEEDS:]` gaps are dropped from the visual and listed in the final report, never guessed.
- The style preset must be passed explicitly or the default applies; nothing else changes.

## Inputs

```
/explain-visually [source] [--style brand-dark|clean-light|blueprint|whiteboard|custom] [--format 16:9|a4|letter] [--max-visuals N] [--no-illustrations] [--autonomous] [--output-dir PATH]
```

| Flag | Default | Description |
|------|---------|-------------|
| `source` | (the conversation) | **What to explain.** If omitted, it explains **what was just discussed** (the current conversation + any material already in context). Can also be a topic we covered, a paste, or a file path. NEVER triggers research - if there's no substance to explain, it halts and asks. |
| `--style` | `brand-dark` | Visual language for ALL diagrams this run. See `style_library.md`. `custom` -> you describe the look and it maps to theme vars. |
| `--format` | `16:9` | Final bundled-page format (passed to `/one-pager`): `16:9` screen, `a4`/`letter` print. |
| `--max-visuals` | `5` | Cap on visuals (facets). The decomposition keeps the highest-signal facets up to this cap. |
| `--no-illustrations` | (off) | Mermaid/structural diagrams only - skip all `/create-explanatory-image` facets. free, faster, fully deterministic. |
| `--autonomous` | (off) | Headless mode for scheduled/unattended runs: skip both approval gates. See Headless mode above. |
| `--output-dir` | `explain_{slug}/` | Where `visuals/`, the HTML sources, and the final PDF land. Relative to the working directory unless given absolutely. |

### Content model (LOCKED): explain, don't research; structure, don't fabricate

- The skill's job is to **re-present material that already exists** in the discussion/source as visuals. The *structure* and *teaching framing* are the skill's synthesis - that's expected and good.
- **Facts, numbers, names, and claims must come from the source/discussion.** If a visual needs a specific fact the discussion never established, leave a `[NEEDS: ...]` marker and surface it at Gate 1. Do not guess, and do not reach for outside knowledge to fill it.
- If the source is a bare topic with no substance behind it ("explain quantum gravity") and nothing was discussed, **halt** and ask what material to explain. This skill does not research.

## Composes

- `/one-pager` - bundles the rendered visuals into the single page + PDF (the deliverable). Always invoked.
- `/create-explanatory-image` - renders any **conceptual-illustration** facet (a metaphor / rich visual that no structural diagram captures). Invoked per such facet unless `--no-illustrations`.

Called by their **unversioned** names so child fixes propagate. Structural diagrams are rendered in-skill (themed Mermaid -> `render_html_to_png.py`); Mermaid is a tool, not a skill, so it is used directly.

## Process (transactional)

ultrathink - the load-bearing reasoning here is **decomposition + modality matching** (Step 2): choosing *which* facets of the topic to show and the *right* visual type for each is what makes the explanation land. Reason carefully about what the reader actually needs to see before picking diagrams, and confirm at Gate 1 before spending any render time.

### Step 1: Read state

1. Read `modality_guide.md` (facet -> modality -> engine; Mermaid templates; node budget).
2. Read `style_library.md` (the styles, render wrapper, theme mapping).
3. If `--style brand-dark`, also read `brand_defaults.md` (§0 override first) for the exact palette/fonts the preset cites.

### Step 1.5: Resolve flags + identify the source

- Resolve `--style` (default `brand-dark`), `--format`, `--max-visuals`, `--no-illustrations`. Derive a `{slug}`; set `--output-dir` to `{output-dir}/`.
- Identify the source: by default it is **what was discussed before** (the current conversation + material already in context). If a paste/topic/file is given, use that instead.
- If `--style custom`, ask the user for a one-paragraph style brief (background, line/text color, accent, font feel, mood) before proceeding.
- If there is no real substance to explain, **halt** and ask for the material. Do not research.

### Step 2: Decompose the topic into visual facets

From Abilityai/trinity-skills, Apache-2.0.

More from Abilityai/trinity-skills