Overview
On August 12, HumanLayer's Dex Horthy released show-me, a coding-agent skill of only 3.3KB. It contains minimal demonstrations of seven representation formats: component trees, call trees, file trees, pseudocode, type signatures, diffs, and Mermaid diagrams.
The problem it solves is not "agents can't write code" but rather "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 lives." The one-line discipline: skip the preamble; use the smallest diagram that clarifies the current point. The "represent first, implement, then verify" checkpoints elevate this from a formatting preference to an engineering method.
The Pathology: Prose Has No Falsifiable Structure
Dex's release notes cite a string of complaints — from Reddit's former CEO Yishan, pi author Mario Zechner, and Replicas' Connor — all people drowned in "walls of jargon." He put it more bluntly: "agents are smarter on paper, but the experience has clearly gotten worse along this dimension... the voice, personality, and 'soul' people liked about Claude got RLHF'd into the dungeon."
Why does 40 lines of fluent prose leave nothing behind? Because prose is narrative, optimized to "sound right" — exactly what RLHF training rewards. 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 individually checked and falsified.
Moving from prose to diagrams is a shift from persuasion to specification. This is the same pathology seen in agentic outputs that produce persuasive but unfalsifiable text: the cure is replacing the output with a representation that can be mechanically checked.
Seven Representations, Seven Problem Classes
The SKILL.md contains no "think deeply" style incantations — only format demonstrations plus one governing rule: "choose the minimal view that makes the key point clear."
| Representation | Fits | What you verify | |---|---|---| | Call tree (indented) | Control flow, orchestration | Call direction, hierarchy | | Component tree | Frontend structure | Where state hooks live, module boundaries | | File tree (one-line responsibility each) | Refactoring scope, "where does this live" | Responsibility ownership | | Pseudocode | Algorithm logic | Including failure paths | | Types / signatures | Contracts before work begins | Data shapes precede implementation | | Diff | "What changed" | Minimal change surface | | Mermaid sequence / state diagram | Component interaction | Message ordering, dual-write races |
Two easily missed details:
1. In the pseudocode example, the last line is else scrollTop = snapshot.scrollTop // failure path — failure paths are first-class citizens, which is exactly what evaporates first in prose explanations.
2. The guidance is only ~60 words: "keep only the calls, files, props, state, and boundaries needed to answer the current question... you'll likely use a few, unlikely all." This is token-level information density discipline, not a love of drawing.
Case Study: "Saved Values Revert" — Diagrams Earn Their Keep at the Bug
The worked example in the video is worth unpacking. "Config saves, then reverts to the old value" is a classic vague complaint — unverifiable, because you don't know how many writers exist, who reads when, or whether a cache resurrects old values. Once drawn as a sequence diagram, every arrow becomes a checkable assertion: the UI→API write, the API→storage persistence, the UI's read-back path... Then the real kill shot:
The missing arrow is where the bug lives. A second writer (background sync? a retry from a stale instance?) or a cache-invalidation path resurrecting old values — the parts that can't be drawn = the parts the agent doesn't understand = very likely the parts that break. So the diagram's first function is not documentation but belief externalization: pinning the agent's mental model of the system onto paper as a gradeable confession. A wrong diagram is more valuable than a correct one.
But the video's warning must be equally emphasized, and it is the most honest part of the method: diagrams are static beliefs; bugs live in dynamic behavior. Dynamic dispatch, retry storms, dual-write races, message reordering — none of these are visible in any static diagram. So the third step — verify — cannot be skipped: go back to source code, tests, and runtime records to falsify every arrow.
The three checkpoints in practice:
1. Before work — change contract: signatures, diff shape, call-tree touch points; align on "what will we move"; 2. During coding — decision structure: failure paths and branch ownership in pseudocode; 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."
Ecosystem: 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 they think." The company built its reputation on agent behavior approval — human sign-off before tool calls (human-in-the-loop as a first-class primitive in their 12-factor agents work). show-me moves the gate from the behavioral layer up to the cognitive layer: code is crystallized cognition; rather than intercepting wrong artifacts at PR review, intercept wrong mental models at the diagramming stage. Companions in the same repo — design-control-loop (cybernetic modeling of sensor/controller/actuator), improve-claude-md — walk the same path. The whole skill collection shares a consistent shape: capability converges into the model; discipline is externalized into skills — skills no longer teach the model "how to do it" but force it to "show its work first."
The community's line: parallel convergence on representation discipline. Dillon Mulroy's /bro (forcing models to speak plainly), Matt Pocock's /teach (HTML explainers), and tanishq's tool that extracts call trees directly from the AST. The last one deserves special attention: "don't generate, extract" is structurally identical to "don't self-evaluate, evaluate with predicates" — whatever can be deterministically computed should not be left to probabilistic generation.
Editorial Observations
The interface trilogy. show-me completes a principle into a trilogy of interfaces: world→model (read raw slices, not captions — recover the morphological relations the interface dropped); human→model (physical prompting — demonstrate tasks rather than describe them; description is lossy compression); model→human (show-me — structural diagrams rather than prose; prose "fluency" is itself the loss). Three interfaces, one principle: system reliability depends not on generation capability but on the structure that survives the interface.
Verification-bandwidth economics. Once generation is free, the only bottleneck left is human verification bandwidth. The argument Dex cites from Coda Hale is worth remembering: the visual cortex is a free pattern matcher with a hundred million years of pretraining — structural semantics like indent depth = hierarchy are *seen*, not *read*. Diagrams are not decoration; they route verification load to the right processor. The conversion rate that "turns AI generation speed into reliable delivery" is essentially 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 also be pretty and empty, and humans still grade assertion density. Second, the "minimal view" aesthetic carries a reflexive risk: real-world ownership often spans five files, and a diagram's cleanliness can manufacture false confidence — which is why the third checkpoint (returning to source and runtime records) is not procedural 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.*