English | 简体中文

Open-source skills for generating and accepting real, editable, CJK-aware PPTX decks built with PptxGenJS — verified by a deterministic QA gate, not just eyeballed.

The first released skill, themed-cn-pptx, ships two locked aesthetic recipes (editorial-grid, dark-launch), a provider-aware AI image layer (StepFun / MiniMax), and three QA tools (render QA, CJK overflow, editable-text check).

Three locked demo decks, all generated from this repo with zero API keys (solid-color / hairline fallbacks). Rendered here with LibreOffice at 150 DPI.

The .pptx files themselves are committed at examples/slides/output/ — open them in PowerPoint and edit directly.

• Editable PPTX — real .pptx, not flattened slide images; verified by pptx-editable-check.py.
• CJK-first layout — font fallback, full-width punctuation, conservative sizes; overflow predicted before render.
• Render QA gate — render-qa.mjs catches overflow, overlap, off-canvas, bad image ratios, missing page badges.
• Locked recipes — two locked aesthetic recipes (editorial-grid, dark-launch) so you stop re-deciding every detail.
• Provider-aware AI images — StepFun (recommended) / MiniMax, CN + global regions, PPT-friendly size presets.
• WCAG color QA — sRGB luminance contrast, not eyeballing; CI gate fails on P0.
• Graceful degradation — no API key? builds continue with solid-color placeholders, never crash.

git clone https://github.com/CacinieP/ppt-skills.git
cd ppt-skills
npm ci          # install locked deps
npm test        # smoke + preset palette contrast QA
npm run demos   # build all three demo PPTX (no API key needed)

Then hand a prompt to an Agent with shell access:

Make this README into an editable Chinese PPTX, ~8 slides, editorial-grid recipe.

Or install the skill directly:

npx skills add https://github.com/CacinieP/ppt-skills --skill themed-cn-pptx

A. Modify an existing deck — read the deck / build_*.js, scope the change (colors, pages, images, copy, QR, layout), edit + regenerate, then run render QA and fix until clean.

B. Generate from manuscript — extract source → decompose into slide-level messages → define theme tokens + image needs → pick reusable layouts → generate AI images, embed, run render QA.

Use skills/themed-cn-pptx/lib/ai-image.js. No key → returns null, build falls back to placeholders.

import { generateSlideImage, addImageToSlide, addImageOverlay } from "./lib/ai-image.js";

const cover = await generateSlideImage({
  provider: "stepfun-cn",        // recommended; also: stepfun-global, minimax-cn, minimax-global
  prompt: "teal tech cover background, clean whitespace, room for a title",
  usage: "cover",                // -> 1360x768 on StepFun, 16:9 on MiniMax
});

if (cover) {
  addImageToSlide(slide, cover, { x: 0, y: 0, w: 10, h: 5.625 });
  addImageOverlay(slide, pres, { color: "0B1B2B", opacity: 45 }); // 40-55% over any image with text
}

1. provider arg to generateSlideImage()
2. PPT_IMAGE_PROVIDER / AI_IMAGE_PROVIDER env
3. MiniMax only if MINIMAX_API_KEY set and no STEPFUN_API_KEY
4. Default: StepFun CN

PPT_IMAGE_PROVIDER=stepfun       # stepfun | minimax    (stepfun recommended)
PPT_IMAGE_REGION=cn              # cn | global
STEPFUN_API_KEY=sk-xxx
STEPFUN_REGION=cn                # cn -> api.stepfun.com | global -> api.stepfun.ai
STEPFUN_API_MODE=platform        # platform | step_plan
MINIMAX_API_KEY=sk-xxx
MINIMAX_REGION=global            # cn -> api.minimaxi.com | global -> api.minimax.io

The helper auto-loads .env on import; shell/CI vars take priority. Create .env locally — it's gitignored, never commit keys.

Rules: use getImageUsageConfig(usage, provider) or SIZE_MAP; never hand-mix StepFun concrete sizes with MiniMax ratios. StepFun step-image-edit-2 exposes exact PPT-friendly pixel sizes — that's why it's recommended.

Official docs: StepFun CN · StepFun Global · StepFun Step Plan · MiniMax CN

Before delivering a real deck, render and inspect:

soffice --headless --convert-to pdf deck.pptx
pdftoppm -jpeg -r 100 deck.pdf slide

Watch for: CJK overflow, cropped full-width punctuation, unreadable text on images, QR contrast, footer collisions, AI image aspect mismatches. render-qa.mjs automates the deterministic checks.

• Body text / URLs / footnotes: ≥ 4.5:1
• Large titles / icons / borders / UI: ≥ 3:1
• Never use a saturated accent as body text
• Never rely on red/green alone for status
• Text over AI images needs a 40–55% overlay

guizang-ppt-skill is a mature single-file HTML horizontal-slide deck skill — browser-first, strong aesthetic templates. This repo is a different route, not a competitor.

Two routes, complementary. Browser talks → HTML; deliverable .pptx → this repo.

ppt-skills/
  README.md            README.zh-CN.md      docs/                 # rendered demo images (committed)
  package.json         design-principles.md
  .github/workflows/ci.yml
  examples/
    build_miku_demo.mjs  build_editorial_demo.mjs  build_darklaunch_demo.mjs
    color-qa.sample.json  color-qa.presets.json  cjk-overflow.sample.json  render-qa.sample.json
    slides/output/        # the committed .pptx demos — open & edit in PowerPoint
      miku-demo.pptx  editorial-demo.pptx  darklaunch-demo.pptx
  scripts/
    smoke-test.mjs  color-qa.mjs  color-qa-presets.mjs
    render-qa.mjs   cjk-overflow-check.mjs   pptx-editable-check.py
  skills/themed-cn-pptx/
    skill.md
    references/   aesthetic-rules.md  image-constraints.md  layout-slots.md
    recipes/      recipe-editorial-grid.mjs  recipe-dark-launch.mjs  design-contract*.md
    lib/          ai-image.js  stepfun-image.js  cjk-text.js  pptx-shapes.js  zip-reader.js

✅ Suitable — needs a .pptx deliverable / later editing in PowerPoint / stable Chinese typography / QR closing slide / verifiable CI-gated build.

❌ Not suitable — only need a browser presentation (use an HTML deck skill) / large animated data dashboards / decks that must never touch PowerPoint.

For character/IP-themed decks, prefer color systems, abstract visual motifs, and user-provided licensed assets. Do not imply official endorsement; do not generate trademarked character art unless the user has rights or explicitly asks for a legally-safe, inspired-by direction.

Got a PPT skill recipe? Submit a PR under:

skills/<skill-name>/skill.md
skills/<skill-name>/lib/          # optional utility code
skills/<skill-name>/examples/     # optional build scripts

MIT