minto-pyramid

An Agent Skill that makes your coding agent write the way consultants are taught to write: answer first, then the reasons, then the evidence.

Works in Claude Code, Claude Desktop, and anything else that reads Agent Skills. One file, no dependencies.

Install

git clone https://github.com/millwright-labs/minto-pyramid-skill ~/.claude/skills/minto-pyramid

Windows (PowerShell):

git clone https://github.com/millwright-labs/minto-pyramid-skill "$env:USERPROFILE\.claude\skills\minto-pyramid"

Or hand the repo URL to your agent and ask it to install the skill. Or download SKILL.md and drop it in ~/.claude/skills/minto-pyramid/SKILL.md. Restart your session and it's live.

Use

It asks before it rewrites you. That's the design. When it loads on a draft you shared, it doesn't hand back a restructured version — it says one line about what it noticed and waits:

"This looks like a pyramid case — your recommendation lands in paragraph four. Want me to restructure it, conclusion first?"

Say yes and it goes. Say nothing and your draft stays yours. You know who the reader is, what's political, and what was already settled on a call; the agent doesn't. The exceptions are when you asked for it outright, or asked the agent to write the document — then it just does the work:

Use the minto-pyramid skill on this draft.

And when the document isn't a decision document at all — a timeline, a runbook, a thank-you note — it says so in a line and leaves it alone.

Five operations are defined inside: restructure, buried-lede test, reason audit, so-what pass, email version. Ask for one by name, or hand over a draft and let it start with the restructure.

What it actually does

The default order for a model is narrative: background, then findings, then the point — because that's the order most prose is written in. It buries the one line your reader needed. This skill inverts the order, enforces Minto's grouping rules on the middle layer, and bars the model from inventing facts while it tightens.

It is deliberately narrow. It declines incident timelines, runbooks, tutorials, and anything where chronology is the content, because forcing a pyramid onto those makes them worse.

Known limits

The restraint behaviour — offering instead of rewriting, declining documents it shouldn't touch — is verified on Opus, Sonnet, GPT-5 and Gemini. It does not hold on Haiku, which restructured an incident timeline into a postmortem template, invented figures while "helping", and on one run matched a different installed skill altogether. Full detail in evals/RESULTS.md. Use it on a frontier model, or check its output when you don't.

Provenance and fact-check

The idea came from an Instagram post by @thewizeai (16 Aug 2026). The five prompts in that post are the seed of the five operations here. The framing around them had some slippage, so everything was checked before it was written down, and the skill was then reviewed by three other models and tested against a control.

Checks that held