yuv-decks

What this skill does

# yuv-decks — Build Yuval Avidani-style cinematic decks

The opinionated playbook for **talk decks** built on open-slide. Defines:

- **The Yuval voice** — plain-language, no jargon, story-driven
- **The 4-act narrative arc** — Boarding → Ascent → Cruise → Descent
- **The JourneyBar** — the single unifying visual on every slide
- **Companion-skill orchestration** — yuv-design-system, slide-authoring, nano-banana-pro, hyperframes, mermaid

**Visual palette is pulled from `yuv-design-system` in Decks mode** — Fly High purple/yellow/grey (the dedicated palette for slide-based output). For talks whose central metaphor IS literal flight, this skill's own **cinematic-flight** opt-in mode (sky-blue + hot pink) — see Step 5 — overrides the design system's Decks tokens. Never use Neon mode for slides; Decks mode is exclusive to presentations.

This skill is the distillation of building "Build Agents That Ship" for the NICE pre-hackathon (May 2026). Read it end-to-end before drafting any slides.

## Where this skill sits in the YUV.AI pyramid

`yuv-decks` is in the **middle tier** of the YUV.AI skills pyramid. The top-tier orchestrator `yuv-pilot` routes here when the user wants a slide deck. You can also be invoked directly when the user says "make me a deck" without going through yuv-pilot first.

When this skill calls `yuv-design-system`, it **MUST lock the mode to "Decks"** — never let it fall through to Neon (web/app palette) or Warm Editorial. Decks mode is the only palette mode for slides.

See `yuv-pilot/SKILL.md` for the full pyramid map and routing table.

**Reference implementation**: <https://github.com/hoodini/build-agents-that-ship> (private — clone if you have access; the entire pattern this skill describes is implemented there).

---

## What this skill builds on

`yuv-decks` is the **opinionated layer**. It explicitly delegates to:

| Skill | Owns | When to consult |
|---|---|---|
| **`yuv-design-system`** | Palette, typography, animation library, brand assets, signature components (`PurpleBar`, `YellowUnderline`, `FlightHUD`, `CompassDial`, `CounterUp`, `HeroBg`), canonical social links, Hyperframes patterns | Always. Step 5, Step 6, and any time you touch palette/type/components. |
| **`slide-authoring`** | Open-slide file contract, 1920×1080 canvas, type scale defaults, vertical budget math, asset paths, hard framework rules | When writing the JSX for each page (Step 6 onward). |
| **`create-slide`** | Generic open-slide author (asks scoping questions and picks a theme) | For non-Yuval-voice decks (other people, generic content). `yuv-decks` supersedes it for Yuval's signature talk style. |

The yuv-decks rules **add on top** of yuv-design-system and slide-authoring; they never override them.

---

## When to invoke this skill

The user wants a *talk* or *presentation* deck. Triggers:

- "Make me a deck about X"
- "Create slides for a talk on Y"
- "Build a presentation for the [company] hackathon"
- "I'm presenting about Z — help me build the deck"
- "מצגת על..." / "שקפים על..." / "דק על..."

Do NOT invoke for: a single landing page, a video, a document, a Google Slide PowerPoint export. This skill is for **open-slide React decks** rendered at 1920×1080 with cinematic motion.

---

## Step 0 — Bootstrap the project

**Default save location:** `~/Documents/yuv-projects/decks/<deck-slug>/` — always save decks here so you can find them again later. The skill creates the parent directory if it doesn't exist. Override only if the user explicitly asks for a different location.

```bash
# Pick a slug. Lowercase, hyphenated, descriptive.
mkdir -p ~/Documents/yuv-projects/decks
cd ~/Documents/yuv-projects/decks
npx @open-slide/cli init <deck-slug>
cd <deck-slug>
npm install
npm run dev   # starts the preview at http://localhost:5173
```

Final path: `~/Documents/yuv-projects/decks/<deck-slug>/`. Tell the user where the deck lives at the end of every session.

The scaffold creates `slides/getting-started/` (a demo). You will create your own slide under `slides/<deck-id>/index.tsx` and delete or ignore the demo.

---

## Step 1 — Scope the deck (ASK BEFORE WRITING)

Before drafting, lock in these four decisions via a single `AskUserQuestion` (multi-question form):

1. **Topic & audience** — what is the deck *for*, and *who* will be in the room? Get the customer's actual agenda if possible (literal bullets they expect to hear) — match 1:1.
2. **Page count** — Short (5–6), Standard (8–10), Deep dive (12–24).
3. **Language** — English / Hebrew / Bilingual. Yuval is bilingual; pick based on audience.
4. **Speaker context** — Is Yuval the presenter? Is this for a specific company (NICE, etc.)? Knowing the host lets you craft callback moments ("…yes, the company you're sitting in…").
5. **Visual mode** — Fly High (default purple) or cinematic-flight (sky-blue + hot pink, only when the talk's central metaphor IS literal flight). When in doubt: Fly High.

Do NOT skip this step. Every redirect later in the build traces back to a wrong assumption here.

---

## Step 2 — The Yuval Voice (non-negotiable rules)

All copy follows these three rules:

### Rule 1 — Plain language, never jargon
Replace every term that isn't a household word:

| Don't say | Say instead |
|---|---|
| EBIT | real profit |
| PoC | the prototype / the demo phase |
| BYOC | your own cloud |
| service-account-as-god | admin-token-for-everything |
| RAG | lookup before answering |
| fine-tuning | training the model on your data |
| vLLM | local LLM runner |

If a *name* must stay (LiteLLM, Bedrock, Anthropic, Cognigy) — keep it, but **define it in 3 words on first mention** ("LiteLLM — an AI gateway library").

### Rule 2 — Short sentences. Punchy fragments. Like this.
Maximum **8–12 words per bullet**. Cut all "thus / therefore / however." If a sentence wraps to 3 lines, split or shorten.

**Calibration test** — transform this BEFORE writing any draft:

> ❌ "When Watson got a recommendation wrong, nothing learned from it. Same mistakes, repeated for years. The system never improved with use."
>
> ✅ "Watson made a mistake. Watson kept making it. For years."

### Rule 3 — Define every name on first mention
"Watson is IBM's AI. Won Jeopardy in 2011. Then aimed at hospitals."
"Klarna is Sweden's biggest fintech — Buy Now Pay Later, 150M customers."

Never assume the audience knows who/what.

---

## Step 3 — The Narrative Arc (4 acts)

The structure that survives audiences:

```
ACT I · BOARDING — The Stakes              (slides 1–4)
  Cover · Hook stat · Sources agree · Failure patterns

ACT II · ASCENT — The Stories              (slides 5–9)
  Failure case story · Why it failed (4 bullets) ·
  Success case story · Why it worked (4 bullets) ·
  Reference example (real product the audience knows)

ACT III · CRUISE — The Build               (slides 10–22)
  Anatomy · Agent types · MCP · Multi-agent · Where to apply ·
  Client stack · Server infra · Gateway · Routing · Tracking ·
  Optimization · Evals · MVP → Production

ACT IV · DESCENT — The Action              (slides 23–24)
  How to start tomorrow · Closing
```

**Structural laws:**
- Case studies CLUSTER together (slides 5–9). Don't interleave with considerations.
- Each case study is **TWO slides**: the *story* + the *lessons* (4 specific failure points or success moves). The lessons slide is where "aha tokens drop."
- Stories BEFORE considerations. The audience needs *why it matters* before *how to do it*.
- Cut anything not in the customer's agenda — even if you love it. (Examples cut in the NICE deck: ROI math, Mgmt Pitch, Skill-vs-Agent-vs-Feature-vs-Product, Obsolescence Check.)

---

## Step 4 — Case Study Triplet (failure + success + reference)

Always anchor with three **real, public, verifiable** stories:

| Role | What it is | Example used in the NICE deck |
|---|---|---|
| **Failure** | The most-funded, most-public AI/enterprise project that crashed. Name the *specific* failure points. | IBM Watson Health ($4B over 11 years, 0