A picture is worth a thousand tokens

I wanted my agent to believe that a picture is worth a thousand words, not as a feature I invoke, but as a default it holds. When I ask for a plan, I should get a flowchart of phases with dependencies. When I ask for a recap, a timeline and a reconciled plan diagram. When we talk architecture, subgraphs and sequence diagrams with contracts on the edges. Prose describes; diagrams show. If the content has a shape (order, connection, state, proportion), the shape should be rendered, not narrated.

That instinct is older than this write-up. Dual channels and rule layers (July 2025) already treated diagrams as a forked, residue-aware path, and Diagram Generator (September 2025) made compiled Mermaid/SVG a regression-checked artifact. This post is what happened when those threads became a default skill stack in 2026.

So I built a skill. This is the story of what it actually took to make it a default, and what broke along the way.

Defaults are a stack, not a sentence

The first version failed the only test that mattered: unprompted use. Skills in an agent harness are suggestions. The model reads a one-line description and decides whether to open the folder. That decision is semantic matching, and semantic matching is a preference, not a policy.

A real default needs layers with different determinism guarantees. The skill description is the probabilistic layer: written aggressively, listing every artifact type it covers, including the phrase “even if the user never says diagram.” The always-in-context project rules are the near-deterministic layer: one line stating that plans, recaps, and architecture docs must go through the skill. A prompt-submit hook is the deterministic backstop: regex the request, inject the reminder. Description, rule, sensor. When “recap this sprint” produces a timeline without anyone asking for one, the stack is working.

The scaffolding is not the deliverable

The second problem was cost. A skill that fires on every plan and recap sits on the hot path, and my first instinct (load reference material, draft, iterate) was dumping construction sawdust into the main context window. The instructions for making a diagram are scaffolding. Only the diagram is the deliverable.

The fix was an audit I now run on every skill I write. Four surfaces, each with a different price: the always-loaded description, paid in every session forever; the on-trigger skill body, permanent once fired; the on-demand references, permanent once read; and the residue (everything left behind after the work, including every discarded draft). The metric is the deliverable-to-residue ratio.

The heavy path now forks. A builder agent burns its own isolated context on reference files, ground-truth reads, and draft iterations, then dies, returning file paths and a summary capped at twelve lines. Dispatches pass pointers, not payloads; the fork reads the schema files itself. Worst-case main-thread residue dropped from roughly 6,300 tokens of machinery to about 500 of dispatch-and-return.

Judgment is one stage; everything else is code

I've argued before that Let the scripts judge and the agents fix. Building this pushed me one step further: most of an agentic pipeline shouldn't be agentic at all.

The move that makes it real is an intermediate representation. The strong model's only job is emitting a schema-validated spec: which diagrams, which nodes, which edges carry which contracts, which open questions the half-drawn diagram just surfaced. Everything downstream is Python. Rendering the spec into diagram syntax is a template function, which means the output is syntactically valid by construction; an entire class of syntax pitfalls stops existing. Half of my design-review rubric turned out to be graph properties (orphan nodes, dead-end flows, unlabeled edges, node counts), so the blind-spot review became lint.

Six stages. One needs a strong model. One needs a small one: a cold reader that states, in one sentence, what each diagram claims, precisely because it never saw the reasoning. Four are Python. Improving the pipeline is now a code review and an eval run, not prompt archaeology. And because the orchestration lives in a saved workflow script rather than API calls, the whole thing runs on a subscription instead of metered pricing: determinism of process without paying per token of it.

Parse-valid, render-dead

Then I shipped a broken artifact, and the failure taught me more than the design did.

The deliverable was a multi-tab HTML page of diagrams. On my phone, a tab showed the renderer's error card: “Syntax error in text.” I re-read the diagram four times and couldn't find the bug. There wasn't one. Every block parsed clean against the exact pinned renderer version. The error card lies about its category.

Two real mechanisms, both invisible to any parse-level check. Rendering into hidden tab panels kills some diagram types and spares others. Flowcharts and class diagrams need layout measurement that returns zeros in a hidden container, while sequence diagrams survive, which makes the failure look random. And the renderer reads innerHTML, meaning the browser's HTML parser has already rewritten your source before the renderer sees a byte of it. My validation had checked textContent. I was testing a different system than the one that runs.

Both classes are now impossible rather than caught: diagram sources travel as JSON and render programmatically, only when visible. But detection got rebuilt too, as a last line of defense. A headless browser loads the artifact, clicks every tab, and asserts that every diagram rendered, at the same pinned version the page ships. Nothing goes out without a stated verification grade: render-verified, parse-validated, or unverified, and unverified never ships silently. The gate paid for itself within minutes: my own rebuild script crashed mid-fix, left the stale broken file on disk, and the gate caught it while I was busy believing I'd fixed things.

Pinned is not validated. Validate the pipeline the renderer uses, not a lookalike. And when an error message names its category, don't believe it.

What you learn becomes the map

The failure didn't end as a fix; it ended as a new section in the skill's own review rubric, which the fresh-context reviewer now applies to everything the skill produces next. That loop (before, during, after, with the after feeding the next before) is the part I'd defend hardest. A default worth having is one that gets more trustworthy every time it burns you.

The test for shipped hasn't changed since the first day: I say “recap this sprint,” and a verified diagram comes back without me asking for one.