World Class Carousel

World-Class Instagram Carousel Generator

Generate Instagram carousels that are genuinely world-class: content people save, share, and come back to. Not engagement bait. Not AI slop. Actual value, delivered through precise visual design and narrative structure.

This skill is fully generalized. It contains FORM (structure, principles, patterns), not MATTER (specific topics). The user provides the matter (topic); the skill provides the form (archetypes, design system, music matrix, quality gates). Together they produce the carousel. Nothing is hardcoded.

---

BEFORE YOU START: Read KNOWN_ISSUES.md

Before generating ANY carousel, read /home/node/.claude/skills/world-class-carousel/KNOWN_ISSUES.md. It contains compressed rules from all previous sessions -- data format gotchas, sizing rules, visual strategy decisions, and quality gates. Ignoring it means repeating solved mistakes.

---

EXECUTION PIPELINE

When the user requests a carousel, execute these 6 phases in order (Phase 6 runs post-delivery):

PHASE 1: RESEARCH & STRUCTURING

1. Analyze the topic -- What is the core insight? What specific value can this deliver?
2. Identify the audience -- What does the target audience NOT already know? What's their current understanding?
3. Auto-detect content vertical and theme -- Use the Content Vertical Detection table below
4. Select the archetype -- Which of the 7 carousel archetypes (see below) fits best? Use the Archetype Selection Guide below. Auto-select unless the user specifies.
5. Design the narrative arc -- Map each archetype role to a renderer slide type using the Role-to-SlideType Mapping below. Ensure each slide creates a curiosity gap that the next slide resolves.
6. Run the Bullshit Test on the outline -- Does every slide pass? (See QUALITY GATE below)

Content Vertical Detection (Topic -> Theme)

Analyze the topic and auto-select the renderer theme:

| Content Vertical | Keywords/Signals | Renderer Theme | Background Style | |-----------------|-----------------|----------------|-----------------| | Tech / AI / Coding | AI, code, developer, API, tools, stack, programming, SaaS, data | dark | gradient (default) | | Business / Strategy | growth, revenue, startup, founder, marketing, sales, strategy, scale | earth | gradient | | Education / How-To | learn, tutorial, guide, roadmap, beginner, master, course, how to | clean | gradient | | Creative / Design | design, UX, brand, visual, aesthetic, portfolio, creative | dark | gradient_mesh | | Mindset / Philosophy | mindset, habits, productivity, stoic, growth, mental, philosophy | warm | gradient |

If the user specifies a brand config with a theme, always use that instead.

Content Category Selection (10 Categories, Aristotelian)

Each category has unique visual DNA derived from psychology axioms (Cialdini, cognitive load theory, dual coding, serial position effect). Select based on topic:

| If the topic is about... | Category | Arc Shape | Hook Style | Primary Cialdini | |--------------------------|----------|-----------|------------|------------------| | Explaining a research paper | paper_decoder | Revelatory | Face + paper panel | Authority | | Comparing AI tools/models | tool_showdown | Divergent | Multi-screenshot face-off | Social Proof | | Today's AI development | breaking_news | Convergent | News-editorial face | Scarcity | | Step-by-step AI tool how-to | tool_tutorial | Linear | Phone-in-hand / device mockup | Reciprocity | | Controversial opinion | hot_take | Confrontational | Bold abstract typography | Authority | | Copy-paste prompts/templates | prompt_playbook | Divergent | Phone screenshot mockup | Reciprocity | | Complete sector overview | industry_map | Divergent | Multi-person face-off | Authority | | Build [X] with AI project | build_this | Linear+Reveal | Multi-device result showcase | Social Proof | | Funding/business news | founders_money | Convergent | Founder portrait + data | Scarcity | | Future predictions/timeline | future_scenario | Revelatory | Abstract cinematic AI imagery | Scarcity |

Universal Psychology Rules (apply to ALL categories):

• Max 4 information chunks per slide (Cognitive Load Theory, Sweller)
• Pattern interrupt every 2-3 slides (diagram, comparison, color shift, or layout change)
• Density wave: H-M-H-M-H-H-M (never 3 high-density slides consecutively)
• Synthesis slide = THE save trigger (Serial Position Effect: last items remembered best)
• Dual-code the hardest concept (Paivio: visual + text = 6.5x retention)
• CTA matches save trigger: utility categories → "Save this", social categories → "Share/Comment"

Category-to-Slide-Sequence Quick Reference:

• paper_decoder (9 slides): hook → body → diagram → body → body → diagram → body → synthesis → cta
• tool_showdown (8 slides): hook → body → comparison → body → body → comparison → synthesis → cta
• breaking_news (8 slides): hook → body → body → body → diagram → body → synthesis → cta
• tool_tutorial (8 slides): hook → body → tool → tool → tool → body → synthesis → cta
• hot_take (7 slides): hook → body → body → body → body → synthesis → cta (text-driven, no diagrams)
• prompt_playbook (9 slides): hook → body → body → body → comparison → body → body → synthesis → cta
• industry_map (9 slides): hook → diagram → body → body → body → comparison → diagram → synthesis → cta
• build_this (8 slides): hook → body → tool → tool → tool → body → synthesis → cta
• founders_money (7 slides): hook → body → body → body → diagram → synthesis → cta
• future_scenario (8 slides): hook → body → body → diagram → body → body → synthesis → cta

Role-to-SlideType Mapping

Map each archetype role to a renderer slide type when building the carousel spec:

| Archetype Role | Renderer Slide Type | Notes | |---------------|-------------------|-------| | hook | hook | Use title + title_highlight for split title effect | | intro, context, reveal, before | body | Use title_highlight for the key phrase | | step, component, layer, shift, evidence, action | body | Use bullets for key points | | item | body | Use title_highlight for the item name, bullets for details | | diagram, connection | diagram | Use diagram_nodes with vertical or horizontal layout | | contrast, reframe | comparison | Use columns with opposing views | | result, after, lesson, implication | body | Use title highlight to emphasize the key outcome | | synthesis | synthesis | Use points[] for numbered key takeaways | | cta | cta | Use handle, cta_text, optional stats[] | | bonus, pitfalls, prediction | body | Use bullets for listed points |

PHASE 1.5: VISUAL STRATEGY DECISION (Before Writing Content)

Before writing any content, decide the visual strategy for this carousel. You have access to multiple tools -- choose the right ones for the topic.

Available Visual Tools Inventory

| Tool | What It Does | When to Use | How to Invoke | |------|-------------|-------------|---------------| | AI Cinematic Images | HD photorealistic/artistic images (Gemini 3 Pro) | Hook/CTA backgrounds, emotional priming, conceptual anchoring | generate-image skill with hyper-detailed prompt (50+ words) | | AI Flowcharts/Diagrams | Production-quality flowcharts with text labels, arrows, boxes | Process flows, pipelines, decision trees -- REPLACES TikZ for better visuals | generate-image skill with structural prompt describing boxes + connections | | AI Architecture Diagrams | Blueprint-style system diagrams with components and connections | Microservices, tech stacks, system design | generate-image skill with component/connection prompt | | AI Infographics/Charts | Bar charts, data visualizations with accurate labels and proportions | Market data, statistics, comparisons | generate-image skill with data + style description | | AI Abstract Backgrounds | Neural networks, geometric patterns, cosmic visuals | Slide backgrounds via ai_bg | generate-image skill with atmosphere/material prompt | | TikZ Diagrams | Vector flowcharts in LaTeX (basic but reliable) | Simple 3-5 node flows where AI image gen is overkill | Use diagram slide type with diagram_nodes | | Gradient Backgrounds | TikZ-rendered gradient fills with geometric accents | Default for all text-only slides | Set bg_style: "gradient" in slide data |

CRITICAL: Slide-Type Visual Rule (Experimentally Verified)

This rule was established through controlled A/B experiments (7 strategies, same content, scored 1-10). It overrides gut instinct:

| Slide Type | Visual Strategy | WHY (Experimental Evidence) | |-----------|----------------|---------------------------| | Hook | ai_bg full-bleed + 0.60-0.68 overlay | Scroll-stopping power. First slide = 80% of engagement. Score: 8.0/10 | | Body | TEXT-ONLY. No images. | Images on body slides destroy 40% of content space. Text-only scored 8.3/10 vs 5.7/10 with images | | Diagram | AI-generated diagram as ai_bg (preferred) OR TikZ fallback | Gemini 3 Pro generates production-quality flowcharts with readable labels, arrows, and boxes. Far more visually striking than basic TikZ. Use ai_bg + 0.55-0.65 overlay so text remains readable over the diagram. | | Synthesis | Text-only | Save-worthy reference material. Images would reduce information density. | | CTA | ai_bg full-bleed + 0.65-0.70 overlay | Emotional close with visual punch. |

DO NOT put AI images on body slides. This was the single biggest quality mistake found in testing. DO NOT use browser screenshots on any slides. They always look terrible embedded in carousel slides.

Visual Strategy Decision Matrix (Topic-Level)

For each topic, determine the primary visual mode, background style, and which slide-level visuals to use:

| Topic Type | Background Style | Hook Visual | Body Visuals | Diagram Strategy | Example | |-----------|-----------------|-------------|-------------|-----------------|---------| | Philosophy / Mindset | gradient | AI image: symbolic figure | None (text carries weight) | AI-generated concept map | Stoic principles: marble bust + storm | | Tool Review / SaaS | gradient or gradient_mesh | AI image: abstract tech glow | None (text-only bullets describe tools) | AI-generated comparison chart | "6 AI Tools": text descriptions + AI chart | | News / Current Events | gradient | AI image: dramatic scene | None (text with citations) | AI-generated timeline or power map | "AI War 2025": cinematic + AI power map | | Technical Tutorial | gradient (clean) | AI image: conceptual diagram | None (step-by-step text) | AI-generated architecture/flowchart | "Deploy with Docker": AI architecture diagram | | Business / Strategy | gradient | AI image: bold abstract | None (text with real data citations) | AI-generated bar chart or funnel | "Growth Hacking": AI infographic | | Comparison / Versus | gradient_mesh | AI image: abstract contrast | comparison slide type columns | AI-generated side-by-side chart | "React vs Vue": comparison columns + AI chart | | Creative / Design | gradient_mesh (dark) | AI image: artistic/gallery quality | None (text-only) | AI-generated process flow | "UX Trends 2025": artistic + AI flow | | Framework / Mental Model | gradient | AI image: system metaphor | None (text explains components) | AI-generated flowchart (preferred over TikZ) | "OODA Loop": AI flowchart as ai_bg | | Data / Research | gradient | AI image: data visualization concept | None (text with specific numbers) | AI-generated bar chart / infographic | "AI Market 2025": AI bar chart |

AI Image Generation Best Practices

Model & Routing:

• Use generate-image skill (uses AI_GATEWAY_API_KEY). Nano-banana-pro requires GEMINI_API_KEY (often unset) but uses the same underlying model.
• Model: google/gemini-3-pro-image-preview (primary). Fallback: google/gemini-3.1-flash-image-preview.
• Output: ~1408x768 landscape. Overlay compensates for portrait stretch on slides.

Gemini 3 Pro Proven Capabilities (Experimentally Verified):

| Capability | Quality | Best Use in Carousels | Prompt Strategy | |-----------|---------|----------------------|-----------------| | Cinematic portraits | Excellent | Hook/CTA backgrounds | 50+ words: materials, lighting, composition, colors, atmosphere | | Multi-image composition | Excellent (avg 9.6/10) | Hook slides with real faces + screenshots | Aristotelian axioms below. Send base64 to /api/v1/images/generations | | Screenshot → device mockup | Excellent | Tool showcase, product launch slides | "floating laptop/phone mockup, dark studio, reflective surface" | | Person + screenshot editorial | Excellent | News hooks with evidence | "person as SUBJECT, screenshot as floating holographic EVIDENCE panel" | | Multi-screenshot dashboard | Excellent | Comparison/versus slides | "floating panels at varied depths, color-coded edge glows, grid floor" | | Flowcharts | Excellent | Diagram slides as ai_bg | Describe boxes, arrows, labels, and connections structurally | | Abstract backgrounds | Excellent | Any slide background | Materials, colors, atmosphere, "no text no words" |

The 7 Aristotelian Axioms for Multi-Image Composition (Experimentally Proven)

These irreducible premises govern ALL multi-image prompts. Every prompt must satisfy all 7:

A1: VISUAL HIERARCHY -- Eye processes: faces > contrast edges > text > color fields. Composition must respect this order. A2: INPUT TYPE DETERMINES ROLE -- Each input has exactly one role:

• Photo of person → SUBJECT (preserve face, never modify)
• Screenshot/UI → EVIDENCE (float as holographic panel, stylize frame, preserve content)
• Logo/brand → ANCHOR (small, consistent corner placement)
• Abstract/texture → ATMOSPHERE (background only)

A3: UNIFIED LIGHT SOURCE -- All elements share one dominant light direction. Mixed lighting = instant "fake" detection. A4: DEPTH CREATES DRAMA -- Foreground sharp (subject), midground recessed (screenshots), background soft (atmosphere). 3 layers minimum. A5: NEGATIVE SPACE IS FUNCTIONAL -- Bottom 30-35% dark for text overlay. Not waste -- it's where the headline goes. A6: COLOR TEMPERATURE = STORY -- Cool blue/teal = innovation. Warm red = urgency. Split red/blue = competition. Mono + accent = editorial. A7: NO-TEXT SEAL -- Always end with "absolutely no text, no words, no letters, no watermarks" (outside screenshots).

Proven Scenario Prompt Templates (avg 9.6/10 across 10 tests)

Person + News Screenshot (9.5/10): "Image 1 is [person] -- preserve face, place in left 60%, dramatic side lighting. Image 2 is screenshot -- float as glowing translucent panel, tilted 8 degrees, recessed behind subject, cyan edge glow. Dark moody background, cinematic depth of field. Bottom 30% dark. No text outside screenshot."

Tool Screenshot Showcase (9/10): "Place screenshot on sleek floating laptop mockup angled 15 degrees. Dark gradient background, ambient teal glow from screen. Glossy reflective surface below. Premium Apple product launch aesthetic. No text outside screenshot."

Multi-Screenshot Dashboard (9.5/10): "Arrange as glowing panels floating in dark space, varied depths and angles (5-15 degrees). Largest centered. Color-coded edge glows. Grid floor, particle effects. Digital command center aesthetic. No text outside screenshots."

Person + Screenshots + Logo (10/10): "Person as dominant subject center-left, face preserved. Screenshots as holographic panels around them. Logo small in upper corner with glow. Volumetric light rays, 3-layer depth. No text outside screenshots/logo."

Face-Off + Data (10/10): "Person A on LEFT in profile fa

…

Source & license

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

• Author: happycapy-ai
• Source: happycapy-ai/Happycapy-skills
• License: MIT

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