grokkable-output

Make your agent's replies parseable in one pass — verdict first, no decoding required.

TL;DR

A portable skill (SKILL.md) that changes how an agent writes replies, reports, and status updates. Install:

git clone https://github.com/conorbronsdon/grokkable-output ~/.claude/skills/grokkable-output

What it makes the agent do:

• Answer in the first sentence, then layer detail — you can stop reading anywhere and be correctly informed
• Write causality as sentences, not A → B → fails chains, invented codenames, or fragment piles
• Shorten by dropping what you don't need, never by cutting caveats or compressing grammar
• Use structure (bullets, headers, bold) only when the content has that shape — a quick status is a paragraph, not a document
• Trace every number and claim to something it observed; keep open questions open

Works with Claude Code, Cursor, OpenClaw, Codex, and anything reading the agentskills.io format. Real before/after outputs in examples/. Everything below is detail.

Models are rewarded for looking thorough; this skill makes them optimize for your parse time instead — a prompt-layer fix for an incentive problem.

Quick demo

An agent spent 40 minutes debugging production 500s. You stepped away, came back, and ask: "ok what did you find?" What you actually want to know: is it fixed, and what caused it?

Without the skill, that answer is distributed across a 371-word document you have to hunt through:

Short version: [a bolded paragraph] · The causal chain · Why rollback and not something else · Follow-ups filed · Two things worth your judgment

— and the mechanism, when you find it, is a puzzle to decompile:

sandbox host → Avalara 429s → each 429 retried 3x with 2s backoff (up to +6s latency) → tax-svc p99 goes 210ms → 8.4s → blows past payment-orchestrator's 5s downstream timeout → TaxLookupTimeout → checkout-svc catches it as a generic Exception and rethrows as a 500.

With the skill, sentence one answers the question, and you can stop reading whenever you have enough:

The checkout 500s came from tax-svc v2.14.0, which shipped pointing at the Avalara sandbox endpoint instead of prod. I rolled tax-svc back to v2.13.2 at 15:12 UTC under the sev2 runbook, where rollbacks are pre-approved. The 500 rate was back to baseline (0.02%) by 15:19 and held stable across 30 minutes of monitoring.

The rest is the mechanism in plain sentences, the one decision the engineer needs to make — stated as an answerable question — and an unprompted scope-limit caveat ("I only traced the checkout path"). 288 words, no headers, nothing dropped that the reader needed: the cut is selection, not compression.

The same discipline on a smaller question: ask "quick status?" mid-migration and the baseline returns a 273-word formatted document with three bold pseudo-headers; the skill returns a few short paragraphs opening with "48 of the 61 route handlers are migrated" and ending with the two decisions blocking progress.

Both versions of every pair are factually correct. One of them you read once. Full unedited outputs, with the input notes they were written from, in examples/.

What it teaches the agent

• Verdict first, layered depth. The first sentence answers the question asked. The reader can stop after one sentence, three, or the whole message and be correctly informed at every depth.
• One pass, no rereads. No arrow chains, no invented codenames, no undefined jargon, no telegraphic fragments. If a sentence needs rereading, the sentence failed.
• Shorten by selecting, not compressing. Drop what doesn't change the reader's understanding or next action; never crush the rest into fragments. Caveats are content, not padding — they survive selection.
• Structure mirrors logic. Headers, bullets, and bold are claims about the content's shape; make them only when true. A quick status is a paragraph, not a document.
• Calibrated claims. Status carries its evidence, confidence is stated once and plainly, and every number, estimate, and mechanism traces to something observed. Open questions stay open.
• Size the reply to the question. "Quick status?" earns a paragraph no matter how much work happened.

Three modes: write (default — compose replies this way), review (audit an existing output, flag anti-patterns by name), rewrite (fix an output, preserving every fact and caveat).

Why a skill, not just "be concise"

"Be concise" makes agents cut the wrong things — models under length pressure drop caveats and qualifiers first because hedges look like padding, while keeping their most confident claims. This skill targets parse cost, not word count: it names 12 specific anti-patterns (buried lede, process narration, checkmark overclaiming, fake structure, hedge stacks...), explains why each fails, and ends with a three-check self-test the agent runs before sending. In A/B testing the with-skill replies were usually shorter — but by selection, not compression.

Testing

Fresh A/B validation on claude-sonnet-5 used four scenarios, with and without the skill, across three independent runs per cell (24 replies total). An independent free model graded each semantic expectation; fresh Sonnet sessions adjudicated disputed grades; deterministic word ceilings were computed by the harness. Raw grader scores were 108/108 semantic expectations with the skill versus 101/108 baseline; after archived evidence-backed corrections, they were 107/108 versus 90/108. All 11 model-adjudication corrections reduced baseline scores, while the primary verifier reduced one skilled score, so both raw and adjusted results matter.

Across the three write scenarios, all nine skilled replies met their length ceilings. In the combined review + rewrite scenario, fidelity held but all three skilled replies missed the 500-word ceiling (560-715 words), so the result does not support proportionality in that mode.

Historical corpus:

Tested A/B on Opus subagents: three scenarios (a production debug report, a mid-migration "quick status?", a dependency audit explained to a non-engineer), identical input notes, with and without the skill, graded against per-scenario assertion sets by an independent model instance — including a fidelity pass checking every number and mechanism against the input notes.

Final round: 21/22 assertions with the skill vs 15/19 baseline on the original set. Every baseline failure was structural: arrow-chain causality, bold section headers on chat-length replies, a trailing recap restating the message. One known limitation is documented honestly: in one scenario the with-skill reply invented an effort estimate the notes didn't contain; the skill's trace-every-number rule narrowed but has not fully closed that failure class. The before/after pairs in examples/ are unedited outputs from these runs, chosen from the scenarios that passed the fidelity check.

The whole corpus is public in evals/: fixtures, assertion sets, per-assertion grading with verbatim evidence quotes, the fresh 24-reply v2 run, and the graded outputs of two later versions (v0.4.0, v0.5.0) that failed independent validation and never shipped. evals/RESULTS.md is the summary, including the new limitation and what each rejected round taught.

The next experiment is architectural rather than another rule stack: a conservative post-hoc output linter detects mechanical failures such as arrow chains, oversized blocks, depth offers, and estimates that need source review. It is a prototype; SKILL.md remains at v0.3.1 while the review/rewrite proportionality failure is investigated.

Installation

Claude Code — clone as a skill:

git clone https://github.com/conorbronsdon/grokkable-output ~/.claude/skills/grokkable-output

Or download just SKILL.md and reference it from your CLAUDE.md. To invoke on demand, add a slash command at ~/.claude/commands/grokkable.md that points at the skill file.

skills.sh:

npx skills add https://github.com/conorbronsdon/grokkable-output --skill grokkable-output

OpenClaw — clone to ~/.openclaw/skills/grokkable-output.

OpenAI Codex — place at .agents/skills/grokkable-output/SKILL.md (project) or ~/.agents/skills/ (global).

Cursor / Windsurf / Cline / Copilot — paste SKILL.md into .cursor/rules/, .windsurf/rules/, .clinerules/, or .github/copilot-instructions.md respectively.

Claude.ai Projects / custom GPTs — paste SKILL.md into the project or GPT instructions.

The problem in the wild

This isn't one person's pet peeve. The complaints repeat everywhere agent output gets read:

• "It explains the test framework, restates the task, writes a 'I will' paragraph, and only then says which file changed." — knightli.com on Claude Code defaults
• "I find all coding agents to be verbose, even with explicit instructions to reduce verbosity." — recurring Hacker News sentiment; others note Claude's "overly verbose 'walls of text' comments" are how they spot its code
• Geoffrey Litt's thesis: "reading is hard work" — agents produce faster than humans can understand, and raw output order (alphabetical diffs, discovery-order reports) doesn't match how a person builds understanding

The common home-grown fixes — "result first" CLAUDE.md rules, fixed report schemas (changed files → behavior → validation → risks), per-item length caps, banned-phrase lists — are all fragments of the same missing skill. This repo is that skill in one portable file, tested rather than vibes-tuned.

One caveat from those discussions is built in: verdict-first governs presentation order, not thinking order. The skill tells the agent to finish its reasoning, then write the conclusion first — not to shortcut the investigation.

Related work

The ecosystem attacks adjacent problems; none of these covers verdict-first analytical reports, which is the niche this skill fills.

When not to use it

This skill governs working communication from agent to human — replies, reports, status updates. For removing AI tells from published content (essays, posts, docs), use its sibling avoid-ai-writing; the two compose. And if you want maximum token compression at the cost of grammar, that's caveman's trade, deliberately not this one — Simplified Technical English prohibits telegraphic writing for a reason: fragments save the writer tokens by spending the reader's attention.

Credits

The framing draws on Geoffrey Litt's "Understanding is the new bottleneck"; BLUF and the Minto Pyramid Principle; the Federal Plain Language Guidelines; ASD-STE100 Simplified Technical English (sentence architecture, not the controlled dictionary); juliusbrussee/caveman (deletion targets and the never-drop-negations rule); boldsoftware/meat (report what the reader must judge; the artifact holds the mechanics); and ayghri/i-have-adhd (paragraph discipline — reducing reading load is about reordering and breaking text at thought boundaries, not just shortening it).

About

Built by Conor Bronsdon — host of Chain of Thought · GitHub · X · LinkedIn

Disclaimer

This is an independent personal project, not affiliated with, sponsored by, or endorsed by any company. All views expressed are my own.

License

MIT