sn-ppt-creative

sn-ppt-creative

Translate the public Story into a set of 16:9 full-page visuals: generate one complete PNG per page, which can be assembled into a PPTX. Creative is responsible for visual translation, not for Research, and does not generate its own content outline.

Prerequisites and directory boundaries

Must exist:

<DECK_DIR>/task_pack.json
<DECK_DIR>/info_pack.json
<DECK_DIR>/outline.md
task_pack.choices.output == "creative", or for legacy tasks the ppt_mode == "creative"

DECK_DIR can only take the absolute path of task_pack.deck_dir . All generated artifacts are written only to that directory; must not write to the user home root directory, the host workspace root directory, the Skill directory, the repo,/tmp or another workspace. Existing tasks must reuse the original DECK_DIR, and must not create another directory.

Record the directory where the current Skill resides as the read-only SKILL_ROOT, and resolve the sibling sn-ppt-tools/ as the absolute PPT_TOOLS_DIR. Before starting image generation, read $PPT_TOOLS_DIR/references/capability-policy.md. Use the host Agent's native capabilities for text reasoning, style judgment, and visual understanding; prefer the host's native tools for image generation, and only when the native capability does not exist or a single actual call fails, use the image_generate.py。

must not call model_client.py、sn_agent_runner.py, and must not require the user to configure text or vision model APIs outside the Agent.

Public Story contract

On start and resume, re-read the outline.mdon disk. It fixes:

page count, page order, and titles;
each page's core conclusion, content basis, on-screen content boundaries, and preceding/following relationships;
content the user explicitly kept, deleted, or modified.

Creative may decide the visual metaphor, artistic medium, composition, page dynamics, and information graphic language, but must not:

merge, split, add, remove, or reorder pages;
change the meaning of titles and core conclusions;
restore content the user deleted from the outline;
search for facts on its own, add cases, or write another outline.json；
sacrifice facts, logic, or text readability for the sake of full-page image generation.

When existing material is found to be insufficient, keep the corresponding page slot and clearly state the gap, and return to Entry/Story; must not supplement Research within Creative.

Design richness

Read task_pack.choices.design_richness：

restrained: converge composition, materials, text decoration, and visual metaphor, prioritizing stability and clarity.
rich: default, providing ample imagery, page-type variation, and cross-page consistency on a clear information hierarchy.
high_creative: allows bolder composition, artistic media, hero pages, and visual dynamics, but does not sacrifice text readability, facts, and Story.

Richness only controls visual investment, and does not change page count, conclusions, and Research boundaries. This release no longer provides additional Artistic/Classical branch choices.

Artifacts

style_spec.md
pages/
  page_001.prompt.txt
  page_001.png
  page_002.prompt.txt
  page_002.png
...
<deck_id>.pptx

style_spec.md is the visual specification inside the exit, not a second Story; it may only supplement cross-page visual language, composition rules, color palette, materials, typographic character, and negative constraints, and must not rewrite the outline.

Resume

First run:

python3 "$SKILL_ROOT/scripts/resume_scan.py" --deck-dir "$DECK_DIR"

Continue according to the actual artifacts on disk:

style_spec.md does not exist: re-form the deck-level visual specification;
page_NNN.prompt.txt exists but PNG is missing: only regenerate the image;
PNG already exists: skip that page;
the user modified the outline: regenerate the prompt and PNG for the affected pages, and do not let the old prompt overwrite the new content;
PPTX is missing or pages have changed: repackage;
existing style, prompt, PNG, and PPTX are not deleted without reason.

Workflow

1. Read the input and form the visual specification

Read the task/info pack, the current outline, the user material index, the existing Research main report, and reference_image_captions. Write task_pack.state.current_stage as output.creative.plan, and write the status as generating。

formed directly by the host Agent <DECK_DIR>/style_spec.md. At minimum specify:

theme, audience, scenario, and visual goal;
a one-sentence cross-page visual concept;
background light/dark, primary and secondary colors, text hierarchy, and visual medium;
the unified relationship among cover, body, data pages, transition pages, and closing page;
negative constraints set to ensure readability and to avoid drawing design specifications into the pages.

When reference images are available, use the host's native visual capabilities to understand them, and preferentially reuse info_pack the existing descriptions in; the same image is not understood repeatedly. Do not search for facts or rewrite the outline at this stage.

2. Form the final image-generation prompt page by page

For each page, generate one <DECK_DIR>/pages/page_NNN.prompt.txtfrom the page with the same sequence number in the current outline. The prompt must include:

the title, core conclusion, and final on-screen text of this page;
the narrative relationship between this page and the preceding and following pages;
composition, visual hierarchy, subject, background, whitespace, and reading path;
style_spec.md the visual language that needs to be consistent across pages in;
a 16:9 full-page presentation frame, and the requirement that all text be clear, complete, and in a consistent language;
design specifications, color values, dimension annotations, code, placeholders, and extra copy are prohibited.

Do not splice style_spec.md, JSON, CSS, or internal field names directly into the prompt. After writing each page, execute:

python3 "$SKILL_ROOT/scripts/sanitize_prompt.py" \
  --path "$DECK_DIR/pages/page_NNN.prompt.txt"

one independent Agent action per page; do not use a single script loop to generate the entire set of prompts. After each page is completed, output brief progress.

3. Generate the full image page by page

For each page missing a PNG:

when the current Agent has a native image-generation tool, first use it to read the corresponding prompt, generate a 16:9 full-page image, and save the final file to $DECK_DIR/pages/page_NNN.png。

when the native tool does not exist or one actual call fails, execute the built-in fallback:

python3 "$PPT_TOOLS_DIR/scripts/image_generate.py" \
  --prompt-file "$DECK_DIR/pages/page_NNN.prompt.txt" \
  --deck-dir "$DECK_DIR" \
  --output "pages/page_NNN.png" \
  --size "2752x1536"

when both layers are unavailable or fail, record that page as failed and continue with the other pages. Do not create blank images, transparent images, placeholder images, or fake success.

Generating each page's image is an independent tool call; output a heartbeat after either success or failure. Do not loop retries after the first failure; resume that page only when the user later explicitly requests a retry.

If it has already been confirmed before production begins that both native and built-in image generation are unavailable, keep the style, prompt, and preceding common artifacts, write the status as partial and stop the Creative exit; do not silently switch to Standard, Dynamic, or Native PPTX.

4. Package the PPTX

After all pages have been processed, execute:

python3 "$SKILL_ROOT/scripts/build_pptx.py" --deck-dir "$DECK_DIR"

the script places the existing PNGs full-bleed into a 16:9 PPTX by page number; missing pages are kept as blank pages and reported in the results. When the script or local dependencies are unavailable, do not install new dependencies and do not switch to another builder; the per-page PNGs are still a valid deliverable.

Write pages/ and the absolute path of the available PPTX into task_pack.state.artifacts, and add creative to completed_stages. When all pages succeed, write the status as completed; when pages are missing or packaging fails, write partial and last_error。

Progress and wrap-up

Brief progress visible to the user must be provided:

已进入 sn-ppt-creative，共 N 页
[style] style_spec.md 完成
[prompt 2/N] 完成
[图 2/N] page_002.png 完成
[pptx] <deck_id>.pptx 完成

On failure, explain the reason on the corresponding line, then continue. At the end, only summarize the output directory, successful pages, failed pages, and PPTX status, and point out that outline.md is the user-editable narrative source.

Hard rules

Do not call model_client.py、sn_agent_runner.py or an additional text model API.
Do not generate a second content outline, and do not let the visual plan override outline.md。
Do not Research or add facts at the Creative exit.
Do not fake images, and do not treat remote URLs as final pages.
One prompt and one image-generation action per page; do not hide the entire set of pages in an invisible loop.
All user-visible text uses the language requested by the user.
All writes are located at the absolute path specified by the task pack DECK_DIR。
Existing usable artifacts, breakpoint recovery, and PNG -> PPTX capability must not be removed without reason.