show-me — the smallest picture that answers the question
A second paragraph never fixes the first one. Pick the smallest view that makes the point, put two
lines of prose beside it, stop.
The contract
- One form, chosen on purpose. Read what the question is about, pick the matching form from
the table, draw that. Several forms in one answer is the failure mode, not thoroughness.
- Only the parts that answer the question. Keep the calls, files, props, states and boundaries
the user asked about. Everything else is noise that hides the answer.
- Prose shrinks to fit. No preamble, no "here is a diagram of". The picture leads; the words
caption it.
- Real names. Actual paths, actual function and component names, actual state values. A diagram
of
ServiceA → ServiceB explains nothing.
- Say so when there is nothing to draw. A topic with no shape gets a straight answer in prose.
A decorative diagram costs the reader time and buys nothing.
Pick the form from what the topic is
| The question is about |
Draw |
Why this one |
| Logic, an algorithm, a decision |
pseudocode |
branches read top-down; syntax would distract |
| What calls what at runtime |
call tree |
shows order and nesting, which prose loses |
| UI structure |
component tree, with state and module boundaries |
ownership is the answer most of the time |
| Which file is responsible for what |
shallow file tree with one comment per entry |
depth hides the point; one level shows it |
| Interaction, control flow, data flow between pieces |
Mermaid sequence or flow diagram |
two-way traffic over time needs an axis |
| What changes in a shape that already exists |
diff, in the shape of the topic |
the reader keeps their bearings |
| Layout, visual state, a dense comparison |
one self-contained HTML page |
text cannot hold it |
| Nothing with a shape |
prose |
see contract rule 5 |
on(save)
if content is unchanged
return cached result
write new content
return fresh result
submitForm
createSession
persistPrompt
launchAgent
navigateToSession
<SessionPage> (apps/example/src/routes/session.tsx)
useSessionEvents()
<SessionToolbar>
<RunSkillButton> (packages/ui)
src/
├── commands/ # parses user actions
├── sessions/ # owns session state
└── transport/ # sends API requests
sequenceDiagram
participant User
participant UI
participant Daemon
User->>UI: choose command
UI->>Daemon: send expanded prompt
Daemon-->>UI: stream result
The diff rule
Use diff when the surrounding shape already exists and the point is what moves. Match the diff
to the topic: a component change is a component diff, a layout change is a file-tree diff, a
control-flow change is a pseudocode diff. A unified source diff for a structural change makes the
reader rebuild the structure in their head.
src/
├── commands/
+│ └── show-me.ts # expands the slash command
├── sessions/
-└── transport.ts
+└── transport/
+ ├── client.ts
+ └── stream.ts
on(save)
- write content
+ if content is unchanged
+ return cached result
+ write new content
+ invalidate cache
Show the whole block instead of a diff when most of it is new, when the omitted context would hide
ownership or order, or when the user needs something copyable.
When it earns an HTML page
Layout, visual state, a side-by-side comparison, or a concept too dense for a text diagram. One
page, self-contained, real labels and real data, readable on a phone and on a desktop. Inherit the
product's colours, type and spacing from where it lives; this skill borrows an identity, it never
invents one. Then open it:
open path/to/show-me-<topic>.html
Anti-patterns
| Anti-pattern |
Why it fails |
Do this instead |
| Ship four forms because each adds a little |
The reader now has to pick; that was your job |
One form, the smallest that answers it |
| Diagram the whole system when asked about one path |
The answer is in there somewhere, which is the same as absent |
Draw the path, drop the rest |
Placeholder names (ModuleA, doThing) |
Nothing maps back to the codebase |
Real paths and real identifiers |
| A unified source diff for a structural change |
Forces the reader to rebuild the shape |
Diff in the shape of the topic |
| Mermaid for a layout question |
Boxes and arrows cannot show visual space |
One HTML page |
| A diagram to look thorough |
Costs attention, adds nothing |
Answer in prose and say why there is nothing to draw |
Where this ends
- The visual identity of an interface, a landing page or a poster is
design-loop and design.
- A deck someone presents from is
presentations.
- Zero prior knowledge, big pictures, few words, is
eli5.
- Restructuring a document, a README or a reference is
technical-writing.
- A guided tour of an unfamiliar repository is
codebase-onboarding; this skill draws the pieces it
finds, it does not run the tour.
1---2name: show-me3description: Use when the user needs to see how something works instead of reading about it: picks the smallest visual that carries the point — pseudocode, call tree, file tree, component tree, Mermaid, a shaped diff, or one HTML page. NOT visual identity (that is `design-loop`), NOT slides (that is `presentations`), NOT a from-zero explainer (that is `eli5`).4---56# show-me — the smallest picture that answers the question78A second paragraph never fixes the first one. Pick the smallest view that makes the point, put two9lines of prose beside it, stop.1011## The contract12131. **One form, chosen on purpose.** Read what the question is *about*, pick the matching form from14 the table, draw that. Several forms in one answer is the failure mode, not thoroughness.152. **Only the parts that answer the question.** Keep the calls, files, props, states and boundaries16 the user asked about. Everything else is noise that hides the answer.173. **Prose shrinks to fit.** No preamble, no "here is a diagram of". The picture leads; the words18 caption it.194. **Real names.** Actual paths, actual function and component names, actual state values. A diagram20 of `ServiceA → ServiceB` explains nothing.215. **Say so when there is nothing to draw.** A topic with no shape gets a straight answer in prose.22 A decorative diagram costs the reader time and buys nothing.2324## Pick the form from what the topic is2526| The question is about | Draw | Why this one |27| --- | --- | --- |28| Logic, an algorithm, a decision | pseudocode | branches read top-down; syntax would distract |29| What calls what at runtime | call tree | shows order and nesting, which prose loses |30| UI structure | component tree, with state and module boundaries | ownership is the answer most of the time |31| Which file is responsible for what | shallow file tree with one comment per entry | depth hides the point; one level shows it |32| Interaction, control flow, data flow between pieces | Mermaid sequence or flow diagram | two-way traffic over time needs an axis |33| What changes in a shape that already exists | `diff`, in the shape of the topic | the reader keeps their bearings |34| Layout, visual state, a dense comparison | one self-contained HTML page | text cannot hold it |35| Nothing with a shape | prose | see contract rule 5 |3637```text38on(save)39 if content is unchanged40 return cached result41 write new content42 return fresh result43```4445```text46submitForm47 createSession48 persistPrompt49 launchAgent50 navigateToSession51```5253```tsx54<SessionPage> (apps/example/src/routes/session.tsx)55 useSessionEvents()56 <SessionToolbar>57 <RunSkillButton> (packages/ui)58```5960```text61src/62├── commands/ # parses user actions63├── sessions/ # owns session state64└── transport/ # sends API requests65```6667```mermaid68sequenceDiagram69 participant User70 participant UI71 participant Daemon72 User->>UI: choose command73 UI->>Daemon: send expanded prompt74 Daemon-->>UI: stream result75```7677## The diff rule7879Use `diff` when the surrounding shape already exists and the point is what moves. **Match the diff80to the topic**: a component change is a component diff, a layout change is a file-tree diff, a81control-flow change is a pseudocode diff. A unified source diff for a structural change makes the82reader rebuild the structure in their head.8384```diff85 src/86 ├── commands/87+│ └── show-me.ts # expands the slash command88 ├── sessions/89-└── transport.ts90+└── transport/91+ ├── client.ts92+ └── stream.ts93```9495```diff96 on(save)97- write content98+ if content is unchanged99+ return cached result100+ write new content101+ invalidate cache102```103104Show the whole block instead of a diff when most of it is new, when the omitted context would hide105ownership or order, or when the user needs something copyable.106107## When it earns an HTML page108109Layout, visual state, a side-by-side comparison, or a concept too dense for a text diagram. One110page, self-contained, real labels and real data, readable on a phone and on a desktop. Inherit the111product's colours, type and spacing from where it lives; this skill borrows an identity, it never112invents one. Then open it:113114```bash115open path/to/show-me-<topic>.html116```117118## Anti-patterns119120| Anti-pattern | Why it fails | Do this instead |121| --- | --- | --- |122| Ship four forms because each adds a little | The reader now has to pick; that was your job | One form, the smallest that answers it |123| Diagram the whole system when asked about one path | The answer is in there somewhere, which is the same as absent | Draw the path, drop the rest |124| Placeholder names (`ModuleA`, `doThing`) | Nothing maps back to the codebase | Real paths and real identifiers |125| A unified source diff for a structural change | Forces the reader to rebuild the shape | Diff in the shape of the topic |126| Mermaid for a layout question | Boxes and arrows cannot show visual space | One HTML page |127| A diagram to look thorough | Costs attention, adds nothing | Answer in prose and say why there is nothing to draw |128129## Where this ends130131- The visual **identity** of an interface, a landing page or a poster is `design-loop` and `design`.132- A **deck** someone presents from is `presentations`.133- **Zero prior knowledge**, big pictures, few words, is `eli5`.134- Restructuring a document, a README or a reference is `technical-writing`.135- A guided tour of an unfamiliar repository is `codebase-onboarding`; this skill draws the pieces it136 finds, it does not run the tour.
ericrisco