Minto

Minto is an installable skill for Claude Code and Codex that applies the Minto Pyramid Principle to business writing and thinking.

Website: welltraum.github.io/minto

It turns a topic into the reader's question, puts one answer at the top, groups supporting ideas by kind, checks the logic for overlaps and gaps, and makes the result easy to scan. The instructions are written in English, but the skill answers in the language of the source material or request, including Russian.

What it does

Minto routes a request into one of five modes:

• intent: interview the author and turn a vague goal into a reader question, one-sentence answer, and provisional key line.
• audit: diagnose pyramid-logic defects without rewriting the document.
• write: draft or restructure an answer-first memo, email, one-pager, decision note, chat update, or deck storyline.
• digest: report on read sources answer-first in chat, with source references and cross-source synthesis; for one long source (a talk, a transcript) the digest shows three levels — the claim, its conclusions, and the concrete supports with locators.
• viz: render the pyramid and SCQ flow in Mermaid, with an optional self-contained HTML view when explicitly requested.

The skill preserves source facts, marks unsupported gaps instead of inventing evidence, and adapts directness and context to the document's reader and genre.

Install

Claude Code

claude plugin marketplace add welltraum/minto
claude plugin install minto@minto

Restart Claude Code or run /reload-plugins, then invoke the skill explicitly:

/minto:minto

Claude can also invoke the skill automatically when a request matches its description. See the official Claude Code plugin and marketplace documentation for scopes and update behavior.

Codex

codex plugin marketplace add welltraum/minto
codex plugin add minto@minto

Start a new Codex session, then invoke:

$minto

You can also open /plugins in Codex CLI and install Minto from the configured marketplace. Plugins are not available in the Codex IDE extension; this repository includes a .agents/skills/minto symlink so the skill is available when developing the repository itself. See the official Codex plugin packaging guide.

Example requests

Use Minto intent mode to clarify what this board note must achieve.

Audit this proposal for pyramid logic. Do not rewrite it.

Rewrite these notes as a one-page decision memo, answer first.

Show the resulting pyramid and SCQ flow in Mermaid.

For a deliberately unstructured input, use messy-memo.md.

Repository layout

.
├── .agents/plugins/marketplace.json
├── .claude-plugin/marketplace.json
├── plugins/minto/
│   ├── .claude-plugin/plugin.json
│   ├── .codex-plugin/plugin.json
│   └── skills/minto/
│       ├── SKILL.md
│       ├── agents/openai.yaml
│       ├── assets/
│       └── references/
└── eval/

plugins/minto/skills/minto/SKILL.md is the only copy of the skill. Both plugin manifests package that same directory.

Local development

Validate and test Claude Code directly from the checkout:

claude plugin validate --strict ./plugins/minto
claude plugin validate --strict .
claude --plugin-dir ./plugins/minto

Validate the Codex package:

python3 /path/to/plugin-creator/scripts/validate_plugin.py ./plugins/minto
python3 /path/to/skill-creator/scripts/quick_validate.py \
  ./plugins/minto/skills/minto

Build the evaluation prompts and run the pinned benchmark:

bash eval/build-prompts.sh
PARALLEL_ENGINES=1 NEURALDEEP_API_KEY=... \
NEURALDEEP_MODELS="gpt-oss-120b qwen3.6-35b-a3b qwen3.6-fp8 qwen3.8-27b" \
NEURALDEEP_MAX_TOKENS=24576 bash eval/run-cli.sh eval/runs/v1.7.0-final \
  "skill control" "" \
  "gpt-oss-120b qwen3.6-35b-a3b qwen3.6-fp8 qwen3.8-27b codex haiku45 sonnet5 opus5"
SHUFFLE_SEED=v1.7.0-final bash eval/shuffle.sh eval/runs/v1.7.0-final
bash eval/run-judge.sh eval/runs/v1.7.0-final
python3 eval/aggregate.py eval/runs/v1.7.0-final --allow-partial
bash eval/build-report.sh eval/runs/v1.7.0-final eval/report-v1.7.0.md

The benchmark on the site (v1.7.0-final) uses eleven English fixtures, eight engines, and two arms (skill and control) for 172 judged cells, all generated at low reasoning effort; it measures the 1.7.0 skill text. The 1.8.0 revision was measured on the twelfth fixture only, against the 1.7.0 text and through removal tests of each edit — see CHANGELOG.md and eval/report-v1.8.0.md; the site figures were not re-run for it. Model identifiers, CLI versions, effort settings, UTC time, and the commit SHA are recorded with the run. Every published figure is computed from the verdicts by eval/aggregate.py; nothing downstream recomputes it. See eval/README.md for the arms, the isolation each engine runs under, and which release a given run belongs to.

Evaluation sources

The book-derived fixtures are faithful paraphrases of examples in Barbara Minto's The Minto Pyramid Principle: Logic in Writing, Thinking and Problem Solving (2010), including Big Chief, TTV, Period Graph Books, the meeting note, the board-role memo, and the project-team headings example.

The source book and online course are copyrighted and are not distributed with this repository. Fixtures preserve the structural problem and evaluation target without reproducing long source passages. The modern technical-debt fixture is an original paraphrase inspired by a Planio article. The digest, rollout-review, and plain-list fixtures are modeled on real usage patterns with every company, product, person, system, and number invented for the benchmark. The talk-digest fixture is a condensed English translation of a public 2026 conference talk on agent-driven development, with the speaker anonymized and one company name in an example replaced.

Releasing

The version string is what both hosts use to decide that an update exists: Codex caches a plugin under <name>/<version>/ and Claude Code records the installed version, so skill text that changes without a bump never reaches an installed user. Three files carry that string:

• .claude-plugin/marketplace.json
• plugins/minto/.claude-plugin/plugin.json
• plugins/minto/.codex-plugin/plugin.json

Bump all three together, add the matching ## <version> - <date> section to CHANGELOG.md, and verify before pushing:

python3 scripts/check_manifest_versions.py

The check fails when the manifests disagree, when the changelog has no section for the version, and when plugins/minto has changed since the latest tag while the version has not. It runs in CI on pull requests and on main, and with --tag against the tag name when a v* tag is pushed.

Both hosts install from the default branch, so a release reaches users only once it is merged into main and tagged vX.Y.Z.

Updating

Claude Code:

claude plugin marketplace update minto
claude plugin update minto@minto

Codex:

codex plugin marketplace upgrade minto
codex plugin add minto@minto

Start a new session after an update so the host loads the new skill contents.

License

The plugin code and original documentation are available under the MIT License. Minto Pyramid Principle source material remains the property of its respective rights holders.