/Mck-ppt-design-skill

name: mck-ppt-design
description: >-
  Create professional, consultant-grade PowerPoint presentations from scratch
  using MckEngine (python-pptx wrapper) with McKinsey-style design. Use when
  user asks to create slides, pitch decks, business presentations, strategy
  decks, quarterly reviews, board meeting slides, or any professional PPTX.
  AI calls eng.cover(), eng.donut(), eng.timeline() etc — 67 high-level methods
  across 12 categories (structure, data, framework, comparison, narrative,
  timeline, team, charts, images, advanced viz, dashboards, visual storytelling),
  consistent typography, zero file-corruption issues, BLOCK_ARC native shapes
  for circular charts (donut, pie, gauge), production-hardened guard rails
  for spacing, overflow, legend consistency, title style uniformity,
  dynamic sizing for variable-count layouts, horizontal item overflow
  protection, chart rendering, and
  AI-generated cover images via Tencent Hunyuan 2.0 with professional cutout,
  cool grey-blue tint, and McKinsey-style Bézier ribbon decoration.

McKinsey PPT Design — Harness Framework

> **Version**: 2.3.3-harness-v2 · **Engine**: MckEngine (python-pptx) · **Author**: [likaku](https://github.com/likaku/Mck-ppt-design-skill) > > **Required tools**: Read, Write, Bash · **Requires**: `pip install python-pptx lxml`

---

常见崩坏模式（每次生成前必读，先于 HARD RULES）

> 告诉 AI 要做什么效果一般，告诉它前人最容易在哪里塌效果更好。 > 以下三种反模式均已在真实执行中被验证，每次必须主动警惕。

反模式 1：口头宣布"门禁通过"（最常见）

**错误做法**： > 「S4 QA 共 7 个 errors，判断均为 engine 设计行为，门禁通过，进入 S5」

**问题所在**：`passed` 是由 AI 口头判断的，不是由程序派生的。无论理由多充分，这句话都是 AI 在给自己写完成证书。

**正确做法**： 1. 执行 `python references/scripts/gate_check.py <pptx路径> <项目目录>` 2. 读取 `<项目目录>/gate_result.json` 3. 只有 `gate_result.json` 中 `"passed": true` 时，才能进入 S5 4. 如果 `"passed": false`，修复 `user_code_errors` 列表中的问题，重新渲染，再次执行 gate_check

---

反模式 2：S3 门禁"脑子里过一遍"就算通过

**错误做法**： > 「S3 内容门禁预检：API 格式正确，字数在限制内，通过，进入 S4」（没有执行任何代码）

**问题所在**：今天真实发生的 3 个 API 格式错误（`four_column`/`matrix_2x2`/`executive_summary` 参数格式），靠脑子过是过不出来的，必须靠代码检查。

**正确做法**： 1. 执行 `python references/scripts/gate_check_s3.py <content.json路径> <项目目录>` 2. 读取 `<项目目录>/gate_s3.json` 3. 只有 `"passed": true` 时，才能进入 S4 4. 如果有 `fail` 项，修正 `content.json`，重新执行 gate_check_s3

---

反模式 3：engine_bug 分类作为软话逃生口

**错误做法**： > 「peer_font_inconsistency 是 engine 内部设计行为，不是用户代码问题，可以放行」

**问题所在**：这个分类本身是正确的，但由 AI 在对话里口头做出，等于把豁免权交给了 AI 自己——而 AI 有动机让自己通过。

**正确做法**： `gate_check.py` 里有硬编码的 `ENGINE_BUG_WHITELIST` 枚举。只有在白名单里的 error category，才会被豁免。白名单是代码，不是 AI 的判断。如果你认为某类 error 应该加入白名单，修改 `gate_check.py` 里的枚举，而不是口头声明豁免。

---

HARD RULES（必须遵守，不可绕过）

1. **每次生成必须走五阶段流程**，不允许"一句话直接生成"跳过前置阶段 2. **TaskCreate 驱动进度**：开始前创建5个 task，每阶段完成后立即 TaskUpdate completed 3. **按需加载上下文**：每个阶段只读对应文件，不要全量加载旧版 SKILL.md 里的内容 4. **门禁必须机读化**：S3 和 S4 门禁必须执行对应的 gate_check 脚本，读 JSON 结果，不得口头判断 5. **Self-Refinement 必做**：每次修正 pattern-level 问题后，写入 `experiences/` 对应文件 6. **引擎路径固定**：`sys.path.insert(0, os.path.expanduser('~/.workbuddy/skills/mck-ppt-design'))`

---

知识路由（上下文加载索引）

> **在每个阶段开始时，读对应文件**。不要一次性全读。

| 阶段 | 必须读 | 说明 | |------|--------|------| | S1 需求 | `references/team/brand-guide.md` | 了解设计约束 | | S2 结构 | `references/framework/engine-api.md` + `references/layout-matrix.yaml` | 版式选择和能力边界 | | S3 内容 | `references/framework/guard-rails.md` + `experiences/*.md`（存在时）| 防溢出规则 + 历史踩坑 | | S4 渲染 | 用到的 `references/layouts/*.md`（只读实际用到的版式）| 版式实现细节 | | S5 交付 | 无 | — |

**完整路由表**：`references/INDEX.md`

---

五阶段生成流程

┌─────────┐   ┌─────────────┐   ┌─────────────┐   ┌──────────────┐   ┌──────────┐
│ S1 需求  │──▶│ S2 结构 ⭐   │──▶│ S3 内容 ⭐   │──▶│ S4 渲染+QA ⭐⭐│──▶│ S5 交付   │
│ brief.md│   │ outline.json│   │content.json │   │  .pptx       │   │ + 沉淀   │
└─────────┘   └─────────────┘   └─────────────┘   └──────────────┘   └──────────┘
                    ⭐ = 门禁（FAIL 则在本阶段修正，不得跳过）
    S3/S4 门禁必须运行 gate_check 脚本，读 JSON 结果 — 不得口头宣布通过

Stage 1: 需求定义

**读文件**：`references/team/brand-guide.md`

**收集信息**：

• 受众（职位/决策角色）
• 目标（决策/汇报/说服）
• 时长（分钟数 → 约 1 分钟/页）
• 关键信息（最多 5 条核心 message）
• 数据来源（有哪些数据可用）

**产出**：在工作目录创建 `ppt-project-{slug}/brief.md`

**门禁**：`audience` + `goal` + `key_messages` 三项非空（AI 自评即可）

---

Stage 2: 结构设计

**读文件**：`references/framework/engine-api.md`, `references/layout-matrix.yaml`

**任务**： 1. 根据时长确定页数（1分钟/页） 2. 为每张幻灯片选定 `layout`（查 engine-api.md 速查表） 3. 每页写一句核心 `key_point`（完整句子，不是标签） 4. 确认版式在能力边界内（查 layout-matrix.yaml）

**产出**：`ppt-project-{slug}/outline.json`

{
  "brief": {"audience": "董事会", "goal": "战略汇报", "duration_minutes": 15},
  "slides": [
    {"idx": 1, "layout": "cover", "title": "Q1 2026 战略回顾", "key_point": ""},
    {"idx": 2, "layout": "toc", "title": "目录", "key_point": ""},
    {"idx": 3, "layout": "table_insight", "title": "市场格局三大转变驱动战略重构", "key_point": ""}
  ]
}

**⭐ 门禁 S2**（AI 自评）：

• [ ] `cover` 幻灯片存在
• [ ] 幻灯片数量在时长约束内（`count <= duration_minutes * 1.2`）
• [ ] 所有 layout 在 `layout-matrix.yaml` 中有定义
• [ ] Action Title 均为完整句子（len > 10，包含动词）
• [ ] `two_column_text` 数量 ≤ 1

---

Stage 3: 内容填充

**读文件**：`references/framework/guard-rails.md`, `experiences/*.md`（全部存在的文件）

**任务**： 1. 为每张幻灯片填充具体文案、数字、图表数据 2. 确保每页有 `source` 出处 3. 按 `layout-matrix.yaml` 的 `char_budget` 控制文字量

**产出**：`ppt-project-{slug}/content.json`

**⭐ 门禁 S3**（必须机读化，不得 AI 自评）：

python ~/.workbuddy/skills/mck-ppt-design/references/scripts/gate_check_s3.py \
    <项目目录>/content.json  <项目目录>

读取 `<项目目录>/gate_s3.json`：

• `"passed": true` → 进入 S4
• `"passed": false` → 修正 `content.json` 中 `fail_items` 列出的问题，重新执行

---

Stage 4: 渲染 + QA

**读文件**：用到的版式对应的 `references/layouts/*.md`

**任务**： 1. 根据 `content.json` 生成 Python 渲染脚本 2. 执行脚本生成 `.pptx` 3. 运行 QA 门禁脚本

**⭐⭐ 门禁 S4**（必须机读化，不得口头宣布通过）：

python ~/.workbuddy/skills/mck-ppt-design/references/scripts/gate_check.py \
    <pptx路径>  <项目目录>

读取 `<项目目录>/gate_result.json`：

• `"passed": true` → 进入 S5
• `"passed": false` → 查看 `user_code_errors`，修复渲染代码，重新渲染，再次执行

**注意**：`engine_bug` 类 errors（`peer_font_inconsistency` 等白名单条目）由脚本自动豁免，不需要 AI 口头判断。

**产出**：`<项目目录