How the Show-Me Skill Decides Between Mermaid Diagrams, ASCII Sketches, and HTML Artifacts

The show‑me skill selects output formats by choosing the smallest visual representation that conveys the essential point, defaulting to ASCII for hierarchies, Mermaid for relationships, diff blocks for changes, and focused HTML only when UI density requires it.

The show‑me skill in the humanlayer/skills repository generates visual aids that "make the key point clear" while maintaining extreme minimalism. According to the specification in plugins/show-me/skills/show-me/SKILL.md, the skill follows a strict two-tier hierarchy to determine whether to emit ASCII sketches, Mermaid diagrams, diff blocks, or focused HTML artifacts based on the nature of the information requested.

The Decision Hierarchy in show-me

The skill’s decision-making logic is codified in lines 3–9 of the SKILL.md specification, which establishes a "scope-first, prose-second" approach followed by a minimalism filter.

Scope-First, Prose-Second

The skill always skips the preamble and keeps prose brief (lines 6–7). It never buries the visual under explanatory text. Instead, it places each visual immediately adjacent to the short text it supports (line 25), ensuring the user sees the diagram before reading context.

Smallest View That Conveys the Point

After establishing brevity, the skill selects the most compact representation that still captures the essential information (lines 8–9). This means it examines the type of information requested and picks the first format in its hierarchy that can express the concept with the fewest characters or lines without losing clarity.

Visual Output Formats and Selection Criteria

The skill recognizes four distinct visual forms, each triggered by specific data characteristics.

ASCII Sketches for Hierarchical Structures

For simple hierarchical structures—such as logic flows, runtime call trees, UI component trees, or file layouts—the skill emits ASCII sketches (lines 18–44). These plain-text trees are preferred for their zero-dependency rendering and small footprint.

The skill enforces minimalism by showing only relevant nodes; extraneous branches are explicitly omitted (lines 26, 44). For example, a component tree skips unrelated sibling components:

<SessionPage> (apps/example/src/routes/session.tsx)
  useSessionEvents()
  <SessionToolbar>
    <RunSkillButton> (packages/ui)

Mermaid Diagrams for Relationships and Flows

When the information represents a relationship, sequence, or data-flow better expressed as a graph, the skill generates Mermaid diagrams (lines 46–56). Sequence diagrams are the primary choice for illustrating interactions between participants.

Minimalism is enforced by limiting the diagram to the participants and steps directly involved in the current question (line 52). Unrelated actors or alternative flows are excluded:

sequenceDiagram
    participant User
    participant UI
    participant Daemon
    User->>UI: choose command
    UI->>Daemon: send expanded prompt
    Daemon-->>UI: stream result

Diff Blocks for State Changes

To highlight what changed—whether a component addition, file-layout modification, or state transition—the skill uses diff blocks (lines 58–96). This format is selected whenever the core question involves a delta rather than a static structure.

The diff is scoped to the changed region; unchanged sections are omitted, showing only additions (+) or removals (-) (lines 62–63, 96):

 <SessionPage>
   useSessionEvents()
   <SessionToolbar>
+  <RunSkillButton />
   <SessionTimeline>
+  <SkillResultCard />

Focused HTML Artifacts for Dense UI Concepts

For UI-heavy, dense concepts where ASCII or Mermaid would be too cramped or lose fidelity, the skill generates focused HTML artifacts (lines 17–22, 98–102). This is the last resort when the visual requires styling, real labels, or complex layout that text cannot represent.

The generated HTML is a single, self-contained page containing only the necessary diagram or infographic, using the product’s styling and real labels (line 20). It is opened via a Bash command rather than embedded:

open path/to/show-me-component-overview.html

Enforcing Minimalism in Visual Outputs

The specification reinforces minimalism through three concrete rules:

• "Place each visual next to the short text it supports" (line 25) — prevents visual dislocation.
• "Show only the calls, files, props, states, and boundaries needed to answer the user’s current question" (line 26) — enforces node-level filtering.
• "Don’t overwhelm the user – you may use several visuals, but it is unlikely you will use all of them" (line 27) — caps visual density.

In practice, this means the skill examines the request type (component tree vs. state change vs. relationship flow) and selects the first format in the hierarchy (ASCII → Mermaid → Diff → HTML) that can represent the answer without requiring extraneous detail.

Implementation Details

The decision logic and examples are defined in plugins/show-me/skills/show-me/SKILL.md (lines 1–120), while the skill registration is handled in plugins/show-me/.claude-plugin/plugin.json. These files together determine the emission rules and minimalism constraints that govern when ASCII text, Mermaid syntax, diff notation, or standalone HTML files are generated.

Summary

• The show‑me skill follows a "smallest view that conveys the point" hierarchy to select output formats.
• ASCII sketches are used for hierarchical trees (call stacks, file layouts) with irrelevant branches omitted.
• Mermaid diagrams handle relationships and sequences, limited to directly involved participants.
• Diff blocks visualize changes, scoped strictly to added or removed lines.
• Focused HTML artifacts are generated only for dense UI concepts that cannot fit in text formats, opened via Bash commands.
• All formats adhere to the "scope-first, prose-second" rule to keep outputs minimal and adjacent to brief explanatory text.

Frequently Asked Questions

What triggers the show‑me skill to generate a Mermaid diagram instead of ASCII?

The skill selects Mermaid when the information represents a relationship, sequence, or data-flow that requires graph notation to express connections between participants (lines 46–56). ASCII is reserved for simple hierarchical structures like trees and stacks where parent-child relationships suffice.

How does show‑me keep ASCII sketches from becoming cluttered?

The skill enforces a "relevant nodes only" policy (lines 26, 44). It omits extraneous branches and shows only the calls, files, props, states, and boundaries needed to answer the specific user question, preventing the tree from expanding into an unreadable wall of text.

When should I expect a focused HTML artifact instead of inline code?

Expect a focused HTML artifact when the concept is UI-heavy or information-dense—such as complex component layouts or styled infographics—where ASCII or Mermaid would be too cramped to convey the point clearly (lines 17–22, 98–102). The skill generates a single self-contained page opened via open path/to/file.html.

Where is the show‑me skill configuration defined?

The visual decision rules, examples, and minimalism guidelines are defined in plugins/show-me/skills/show-me/SKILL.md (lines 1–120), while the plugin registration metadata resides in plugins/show-me/.claude-plugin/plugin.json according to the humanlayer/skills repository structure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}