SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsgorden-ppt-skill

gorden-ppt-skill

Office & productivity

View repository

Updated 10-14 13:43

About this skill

gorden-ppt-skill

Version See same directory VERSION。

🚨 The first thing to do after enabling this Skill: run an automatic update once

Any AI in this sessionthe first time it uses this Skill，mustfirst make the following command its first tool call:

python3 scripts/apply_update.py

This command will automatically:

  1. From the remote update_source(git+ repository) pull the latest updates.json
  2. Compare the local VERSION with the remote latest_version
  3. If there is a new version → download only the files that actually changed (incremental update, no wasted LFS traffic)
  4. If it is already up to date → exit within seconds, output OK Nothing to do

⚠️ This Skill does not automatically push updates, the AI must actively pull. If this step is skipped, you may be using an outdated version, and the behavior, rules, and templates may not match the documentation.

✅ Only needs to be done once per session; subsequent tool calls do not need to repeat the check.

⚠️ Non-commercial use only: This Skill and its built-in PPT templatesare for personal study and research only，strictly prohibited for any commercial use(including commercial presentations, sales, training distribution, client proposals, internal enterprise use for profit, etc.). The template materials come from third-party designers' works; secondary commercial use requires authorization from the original authors.

When to use this Skill

Call this Skill when the user's needs meet any of the following:

  • Needs to "make a PPT / presentation / slide deck", whether it is a work report, year-end summary, quarterly review, project proposal, job application presentation, teaching courseware, thesis proposal defense, book report...
  • The user provided a text outline or a description and wants to "turn it into a PPT"
  • The user brings a .pptx file and wants to "make a new one based on this template"
  • The user wants to "adjust / edit some text in a PPT" and requires "not breaking the layout"
  • The user wants to compare multiple PPT templates and choose a suitable one

Update mechanism description

The complete update tool has two scripts:

Script What it does When to use
scripts/apply_update.py Check + apply(all in one step) The first thing to do each time the Skill is enabled(see the red box at the top)
scripts/check_update.py Only check, do not apply; list the files that would change When you only want to preview what changed and do not want to update immediately

If you only want to see the changes first before deciding whether to upgrade:

python3 scripts/check_update.py     # 列出 added / modified / removed

updates.json of update_source has been configured as git+https://github.com/GordenSun/GordenPPTSkill.git#main, ready to use out of the box, no modification needed.

Three modes

After receiving the user's request, first determine which mode to use:

Mode A: Choose from built-in templates

This is the default path. The 21 built-in templates cover the vast majority of Chinese scenarios.

  1. Read templates/INDEX.md — A concise checklist listing each template's style, primary color, applicable scenarios, and page count.
  2. Match user input — Compare the user's description (scenario, style keywords, required page types, color preferences) with each template's intro.md.
  3. Decision rules for choosing a template：
    • The user has clearly specified a template → Use it directly.
    • You are highly confident that only 1 template is the most suitable(scenario + style + primary color all strongly match, and it is clearly better than the others) → You may use it directly, but before starting, tell the user in one sentence which one you chose and why, giving the user a chance to veto.
    • In all other cases (the user did not specify, or you cannot be fully certain which is most suitable) → the user must choose：
      • Use AskQuestion to provide exactly 3candidate templates, each with a one-sentence reason (style / applicable scenarios / page count), andshow the corresponding templates/<slug>/preview.png as wellso the user can look at the images and decide.
      • Among the optionsalways include an extra "none of these, show another batch". When the user selects it, then based on match level provideanother 3candidates that have not appeared before (also with preview images). You can keep swapping until the user chooses or the candidates are exhausted.
      • If all candidates are exhausted and the user is still unsatisfied → ask the user for more specific preferences (style / color / scenario), or switch to Mode C for original creation.
    • ⚠️ Do not decide on a template on your own based on vague matching without letting the user see preview images.
  4. After obtaining the target template：
    • Read templates/<slug>/intro.md(highly condensed, tells you the characteristics of this template)
    • Read templates/<slug>/detail.json(structured data, tells you the details of each page / each text slot)
    • According to Mode A workflow , select pages, write edits.json, run build_pptx.py

Mode B: The user brings their own PPT template

When the user provides a .pptx file and clearly wants to use it as a template:

  1. Treat the user's pptx as an "unknown template"
  2. Use scripts/render_slides.py to render each page as PNG, then use python-pptx to inspect on the spot the shape / paragraph / run structure of each page (no additional script needed)
  3. Look at each page yourself (PNG + shape output):
    • Infer what role each page plays (cover / table of contents / section divider / content page / ending / template promotion)
    • Infer what content each page is suitable for
    • Skip template promotion / "稻壳儿" / thanks for downloading and the like
  4. According to Mode B workflow use explicit address write edits.json page selection + text replacement
  5. Do not modify the user's original template file; write all changes to a new output.pptx

Mode C: Fully original creation (not based on any template)

When the user explicitly requests "original design / no template / simple and clean style":

  1. Create layouts that are as concise as possible — lots of white space, strict alignment, minimal decoration
  2. ≤ 4 elements per page; avoid complex graphics / icon groups
  3. Font: English Arial / Helvetica; Chinese Microsoft YaHei / Source Han Sans; bold for headings is enough
  4. 1 primary color + grayscale + white background; do not mix multiple styles
  5. Use python-pptx to generate code directly, refer to references/original-design-guide.md

Editing iron rules (common to all modes)

  1. Do not change layout — only change text. Do not touch shape position, size, color, font, font size, or line spacing.
  2. All placeholder text must be replaced — placeholder text in the template such as "Question 1" / "Vivamus..." / "Key Words Here" / "项目名称" must all be replaced with real content. A finished PPT should not contain any example placeholder words.
  3. max_chars is a soft reference, not a hard upper limit; never truncate with ellipses — the max_chars / chars_per_line / max_lines of each slot in detail.json is an estimated capacity based on the text box size,for reference only, to help you gauge "roughly how many characters can fit in this cell".
    • Prioritize writingnatural, complete, concisetext. Slightly exceeding is usually fine (capacity already has 20% margin, and PPT text boxes themselves are flexible).
    • It is absolutely forbidden to cut off the second half of a sentence just to fit the count, or to add ... / … / 等等 at the end to force the length — a half sentence truncated by an ellipsis is much uglier than a slight overflow, and is the worst result.
    • When it is truly too long, handle by priority: ① Rewrite with more concise wordingrewrite(a true summary, not cutting off); ② Reduce the number of bullet points / switch to a layout or page with more space; ③ If all else fails,rather let it slightly overflow than have an ellipsis appear。
    • build_pptx.py overflow detectionis only a hint, not blockingsave.Do not add --strictin daily use (it will refuse to save due to overflow, thereby inducing truncation).capacity_unknown:true slots are measured inaccurately; judge by eye.
  4. Numbers / sequence numbers stay unchanged by default —— editable: false slots are decorative "01/02/1/2/%" and the like; keep them unless the user explicitly asks to change the order.
  5. Graphics / charts usually cannot be synchronized — decorative progress bars / rings / flag paths / flow arrows are fixed shapes; changing the percentage text will not change the arc length. If each template's detail.json has such pages, they will be listed in the cautions field.
  6. Only real data charts can have their data changed — if a page has a PPT native chart (shape.has_chart=True), you can use build_pptx.py --chart-data to update it synchronously; see references/chart-editing.md。
  7. Chapter names should echo before and after — if you change the table of contents chapter name, the corresponding chapter divider page + content page breadcrumb text must also be changed accordingly.
  8. Cover / acknowledgments page should follow template capabilities; do not force-create ——
    • Read detail.json of page_roles; if cover array is empty,start directly from the first content page, do not use a content page as a cover, and even less should you temporarily piece together a cover page from another template.
    • If ending array is empty,End directly with the last content page, do not force a "thank you for listening" slide.
    • Likewise,agenda empty → do not impose a table of contents;section_divider empty → do not impose a section divider page.
    • In other words:use whatever roles the template has, one fewer role means one fewer page, do not break visual consistency just to fill things in. This rule applies to all templates starting from v1.0.3.
  9. Headings at the same level must have the same font size, do not change font size here and there ——
    • At the top of detail.json there is type_scale(font size hierarchy table, level 1 = largest), each slot is marked with level。text at the same level keeps the template's original font size, do not change the font size.
    • When some text is too long, usemore concise wording to rewrite itto control length (see item 3),do not make this spot's font size smaller(it would break same-level consistency),and do not truncate with ellipses。
    • When selecting multiple pages to assemble one PPT, make the heading wording length at the same level across pages similar, so the whole thing looks neat.

Standard Workflow (Mode A)

# 1. 从 templates/INDEX.md 选定一个模板，例如 minimal-business-summary
TEMPLATE=templates/minimal-business-summary

# 2. 读两个文件
#    - $TEMPLATE/intro.md     -> 模板风格 / 适用场景 / 结构概述
#    - $TEMPLATE/detail.json  -> 每页 / 每个文本位的详细描述

# 3. 自己决定要用哪些页（用 detail.json 的 page.role 和 use_for）
#    生成 edits.json：
#    {
#      "template_slug": "minimal-business-summary",
#      "selected_slides": [1, 2, 3, 5, 7, 9, 10, 12, 13, 14, 16],
#      "edits": [
#        {"slide": 1, "slot_id": "cover_title_cn", "new_text": "2026 年度复盘"},
#        ...
#      ]
#    }

# 4. 跑构建（不要加 --strict：出框检测只作提示，不应阻断；超框宁可轻微超出也别截断加省略号）
python3 scripts/build_pptx.py \
    $TEMPLATE/template.pptx \
    edits.json \
    out/final.pptx \
    --detail $TEMPLATE/detail.json

# 5. （可选）渲染最终 pptx 给用户预览 / 自检（每页一张 PNG）
python3 scripts/render_slides.py out/final.pptx out/renders --dpi 144

Directory Structure

GordenPPTSkill/
├── SKILL.md               ← 本文件
├── VERSION                ← 当前版本号
├── CHANGELOG.md           ← 人类可读变更日志
├── updates.json           ← 机器可读版本增量索引
├── manifest.json          ← 所有文件的 sha256 与版本归属
├── README.md              ← 仓库概览（用户阅读）
├── scripts/
│   ├── build_pptx.py          # 按 edits.json 选页 + 换字 → 输出 pptx（含出框检测）
│   ├── render_slides.py       # pptx → PDF → 每页 PNG（预览/自检）
│   ├── compute_capacity.py    # 由 template.pptx 计算每个 slot 的容量字段（数据准备）
│   ├── check_update.py        # 检查远端是否有更新
│   ├── apply_update.py        # 增量更新本地文件
│   └── build_manifest.py      # 重建 manifest.json
├── references/
│   ├── workflow.md
│   ├── pptx-edit-schema.md
│   ├── custom-template-workflow.md
│   ├── chart-editing.md
│   └── original-design-guide.md
└── templates/
    ├── INDEX.md
    └── <slug>/
        ├── template.pptx
        ├── intro.md       # 高度浓缩简介
        ├── detail.json    # 详细页面 / slot 数据（含容量字段 + type_scale）
        └── preview.png    # 4 页 2×2 拼接预览图

Key Scripts in One Sentence Each

Script What it's for
build_pptx.py Generate the final pptx from the template via edits.json(page selection + text replacement); includes overflow detection,--strict rejects saving when overflowing
render_slides.py Render any pptx into one PNG per page (using LibreOffice + pdftoppm), for preview / self-check
compute_capacity.py Compute each slot's chars_per_line/max_lines/max_chars and other capacity fields from template.pptx (already computed for built-in templates, only needed when adding a new template)
check_update.py Compare the local VERSION with the remote updates.json and tell you whether to update
apply_update.py Download only the changed files according to the delta list in updates.json
build_manifest.py Recompute manifest.json

Font Notes

The template XML uses a lot of 微软雅黑. If the runtime environment does not have that font, use ~/.config/fontconfig/fonts.conf to alias it to a locally installed font (recommended order: WenQuanYi Micro Hei → DengXian → Noto Sans SC → PingFang SC). The preview images are rendered using exactly this fallback chain.

The final .pptx delivered to the user will automatically render with the host machine's fonts when opened in PowerPoint / WPS / Keynote, so there is no need to worry about missing fonts.

Some Common Misconceptions

  • Don'tOnly change the text without keeping section names consistent — changing the agenda requires also changing the section divider pages
  • Don'tAdd text on top of a decorative image and think it's a real chart
  • Don'tLeave lorem ipsum in the final PPT
  • Don'tIgnore max_chars
  • Don'tModify the user's original template file — all output goes to new files
  • Don'tUse this Skill for commercial projects — see the notice at the top