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:

--style <name> flag (per-run override)
Brand default_style field in <brand>/config.json
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

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