/show-me Makes Coding Agents Draw

HumanLayer's /show-me: agent skill for compact visual representations is a Show HN project that teaches coding agents to present work as compact visuals instead of long prose. It deals with a very ordinary agentic coding problem: Claude, Codex, and similar tools can bury the important shape of a change inside pages of Markdown. The useful takeaway is simple: ask the agent to compress structure before it explains, then review the picture before you read the wall of text.

An agent skill is a reusable, on-demand instruction bundle that tells a coding agent how to perform a recurring task. In this case, the task is not write better sentences. It is show me the dependency graph, flow, boundary, state machine, or comparison that the prose is trying to describe.

Make the agent compress before it explains

The neat part of /show-me is that it treats visual output as a forcing function. A coding agent can ramble when it writes a plan. It has a harder time hiding behind filler when it must draw the call path from an HTTP handler to a database write.

That matters because many code reviews are shape problems before they are syntax problems. You want to know whether a new queue worker bypasses auth, whether a cache invalidation path is circular, or whether a migration touches three services instead of one.

The trap is asking for a pretty diagram too early. The first useful visual is often ugly: a Mermaid graph, a compact table, or a few boxes with arrows. If it lets you reject a bad plan in 30 seconds, it worked.

For Claude Code, Anthropic's coding agent, the closest pattern is to keep this as an on-demand skill or slash-command habit, not an always-on repository rule. A small instruction like ask for a call graph when touching auth code belongs near the task. A global CLAUDE.md rule that says always diagram everything will become background noise.

Why developers cared on Hacker News

The Hacker News reaction was not about diagrams as decoration. It was about fatigue. Developers recognized the specific pain of scrolling through agent plans that sound confident but make the actual system harder to see.

The project also landed because it uses a thing humans are good at. We spot clusters, loops, missing branches, and suspicious arrows quickly. A visual representation gives the reviewer a second sense check before the agent gets permission to edit code.

One honest objection came up too: visual output is easier to admire than to test. If the diagram is wrong, the agent may have produced a more convincing mistake. That is especially awkward when the model or harness is weak at visual understanding, because the picture becomes write-only evidence.

The answer is not to trust the diagram. It is to make the diagram cheap, textual, and reviewable. Mermaid, ASCII flow, tables, and small SVG-like structures are better than screenshots because you can diff them, copy them, and ask another model or human to challenge them.

Use it where prose hides shape

/show-me fits best when the code has topology. Good targets include request lifecycles, permission boundaries, background jobs, event streams, retry logic, service dependencies, and test coverage maps.

A real example: before asking an agent to refactor billing webhooks, ask it to show the event flow from provider callback to idempotency check to ledger write to notification. If the diagram has no failure branch for duplicate events, you found the review question before the patch exists.

It is overkill for small edits. Do not draw a diagram for a typo, a one-line type fix, or a local rename. The visual should remove ambiguity, not add ceremony.

This is also where the story touches agentic coding governance without turning into process theater. A compact visual can be a lightweight guardrail: it makes the agent expose the boundary it thinks it is crossing.

Keep the visual output reviewable

The safest version of this pattern is text-first. Ask for Mermaid when you need a graph, a table when you need a comparison, and a short sequence diagram when you need ordering.

Here is a small Claude Code skill outline I would use as a local experiment, not as a claim about the source project's exact implementation:

---
name: show-me-change-shape
description: Use when a code change involves flows, boundaries, dependencies, state, retries, or cross-file behavior.
---

Before writing the plan, produce one compact visual representation.
Prefer Mermaid for graphs or sequence diagrams.
Prefer a table for tradeoffs, permissions, or file-by-file impact.
Keep it under 40 lines.
After the visual, list the two review questions the visual raises.
Do not edit files until the reviewer confirms the visual matches the system.

The important line is not the Mermaid preference. It is the pause before file edits. A picture that catches a wrong architecture assumption is most valuable before the agent has generated a 900-line patch.

There is a related pattern in terminal-agent routing projects like FEDERaiDE Routes Agents in Your Terminal: the useful interface is often the one that makes the agent's next move visible. /show-me applies that idea to representation instead of routing.

Try /show-me safely

Use this as a small experiment around one confusing change. The goal is to learn whether visual compression improves your review, not to make every agent response more elaborate.

A good first run is this: ask the agent for a visual, compare it against the code, correct one wrong edge, then ask for the plan. If the corrected visual changes the plan, the skill paid for itself.

Try the smallest useful picture

Pick one agent task this week where the plan feels wordy. Ask for the shape first, fix the shape, then let the code change start.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.

Practical starter checklist

- [ ] Name the Claude Code artifact first: a hook boundary, an MCP permission note, a slash-command workflow, a Claude skill outline, a review checklist, or a concise CLAUDE.md note when repository memory is the topic.
- [ ] Write the review checklist before generation starts: scope, owner, tests, rollback.
- [ ] Keep the first step small enough that a reviewer can inspect the receipt without replaying the whole chat.

Common questions

• How should teams start with Claude Code?

  Start by writing down one visible team rule for Claude Code, not a loose preference. That usually means a short repository convention, a review checklist, and one owner who can reject agent output when the evidence is missing.

• Which Claude Code artifact should teams standardize first?

  Standardize the smallest artifact that reviewers already touch: a hook checklist, MCP permission rule, slash-command workflow, skill outline, or concise CLAUDE.md note. The point is not documentation volume; it is a shared place where scope, allowed tools, expected tests, and rollback notes are visible before generated code reaches review.

• How do teams know the convention is working?

  The convention is working when reviewers can approve or reject agent output from the artifact and evidence alone. Track whether pull requests name the rule used, include the promised checks, and avoid replaying long sessions just to understand what changed.

Best ways to use this research

• Best for: Claude Code teams deciding which hook, skill, MCP boundary, slash-command workflow, review habit, or repository-memory convention to standardize next around “/show-me Makes Coding Agents Draw.”
• Best first artifact: turn the named fix into a hook checklist, skill note, MCP permission note, review receipt, or concise CLAUDE.md convention when repository memory is the real topic before the next automated run.
• Best comparison angle: compare the workflow against the current Claude Code handoff, hook behavior, and MCP scope; keep the path that leaves the shortest auditable trail.

Further reading

• /show-me: agent skill for compact visual representations — source
• Claude — Agent
• GitHub — anthropics/skills
• developers.google.com: fundamentals creating helpful content

Where to go next

Start from the related training topic and make the first exercise prove scope, verification, and ownership in the PR body.