# Slidesage

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-vedraut-slidesage-slidesage`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [vedraut](https://agentstack.voostack.com/s/vedraut)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [vedraut](https://github.com/vedraut)
- **Source:** https://github.com/vedraut/slidesage

## Install

```sh
agentstack add skill-vedraut-slidesage-slidesage
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# SlideSage

Turn a topic into a **static but stunning `.pptx`** whose order and content are driven by a
**storytelling + instructional-design engine**. You (the agent) reason out a *storyboard*; a deterministic
Node renderer turns it into a designed deck. No motion — the **sequence of slides and the section-divider
"transition" beats** carry the narrative.

Two modes:

- **`business`** *(default, priority)* — persuasive, executive-ready decks: pitches, keynotes, QBRs,
  strategy, reports. Narrative arc = Pyramid Principle / Situation→Complication→Resolution.
- **`education`** *(toggle)* — teaching decks with Bloom's-aligned objectives, prerequisite sequencing, and
  learning-science beats (retrieval practice, spacing, worked examples).

## When to use this skill

Trigger when the user asks to create a presentation, slide deck, PowerPoint, `.pptx`, pitch, keynote, business
review, report-out, lecture, course, or workshop. If the user explicitly wants **animated or web/HTML** slides,
this skill is the wrong tool (it is static `.pptx` by design) — say so and stop.

## Operating principles (read before generating)

1. **Understand content before style.** Run the storyboard steps first; apply visual style last.
2. **One message per slide**, written as an **action title** — a full-sentence takeaway, never a topic label.
   Reading the titles top-to-bottom must tell the whole story on its own.
3. **Lead with the answer (business) / lead with the objective (education).** In `business` mode use the
   Pyramid Principle: state the recommendation first, then support it. In `education` mode, objectives drive
   what appears and in what order.
4. **Separation of concerns.** Your job is the *storyboard* (`storyboard.json`); the script does the
   rendering. Never hand-write PPTX XML.

## Workflow

### Step 1 — Brief
Fill `templates/brief.template.md` with the user: topic, audience, the single goal (the decision you want, or
the thing learners can do after), `mode` (`business` default / `education`), time budget, hard constraints, and
a style preference. Ask only what you can't reasonably infer.

### Step 2 — Build the storyboard spine
- **business:** Read `references/narrative-frameworks.md`. Identify the **governing thought** (the one-line
  recommendation), then the supporting pillars (MECE), then evidence. Map to
  Situation→Complication→Question→Resolution→Ask.
- **education:** Additionally read `references/instructional-design.md` and `references/learning-science.md`.
  Write **learning objectives** with Bloom's 2001 verbs, list **concepts + prerequisites**, and place
  pedagogy beats (worked examples, retrieval checks, spaced recaps).

### Step 3 — Storyboard + narrative transitions
Read `references/deck-architecture.md`. Produce `storyboard.json` conforming to
`schemas/storyboard.schema.json`. Insert **section-divider slides** ("where we've been → where we're going")
at each act boundary — these are the narrative transitions. Validate:

```bash
node scripts/validate-storyboard.mjs storyboard.json
node scripts/check-dag.mjs storyboard.json   # education mode: no concept taught before its prerequisite
```

### Step 4 — Pick a visual style
Read `references/style-systems/README.md` and choose ONE of:
`futuristic-tech` (dark) · `corporate-bright` (light) · `japanese-editorial` · `soft-clay-3d` ·
`minimalist-luxury` · `modern-illustration` · `hand-drawn-editorial`. Tokens live in
`assets/style-tokens/.json`.

### Step 5 — Render
```bash
npm install            # first run only
node scripts/generate.mjs --in storyboard.json --style corporate-bright --out deck.pptx
```
Add a brand logo pinned to the top-right of every slide with `--logo path/to/logo.png` (or set `meta.logo`
in the storyboard). Titles automatically reserve space so they never run under the logo. If the logo has a
white/light wordmark, recolor it for light backgrounds first.

### Step 6 — (Optional) motion — OFF by default
Only if the user asks for motion. Two independent, stackable injectors:

**Slide transitions** (between slides). Pass the storyboard so section dividers turn like a chapter (push) and
the rest fade:
```bash
node scripts/inject-transitions.mjs --in deck.pptx --storyboard storyboard.json
```

**Click builds** (within a slide): the title appears on the first click, then each body topic appears one-by-one
on subsequent clicks. Run this AFTER transitions:
```bash
node scripts/inject-builds.mjs --in deck.pptx
```
Builds target the shapes the renderer tags `sage-title` / `sage-body`, so they apply automatically to content,
data, summary, two-column, comparison, and call-to-action slides. These are intricate OOXML animations —
confirm playback in PowerPoint before presenting.

### Step 7 — QA gate (always)
```bash
node scripts/qa-report.mjs --storyboard storyboard.json --deck deck.pptx
```
Fix every FAIL before delivering. Checklist source: `references/qa-checklist.md` (one message/slide, action
titles, contrast, MECE pillars, DAG order satisfied in education mode, citations present where claims are made).

## The storyboard contract

The single artifact you author. See `schemas/storyboard.schema.json` and `templates/storyboard.example.json`.
Each slide carries an `archetype`, an `actionTitle`, what it `covers`/`teaches`, a `visual` spec, a
`narrativeRole`, and speaker `notes`. Keep it declarative — describe intent, not PPTX primitives.

## Requirements

- **Node.js ≥ 18** and `npm install` in the skill root (PptxGenJS + a zip lib for the optional fade).
- No network needed at render time; fonts are embedded or substituted per style token.

## Provider portability

This skill is plain text + Node scripts following the open Skill convention. Any LLM agent that can read
`SKILL.md`, write a JSON file, and run a shell command can use it. The storytelling/pedagogy reasoning is
model-agnostic; only the renderer is fixed, so output is consistent across providers.

## Reference index (load on demand)

| File | Use it for |
|---|---|
| `references/narrative-frameworks.md` | Pyramid Principle, S-C-R, action titles, transition beats |
| `references/deck-architecture.md` | slide archetypes + deck skeletons (business & education) |
| `references/instructional-design.md` | Bloom's, backward design, objectives *(education)* |
| `references/learning-science.md` | retrieval, spacing, interleaving, cognitive load *(education)* |
| `references/concept-sequencing.md` | building/validating the prerequisite graph *(education)* |
| `references/slide-patterns.md` | per-archetype layout recipes |
| `references/chart-design.md` | data-visualisation styling |
| `references/style-systems/*` | the six visual systems + how to choose |
| `references/qa-checklist.md` | the pre-delivery gate |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [vedraut](https://github.com/vedraut)
- **Source:** [vedraut/slidesage](https://github.com/vedraut/slidesage)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-vedraut-slidesage-slidesage
- Seller: https://agentstack.voostack.com/s/vedraut
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.