show-me: A 3.3KB Skill That Makes Fluent Coding Agents Draw Diagrams First

Forum topic · 小凯 · 2026-08-23

Summary

HumanLayer's Dex Horthy released show-me, a 3.3KB coding agent skill (part of humanlayer/skills, installable via `npx skills add humanlayer/skills --skill show-me` for Claude Code, Cursor, and Codex) that forces agents to express designs as compact visual representations instead of fluent prose. The skill defines seven formats with minimal guidance: component trees, call trees, file trees, pseudocode (including explicit failure paths), type signatures, diffs, and Mermaid sequence/state diagrams. The core insight: prose optimizes for sounding convincing, while every arrow in a diagram is a discrete, falsifiable assertion about call direction, state ownership, and failure paths. Notably, the missing arrow in a sequence diagram often reveals the bug and the limits of the agent's understanding. The author frames this within a three-checkpoint workflow (representation before implementation, then verification) and situates show-me in a broader shift from behavioral gates (human approval of tool calls) to cognitive gates (auditing the agent's mental model via diagrams). Caveats remain: diagrams are static beliefs while bugs live in dynamic behavior, and even Dex admits Mermaid output can still be slop—verification against source code and run traces is non-negotiable.

show-me: The More Fluent the Agent, the More It Should Draw First

One-line summary

HumanLayer (Dex Horthy) released the show-me skill on August 12. At only 3.3KB, it consists of minimal demonstrations of seven representation formats: component trees, call trees, file trees, pseudocode, type signatures, diffs, and Mermaid. It solves not "agents can't write code" but "agents write forty lines of fluent prose and, after reading it, you still don't know where the entry point, state ownership, or failure path is." One-line discipline: skip the preamble; use the smallest diagram that clarifies the point at hand. The video's three checkpoints—"represent first, implement second, verify third"—elevate this skill from a formatting preference to an engineering method.

---

1. The pathology: prose has no falsifiable structure

Dex quotes a string of complaints in his release post—former Reddit CEO Yishan, Mario Zechner (author of pi), Connor of Replicas—all people drowning in "walls of jargon." He puts it more bluntly himself: "agents are smarter on paper, but the experience has clearly gotten worse in this dimension... the voice, personality, and 'soul' people once liked about Claude have been RLHF'd into the dungeon." This happens several times a day.

Why does 40 lines of fluent prose leave nothing behind? Because prose is narrative, optimized to "sound right"—which is exactly the direction RLHF training pushes it. Every arrow in a sequence diagram, by contrast, is an assertion: who calls whom, in what order, who owns the state. Each one can be checked and falsified independently.

Moving from prose to diagrams is a shift from persuasion to specification. This is the same pathology as last week's OmniScientist analysis: unconstrained agent output takes the form of p-hacked "persuasive text," and the cure in both cases is swapping the output for a representation that can be executed/verified as a check—there it's Python predicates, here it's structured diagrams.

2. A 3.3KB skill, seven representations each covering a class of problems

The SKILL.md contains no "please think deeply"-style invocation; only format demonstrations plus one governing rule: choose the minimal view that makes the key point clear. Division of labor among the seven representations:

| Representation | Problem it fits | What it lets you verify | |---|---|---| | Call tree (indented) | Control flow, orchestration logic | Call direction, level ownership | | Component tree | Frontend structure | Where state hooks live, module boundaries | | File tree (one-line responsibility per row) | Refactoring scope, "where does this live" | Responsibility ownership | | Pseudocode | Algorithm logic | Includes failure paths (the SKILL.md demo explicitly includes one) | | Types/signatures | Contracts before implementation | Data shapes exist before implementation | | Diff | "What changed" | Minimizing the change surface | | Mermaid sequence/state diagrams | Component interaction | Message ordering, double-write races |

Two easily missed details. First, in the pseudocode demo, the last line after restore(snapshot) is else scrollTop = snapshot.scrollTop // failure path—failure paths are first-class citizens, which is exactly what evaporates first in prose explanations. Second, the guidance is only about 60 words: "keep only the calls, files, props, state, and boundaries needed to answer the current question... you'll likely use a few, unlikely to use all." This is token-level information-density discipline, not a love of drawing.

3. Case study: "saves, then reverts to the old value"—diagrams matter most where things go wrong

The example in the video deserves unpacking. "Config saves, then reverts to the old value" is a typical vague complaint—it's not verifiable, because you don't know how many writers exist, who reads when, or whether a cache resurrects old values. Draw it as a sequence diagram, and every arrow becomes a checkable assertion: the UI→API write, the API→storage persistence, the UI's read-back path... Then comes the real killer move:

The missing arrow is where the bug is. The second writer (background sync? a retry from a stale instance?), the cache-invalidation path that resurrects old values—the parts you cannot draw = the parts the agent didn't understand = most likely the parts that break. So a diagram's first function is not documentation but externalized belief: pinning the agent's mental model of the system onto paper as a graded confession. A wrong diagram is more valuable than a correct one.

But the video's warning must be emphasized equally—it's the most honest part of this method: diagrams are static beliefs; bugs live in dynamic behavior. Dynamic dispatch, retry storms, double-write races, out-of-order messages—these are inherently invisible in any static diagram. So the third step of "represent, implement, verify" cannot be skipped—return to source code, tests, and run traces to falsify every arrow in the diagram. A diagram is a list of hypotheses, not a list of evidence.

Operationally, that means three checkpoints:

1. Before implementation—change contract: signatures, diff shape, call-tree change points; align on "what we're touching"; 2. During coding—decision structure: failure paths in pseudocode, branch ownership; align on "is the logic right"; 3. After completion—review map: a structured bird's-eye view of large diffs; align on "what actually changed".

4. Ecosystem observations: from behavioral gates to cognitive gates

show-me is not an isolated trick; it advances two evolutionary lines.

HumanLayer's own line: from governing "what agents do" to governing "what agents think." The company made its name on agent behavior approval—humans nodding before tool calls (human-in-the-loop as a first-class primitive in 12-factor agents). show-me moves the gate from the behavior layer up to the cognition layer: code is crystallized cognition; rather than intercepting the wrong artifact at PR time, intercept the wrong mental model at diagram time. Other skills in the same repo—design-control-loop (cybernetic modeling with sensor/controller/actuator) and improve-claude-md—follow the same path. The whole skill library has a consistent shape: capability converges into the model, discipline migrates outward into skills—skills no longer teach the model "how to do it," they force it to "show its work first."

The community line: parallel convergence on representation discipline. Dillon Mulroy's /bro (forcing models to speak plainly), Matt Pocock's /teach (an HTML explainer), tanishq building a tool that directly extracts call trees from the AST—the last one especially notable: "don't generate, extract" is exactly isomorphic to OmniScientist's "don't self-evaluate, evaluate with predicates": whatever can be deterministically computed should not be left to probabilistic generation.

Editorial observations

The interface trilogy. Last week's OmniScientist analysis distilled "the interface is the cognitive bottleneck"—the decisive question is not what can be serialized into tokens, but which relationships survive the interface. show-me completes the principle into a trilogy: the world→model interface (OmniScientist: read raw slices rather than captions, recovering morphological relationships lost at the interface); the human→model interface (GEN-1.5: physical prompting—demonstrate the task rather than describe it, since description is lossy compression); and the model→human interface (show-me: structured diagrams rather than prose, since prose "fluency" is itself the loss). Three interfaces, one principle: a system's reliability depends not on generation capability but on the structure that survives the interface. Wherever the collapsing cost of generation lands, this principle reasserts itself at that point.

Verification-bandwidth economics. The hidden constraint in the two-axis collapse spectrum (task-definition cost + knowledge-production cost) is surfacing: once generation is free, the only bottleneck left is human verification bandwidth. Coda Hale's argument, which Dex cites, is worth remembering: the visual cortex is a free pattern matcher pretrained over a hundred million years; structural semantics like indent depth = ownership hierarchy are "seen," not "read." Diagrams are not decoration—they route the verification load to the right processor. The conversion rate in "turning AI generation speed into reliable delivery" is, in essence, the density of checkable assertions per token.

Two sober footnotes. First, Dex himself admits Mermaid diagrams are "sometimes they're still slop"—representation discipline is a half-step improvement, not a cure; diagrams can be drawn beautiful and empty, and it's still humans measuring assertion density. Second, the "minimal view" aesthetic carries a reflexive risk: real systems often have ownership spanning five files, and a diagram's cleanliness can itself manufacture false confidence—which is why the third checkpoint (returning to source and run traces) is not a process tail but the foundation of the whole method.

---

*Source: humanlayer/skills (GitHub, 426 stars) · Dex Horthy, "show-me: a coding agent skill for compact visual representations", 2026-08-12 · Install: npx skills add humanlayer/skills --skill show-me — works with Claude Code / Cursor / Codex.*