Strategy Consulting Visualization Skill

Messy notes in. Board-ready slides out.

One skill for your AI agent: turn notes, metrics, and prose into consulting-grade visuals — as real SVG slides, as an animated HTML deck, or as a spec any designer or tool can execute.

Python 3 standard library only. Zero dependencies. Zero API keys. Zero network calls.

English | 日本語

An actual deck built by this repo: specs (JSON) → SVG slides → animated HTML deck. Nothing hand-drawn.

Why This Gets Starred

• Install it and get a complete deck immediately. scripts/scaffold_deck.py <archetype> copies a full, coherent 9-12 slide deck — cover through closing — into a working directory. Swap the illustrative data for yours and build. Six archetypes ship, one in Japanese.
• It actually renders. 22 patterns produce real SVG slides — waterfall, executive summary, 2×2, scatter, heatmap, Gantt, small multiples, cover, section dividers, agendas, closings, and more. Every gallery image below is committed renderer output, verified fresh by CI on every push.
• Animated HTML decks from one command. Combine slides into a single self-contained HTML file: quiet staggered reveals, keyboard navigation, progress bar, zero external requests. Press p → your browser prints it → you have a PDF.
• A browser-native report mode. scripts/build_html_report.py turns Markdown into a self-contained, print-to-A4 HTML document with numbered exhibits — the same visual system, for documents instead of decks.
• Works with your slide tools. The SVGs drop straight into PowerPoint, Keynote, and Word (Insert → Picture). For Google Slides, export PNG from any browser first.
• Japanese business documents are first-class. CJK text wraps correctly (measured per fullwidth character, not by spaces), fonts fall back to Noto Sans JP / Hiragino, and there are dedicated profiles for 稟議書, 役員会資料, 週報, 学会抄録.
• Charts that survive an audit. Bar proportions match the data (Lie Factor ≈ 1.0), zero baselines are marked, cell text passes WCAG AA contrast across the whole color ramp, and the accent navy stays readable in greyscale print — all of it asserted in the test suite, not promised in prose.
• Roasted by five design legends, then fixed. We ran the whole system through a five-perspective design panel — Tufte's data-ink discipline, an ex-McKinsey chart master, Swiss grid typography, FT-style data journalism, and modern design engineering. They scored it 5.8/10 and listed every flaw. A previous release shipped every fix. Read the receipts.

60-Second Start

# 1. Get it (this is also how you install it as an agent skill)
git clone https://github.com/kgraph57/mckinsey-style-visualization-skill.git ~/.claude/skills/strategy-consulting-visualization
cd ~/.claude/skills/strategy-consulting-visualization

# 2. Render one slide → SVG
python3 scripts/render_slide_spec.py examples/render-specs/arr-waterfall.json -o slide.svg

# 3. Build the full animated deck → one HTML file
python3 scripts/build_html_deck.py --manifest examples/demo-deck.json -o deck.html
open deck.html   # ← arrows to navigate, "p" to print → PDF

Or skip the terminal and just ask your agent:

Use the strategy consulting visualization skill to turn these notes into a board slide:
ARR grew from $10M to $15M. Enterprise added $3M, expansion $2.5M, churn -$0.5M.
The board must decide on implementation capacity investment.

The Pipeline

flowchart LR
    A["Messy notes,<br/>metrics, prose"] --> B["Slide spec<br/>(JSON)"]
    B --> C["SVG slides"]
    C --> D["Animated HTML deck"]
    C --> E["PowerPoint / Keynote / Word<br/>(insert SVG)"]
    D --> F["PDF<br/>(browser print)"]

Loading

Specs are plain JSON, so they diff, review, and version like code. The renderer and deck builder are single-file Python scripts with no installs.

Gallery

Every image is committed output of scripts/render_slide_spec.py — CI fails if any of them drifts from what the renderer actually produces. Specs live in examples/render-specs/.

ARR Waterfall	Executive Summary Strip

Small Multiples	Scatter / Correlation

Japanese Board Summary（役員会サマリー）	Cover Slide

Benchmark Table	Distribution

Capacity Gap	Process Flow

22 patterns render to SVG: cover, section_divider, end_cover, agenda, bullet_list, closing, quote, waterfall, gap, before_after, time_series, benchmark_table, summary_strip, process_flow, funnel, heatmap, gantt, kpi_scorecard, two_by_two, scatter, distribution, small_multiples. Thirteen more patterns (Sankey, pyramid, maps, decision trees, …) ship as structured specs and image-generation prompts — the catalog says exactly which is which. We don't pretend.

Animated HTML Decks

python3 scripts/build_html_deck.py cover.json bridge.json summary.json -o deck.html --title "Q4 Review"

One command, one file, and you get:

• Quiet, staggered element reveals on every slide — the restrained kind, not slide-carnival transitions (prefers-reduced-motion respected)
• Keyboard + click navigation, progress bar, slide counter, deep links (deck.html#3)
• Print stylesheet: p or Cmd+P gives you one slide per page → save as PDF
• Zero external requests — fonts, styles, scripts, and SVGs are all inline. Email it, host it, present offline.

Try the committed demo: examples/demo-deck.html (open locally after cloning).

Instant Deck: Scaffold → Build

Skip writing specs from a blank page. Pick an archetype, copy it, swap in real data:

python3 scripts/scaffold_deck.py --list                    # see all 6 archetypes + slide counts
python3 scripts/scaffold_deck.py board-update -o my-deck --title "FY27 Board Update"
# edit my-deck/specs/*.json with real numbers — the pattern shapes are already right
python3 scripts/build_html_deck.py --manifest my-deck/deck.json -o my-deck/deck.html

scaffold_deck.py refuses to overwrite a non-empty directory unless you pass --force, and prints the next two commands when it's done.

Template Gallery

Six deck archetypes ship pre-filled with a coherent illustrative storyline — every slide renders, nothing is a stub.

Archetype	Use For	Storyline
board-update	Recurring board / steering updates	Cover → agenda → executive summary → KPI scorecard → ARR waterfall → trend → risk view → closing → end cover
strategy-recommendation	"Where to play, how to win" strategy decks	Cover → agenda → context → two section dividers (Where to play / How to win) → 2×2 → benchmark table → gap or bridge → roadmap → closing → end cover
project-status	PMO / steering-committee status reviews	Cover → summary → roadmap → KPI scorecard → blockers → path-to-green flow → closing → end cover
market-entry	Entry or expansion investment cases	Cover → agenda → market trend → competitor benchmark → segment 2×2 → entry-path flow → distribution or scatter → closing → end cover
sales-proposal	Customer-facing proposals	Cover → client situation → before/after → approach flow → plan → why-us benchmark → customer quote → closing → end cover
board-update-ja	役員会向け月次アップデート（日本語）	board-update と同じ構成を、翻訳調ではなく自然な日本語の見出しで

Report Mode: Markdown → Browser Document

For a document instead of a deck, write Markdown and build it straight to a single self-contained, print-to-A4 HTML report:

python3 scripts/build_html_report.py my-report.md -o my-report.html --lang en

• Front matter (title, subtitle, author, date, classification, lang) drives a navy title band — the only navy surface in the document.
• ##/### headings auto-number and build a "Contents" TOC with anchor links; standard Markdown (bullets, ordered lists, tables, bold/italic, code, blockquotes, links) renders as clean editorial typography — everything HTML-escaped first, so nothing in the source can inject markup.
• Drop in a rendered chart with ![Caption](spec:path/to/spec.json) — it becomes an auto-numbered Exhibit N — Caption with the full slide SVG embedded inline, no header/footer chrome needed. ![Caption](svg:path.svg) embeds an existing SVG file the same way.
• p / Cmd+P exports an A4-portrait PDF with the title band as the first page.
• Zero external requests — same self-contained guarantee as the HTML deck.

Three starting points ship in templates/reports/: board-pre-read.md, one-pager.md, proposal-memo.md. See the committed demo: examples/demo-report.html (built from examples/demo-report.md).

Speaker Script: What You Read at the Podium

Any slide spec can carry a top-level "notes" field — a string, or a list of paragraph strings — holding the spoken narration for that slide. The SVG renderer ignores it completely, so adding notes never changes a rendered slide. Build the same deck manifest into a print-first, one-slide-per-page script:

python3 scripts/build_speaker_script.py --manifest my-deck/deck.json -o my-deck/script.html --lang en

• One printed A4 page per slide: the slide rendered inline above, the narration in podium-readable type below (screen 20px, print ~13.5pt; --lang ja loosens line-height to 1.9 with palt for CJK).
• A slide with no notes still gets its own page, with a muted "(no script)" / "（原稿なし）" marker — never silently skipped.
• A cover page carries the deck title and the date from the deck's own cover slide, if present.
• Zero external requests, no required JavaScript.

See the committed demo: examples/demo-script.html (built with --lang ja from templates/decks/board-update-ja/deck.json).

Deck as an Article: Read It Top to Bottom Like a Web Page

The same notes field also drives a reading-mode build: the whole deck laid out vertically on a single 680px column, each slide's SVG followed by its narration as prose — a paper-first article, like a published M3-series piece, not a side-nav document.

python3 scripts/build_html_article.py --manifest my-deck/deck.json -o my-deck/article.html --lang en

• A hero opens the page: an optional uppercase kicker from the manifest's series key, the title, an optional lead paragraph from lead (falling back to description for older manifests), and meta chips for slide count, presenter, and date (from the deck's cover slide).
• Every slide appears, in manifest order, as its own <article> on the full 680px column — meta line (number + optional per-spec label), heading, SVG, then its notes as prose. There is no "Contents" jump list in this mode; it is a single linear scroll.
• A slide with no notes renders frame-only — the article still shows every slide, like flipping through the deck.
• Optional per-slide refs ([{"label": ..., "url": ...}]) render as a "Links" aside below the notes and roll up, deduped by URL, into an "All links" section after the last slide; only http(s)/mailto URLs render as links.
• --title overrides the manifest title; zero external requests except the href of a ref link itself.

See the committed demo: examples/demo-article.html (built from templates/decks/board-update/deck.json).

Export Anywhere

Target	How	Fidelity
PDF	Open the HTML deck → print → save as PDF	Vector, one slide per page
PowerPoint / Keynote / Word	Insert the SVG files as pictures	Vector, scales losslessly
Google Slides / Docs	Render SVG → PNG in any browser, then insert	Raster at any resolution
Design tools (Figma, Illustrator)	Open the SVG directly	Fully editable vectors
Docs / wikis / GitHub	Embed the SVG — GitHub renders it inline	What you see in this README

Roasted by Five Design Legends

Most chart generators say "beautiful". We wanted defensible, so we convened a five-perspective design review panel (as rigorous AI personas) and told them to be merciless:

Reviewer lens	Verdict	Sharpest cut
Edward Tufte — data-ink, honest scales	5.5/10	"Meaningless decorated rectangles baked into the renderer"
Gene Zelazny — ex-McKinsey, Say It With Charts	6.5/10	"The flagship example violates its own headline rule"
Vignelli × Müller-Brockmann — Swiss grid	6/10	"A corporate template, not a design system"
Alan Smith — FT data journalism	5.5/10	"The waterfall draws off-canvas on negative bridges" (he proved it)
Modern design engineering	5.5/10	"2016 visuals wearing a 2020s spec sheet"

Then we shipped every fix in a prior release: zero-floor waterfalls, CJK-correct wrapping, no silent truncation, a single re-derived navy that survives greyscale printing, diverging heatmaps for signed data, WCAG-AA cell text asserted across the entire ramp, decoration stripped, a comparison-type gate before every chart choice, and a rubric that now measures data-ink integrity and deck-level storyline logic.

The result is a visual system you can defend in front of a board, an auditor, or a design critic — because it already survived one.

The Discipline Under the Hood

The renderer is the visible part. The skill underneath is a full operating system for executive visualization:

• Message first: every visual starts from the reader's decision, gets a single-proposition insight headline, and only then picks a chart — gated by the five comparison types (component / item / time series / distribution / correlation).
• A real style system: design tokens on an 8px grid, a fixed type scale, one navy, an emphasis ladder (fill > line > text) with hard caps — the same constants the renderer executes.
• A quality rubric with teeth: 24-point scoring across strategy, data integrity, data-ink honesty, hierarchy, portability, and safety, plus blocking gates (no color-only meaning, no invented data, no implied rendering that doesn't exist).
• An adversarial review loop: expert lenses that hunt overclaims, insider jargon, accessibility failures, and cultural assumptions before anything is called publishable.

By Role

The persona playbook gives every role a copy-paste prompt and a rendered example:

Role	Ask For	Rendered Example
Sales	Pipeline QBR, proposal visuals
Project manager / PMO	Roadmap with critical path
Marketing	Channel × segment performance
HR / People ops	Talent scorecard
Product manager	Effort vs. impact prioritization
Engineer / Tech lead	Incident postmortem flow
Researcher / Clinician	Study outcome summary

Japanese business formats (稟議書, 週報・月報, 役員会資料, 学会抄録, 提案書) have dedicated profiles in document-type-profiles.md.

One-Minute Example

Give the skill this:

ARR grew from $10M to $15M.
Enterprise expansion contributed $3M. Existing customers added $2.5M. Churn cost $0.5M.
AI workflow adoption grew from 18% to 64%.
The board needs to decide whether to invest in implementation capacity.

It returns a decision-framed spec — strategic question, single-proposition headline, pattern choice with reasoning, exact values and labels, assumptions, and a rubric score — that renders to the waterfall you saw in the gallery. See the full worked proof: input → slide specs → evaluation.

What You Can Point It At

Starting Point	You Get
Board update metrics	5-slide story: cover, waterfall, trend, gap, recommendation
Revenue bridge data	Waterfall with drivers, honest baselines, assumptions
Competitor / vendor data	Benchmark table + 2×2 positioning with leader highlights
KPI before/after data	Impact slide with deltas and an implication headline
Process description / SOP	Process flow with owners and the bottleneck highlighted
Segment metrics over time	Small-multiples grid on one honest shared scale
Research notes / whitepaper	Numbered report figures with sources and distributions
Any prose — "visualize this"	Input triage → right pattern → document profile → spec

Install

# Personal skill (Claude Code)
git clone https://github.com/kgraph57/mckinsey-style-visualization-skill.git ~/.claude/skills/strategy-consulting-visualization

# Project skill
git clone https://github.com/kgraph57/mckinsey-style-visualization-skill.git .claude/skills/strategy-consulting-visualization

Verify the package (same checks CI runs):

python3 -m unittest discover -s tests
python3 scripts/validate_skill.py   # → OK: skill package passed validation

The validator re-renders every committed SVG and the demo deck from source specs and fails on any drift — the gallery cannot silently rot.

Star It, Break It, Share It

If this turned your rough notes into a usable slide, star the repo — stars are how other people find tools that actually render instead of hallucinate.

Even better contributions:

• A messy input and the slide it produced (Discussions)
• A business scenario that needs a pattern we don't have (request template)
• An output that's broken, confusing, or overconfident — it becomes a regression test

Repository map & package internals

Layer	What It Does	File
Skill entrypoint	Tells agents when and how to use the skill	SKILL.md
Input triage	Maps any input to a pattern family	input-triage.md
Document profiles	Adapts format and tone per deliverable	document-type-profiles.md
Pattern library	Comparison-type gate + 35-pattern catalog	visualization-patterns.md
Style system	Tokens, palette, typography, chart rules	style-system.md
Prompt templates	Reproducible spec formats	prompt-templates.md
Quality rubric	24-point scoring + blocking gates + deck check	quality-rubric.md
Expert review loop	Adversarial pre-publication review	expert-review-loop.md
SVG renderer	Spec JSON → styled SVG slide (22 patterns)	render_slide_spec.py
Deck builder	SVG slides → animated single-file HTML deck	build_html_deck.py
Deck scaffolder	Copies a ready-made deck archetype into a working directory	scaffold_deck.py
Report builder	Markdown → self-contained, print-to-A4 HTML report	build_html_report.py
Speaker script builder	Deck manifest + notes → print-first, one-slide-per-page podium script	build_speaker_script.py
Slide article builder	Deck manifest + notes → self-contained, top-to-bottom reading article	build_html_article.py
Structural review	Lint a drafted spec document	review_slide_spec.py
Validation	Package integrity + render parity	validate_skill.py

Iterative review-loop examples (draft → review → revision, four scenarios) live in examples/review-loop/. Distribution and commercial docs: MARKETPLACE.md, BUYER_BRIEF.md, ROADMAP.md, SECURITY.md, CHANGELOG.md.

Disclaimer

This is an independent skill package. It is not affiliated with, endorsed by, or sponsored by McKinsey & Company, Boston Consulting Group, Bain & Company, or any other consulting firm. Named firms may appear only as common style references or search terms.

License

MIT. See LICENSE.