Visual Explainer Skill

visual-explainer teaches Codex, Claude Code, and other IDE agents to explain with the right visual artifact by default: Mermaid diagrams, real screenshots/images, generated GPT images, Ian/Xiaohei-style conceptual illustrations, compact tables, or plain prose when a visual would be noise.

This skill comes from Ojima's explicit rule: use images, Mermaid diagrams, screenshots, tables/cards, and similar scannable formats when they help understanding happen faster. The correction that matters is enforcement: memory alone made this a preference; this skill makes it an operating workflow.

Visual Rules

The core rule is:

Do not make the user imagine something that can be shown.

That does not mean "always use Mermaid." It means choose the clearest representation of the thing being explained.

Situation	Best visual source	Why
Architecture, workflows, queues, state machines, dependencies, approvals, ranking/scoring, event/data flow	Mermaid	Shows structure and motion without inventing a fake picture.
Existing products, hardware, places, people, public artifacts, company UI, source examples	Real images or screenshots	The real thing is more truthful than a generated substitute.
Local UI/app behavior, before/after state, runtime evidence	Browser, simulator, or local screenshots	Grounds the explanation in what is actually happening.
Imagined, speculative, creative, or conceptual material	GPT image generation	Creates a new visual when no real image exists yet.
Abstract ideas that need a sticky metaphor	Ian/Xiaohei-style generated illustration	Makes fuzzy concepts memorable without turning them into corporate slides.
Comparisons, tradeoffs, checklists, bug evidence, implementation status	Tables or compact cards	Keeps dense information scannable.
Tiny answers	Plain prose	Avoids adding visual friction.

How Ojima Defined It

The original request was to explain things with images and Mermaid diagrams where images would help understanding happen faster. The later correction was sharper: the rule was saved to memory, but it was not being applied. This skill exists so agents proactively choose and include visuals in eligible explanations, rather than asking after the fact or defaulting back to prose.

The refined rule is:

• Use Mermaid for logic and structure.
• Use real fetched images or screenshots when the thing already exists.
• Use generated images for creative, speculative, or conceptual material.
• Use local screenshots for app behavior.
• Use tables/cards for comparisons and evidence.
• Do not force visuals into tiny answers.
• Do not default to Mermaid when another visual source would be clearer.

Ian/Xiaohei Mode

This skill also folds in the installed tojileon/ian-xiaohei-illustrations-en workflow.

Use Ian/Xiaohei mode when a conceptual explanation benefits from a memorable article-style metaphor. The default image style is:

• 16:9 horizontal illustration.
• Pure white background.
• Black hand-drawn line art.
• Lots of empty space.
• Sparse red/orange/blue handwritten English annotations.
• Xiaohei as the core action subject: a black solid little creature with white dot eyes, thin legs or arms, and a blank serious expression.
• Dry, weird, clean, product-sketch energy.

Avoid:

• PPT infographic look.
• Formal flowchart.
• Commercial illustration.
• Cute children's cartoon.
• Complex architecture diagram.
• Polished flat-vector style.
• Top-left title text.
• Too many labels.
• Xiaohei as a decorative mascot.

Decision Flow

flowchart TD
  A["Will a visual reduce cognitive load?"] -->|No| B["Use concise prose"]
  A -->|Yes| C{"What needs to be shown?"}
  C -->|"Structure or motion"| D["Mermaid"]
  C -->|"Existing thing"| E["Real image or screenshot"]
  C -->|"Local UI/runtime state"| F["Local screenshot/artifact"]
  C -->|"Creative or imagined concept"| G["Generated GPT image"]
  C -->|"Sticky conceptual metaphor"| H["Ian/Xiaohei illustration"]
  C -->|"Comparison or evidence"| I["Table/cards"]

Loading

Example Uses

Use $visual-explainer to explain this architecture change.

Use $visual-explainer to teach me how this ranking pipeline works. Include visuals where they help.

Use $visual-explainer and make a Xiaohei-style conceptual image for this product idea.

Use $visual-explainer to explain this bug with evidence and a diagram.

Install

Clone the public repo, then install the skill folder under the canonical skill name:

git clone https://github.com/uncoooloj/visual-explainer-skill.git
mkdir -p ~/.codex/skills/visual-explainer
cp -R visual-explainer-skill/visual-explainer/SKILL.md visual-explainer-skill/visual-explainer/agents ~/.codex/skills/visual-explainer/

The repository uses the public -skill suffix. The installed skill name stays clean: visual-explainer.

Package Shape

• Repository: visual-explainer-skill
• Skill folder: visual-explainer
• Skill name: visual-explainer

Files

• visual-explainer/SKILL.md - runtime instructions for agents
• visual-explainer/agents/openai.yaml - Codex UI metadata

License

No license has been selected yet.