ppt-as-code

Category: Content & Multimedia | Uploader: Russell-cell | Downloads: 0 | Version: v1.0（Latest）
use basic mode for confirmed deck planning plus script plus image flow, and use advanced mode
Changelog: Source: GitHub https://github.com/Russell-cell/PPT-as-code
Directory Structure

Current level: tree/main/
📁 agents/
- 📄 openai.yaml 427 B
📁 companion-skills/
- 📁 pptx-export-for-ppt-as-code/
  - 📁 agents/
    
    📄 openai.yaml 373 B
  - 📁 references/
    
    📄 manifest-contract.md 819 B
    
    📄 rendering-rules.md 1.0 KB
  - 📄 SKILL.md 4.4 KB
📁 references/
- 📄 advanced-mode.md 3.5 KB
- 📄 basic-mode.md 3.3 KB
- 📄 component-libraries.md 4.7 KB
- 📄 evolution-log.md 420 B
- 📄 pptx-export-handoff.md 2.3 KB
- 📄 quick-mode.md 2.4 KB
- 📄 visual-and-images.md 3.7 KB
📁 workflows/
- 📄 evolution-writeback.md 960 B
- 📄 mode-delivery.md 1.9 KB
📄 .gitignore 32 B
📄 CONTRIBUTING.md 3.0 KB
📄 LICENSE 1.1 KB
📄 README-zh.md 7.3 KB
📄 README.md 10.3 KB
📄 SKILL.md 21.9 KB
SKILL.md

---
name: ppt-as-code
description: >
  Build HTML-based web presentations with a creator-first workflow: keep quick mode lightweight,
  use basic mode for confirmed deck planning plus script plus image flow, and use advanced mode
  for reference-driven decks, static-first delivery, optional motion follow-up, optional PPTX
  export handoff, and safe fallbacks when file persistence or web search is unavailable.
---

# PPT as Code

> Plan and build HTML-based presentations with a creator-first staged workflow.

**Core Pipeline**: `Ingest -> Route Mode -> Load References -> Diagnose Gaps -> Produce Artifacts -> Confirm Key Decisions -> Deliver HTML -> Optional PPTX Export`

---

## Mandatory Rules

> [!CAUTION]
> ### Serial Execution & Gate Discipline
>
> This workflow is a strict serial pipeline.
>
> 1. **SERIAL EXECUTION**: Steps must execute in order; output of each step becomes input for the next.
> 2. **BLOCKING = HARD STOP**: A `BLOCKING` step requires explicit user confirmation before continuing.
> 3. **NO SPECULATIVE EXECUTION**: Do not pre-build future artifacts before the current gate is cleared.
> 4. **KEEP THE ROUTE PROPORTIONAL**: Do not escalate a lightweight deck into a heavier stack unless the request clearly needs it.
> 5. **DEFAULT TO SHIPPING**: Deliver usable artifacts, prompts, or HTML handoff routes, not theory essays.
> 6. **FINAL ARTIFACT MUST RUN**: If the user wants a direct handoff, prefer a self-contained file or a locally runnable folder over a CDN-only prototype.

> [!IMPORTANT]
> ### Creator-First Delivery
>
> - Default delivery is **staged artifacts + HTML route or prompt pack + image plan**, not a long code dump.
> - When the user is a creator or wants to move fast, prefer staged prompts and intermediate artifacts over large code blocks by default.
> - Use full implementation only when the user explicitly asks for code or the workflow has reached the final HTML stage.

> [!IMPORTANT]
> ### PPTX Export Handoff
>
> - `ppt-as-code` remains an **HTML-first** presentation skill.
> - PPTX export is an optional **final-delivery post-process**, not a replacement for the HTML workflow.
> - Default export target is `html`; allow `pptx` or `both` when the user explicitly wants PowerPoint delivery.
> - When the target includes PPTX, finish the static HTML pass first, then produce `deck_manifest.json`, then hand off to `pptx-export-for-ppt-as-code`.
> - `deck_manifest.json` is the export bridge and source of truth for PPTX delivery; do not rely on ad-hoc DOM scraping as the primary route.
> - PPTX export is static-only: motion is downgraded to a static state, simple pages should stay editable, and complex pages may fall back to full-slide raster images.

> [!IMPORTANT]
> ### Persistence Strategy
>
> - Default to **conversation-first artifacts**.
> - Only write files when the user explicitly wants persisted deck materials, or when the repo already has a clearly compatible project structure that invites file-based output.
> - When persistence is enabled, use conventional artifact names such as `deck_brief.md`, `theme_breakdown.md`, `style_options.md`, `deck_script.md`, `image_plan.md`, `index.html`, and `assets/`.

> [!IMPORTANT]
> ### PPT-First Grammar
>
> - `PPT-like` means stage-like: one active slide at a time, clear page state, and visible presentation furniture.
> - Do not let a deck drift into a long webpage, editorial article, or dashboard shell when the user explicitly asked for a presentation.
> - A finished deck must preserve clear slide roles such as cover, hook, concept, compare, quote, data, divider, and conclusion when relevant.

> [!IMPORTANT]
> ### Style Lock Rules
>
> - `quick` and `basic` still need a real visual direction; do not return a bare technical skeleton.
> - If style is undecided, recommend **3 to 4 design directions** before starting final HTML work.
> - Do not lock the final visual direction before the reference-image step when the chosen mode requires reference selection and browsing is available.
> - Once a reference is chosen, or the workflow has explicitly fallen back to style-word synthesis, translate the direction into structured design constraints before final implementation.

> [!IMPORTANT]
> ### Image Workflow Rules
>
> - Image quality beats image quantity. A weak image is worse than no image.
> - Never search body images from the full deck topic alone.
> - For each page that needs an image, first compress the page into one thesis, then derive page-level keywords, then search.
> - If image download fails, keep the source link, record the failure, and hand the link to the user for manual download instead of blocking the run.

> [!IMPORTANT]
> ### Network And Tool Fallbacks
>
> - If browsing or downloading is unavailable, do not block the workflow.
> - In `advanced`, if web reference search is unavailable, skip the web-reference branch and derive structured design constraints directly from the chosen style direction and any user-provided inspiration.
> - If file persistence is unavailable or undesired, keep the same staged artifacts in conversation instead of forcing repo writes.

> [!IMPORTANT]
> ### Runtime Source Of Truth
>
> - Runtime behavior must come from `SKILL.md` and the active mode/reference files.
> - Stable feedback should be integrated into the main docs, not left in logs.

### Role Dispatch Protocol

This skill operates as a single inline agent - no role switching required.

---

## Resource Manifest

### UI Metadata

| File | Path | Purpose |
|------|------|---------|
| skill interface metadata | `${SKILL_DIR}/agents/openai.yaml` | display name, short description, and default prompt |

### References

| Resource | Path | Runtime Use |
|----------|------|-------------|
| quick mode workflow | `${SKILL_DIR}/references/quick-mode.md` | required only when mode = `quick` |
| basic mode workflow | `${SKILL_DIR}/references/basic-mode.md` | required only when mode = `basic` |
| advanced mode workflow | `${SKILL_DIR}/references/advanced-mode.md` | required only when mode = `advanced` |
| visual and image workflow | `${SKILL_DIR}/references/visual-and-images.md` | required when style, references, or images are in scope |
| component library guidance | `${SKILL_DIR}/references/component-libraries.md` | required only when the route needs libraries |
| PPTX export handoff | `${SKILL_DIR}/references/pptx-export-handoff.md` | required only when export target = `pptx` or `both` |

### Workflows

| Workflow | Path | Purpose |
|----------|------|---------|
| `mode-delivery` | `${SKILL_DIR}/workflows/mode-delivery.md` | mode routing and output shaping |

---

## Workflow

### Step 1: Input Ingestion

`GATE`: The request is about a web-based presentation, HTML deck, slide system, reveal.js deck, presentation page, or a closely related deck-building workflow.

`EXECUTION`:

1. Extract the request shape:
   - topic
   - audience
   - delivery context: live presentation, shared link, async reading, or screen recording
   - export target: `html`, `pptx`, `both`, or unspecified
   - current stack: native HTML, React, Next.js, reveal.js, or unspecified
   - what the user already provided: notes, outline, raw material, references, images, existing code
2. Diagnose missing inputs:
   - theme breakdown
   - style direction
   - audience positioning
   - deck structure
   - visual references
   - image assets
3. Identify whether the request is about:
   - building from scratch
   - refining an existing deck
   - choosing a route
   - improving script, style, imagery, or motion
4. Decide the artifact persistence strategy:
   - default to conversation-first artifacts
   - enable file persistence only if the user asks for it or the repo clearly supports it
5. If persistence is enabled, choose the nearest reasonable project folder or deck folder that matches repo conventions.
6. Define the canonical artifact set for non-trivial runs:
   - `deck_brief.md`
   - `theme_breakdown.md`
   - `style_options.md`
   - `deck_script.md`
   - `image_plan.md`
   - `index.html`
   - `assets/`
7. If the export target includes PPTX, add the optional export artifacts:
   - `deck_manifest.json`
   - `output.pptx`

`CHECKPOINT`:

```markdown
## Step 1 Complete
- [x] Presentation request identified
- [x] Missing inputs diagnosed
- [x] Persistence strategy defined
- [ ] Next: auto-proceed to Step 2
```

---

### Step 2: Mode Routing

`GATE`: Step 1 complete; the request is clear enough to choose a mode.

`EXECUTION`:

1. Read `${SKILL_DIR}/workflows/mode-delivery.md`.
2. Respect an explicit user choice of `quick`, `basic`, or `advanced`.
3. If the user did not choose a mode, infer it:
   - choose `quick` for MVP decks, lightweight prototypes, and "get it running first"
   - choose `basic` for creator-facing deck planning that needs confirmed breakdown, confirmed script, and image handling before HTML
   - choose `advanced` for reference-driven deck design, richer style decisions, or a static-first then motion-follow-up workflow
4. Preserve the smallest route that satisfies the request.

`CHECKPOINT`:

```markdown
## Step 2 Complete
- [x] Execution mode chosen
- [x] Routing rationale prepared
- [ ] Next: auto-proceed to Step 3
```

---

### Step 3: Reference Loading

`GATE`: Step 2 complete; one execution mode has been chosen.

`EXECUTION`:

1. Load exactly one primary mode reference:
   - `quick` -> `${SKILL_DIR}/references/quick-mode.md`
   - `basic` -> `${SKILL_DIR}/references/basic-mode.md`
   - `advanced` -> `${SKILL_DIR}/references/advanced-mode.md`
2. Load `${SKILL_DIR}/references/visual-and-images.md` when style, references, or images are relevant.
3. Load `${SKILL_DIR}/references/component-libraries.md` only when the route truly needs component or chart libraries.
4. Load `${SKILL_DIR}/references/pptx-export-handoff.md` only when the export target is `pptx` or `both`.

`CHECKPOINT`:

```markdown
## Step 3 Complete
- [x] Primary mode reference loaded
- [x] Supporting references loaded only if relevant
- [ ] Next: auto-proceed to Step 4
```

---

### Step 4: Artifact Setup And Gap Diagnosis

`GATE`: Step 3 complete; the active mode workflow is loaded.

`EXECUTION`:

1. Define the artifact set for the chosen mode.
2. For `basic` and `advanced`, prepare the brief artifact first.
   - If persistence is enabled, materialize it as `deck_brief.md`.
   - Otherwise, keep it inline in the conversation.
3. Decide which artifacts are required now versus later:
   - `quick`: brief or outline, style directions, minimal HTML route
   - `basic`: brief, breakdown, style options, script, image plan, HTML
   - `advanced`: same as `basic`, plus structured design constraints and optional motion follow-up
   - `pptx` or `both`: add manifest and PPTX handoff after static HTML is ready
4. Record the missing gaps that must be resolved before HTML is allowed to begin.

`CHECKPOINT`:

```markdown
## Step 4 Complete
- [x] Artifact list defined for the chosen mode
- [x] Immediate gaps recorded
- [ ] Next: branch into the chosen mode workflow
```

---

### Step 5: Quick Workflow

`GATE`: Chosen mode is `quick`.

`EXECUTION`:

1. Produce a lightweight deck brief:
   - topic
   - audience
   - core message
   - missing inputs
2. If the theme is still vague, create a lightweight outline before implementation.
3. If style is missing, recommend **3 to 4 style directions** and clearly mark one as the default recommendation.
4. Continue with the recommended direction unless the user explicitly wants to choose.
5. Produce:
   - a minimal slide structure
   - one cover direction
   - a minimum viable HTML route or short prompt pack
6. If the user asked for images in `quick`, use the page-thesis keyword workflow from `visual-and-images.md`, but keep the image plan lightweight.
7. If the user wants `pptx` or `both`, keep the slide roles clear enough to support a later manifest handoff.
8. Include an upgrade path toward `basic`.

`CHECKPOINT`:

```markdown
## Step 5 Complete
- [x] Lightweight structure prepared
- [x] Visual direction prepared
- [x] Minimal HTML route or prompt pack prepared
- [ ] Next: auto-proceed to Step 15
```

---

### Step 6: Basic Workflow A - Breakdown First

`GATE`: Chosen mode is `basic`.

`EXECUTION`:

1. Prepare the brief artifact with current inputs and missing gaps.
2. Recommend **3 to 4 design directions** in the style-options artifact.
3. Always include arrow / progress / page-furniture suggestions as part of the style pack, using options such as:
   - floating
   - transparent
   - large footprint
   - small footprint
4. Prepare the theme-breakdown artifact before any slide script exists.
5. The theme-breakdown artifact must define:
   - the deck thesis
   - the page sequence
   - what each slide is trying to say
   - which pages likely need images
6. If persistence is enabled, materialize these as `deck_brief.md`, `style_options.md`, and `theme_breakdown.md`.

`BLOCKING`: Ask the user to confirm the theme breakdown before any script generation begins.

`CHECKPOINT`:

```markdown
## Step 6 Complete
- [x] Brief artifact prepared
- [x] Style options prepared
- [x] Theme breakdown prepared
- [ ] Next: BLOCKING - wait for breakdown confirmation
```

---

### Step 7: Basic Workflow B - Script Lock

`GATE`: Chosen mode is `basic`, and the user has confirmed the theme breakdown.

`EXECUTION`:

1. Lock the chosen style direction.
2. If local writing-style notes exist, scan likely style docs such as `voice_profile.md`, `brand.md`, `writing_style.md`, or project notes.
3. Prepare the deck-script artifact.
4. The deck-script artifact must define slide by slide:
   - scene or page purpose
   - headline or core copy
   - supporting copy or cue text
5. If persistence is enabled, materialize it as `deck_script.md`.
6. Do not start keyword extraction or image search yet.

`BLOCKING`: Ask the user to confirm the slide script before image work begins.

`CHECKPOINT`:

```markdown
## Step 7 Complete
- [x] Style locked
- [x] Local voice guidance applied when available
- [x] Deck script prepared
- [ ] Next: BLOCKING - wait for script confirmation
```

---

### Step 8: Basic Workflow C - Image Plan

`GATE`: Chosen mode is `basic`, and the user has confirmed the slide script.

`EXECUTION`:

1. Prepare the image-plan artifact.
2. For each slide that needs imagery:
   - compress the slide into one thesis
   - derive exactly **1 to 2 page-level keywords**
   - search using those keywords plus the chosen style direction when browsing is available
   - if browsing is unavailable, provide search strings and image intent instead of pretending search happened
3. Attempt to download selected images into `assets/` only when downloading is available and persistence is enabled.
4. If download fails, record in the image-plan artifact:
   - slide number
   - keywords
   - source URL
   - failure reason
   - note: `user needs to download manually`
5. If persistence is enabled, materialize the plan as `image_plan.md`.
6. Do not hide failed downloads. Surface the links to the user.

`BLOCKING`: Ask the user to confirm the script plus image plan before HTML implementation begins.

`CHECKPOINT`:

```markdown
## Step 8 Complete
- [x] Image plan prepared
- [x] Slide-level keywords extracted
- [x] Download attempts or fallback links recorded
- [ ] Next: BLOCKING - wait for script and image confirmation
```

---

### Step 9: Basic Workflow D - Static HTML

`GATE`: Chosen mode is `basic`, and the user has confirmed the script and image plan.

`EXECUTION`:

1. Generate the static HTML output.
2. Keep the deck presentation-first:
   - one active slide at a time
   - clear navigation state
   - visible progress or page furniture
3. If persistence is enabled, materialize the final output as `index.html`.
4. If the user wants a final artifact, prefer a self-contained HTML file or a locally runnable folder.

`CHECKPOINT`:

```markdown
## Step 9 Complete
- [x] Static HTML generated
- [x] Presentation grammar preserved
- [ ] Next: auto-proceed to Step 15
```

---

### Step 10: Advanced Workflow A - Direction Selection

`GATE`: Chosen mode is `advanced`.

`EXECUTION`:

1. Prepare the brief artifact.
2. Recommend **3 to 4 design directions**.
3. If browsing is available, search for direction-shaping inspiration when it helps the choice.
4. In the style-options artifact, explain each direction in terms of:
   - tone
   - hierarchy
   - palette mood
   - imagery
   - page furniture
   - arrow / progress styling
5. If persistence is enabled, materialize the brief and style artifacts as `deck_brief.md` and `style_options.md`.

`BLOCKING`: Ask the user to choose one direction before final visual locking begins.

`CHECKPOINT`:

```markdown
## Step 10 Complete
- [x] Brief artifact prepared
- [x] Style options prepared
- [ ] Next: BLOCKING - wait for direction choice
```

---

### Step 11: Advanced Workflow B - Reference Lock Or Fallback

`GATE`: Chosen mode is `advanced`, and the user has chosen a direction.

`EXECUTION`:

1. If browsing is available, search for **3 PPT or slide-design reference images** that match the chosen direction.
2. Present found references with:
   - link
   - short label
   - why it fits
   - what to borrow from it
3. If browsing is unavailable, do not block on web references.
4. In the no-browsing path, derive the visual lock directly from:
   - the chosen style direction
   - any user-provided inspiration
   - the deck topic and audience
5. Do not lock the final visual direction before this step completes.

`BLOCKING`: Ask the user to choose one reference image if web references were produced. If the workflow used the no-browsing fallback, skip this blocking step and proceed automatically.

`CHECKPOINT`:

```markdown
## Step 11 Complete
- [x] Reference branch or no-network fallback completed
- [x] Final visual not locked prematurely
- [ ] Next: proceed to Step 12
```

---

### Step 12: Advanced Workflow C - Script And Image Plan

`GATE`: Chosen mode is `advanced`, and either a reference image has been selected or the no-browsing fallback has completed.

`EXECUTION`:

1. Translate the chosen reference, or the chosen style direction in fallback mode, into structured design constraints before HTML work begins.
2. Use a JSON design style system or an equivalent structured constraint format.
3. If local writing-style notes exist, scan likely style docs such as `voice_profile.md`, `brand.md`, `writing_style.md`, or project notes.
4. Prepare the deck-script artifact.
5. For each slide that needs imagery:
   - compress the slide into one thesis
   - derive exactly **3 to 4 page-level keywords**
   - search using those keywords plus the chosen style direction when browsing is available
   - if browsing is unavailable, provide search strings and image intent instead of pretending search happened
6. Attempt to download images into `assets/` only when downloading is available and persistence is enabled.
7. If download fails, record the same fallback fields required by `basic` and surface the source link to the user.
8. If persistence is enabled, materialize these as `deck_script.md` and `image_plan.md`.
9. If the export target includes PPTX, prepare the slide content with explicit export hints after the static deck is approved.

`BLOCKING`: Ask the user to confirm the script and image plan before static HTML begins.

`CHECKPOINT`:

```markdown
## Step 12 Complete
- [x] Structured design constraints prepared
- [x] Deck script prepared
- [x] Image plan prepared
- [ ] Next: BLOCKING - wait for script and image confirmation
```

---

### Step 13: Advanced Workflow D - Static HTML First

`GATE`: Chosen mode is `advanced`, and the user has confirmed the script and image plan.

`EXECUTION`:

1. Generate the static HTML output first.
2. Keep the approved content order and visual hierarchy intact.
3. Do not add advanced motion in this step unless the user explicitly asked to skip the static-first pass.
4. If persistence is enabled, materialize the output as `index.html`.
5. If the export target includes PPTX, treat this static pass as the structure lock for `deck_manifest.json`.

`BLOCKING`: Ask the user whether they want a motion pass after reviewing the static deck.

`CHECKPOINT`:

```markdown
## Step 13 Complete
- [x] Static HTML generated
- [x] Static-first delivery preserved
- [ ] Next: BLOCKING - wait for motion decision
```

---

### Step 14: Advanced Workflow E - Optional Motion Pass

`GATE`: Chosen mode is `advanced`, and the user explicitly asked for a motion pass after reviewing the static deck.

`EXECUTION`:

1. Add motion only after the static deck is approved.
2. Treat motion as pacing, not decoration.
3. Use `transform` and `opacity` by default.
4. Preserve:
   - one active slide at a time
   - keyboard navigation
   - `prefers-reduced-motion`
5. Do not rewrite the approved script to justify animation.

`CHECKPOINT`:

```markdown
## Step 14 Complete
- [x] Motion layer added after approval
- [x] Reduced-motion support preserved
- [ ] Next: auto-proceed to Step 15
```

---

### Step 15: Delivery

`GATE`: The chosen mode workflow has completed.

`EXECUTION`:

1. Deliver in this order:
   - export target
   - chosen mode and why
   - artifact status
   - visual direction or chosen reference or fallback direction
   - script status
   - image status, including failed downloads and manual-download links
   - static HTML status
   - `deck_manifest.json` status when the export target includes PPTX
   - `output.pptx` status or handoff status when the export target includes PPTX
   - optional motion status when relevant
2. If the export target includes `pptx` or `both`:
   - verify the static HTML pass is complete and approved enough to freeze slide structure
   - prepare `deck_manifest.json` with `deckTitle`, `slideSize`, `themeTokens`, and per-slide export hints
   - hand off `index.html`, `deck_manifest.json`, and `assets/` to `pptx-export-for-ppt-as-code`
3. Before calling the deck final, verify:
   - it still feels like a presentation
   - page furniture exists where needed
   - slide roles read clearly
   - images are page-fit, not just topic-related
   - the deck is self-contained enough for the requested handoff

`CHECKPOINT`:

```markdown
## Step 15 Complete
- [x] Final delivery follows the staged artifact order
- [x] Presentation-first checks performed
- [x] Image fallback links surfaced when needed
- [x] PPTX handoff prepared when requested
```
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
ppt-as-code

Directory Structure

SKILL.md

Report

Notice
