minto-pyramid

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

• Barbara Minto joined McKinsey in 1963 in Cleveland and moved to the London office in 1966. (Wikipedia, secondary)
• Minto says she coined MECE. (McKinsey alumni interview: "MECE: I invented it, so I get to say how to pronounce it" — her own account, not independent confirmation)
• The pyramid's rules: every idea summarizes the ideas grouped below it, each group answers the question its parent raises, ideas in a grouping are the same kind of idea and in a logical order.
• MECE tests inductive groupings. It does not test a deductive chain, where premises force the conclusion jointly. Most short summaries of Minto blur the two.

Corrections made

• "Exactly three reasons." The post hard-codes three; so does most of the internet. It isn't one of Minto's rules — the logic determines the count. Forcing three is what manufactures the filler reason.
• SCQA and the grouping rules are missing from the post entirely. They're the part that makes the middle layer hold up, so both are here.
• "The first woman McKinsey hired into consulting." The documented claim is narrower — the first female MBA McKinsey hired. The skill makes no biographical claim at all, so this correction lives here rather than there.
• Publication date: unsettled, so the skill doesn't state one. Minto's own site says the book "was written in 1987 and re-issued by the publisher unchanged in 2002" (barbaraminto.com); earlier editions circulated from 1981; Wikipedia's 1985 doesn't match either. The expanded Minto Pyramid Principle is 1996.
• No primary source is cited above. The book itself was not consulted; these are author statements and secondary summaries, labelled as such.

Tested

The same messy 400-word recommendation email was rewritten twice: once by an agent with this skill, once by an identical agent without it. Both led with the recommendation — a capable model already does that much. With the skill, the three-week investigation narrative was cut as process rather than evidence, the reasons were grouped as reasons instead of listed as vendors, and the risks survived in their own section. The skilled run also sharpened one of the source's facts into something stronger than the original said, while the control left it alone — which is why "invent nothing" is now written into every operation, and why the worked example was rebuilt so both versions carry identical facts.

Expect the gain to be largest on long documents and weaker models, and smallest on a short email in a frontier model that was already going to lead with the ask.

License

MIT — Millwright Labs.