Show me

Make the topic visible. Skip the preamble and keep prose brief. Pick the smallest view that makes the key point clear, and build it for the surface it will be read on.

This skill produces visuals. It does not embed, upload or publish them — the caller does that.

Parameters

Callers may constrain the output. Each is optional except the topic.

/pr calls this with surface: markdown, size: tight and a low max-views, because a PR body is scanned rather than studied.

Surfaces

The surface decides which primitives exist. Getting it wrong is the one mistake that ruins an otherwise good view.

Read references/surfaces.md for the surface you were given before producing anything. It holds the fence-to-color map, the safe glyph set, what GitHub's sanitizer keeps, and the rules for an HTML page.

Never emit a Mermaid fence to terminal. Nothing there renders it, so it arrives as a wall of source — the exact failure this skill exists to prevent. surfaces.md maps each diagram shape to the text view that replaces it.

Composition

How the views sit together matters as much as each one.

• One headline view carries the answer, and it comes first. Everything after it is support.
• Ceiling: one view at tight, at most three at normal. A fourth means you are writing a document, not showing a shape.
• One question per view. A view answering two questions is two views, or one hairball.
• Caption each view with its finding, on the line above it — "state.md is the only shared write", not "Architecture". A caption naming the view's category tells the reader nothing they cannot see.
• No two adjacent views of the same shape. Two trees in a row read as one long tree.

The views

Logic or an algorithm — pseudocode:

on(save)
  if content is unchanged
    return cached result
  write new content
  return fresh result

Runtime control flow or order — call tree:

submitForm
  createSession
    persistPrompt
    launchAgent
  navigateToSession

UI structure — component tree, including the state and module boundaries that matter:

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

File responsibility, or a broad refactor — shallow file tree:

src/
├── commands/       # parses user actions
├── sessions/       # owns session state
└── transport/      # sends API requests

Counts, durations, sizes, proportions — a chart. Numbers buried in prose are numbers nobody compares. On terminal, bars built from block characters; on markdown, a Mermaid pie; on html, a real chart. Recipes per surface live in references/surfaces.md.

specify  ████████████████░░░░░░░░░░░░░░░░░░░░░░░░  2 reviewers
design   ████████████████████████████████░░░░░░░░  4 lenses
execute  ████████████████████████████████████████  5 verifiers

Component interaction, control flow, or data flow — Mermaid, on a surface that renders it. Drawing one has its own checklist, below.

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

Mostly new code, or where omitted context would hide ownership or order, or where the reader needs a copyable target shape — the whole block:

function expandSkill(command: string): string {
  const skillName = command.slice(1)
  return `use the ${skillName} skill`
}

An endpoint's request/response, or a table's columns — the contract:

POST /sessions
  → { email, password }
  ← 201 { sessionId, expiresAt }
  ← 401 { error: "invalid_credentials" }

A key type or data structure that changed shape — diff the type:

 type Session = {
   id: string
-  legacyToken: string
+  idpSub: string
+  expiresAt: Date
 }

Diffing a shape

Use diff when the point is what changes and the surrounding shape already exists. Match the diff shape to the topic — diff the component tree, the file tree, the call tree or the pseudocode. A literal source diff is not a view; the reader can already read the source diff.

A component change:

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

A file-layout change:

 src/
 ├── commands/
+│   └── show-me.ts       # expands the slash command
 ├── sessions/
-└── transport.ts
+└── transport/
+    ├── client.ts
+    └── stream.ts

The diff fence is also the only way to get red and green into a terminal, so prefer it wherever the topic genuinely is a change.

Screenshots

For a change to something the reader would want to see — a UI, a layout, a visual state — a screenshot of the real thing beats any text view.

1. Get the app running. If the project has a skill for launching it, use that.
2. Drive it to the state that matters with Playwright or the browser extension, whichever the session has.
3. Capture to a file outside the repo, and return the path. Capture the state it changed from as well, when the comparison is the point.

Never commit a screenshot into the repository. Embedding, uploading and hosting belong to whoever asked for the visual.

If the app cannot be run or driven, say so plainly and offer the nearest text view. Do not hand-write a mock of a UI that exists.

A screenshot is an image, so it cannot be the view on terminal. Return the path and name what it shows.

Drawing a diagram

Copy this checklist and work it in order.

- [ ] Enumerate the nodes, and the edges as `source --verb--> target`
- [ ] If the subject is a UML subject, pick that UML type and its notation
- [ ] Draw only what is enumerated, 12 nodes or fewer
- [ ] Validate: node show-me/scripts/validate-mermaid.mjs <file>
- [ ] Read the drawn diagram back against the enumeration

Run scripts/validate-mermaid.mjs; there is no reason to read it. It needs node and npm, and names the failing line and the tokens the parser will accept there.

references/diagrams.md holds the rules, their checks, the diagram-type menu, the palette and the syntax that fails silently. references/uml.md holds UML notation, for the subjects that have a UML type — a file tree or a chart does not, and is drawn plainly rather than dressed up as one.

Guidance

Place each visual next to the short text it supports, and keep only the calls, files, props, states and boundaries that answer the question actually being asked. A view that restates the sentence above it is noise with syntax highlighting — drop it.

Before returning, read the output as the reader will: the headline has to land from the first view alone, without the prose around it. If it does not, the wrong view is first, or the caption is not saying the finding.

Credits

Adapted from Dex Horthy's show-me (HumanLayer), MIT licensed. See CREDITS.md.