brand-pptx

Files (4)

• SKILL.md
• comprehension.md · reference/
• visual-audit.md · reference/
• cli.py · scripts/

SKILL.md (first lines)

> **Windows 环境**：技能目录为 C:\Users\Willian\.agents\skills\brand-pptx，脚本请用绝对路径或先 cd 进技能目录；产物写到当前工作目录。本机没有 LibreOffice（soffice），依赖它做渲染、缩略图、接受修订、公式重算的步骤会失败，其余 Python 操作正常。
# brand-pptx

Use this skill when the user wants reusable branded PowerPoint generation from
a company `.pptx` template and variable user-provided content.

This is an AI-agent skill for Codex and Claude Code. The user should describe
the deck they want; the agent converts that request into an IntermediateDocument,
uses the internal Python engine, verifies the output, and returns the generated
`.pptx`.

## The seven verbs: three deterministic + four model-assisted

Every brand skill (`brand-docx`, `brand-pptx`, `brand-xlsx`) implements the same
contract. The deterministic core is **extract / verify / generate**; on top of it
sit the optional learning verbs **comprehend / learn / propose-overrides /
refine**, each fail-closed (the engine validates every proposal and authors every
value).

| Verb | Input | Output |
|---|---|---|
| **extract** | a company `.pptx` template | a reusable Brand Profile |
| **comprehend** *(optional, model-driven)* | a saved profile + a model-authored `comprehension.json` | the profile with a validated, cached `comprehension` block |
| **verify** | a saved Brand Profile | QA findings + a verdict |
| **generate** | content (an IntermediateDocument) + a profile | a new on-brand `.pptx` |
| **learn** *(deterministic distillation)* | the profile's cross-run generation history | recurring QA findings distilled into shell-frozen overrides, advisory until `--accept` |
| **propose-overrides** *(model-driven)* | the recurring remainder `learn` could not bind + a model-authored proposal | shell-backed corrections through the same fail-closed sink, advisory until `--accept` |
| **refine** | end-of-generation user feedback (text or a screenshot) as a `refinement.json` delta | the existing comprehension overlaid for FUTURE generations, advisory until `--accept` |

`comprehend` is **optional**: `generate` works on the deterministic profile alone.
See [reference/comprehension.md](reference/comprehension.md) for the full step.

## Hard Rules

- Treat `python scripts/cli.py ...` as an internal engine command, not the user-facing workflow.
- `scripts/cli.py` is a LAUNCHER that locates the engine root by itself: it works from this skill folder AND from the repo/plugin root (set `BRAND_DOCS_ROOT` to override). Never guess deeper paths like `scripts/brandkit/...`.
- Run the dependency preflight before starting extract / comprehend / verify / generate, and report missing or unusable dependencies before proceeding.
- Extract opens the source template read-only and saves `brand-kit/<name>/template/shell.pptx` byte-for-byte.
- Generate opens the saved shell and resolves every semantic block through `profile.json`.
- Do not put style names, colors, fonts, or brand identifiers in an IntermediateDocument.
- If the user did not provide a template or enough content, ask for the missing input.
- Return the generated file path plus a QA summary.
- Consult `profile.json.artifact_catalog` before generation when the user asks to mimic a specific piece of the template.

## Preflight (always first)

Before doing any work, run:

```bash
python scripts/cli.py doctor
```

Use its output to decide the run mode:

- If a required Python dependency is missing, install/repair it before extraction
  or generation; the core engine is not ready.
- If only visual renderers are missing or unusable (`soffice` plus `pdftoppm` or
  optional PyMuPDF/`fitz`), the
  core L0 workflow can still run, but a full visual audit cannot be claimed.
  Tell the user what is missing, include the install/repair hint printed by
  `doctor`, and either proceed with degraded QA or install the renderer first.
- If optional OCR (`tesseract`) is missing, the visual audit can still run, but
  rendered residual-text proof is incomplete. Report that limitation when
  judging stale placeholders or field caches.
- For `--qa deep` or `--qa strict`, prefer repairing/installing renderers before
  generation. If the environment cannot run them, `deep` generates a degraded
  manifest and `strict` fails with a visual proof blocker.

## Agent Workflow

1. Run the dependency preflight above and report any degraded capability.
2. Determine the brand name and locate the user-provided `.pptx` template.
3. If no matching `brand-kit/<name>` exists, **extract** one.
4. **Comprehend** the template (optional, model-driven; see below). Skip when a
   current comprehension is already cached or no model is available.
5. Convert the user's outline/content into `IntermediateDocument` JSON.
6. **Generate** the `.pptx` with the internal engine.
7. Run **QA** and report any warnings honestly.
8. **Feedback** (only after returning the file): invite a refinement of the
   understanding for future decks (see below).

Before generation, inspect `profile.json.artifact_catalog` when the user asks
to mimic a specific template piece. It records OOXML parts, media parts, slide
layouts, masters, placeholder geometry, slide texts, and slide size.

## Authoring the IntermediateDocument

The IDoc is where "correct deck" becomes "great deck". Author it role-first,
against the profile, never layout-first:

1. **Read `brand-kit/<name>/PROFILE.md` before writing a block.** It lists the
   role table and the brand palette tokens. Choose every block by MEANING from
   that table; the engine maps it to the template's real masters and layouts.
2. **One idea per slide.** A slide carries one heading and a few supporting
   blocks; split dense content across slides instead of shrinking it. Decks
   read in seconds per slide, not minutes.
3. **Lead with structure.** Cover fields first, an agenda where the deck keeps
   sections, then one section heading per major topic so the template's
   section scaffolding stays meaningful.
4. **Prefer native objects.** `chart`, `table` (merged cells included) and
   diagram blocks are authored NATIVELY: never describe a chart in prose or
   paste it as an image when a native block exists.
5. **Color discipline.** Placeholders inherit the brand from the layout: the
   default is NO run color. For true emphasis, reference a palette role
   (`primary`, `text`, ...) or a theme slot (`accent1`), never a hex.
6. **Reuse before re-deriving.** When a comprehension is present, prefer its
   `component` / `section` fragments (`comprehension.fragments` in
   `profile.json`) with `{{slot}}` values over hand-building recurring slides.
7. **Never name a layout, font, size, or hex.** If a block needs something the
   role table cannot express, say so in the QA summary instead of inventing
   formatting: the resolver is the only author of values.

## Feedback (end of generation)

Ask for feedback **only after** you have returned the generated `.pptx` and its
QA summary - never before or during generation. Invite the user to reply with
**text or a screenshot** of the deck, and name the roles, palette colors, and
sections you actually used so the answer is concrete. A screenshot is your own

From Willian8021743/windows-ai-toolkit, MIT.

More from Willian8021743/windows-ai-toolkit