Show-Me Visual Explainer Skill

The useful idea inside the show-me Skill is not “make an infographic.” It is a routing decision: identify the relationship a reader needs to see, then choose the smallest visual that makes that relationship clear. This downloadable Codex adaptation adds evidence labels, content-idea and tool-workflow modes, accessibility requirements, and a review gate for screenshot-ready HTML.

Why this idea belongs in a Skill

A Learn article can explain why visual structure helps. A Prompt can ask for one diagram. The repeated decision here is more operational: on every invocation, inspect the current topic, decide whether a visual is warranted, select the appropriate form, preserve evidence boundaries, and return the result in the user's current context. That is exactly the kind of reusable routing procedure a Skill can hold.

HumanLayer's official launch article frames show-me as a response to coding agents that bury useful structure in walls of prose. It emphasizes program design before implementation and using compact visuals to inspect large diffs. The checked upstream package is intentionally small: its single SKILL.md tells an agent to keep prose brief, select the smallest useful view, and choose among pseudocode, call trees, component or file trees, Mermaid, diffs, complete code blocks, and focused HTML artifacts. It does not include a script, template, evidence model, or dedicated accessibility guide. Its strength is the selection principle, not a large toolchain.

This adaptation keeps that principle but makes the release useful for more than code discussions. It adds explicit routes for content angles, AI concepts, tool workflows, measured charts, and screenshot-ready artifacts. It also introduces a hard distinction that polished visuals often blur: the diagram arranges what you know; it does not make an unsupported connection true.

The four creator jobs become four visual questions

The format is a consequence of the question. An impact map is better than a timeline when the interesting point is who may be affected. A sequence diagram is better than a component tree when timing and handoffs matter. A diff is better than a fresh architecture map when the reader already knows the old shape and needs to see what changed.

Use relationship-first routing

1. Name the visual question. “Explain RAG” is a topic. “Where does retrieved context enter generation?” is a question that can be drawn.
2. Extract evidence atoms. Keep only the actors, states, inputs, transformations, outputs, and uncertainties required for that question.
3. Choose one dominant relationship. Logic, hierarchy, sequence, state change, comparison, magnitude, spatial layout, or impact each has a more natural visual form.
4. Draw the main path first. Add branches only when they change the reader's decision. If an arrow has no clear verb, the relationship is probably still vague.
5. Mark the boundary. Distinguish supplied or verified facts from inference, hypothesis, and unknowns. Keep dates, units, source IDs, versions, and file paths next to the claims they constrain.
6. Review at reading size. Remove detail rather than shrinking labels. Confirm the text equivalent, mobile behavior, and every value before sharing.

Turn an update into an angle without inventing a trend

The content-idea route begins with an event that can be checked: a release note, product page change, filing, official announcement, or observed interface state. It then identifies affected actors and possible consequences. That middle step is where weak content often converts possibility into fact. The Skill therefore uses a solid connector for a supported transition and a dashed connector for a hypothesis that still needs evidence.

In the synthetic example, a hypothetical tool adds source-linked answers. The verified layer should capture the exact release claim, date, version, availability, and limits. “Searchers may reach a first answer faster” is not copied into the fact layer merely because it sounds plausible. It remains a hypothesis. That hypothesis can still produce a useful content angle: test how the path changes, document a verification workflow, or compare source-linked and link-first research. The resulting angle is framed as a question to investigate, not a conclusion already established.

This structure is especially useful for fast-moving AI coverage because it prevents three common substitutions: announcement for capability, capability for adoption, and adoption for outcome. A polished map cannot establish any of those transitions without evidence.

Show the moving thing in AI concepts

Agent, RAG, and MCP explanations become easier when the diagram names what actually moves. A system may move a user request, retrieved document chunks, a structured tool call, an approval decision, a tool result, and a final message. Labeling every arrow “data” hides the mechanism.

question
  → retrieve against a source index
  → select context
  → generate a draft with that context
  → return an answer with source links

Boundary: retrieval selects evidence; generation writes the answer.
Unknown: whether each linked source supports the adjacent claim.

The final boundary is more valuable than another box. Retrieval does not make generation infallible. A protocol does not contain the remote system behind it. A model's decision to request a tool call is not the same as the tool successfully completing the action. A good diagram makes those distinctions visible before the reader learns more terminology.

Map the complete tool workflow, including the gate

A feature list says what a tool can expose. A workflow says what a person must do and where work can stop. Start with the actual input, then show required configuration, action, intermediate result, verification, and usable output. Add account, plan, permission, payment, review, or publication gates only where they really occur.

Use $show-me-visual-explainer to map this AI tool workflow.
Show the path from source input and required configuration to the
generated result, human verification, and usable output. Mark any
account, plan, permission, or publication gate. Distinguish what the
documentation confirms from what we have not tested.

That final distinction matters. “The tool generated a file” is not “the file was checked.” “The preview looked right” is not “the exported artifact preserved it.” “A draft exists” is not “someone approved or published it.” The Skill is designed to display those state changes instead of collapsing them into a smooth success arrow.

When focused HTML earns its extra weight

Inline text, a tree, a table, or Mermaid source is usually enough. HTML becomes justified when placement carries meaning, the result must work as a shareable screenshot, responsive behavior matters, or the concept is too dense for an inline renderer. The included HTML reference requires one self-contained file with semantic headings, live text, system fonts, responsive layout, restrained colors, and no remote scripts, fonts, trackers, or analytics by default.

The static first frame must remain understandable. Interaction is optional and should serve comparison, filtering, or progressive disclosure rather than decoration. Essential information cannot depend on animation, hover, or color alone. W3C guidance also requires text alternatives that convey the purpose and information of complex charts and diagrams; a pretty screenshot with an empty or generic alt attribute is not a complete deliverable.

If the destination supports Mermaid, its diagram type declaration lets the renderer parse different structures such as flowcharts, sequence diagrams, state diagrams, timelines, and mind maps. That breadth is useful, but it does not remove the routing decision. Selecting a sophisticated syntax before identifying the relationship usually creates a sophisticated wrong answer.

What the downloadable package adds

• SKILL.md defines the trigger, relationship-first routing, evidence boundary, inline-first default, artifact permission boundary, and compact output contract.
• references/visual-selector.md maps eleven relationship types to useful forms and adds dedicated content-idea, technical-concept, and tool-workflow guidance.
• references/focused-html.md defines a self-contained, responsive, accessible HTML artifact and a six-part review pass.
• agents/openai.yaml supplies optional display metadata and an explicit starter prompt.
• THIRD_PARTY_NOTICES.md identifies the pinned HumanLayer inspiration and its MIT license without bundling the upstream package.

This is an independently authored adaptation, not a mirror. If you want HumanLayer's exact original behavior or its npx skills add route, review and install the authoritative repository. If you want the evidence-aware Codex routing described here, use the Grow AI Skills download.

Install it at the scope you actually need

OpenAI's current documentation says Codex loads repository skills from .agents/skills directories between the working directory and repository root, and user skills from $HOME/.agents/skills. Use repository scope when the visual language belongs to one codebase or team. Use user scope when you want the same method across projects.

mkdir -p .agents/skills
unzip -q show-me-visual-explainer-skill-v1-0.zip -d .agents/skills

skill_destination="${HOME}/.agents/skills"
mkdir -p "$skill_destination"
unzip -q show-me-visual-explainer-skill-v1-0.zip -d "$skill_destination"

New-Item -ItemType Directory -Force -Path '.agents\skills' | Out-Null
Expand-Archive -Path '.\show-me-visual-explainer-skill-v1-0.zip' -DestinationPath '.agents\skills' -Force

Confirm the final entrypoint at .agents/skills/show-me-visual-explainer/SKILL.md. Codex normally detects a new Skill automatically; restart if it does not appear. Use /skills or type $show-me-visual-explainer to invoke it explicitly.

Start with these three requests

Use $show-me-visual-explainer to turn this release note into an
impact map. Separate verified facts, possible effects, open questions,
and three content angles. Do not invent adoption or performance data.

Use $show-me-visual-explainer to show the data flow and control flow
in this RAG system. Label what moves on every arrow, show where
retrieval ends and generation begins, and mark any unverified link.

Use $show-me-visual-explainer to create one self-contained HTML
infographic for a non-technical audience. Use only the supplied facts,
keep the main relationship readable in one desktop screenshot, add a
mobile layout and text equivalent, inspect it, and open the file for me.

Read the verification label correctly

The downloadable folder passed the bundled Skill Creator structural validator: its name and frontmatter are valid, referenced files exist, interface metadata is present, and no scaffold placeholder remains. We also used the same routing and evidence rules to design the two original diagrams on this page and inspected both 1600×1000 PNG renders at full size.

The repository page displayed about 3.4k stars when checked, but that number establishes interest rather than effectiveness. The supplied X post describes five days of personal use in four creator scenarios. Direct retrieval returned HTTP 403, so the account is treated as supplied commentary rather than an independently reproduced test.

The structural review is not an independent behavior test. We did not run the Skill in a separate model session, test automatic invocation, compare it with the upstream package, measure time saved, ask users to interpret the diagrams, or reproduce it on another host. The release is therefore labeled Structure Checked, not Behavior Tested. The honest next step is a small blind evaluation set covering content angles, an AI concept, a tool workflow, a misleading numeric request, and a case where no visual is needed.

Use it when the relationship is the hard part

This Skill is strongest when the source material is available but its structure is hidden: a release contains several affected actors, a system description mixes data and control, a tool tutorial hides review gates, or a change is easier to understand as a diff. It is weak when the task is decorative illustration, photo editing, unsupported data visualization, or a simple fact that one sentence already explains.

Bottom line: the show-me idea earns a Skill page because the reusable value is a decision loop, not a magic prompt. Name the question, select the relationship, choose the smallest form, preserve the evidence boundary, and stop before clarity turns into decoration.