likaku/mck-ppt-design-skill

---

🖼️ Sample Output

---

⚡ Quick Start

pip install python-pptx lxml

import sys, os
sys.path.insert(0, os.path.expanduser('~/.workbuddy/skills/mck-ppt-design'))
from mck_ppt import MckEngine
from mck_ppt.constants import *

eng = MckEngine(total_slides=12)
eng.cover(title='Q1 2026 Strategy Review', subtitle='Board Presentation', date='2026')
eng.toc(items=[('1', 'Market Overview', 'Current landscape'), ('2', 'Strategy', 'Key actions')])
eng.table_insight(title='Three shifts driving market restructuring',
    headers=['Dimension', 'Before', 'After'],
    rows=[['Distribution', 'Offline-first', 'Digital-first'],
          ['Pricing', 'Cost-plus', 'Value-based']],
    insights=['Digital channels now control 60% of CAC', 'Value pricing unlocks 3× margins'])
eng.donut(title='Revenue Mix', segments=[(0.45, NAVY, 'Product'), (0.35, ACCENT_BLUE, 'Service'), (0.20, ACCENT_GREEN, 'Other')])
eng.timeline(title='12-month roadmap', milestones=[('Q1', 'Foundation'), ('Q2', 'Pilot'), ('Q3', 'Scale'), ('Q4', 'Review')])
eng.closing(title='Thank You')
eng.save('output/deck.pptx')

AI Agent Compatibility

---

🔱 Harness Engineering Mode

New in v2.3.3-harness — Transforms the skill from vibe-coding into structured 5-stage generation with machine-readable gates.

The Problem: Vibe Coding vs. Harness

Without Harness, the entire 3,967-line SKILL.md was loaded every time, AI jumped straight to code, and errors were only discovered after rendering. With Harness, context is loaded progressively, structure is locked before content, and gates run as Python scripts — not AI self-evaluation.

Note on QA scores: The no-Harness deck scored higher because it used simpler layouts (fewer QA rules triggered). The Harness deck used richer layouts (donut, matrix_2×2, value_chain) that expose more QA checks. QA score measures layout health, not content quality — they are different dimensions.

5-Stage Generation Flow

┌─────────┐   ┌────────────────┐   ┌───────────────────┐   ┌──────────────────┐   ┌──────────┐
│ S1      │──▶│ S2 ⭐           │──▶│ S3 ⭐              │──▶│ S4 ⭐⭐           │──▶│ S5       │
│ Brief   │   │ Structure      │   │ Content           │   │ Render + QA      │   │ Deliver  │
│ brief.md│   │ outline.json   │   │ content.json      │   │ .pptx            │   │ + Learn  │
└─────────┘   └────────────────┘   └───────────────────┘   └──────────────────┘   └──────────┘
                   ⭐ = gate (FAIL → fix in current stage, never skip)
                   S3/S4 gates run Python scripts → read JSON result → no AI self-eval

Machine-Readable Gates (the key innovation)

S3 Gate — Content audit before rendering:

python ~/.workbuddy/skills/mck-ppt-design/references/scripts/gate_check_s3.py \
    ./ppt-project-foo/content.json  ./ppt-project-foo/

Checks (all automatic, no AI judgment):

• four_column / executive_summary / meet_the_team items are 3-tuples (num, title, desc)
• matrix_2x2 quadrants are 3-tuples (label, bg_color, desc) — exactly 4
• process_chevron steps ≤ 5, labels contain no \n, desc ≤ 50 chars
• donut / pie segments ≤ 6
• grouped_bar categories ≤ 6, series ≤ 3
• Every content slide has a non-empty source
• Action titles are full sentences (> 10 chars)

Output gate_s3.json:

{
  "passed": true,
  "verdict": "PASS — 可进入 S4 渲染",
  "fail_items": [],
  "pass_items": [...]
}

S4 Gate — QA after rendering:

python ~/.workbuddy/skills/mck-ppt-design/references/scripts/gate_check.py \
    ./output.pptx  ./ppt-project-foo/

Classifies every QA error as user_code (must fix) or engine_bug (whitelisted, with written evidence). passed = user_code_errors == 0. AI cannot override this.

Output gate_result.json:

{
  "passed": true,
  "overall_score": 92,
  "checklist": {
    "user_code_errors": 0,
    "engine_bug_errors": 7,
    "warnings": 1
  },
  "verdict": "PASS — 可进入 S5 交付",
  "user_code_error_detail": []
}

Anti-Patterns (from SKILL.md — read before every generation)

The three most common failure modes observed in real execution:

1. “Gate passed” without running the script — AI declares pass based on self-assessment. Fix: read gate_result.json. If file doesn’t exist, gate hasn’t run.
2. S3 “checked in my head” — Mental review misses API format errors every time. Fix: run gate_check_s3.py. Today’s 3 API format bugs were all caught by script, none by self-review.
3. “engine_bug” as escape hatch — AI reclassifies user errors as engine bugs to pass the gate. Fix: ENGINE_BUG_WHITELIST in gate_check.py is code, not AI judgment. Add to whitelist only with written evidence.

Knowledge Structure

~/.workbuddy/skills/mck-ppt-design/
├── SKILL.md                     # Entry (~245 lines): flow + hard rules + index
│                                  (was 3,967 lines before Harness)
├── references/
│   ├── INDEX.md                 # Per-stage load router
│   ├── layout-matrix.yaml       # Layout × theme × char_budget (source of truth)
│   ├── team/
│   │   ├── brand-guide.md       # Colors, fonts, design principles
│   │   └── presentation-convention.md
│   ├── framework/
│   │   ├── engine-api.md        # 67-method API quick reference
│   │   ├── guard-rails.md       # 10 production rules
│   │   └── planning-guide.md    # Layout selection, content density
│   └── scripts/
│       ├── gate_check.py        # S4 gate: QA classification → gate_result.json
│       └── gate_check_s3.py     # S3 gate: API format + count → gate_s3.json
└── experiences/
    ├── overflow.md              # Text overflow patterns (6 entries)
    ├── chart-limits.md          # Chart data limits (2 entries)
    ├── layout-pitfalls.md       # Layout-specific traps (5 entries)
    └── cjk-issues.md            # CJK rendering (2 entries)

---

🏗️ Architecture

v1.x → v2.0: GPU → CPU Shift

The fundamental change in v2.0: moving ~80% of compute from GPU (LLM inference) to CPU (deterministic Python execution).

In v1.x, every coordinate, every color, every spacing value was produced by the model token-by-token. A single donut chart required 2,800 add_rect() calls — each one a GPU-computed token. A 30-slide deck burned 40,000–60,000 output tokens and ~2 minutes per chart.

v2.0 extracts that deterministic work into Python: eng.donut() → 20 AI tokens → 2,745 lines of CPU execution.

5-Layer Architecture (v2.3.3-harness)

┌──────────────────────────────────────────────────────────┐
│  L5  Harness Engineering (v2.3.3-harness)                │
│      5-stage flow · 4 gates · 3-tier knowledge           │
│      machine-readable gates · self-refinement loop       │
├──────────────────────────────────────────────────────────┤
│  L4  Post-Processing Pipeline                            │
│      Three-layer XML corruption defense                  │
│      Full p:style / shadow / 3D sanitization             │
│      CJK font injection (KaiTi for all East Asian text)  │
├──────────────────────────────────────────────────────────┤
│  L3  Review + Auto-fix Pipeline (v2.3)                   │
│      Dual QA (layout + narrative) → AutoFixPipeline      │
│      Peer font harmonization · Gate: 0 ERROR = PASS      │
├──────────────────────────────────────────────────────────┤
│  L2  Python Runtime Engine (mck_ppt/)                    │
│      67 high-level layout methods                        │
│      Drawing primitives · XML cleanup · Constants        │
│      BLOCK_ARC chart engine · AI cover image (v2.2)      │
├──────────────────────────────────────────────────────────┤
│  L1  Design Specification                                │
│      Color system + typography + layout patterns         │
│      (Split into references/ for progressive loading)    │
└──────────────────────────────────────────────────────────┘

---

🛡️ Production Guard Rails

13 rules hard-won from production use:

---

📁 Project Structure

├── SKILL.md                     # Harness entry (~245 lines, was 3,967)
├── mck_ppt/                     # Python runtime engine
│   ├── engine.py                # 67 layout methods
│   ├── core.py                  # Drawing primitives + XML cleanup
│   ├── constants.py             # Colors, typography, grid
│   ├── qa.py                    # Layout QA engine
│   ├── review.py                # Review + auto-fix pipeline
│   ├── deck_builder.py          # Storyline-driven deck generator
│   ├── cover_image.py           # AI cover image (Hunyuan 2.0)
│   └── storylines/              # Pre-built storyline templates
├── references/
│   ├── INDEX.md                 # Per-stage knowledge router
│   ├── layout-matrix.yaml       # Layout × char_budget (source of truth)
│   ├── team/                    # Brand guide, presentation conventions
│   ├── framework/               # Engine API, guard rails, planning guide
│   └── scripts/
│       ├── gate_check.py        # S4 QA gate → gate_result.json
│       └── gate_check_s3.py     # S3 content gate → gate_s3.json
├── experiences/
│   ├── overflow.md              # Accumulated overflow lessons
│   ├── chart-limits.md          # Chart data limits
│   ├── layout-pitfalls.md       # Layout-specific pitfalls
│   └── cjk-issues.md            # CJK rendering issues
├── assets/icons/                # 6 pre-built PNG icons
├── examples/                    # Minimal example + staircase demo
└── CHANGELOG.md

---

📊 Version History

---

Community

---

中文说明

---