presentation-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Presentation Skill

演示文稿技能

Create editable PowerPoint decks from source. The model owns the argument, evidence, and design judgment; the skill owns deterministic rendering and QA.

从源文件创建可编辑的PowerPoint演示文稿。模型负责论点、证据和设计判断；本技能负责确定性渲染和QA。

Core Contract

核心约定

Treat
```
outline.json
```
, planning files, data, and figure scripts as source.
Build with repository commands. Do not write one-off deck generators or patch a generated PPTX when source exists.
Keep text, charts, tables, diagrams, and figures editable where practical.
Use the selected grammar as a design system, not a fixed slide sequence.
Fix source and rebuild until geometry, readability, placeholders, and rendered visual review pass.
Do not copy proprietary slides, logos, wording, or distinctive geometry.

Run commands from this skill directory. Use absolute paths for deck files kept elsewhere. Check the pinned runtime once:

bash

npm run doctor

If required, run

npm run setup:python

once. Do not substitute arbitrary Python or Office application workflows for the supported runtime.

将
```
outline.json
```
、规划文件、数据和图表脚本视为源文件。
使用仓库命令构建。当存在源文件时，请勿编写一次性的演示文稿生成器，也不要对已生成的PPTX进行补丁修改。
在可行的情况下，保持文本、图表、表格、示意图和图形的可编辑性。
将选定的语法用作设计系统，而非固定的幻灯片序列。
修复源文件并重新构建，直到几何布局、可读性、占位符和渲染后的视觉审查全部通过。
请勿复制受版权保护的幻灯片、Logo、措辞或独特的布局结构。

请在此技能目录下运行命令。对于存放在其他位置的演示文稿文件，请使用绝对路径。请一次性检查固定的运行时环境：

bash

npm run doctor

如有需要，可一次性运行

npm run setup:python

。请勿使用任意Python或Office应用工作流替代受支持的运行时环境。

Choose A Route

选择工作路线

Clarify Only What Matters

仅澄清关键信息

The brief includes optional intake questions. Ask at most three short questions only when missing audience, decision, evidence, or brand information would change the deck. Do not ask again when the request or saved answers already cover it. Otherwise state reasonable assumptions and proceed. Never invent missing results.

Use

present.py intake --prompt "..."

for a standalone intake packet. Pass answers as inline JSON, for example

--answers '{"audience":"Lab directors"}'

, to the next brief. Fields are

audience

purpose

evidence

, and

style

. These are design questions, not permission requests.

If the caller supplies low remaining usage and confirms Luna is available, offer the current model or Luna with the same QA. Ask once; do not silently switch. Without known model availability, offer a leaner workflow on the current model, not a promise of Luna access or lower quota consumption. Never query account usage merely because a deck is requested.

简报包含可选的初始信息收集问题。仅当缺少受众、决策目标、证据或品牌信息会影响演示文稿内容时，才最多提出三个简短问题。如果请求或已保存的答案已经涵盖这些信息，则无需再次询问。否则请说明合理的假设并继续执行。绝不要编造缺失的结果。

使用

present.py intake --prompt "..."

生成独立的信息收集包。将答案以内联JSON的形式传递给下一个简报，例如

--answers '{"audience":"Lab directors"}'

。涉及的字段包括

audience

、

purpose

、

evidence

和

style

。这些是设计相关问题，而非权限请求。

如果调用方提示剩余使用量较低，且确认Luna可用，可提供当前模型或Luna选项，二者享有相同的QA标准。仅询问一次，请勿静默切换模型。在不清楚模型可用性的情况下，仅提供当前模型下的精简工作流，不要承诺Luna访问权限或更低的配额消耗。绝不要仅因为用户请求生成演示文稿就查询账户使用情况。

Quick Deck

快速生成演示文稿

Use for a one-off 5-10 slide deck.

Emit a small model-ready brief:

bash

python3 scripts/present.py brief \
  --topic "Deck topic" \
  --prompt "Original request" \
  --slides 7 \
  --profile auto \
  --output quick_deck_agent_brief.json

Read the brief and author
```
outline.json
```
. Select one bounded route candidate, then adapt its starter sequence to the actual evidence.
```
role
```
names the editable structure;
```
slide_intent
```
names the story job.
Build, render, and hard-gate it:

bash

python3 scripts/present.py finalize \
  --outline /absolute/path/outline.json \
  --output /absolute/path/output.pptx \
  --qa-dir /absolute/path/qa

Read

finalize_receipt.json

and inspect the rendered slides. If checks fail, start from

repair_packet.json

: it contains affected source pointers, measured issues, and image paths. Repair source and rerun until the artifact passes; do not stop after an arbitrary number of attempts. Automated checks do not substitute for actual visual inspection.

When style choice is genuinely uncertain, preview the same representative content in a few candidate styles before building the full deck:

bash

python3 scripts/present.py audition \
  --outline /absolute/path/outline.json --outdir /absolute/path/audition \
  --presets lab-report editorial-minimal warm-terracotta

This is optional, not an extra step for every deck. Inspect

comparison.jpg

and select by evidence fit and hierarchy, not decoration. The source is unchanged.

适用于一次性的5-10页演示文稿。

生成一份适配模型的小型简报：

bash

python3 scripts/present.py brief \
  --topic "Deck topic" \
  --prompt "Original request" \
  --slides 7 \
  --profile auto \
  --output quick_deck_agent_brief.json

阅读简报并编写
```
outline.json
```
。选择一个有明确范围的路线候选方案，然后根据实际证据调整其初始幻灯片序列。
```
role
```
用于定义可编辑结构；
```
slide_intent
```
用于定义幻灯片的叙事作用。
构建、渲染并严格质量把关：

bash

python3 scripts/present.py finalize \
  --outline /absolute/path/outline.json \
  --output /absolute/path/output.pptx \
  --qa-dir /absolute/path/qa

读取

finalize_receipt.json

并检查渲染后的幻灯片。如果检查未通过，从

repair_packet.json

入手：它包含受影响的源文件指针、检测到的问题和图片路径。修复源文件并重新运行，直到产物通过检查；不要在任意次数的尝试后就停止。自动化检查不能替代实际的视觉审查。

当确实无法确定风格选择时，在构建完整演示文稿之前，先用几种候选风格预览相同的代表性内容：

bash

python3 scripts/present.py audition \
  --outline /absolute/path/outline.json --outdir /absolute/path/audition \
  --presets lab-report editorial-minimal warm-terracotta

这是可选操作，不是每个演示文稿都需要的额外步骤。查看

comparison.jpg

，根据证据适配度和视觉层级选择风格，而非根据装饰效果选择。源文件不会被修改。

Saved Workspace

已保存工作区

Use for decks that will be rebuilt, audited, or iterated:

bash

python3 scripts/present.py init \
  --workspace /absolute/path/deck-workspace \
  --title "Deck title" \
  --prompt "Original request" \
  --profile auto \
  --style-preset auto

python3 scripts/present.py build \
  --workspace /absolute/path/deck-workspace \
  --draft

python3 scripts/present.py build \
  --workspace /absolute/path/deck-workspace

The default workspace is compact. Add

--audit-packet

present.py init

only when a full intake/multi-agent recovery ledger is useful.

Author or update:

```
design_brief.json
```
: audience, style, readability, and QA contract
```
content_plan.json
```
: thesis, narrative arc, and slide roles
```
evidence_plan.json
```
: claims, sources, and chart candidates
```
asset_plan.json
```
: figures, tables, charts, images, and icons
```
outline.json
```
: renderable slide source
```
notes.md
```
: assumptions and unresolved decisions

The build also writes deterministic

build/deck_ir.json

, a coordinate-free semantic representation with stable object IDs, evidence links, reading order, and editability metadata. Renderer scripts continue to own coordinates.

适用于需要重新构建、审计或迭代的演示文稿：

bash

python3 scripts/present.py init \
  --workspace /absolute/path/deck-workspace \
  --title "Deck title" \
  --prompt "Original request" \
  --profile auto \
  --style-preset auto

python3 scripts/present.py build \
  --workspace /absolute/path/deck-workspace \
  --draft

python3 scripts/present.py build \
  --workspace /absolute/path/deck-workspace

默认工作区是精简型的。仅当需要完整的需求录入/多Agent恢复台账时，才在

present.py init

中添加

--audit-packet

参数。

编写或更新以下文件：

```
design_brief.json
```
：受众、风格、可读性和QA约定
```
content_plan.json
```
：核心论点、叙事弧和幻灯片角色
```
evidence_plan.json
```
：主张、来源和候选图表
```
asset_plan.json
```
：图形、表格、图表、图片和图标
```
outline.json
```
：可渲染的幻灯片源文件
```
notes.md
```
：假设和未解决的决策

构建过程还会生成确定性的

build/deck_ir.json

，这是一种无坐标的语义表示，包含稳定的对象ID、证据链接、阅读顺序和可编辑性元数据。渲染脚本仍负责坐标相关的处理。

Existing PPTX

已有PPTX文件

When source exists, edit source. For a standalone PPTX, inspect it first:

bash

python3 scripts/python_runtime.py scripts/reference_deck.py inspect \
  --input /absolute/path/input.pptx \
  --output /absolute/path/reference_deck_manifest.json

Use a typed

reference_deck_patch_v1

for narrow text or alt-text edits. Use

scripts/extract_pptx_style.py

plus a fresh workspace for a source-first redesign inspired by an existing deck. Read

references/editing.md

before editing package internals.

如果存在源文件，请编辑源文件。对于独立的PPTX文件，请先进行检查：

bash

python3 scripts/python_runtime.py scripts/reference_deck.py inspect \
  --input /absolute/path/input.pptx \
  --output /absolute/path/reference_deck_manifest.json

对于小范围的文本或alt-text修改，请使用类型化的

reference_deck_patch_v1

。如果要基于现有演示文稿进行源优先的重新设计，请结合使用

scripts/extract_pptx_style.py

和全新的工作区。在编辑包内部结构之前，请先阅读

references/editing.md

。

Model Profiles

模型配置文件

Profiles change orchestration, not the final quality definition:

```
fast
```
/
```
luna
```
: one grammar candidate and small valid payload examples; single-agent authoring with focused repairs.
```
balanced
```
/
```
terra
```
: two grammar candidates; delegate only when useful.
```
quality-first
```
/
```
sol
```
/
```
astra
```
: up to three grammar candidates, optional evidence or design scouts, and flexible content-led composition.
```
auto
```
: quality-first for high-stakes/evidence-heavy work, fast for explicit rough drafts, balanced otherwise.

Profiles are workflow policies, not provider/model switches or quality claims. One capable model can complete the entire workflow. No advisor model or multi-agent setup is required; use bounded advice only when it resolves a specific design or evidence uncertainty, then continue authoring and validation. All models may adapt the suggested sequence and mix supported treatments. Do not feed them the full corpus or arbitrary coordinates. For an unrecognized future model, choose a workflow profile explicitly. Use the recorded fallback when no content-grounded design choice is available.

配置文件仅调整工作编排方式，不改变最终质量标准：

```
fast
```
/
```
luna
```
：单语法候选方案和小型有效载荷示例；单Agent创作，针对性修复。
```
balanced
```
/
```
terra
```
：两种语法候选方案；仅在必要时委托处理。
```
quality-first
```
/
```
sol
```
/
```
astra
```
：最多三种语法候选方案，可选证据或设计侦察，灵活的内容主导型排版。
```
auto
```
：高风险/重证据工作采用质量优先模式，明确的草稿采用快速模式，其余情况采用平衡模式。

配置文件是工作流策略，而非服务提供商/模型切换开关或质量承诺。单个能力足够的模型即可完成整个工作流。不需要顾问模型或多Agent设置；仅当有限建议能解决特定的设计或证据不确定性时才使用，之后继续进行创作和验证。所有模型都可以调整建议的序列，组合使用支持的处理方式。请勿向模型输入完整语料库或任意坐标。对于未识别的未来模型，请显式选择一个工作流配置。当没有基于内容的设计选择时，使用记录的回退方案。

Design Decisions

设计决策

Choose one primary grammar from topic, audience, evidence shape, and density. The eight structural grammar families own distinct title, section, evidence, comparison, data, decision, and references systems. Presets contribute palette, type, and treatment vocabulary; they are not static templates.

Maintain these invariants:

One dominant idea and a clear reading path per slide.
Every content slide has a visual or evidence anchor: chart, table, figure, image, KPI, timeline, matrix, or structured comparison.
No centered body copy and no sequence dominated by bullet-only slides.
Vary composition with the argument; avoid repeating one card grid, border, title treatment, or two-column shell.
Use
```
header_variant: auto
```
with a stable seed for reproducible heading, top-line, bottom-line, no-line, and compact report treatments.
Keep source text and page numbers in the reserved footer region; do not let footer chrome compete with the evidence.
Use
```
role_layout_variant: primary | alternate | dense
```
for bounded structural variation. Do not place arbitrary coordinates in
```
outline.json
```
.
Keep typography, spacing, and semantic colors coherent. Borrow supported treatments when the content benefits; the suggested sequence is not mandatory.
For a visual A/B, freeze one outline and vary only
```
deck_style
```
; this exposes real grammar differences without letting content changes bias the comparison.
Treat auxiliary title-stage anchors as content slots, not decoration. Leave them absent unless the outline supplies a value or asset.

Readable defaults for ordinary delivery:

titles at least 28 pt;
body text at least 16 pt;
supporting subtitles at least 13 pt;
captions, sources, and metadata at least 9 pt;
no more than two title lines;
shorten, split, or convert prose into evidence objects before shrinking.

Use actual content to balance white space. Sparse slides need a stronger anchor; dense slides need fewer words or a more suitable structure, not smaller type.

For structural routing details, read

references/composition_grammar_catalog.md

. For screenshot/template inspiration, read

references/style_reference_catalog.md

. The descriptor corpus is retrieval memory; load only the selected record or distilled atoms.

根据主题、受众、证据形态和密度选择一种主要语法。八种结构语法系列分别拥有独特的标题、章节、证据、对比、数据、决策和参考文献系统。预设提供调色板、字体和处理方式，它们不是静态模板。

请保持以下不变性原则：

每张幻灯片有一个核心观点和清晰的阅读路径。
每张内容幻灯片都有一个视觉或证据锚点：图表、表格、图形、图片、KPI、时间线、矩阵或结构化对比。
正文不要居中对齐，不要出现连续多张只有项目符号的幻灯片。
根据论点调整排版，避免重复使用同一种卡片网格、边框、标题处理方式或两栏布局。
结合稳定的种子值使用
```
header_variant: auto
```
，以实现可复现的标题、顶部线条、底部线条、无线条和紧凑型报告处理方式。
将源文本和页码保留在预留的页脚区域；不要让页脚装饰元素抢了证据的关注度。
使用
```
role_layout_variant: primary | alternate | dense
```
实现有限的结构变化。请勿在
```
outline.json
```
中放置任意坐标。
保持排版、间距和语义颜色的一致性。当内容有需要时可以借鉴支持的处理方式；建议的序列不是强制性的。
进行视觉A/B测试时，固定一个大纲，仅更改
```
deck_style
```
；这样可以展现真实的语法差异，避免内容变化影响对比的客观性。
将辅助标题阶段的锚点视为内容槽位，而非装饰元素。除非大纲提供了值或资源，否则不要添加这些锚点。

普通演示场景下的可读性默认设置：

标题至少28 pt；
正文至少16 pt；
辅助副标题至少13 pt；
说明文字、来源和元数据至少9 pt；
标题不超过两行；
在缩小字号之前，先将长文本缩短、拆分，或转换为证据类对象。

根据实际内容平衡留白。内容稀疏的幻灯片需要更突出的锚点；内容密集的幻灯片需要减少文字或采用更合适的结构，而不是缩小字号。

有关结构路由的详细信息，请阅读

references/composition_grammar_catalog.md

。如需截图/模板灵感，请阅读

references/style_reference_catalog.md

。描述符语料库是检索内存；仅加载选定的记录或提炼后的原子单元。

Data And Figures

数据与图形

For local CSV, TSV, XLSX, or JSON evidence, keep generated artifacts reproducible:

bash

python3 scripts/python_runtime.py scripts/scaffold_figure_artifacts.py \
  --workspace /absolute/path/deck-workspace \
  --run \
  --bind-outline

Preserve source fingerprints, figure scripts, chart/table JSON, artifact manifests, slide bindings, and rebuild commands. Solve whitespace and label readability in the figure script before placing the figure. Stage sourced images through

asset_plan.json

with attribution. Generated imagery must remain optional and carry prompt/model/purpose metadata.

Bar charts include zero by default. Set explicit axis bounds only for an intentional, disclosed comparison; do not exaggerate differences through cropping.

Read

references/reproducible_workflow.md

only when the deck contains computed evidence or generated figures.

对于本地CSV、TSV、XLSX或JSON格式的证据，请保持生成产物的可复现性：

bash

python3 scripts/python_runtime.py scripts/scaffold_figure_artifacts.py \
  --workspace /absolute/path/deck-workspace \
  --run \
  --bind-outline

保留源文件指纹、图形脚本、图表/表格JSON、产物清单、幻灯片绑定和重建命令。在放置图形之前，先在图形脚本中解决留白和标签可读性问题。通过

asset_plan.json

管理来源明确的图片，并注明出处。生成的图像必须是可选的，且带有提示词/模型/用途的元数据。

条形图默认包含零轴。仅在进行有意的、已说明的对比时才设置显式的轴范围；不要通过裁剪来夸大差异。

仅当演示文稿包含计算得出的证据或生成的图形时，才阅读

references/reproducible_workflow.md

。

QA And Delivery

QA与交付

For evidence-led decks, keep a compact source checklist of critical values, units, denominators, caveats, and source IDs. Compare it with both the outline and rendered slides before approval. A correctly rendered chart can still contain swapped counts, missing facts, or an unsupported inference; automated layout checks do not establish factual fidelity.

A deliverable deck must pass:

planning and outline preflight;
geometry, overflow, overlap, density, and whitespace checks;
rendered contact-sheet and slide-level visual review;
placeholder-text checks;
readability and accessibility checks;
final delivery readiness.

Visual review should search for defects: clipped text, weak contrast, awkward empty regions, crowded edges, tiny labels, inconsistent alignment, repeated grammar, and unreadable sources. Fix source and rebuild.

For public proof or audited delivery, bind the actual review to the deck and render hashes with

scripts/visual_review_receipt.py

. Never invent a review receipt from automated counts. An optional

--render-cache-dir /absolute/path/cache

present.py finalize

reuses verified identical renders; content and rendering environment changes invalidate the cache. It never reuses a visual judgment.

If rendering is unavailable in the execution environment, preserve the built deck and static QA report, record the deferred render stage in the receipt, and do not probe unrelated Office apps.

对于以证据为核心的演示文稿，请保留一份精简的源文件检查清单，包含关键数值、单位、分母、注意事项和来源ID。在批准交付前，将清单与大纲和渲染后的幻灯片进行比对。渲染正确的图表仍可能存在数值调换、事实遗漏或无依据的推断；自动化布局检查无法确保事实准确性。

可交付的演示文稿必须通过以下检查：

规划和大纲预检；
几何布局、溢出、重叠、密度和留白检查；
渲染后的联系表和单幻灯片视觉审查；
占位符文本检查；
可读性和可访问性检查；
最终交付准备检查。

视觉审查应排查以下缺陷：文本被裁剪、对比度不足、尴尬的空白区域、边缘拥挤、标签过小、对齐不一致、语法重复、来源文字不可读。修复源文件后重新构建。

对于公开证明或审计级交付，请将实际审查结果绑定到演示文稿，并使用

scripts/visual_review_receipt.py

生成哈希值。绝不要根据自动化计数编造审查凭证。在

present.py finalize

中添加可选参数

--render-cache-dir /absolute/path/cache

可复用已验证的相同渲染结果；内容和渲染环境的变化会使缓存失效。该缓存绝不会复用视觉判断结果。

如果执行环境中无法进行渲染，请保留已构建的演示文稿和静态QA报告，在凭证中记录延迟的渲染阶段，不要探测无关的Office应用。

Progressive References

渐进式参考文档

Read only what the current task needs:

```
DESIGN.md
```
: compact design contract
```
references/model_adaptive_workflow.md
```
: profile selection and context budgets
```
references/deck_workspace_mode.md
```
: persistent workspace workflow
```
references/outline_schema.md
```
: schema or preflight failures
```
references/editing.md
```
: existing PPTX edits
```
references/reproducible_workflow.md
```
: data and figure artifacts
```
references/style_reference_catalog.md
```
: inspiration and screenshot matching

references/composition_grammar_catalog.md

: structural grammar routing

```
references/pptxgenjs.md
```
: renderer development only
```
references/visual_qa_prompt.md
```
: independent rendered review
```
references/benchmark_protocol.md
```
: fair comparison or superiority claims

Do not preload all references, presets, or corpus records.

仅读取当前任务所需的内容：

```
DESIGN.md
```
：精简设计约定
```
references/model_adaptive_workflow.md
```
：配置选择和上下文预算
```
references/deck_workspace_mode.md
```
：持久化工作区工作流
```
references/outline_schema.md
```
：模式或预检失败排查
```
references/editing.md
```
：已有PPTX编辑
```
references/reproducible_workflow.md
```
：数据和图形产物
```
references/style_reference_catalog.md
```
：灵感和截图匹配

references/composition_grammar_catalog.md

：结构语法路由

```
references/pptxgenjs.md
```
：仅用于渲染器开发
```
references/visual_qa_prompt.md
```
：独立渲染审查
```
references/benchmark_protocol.md
```
：公平对比或优势声明

请勿预加载所有参考文档、预设或语料库记录。

Development

开发

After changing runtime behavior, run:

bash

npm run check:python
npm run check:node
npm run check:present
npm run check:focused

Visual changes require a rendered proof. Showcase decks alone do not justify a claim that this skill outperforms another generator; use the frozen benchmark protocol and report only supported results.

修改运行时行为后，请运行：

bash

npm run check:python
npm run check:node
npm run check:present
npm run check:focused

视觉相关的变更需要提供渲染证明。仅靠展示用演示文稿不足以证明此技能优于其他生成器；请使用固定的基准测试协议，仅报告有依据的结果。