# Styled Carousel

> Generate carousels using a named style preset. Reads the brand's visual-system.md (brand layer) and styles/<name>/DESIGN.md (style layer), merges tokens kit -> brand -> style, loads visual references from styles/<name>/refs/, and generates each slide via gpt-image-2. Outputs flat-named PNGs with style baked into the filename. Use when generating any carousel for any brand. Do NOT use for: single-image generation, video, ad copy, or any non-carousel output format.

- Skill: `themattberman/styled-carousel` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add themattberman/styled-carousel`
- Raw SKILL.md: https://api.skillmd.com/api/skills/themattberman/styled-carousel/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: TheMattBerman (https://skillmd.com/u/themattberman)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/themattberman/styled-carousel

---


# Styled Carousel

Generate a carousel for a brand using a named style preset. Each slide is
generated by gpt-image-2 conditioned on resolved style tokens, the style's
DESIGN.md body, and 1-5 visual reference images.

```
HOOK → REVEAL → SETUP → EXAMPLES → OUTCOME → CTA
```

The style determines palette, typography, layout grammar, image treatment, and
mood. The brand layer (`visual-system.md`) provides defaults that the style
inherits unless overridden. The kit provides ultimate fallbacks.

## Inputs

- `--brand <slug>` (required): reads `<brands_root>/<slug>/`
- `--style <name>` (optional): reads `<brands_root>/<slug>/styles/<name>/`. Falls back to brand's `default_style` from config.json. Falls back to `social_native` if neither is set.
- `--script <path>` (required): markdown with one section per slide role
- `--output <dir>` (optional): default `<brands_root>/<slug>/runs/<today>/`
- `--sizes <list>` (optional): comma-separated; default reads from style YAML or kit defaults
- `--provider <auto|api|codex-native>` (optional): default `auto`; Codex Desktop uses `codex-native`, other shells use `api`
- `--dry-run`: emit prompts only, no API spend

## Script format

Scripts are markdown files with optional YAML frontmatter declaring format and
close_action. Missing frontmatter defaults to `format: narrative`,
`close_action: save`.

Example (numbered_diagnostic with 4 items):

```
---
format: numbered_diagnostic
close_action: save
---

# HOOK
single emotional pull, 6-15 words.

# TELL #1
body slide; 15-50 words; should contain a specific fact, dated anecdote,
named framework, specific number, or insider tactical aside.

# TELL #2
...

# TELL #3
...

# TELL #4
...

# FIX
the structural fix; 15-50 words.

# CTA
close slide; 10-50 words; must contain action language matching close_action
(unless close_action: soft).
```

See `references/formats/README.md` for the seven formats and their slot
templates.

Heading aliases let you write `# TELL #1` instead of `# ITEM` (numbered_diagnostic
slot ITEM has aliases `[ITEM, TELL, NUMBER, STEP, POINT, RULE, REASON]`).

## Output

For each slide x each size: a PNG named `<style>-slide-<NN>-<size>.png`. The
style name is included in the filename so multi-style runs do not collide.

Plus:
- `prompts.json`: exact prompts used per slide
- `output-log.json`: model, sizes, cost estimate, durations, resolved tokens

## Style resolution

At runtime the skill resolves the active style identifier in this order:

1. `--style <name>` flag (per-run override)
2. Brand `default_style` field in `<brand>/config.json`
3. Kit default: `social_native` (read from `references/styles/social_native/`)

Tokens then merge kit defaults <- brand `visual-system.md` <- style `DESIGN.md`.

Visual references in `<style>/refs/*.png` (cap 5) load into gpt-image-2's
`image_input` array.

## Workflow

1. Resolve active style identifier per the order above
2. Load brand DNA: brand-voice.md, brand-perspective.md (for copy + framing)
3. Resolve token bundle via `lib/style_resolver.resolve(brand_design, style_design)`
4. Read style DESIGN.md body (markdown intent + do/don't rules)
5. Read script and parse the slide-role sections
6. For each slide: compose prompt = (resolved tokens block) + (DESIGN.md body) + (slide intent)
7. Load `<style>/refs/*.png` (sorted, capped at 5) into image_input
8. Call `scripts/generate_styled_carousel.py` per slide x size
9. Save PNGs + prompts.json + output-log.json

When running inside Codex Desktop, `--provider auto` writes
`native-generation-requests.json` instead of calling the OpenAI image API. The
Codex agent must generate each request natively and save the PNG at the listed
`output_path`. Use `--provider api` only when the operator explicitly wants the
OpenAI API path.

## Authoring a new style

Run `scripts/add_style.sh --brand <slug> --style <name>` with either a
description, reference images, or both. The script invokes the host agent to
generate a DESIGN.md and populate refs/.

## References (one level deep)

- `references/styles/social_native/` - kit-default reference style
- `references/style-system.md` - DESIGN.md schema, token inheritance, authoring guide
- `references/slide-arc.md` - the 6-slide narrative arc (HOOK -> CTA)