A complete content creation toolkit — writing, content strategy, visual design, AI image generation, branding, and YouTube/Substack platform workflows

GitHub stars
128

Install

/plugin install creator-stack@ai-launchpad

Run it inside Claude Code after adding the marketplace with /plugin marketplace add kenneth-liao/ai-launchpad-marketplace.

Contents

Discovered from source

Skills 21

Brand Guidelines Generator

Create a self-contained brand guidelines skill through guided discovery. The generated skill lives at the user level and enforces brand identity across all future Claude Code sessions.

Workflow Overview

Execute these phases in strict order. Phase 0 is optional (skip if the user has no existing assets to share). Never skip Phases 1-4. Each phase builds on the previous.

PhaseNameActionOutput
0Context IngestionCollect + analyze existing business assetsExtracted brand signals + smart defaults for discovery
1Brand DiscoveryInteractive questionnaire across 6 dimensionsUser preferences for brand identity
2Synthesis & PreviewFormat and present brand summaryUser-confirmed brand identity spec
3Skill GenerationGenerate user-level SKILL.md from template~/.claude/skills/{brand-slug}/SKILL.md
4Optional DS CreationCreate design systems for unmapped asset typesUpdated mapping table in brand skill

Phase 0: Context Ingestion (Optional)

Before starting discovery, ask the user if they have existing business assets to share. Existing context dramatically reduces the number of questions needed — the skill extracts what it can and only asks about what's missing or ambiguous.

Opening prompt: "Before we start defining your brand, do you have any existing assets I can learn from? These could be your website, newsletter archives, social media profiles, pitch decks, brand documents, images, or anything that represents your brand today. This is optional — we can build entirely from scratch too."

Supported input types:

Input TypeHow to ProvideWhat to Extract
Website URLUser provides a URL like https://mybrand.comUse WebFetch to capture the page. Extract: brand name, tagline (from hero/header), mission/about copy, value proposition, tone signals from copywriting style, target audience signals, content categories (→ asset types). Follow internal links to About, Mission, and similar pages if present.
Newsletter / blog postsUser provides URLs, files, or pastes contentAnalyze writing style for voice and tone signals. Extract: recurring topics (→ value prop), how the author addresses readers (→ audience), vocabulary level (→ tone modifiers), sentence structure patterns.
DocumentsUser provides file paths (PDF, MD, TXT, DOCX)Read and analyze. Could be pitch decks, brand guides, one-pagers, course outlines, etc. Extract any brand identity data present.
Images / logosUser provides file paths or pastes imagesRead images visually. Extract: brand name from wordmarks, color palette signals, visual style/mood, existing design system hints.
Social media profilesUser provides profile URLsUse WebFetch to capture. Extract: bio (→ tagline/mission), content themes, posting style (→ voice), follower description (→ audience), platform mix (→ asset types).
Existing brand skillUser points to a previous SKILL.mdRead it as a starting point for updates. Pre-fill all dimensions from existing data.
SkipUser has no assets to shareProceed directly to Phase 1 with no smart defaults.

Analysis protocol:

For each provided asset, extract and categorize signals into the 6 discovery dimensions:

DimensionWhat to Look For
1. Brand name & taglineLiteral brand name, slogans, header text, social bios
2. Mission & value propAbout pages, mission statements, "what we do" sections, pitch deck opening slides
3. Voice & tone traitsCopywriting style — formal vs. casual, assertive vs. supportive, humorous vs. serious
4. Tone modifiersSentence length patterns, vocabulary level, use of jargon, narrative vs. direct style
5. Target audiencesWho the content addresses ("you" references), testimonials, case studies, subscriber descriptions
6. Asset typesWhat visual content exists (thumbnails, social posts, headers, slides, etc.)

After analysis, present a summary:

"Here's what I extracted from your assets:

  • Brand name: {name} | Tagline: {tagline or "none found"}
  • Mission signals: {1-2 sentence summary of what the brand appears to be about}
  • Voice signals: {detected traits, e.g., "Reads as friendly and expert — conversational but backs up claims"}
  • Tone signals: {detected modifiers, e.g., "Short punchy sentences, casual vocabulary, avoids jargon"}
  • Audience signals: {who the content seems to target}
  • Asset types spotted: {list of visual content types found}

I'll use these as starting points during discovery. You'll have full control to confirm, adjust, or override everything."

Store the complete analysis as context_analysis with per-dimension confidence levels:

  • High confidence — clear, unambiguous signal (e.g., brand name from a logo, explicit mission statement)
  • Medium confidence — strong signal but inferred (e.g., voice traits from writing style analysis)
  • Low confidence — weak or mixed signals (e.g., audience guessed from content topics)

Phase 1: Brand Discovery

Guide the user through structured questions to define their brand identity. Use the AskUserQuestion tool to present options. Ask questions one dimension at a time to keep the conversation focused.

Load the full question bank from references/discovery-framework.md.

Rules:

  • Ask dimensions in order (they build on each other)
  • One dimension per AskUserQuestion call — do not batch across dimensions
  • If Phase 0 produced smart defaults, adapt each dimension based on confidence level (see Smart Default Behavior below)
  • For open-ended dimensions, use AskUserQuestion with broad options that prompt elaboration
  • For multi-choice dimensions, present all options with descriptions and enable multiSelect
  • After each answer, give a brief 1-sentence acknowledgment contextualizing the choice, then move to the next dimension
  • Complete ALL 6 dimensions before moving to Phase 2
  • If the user wants to go back and change a previous answer, allow it

Smart Default Behavior (when Phase 0 data exists):

ConfidenceBehavior
HighPresent the extracted value and ask for confirmation: "From your website, I found your brand name is {name} with tagline {tagline}. Sound right, or want to change it?" Use AskUserQuestion with the extracted value as the first option and "I want to change this" as the second.
MediumPresent the extracted value as a suggested default: "Based on your writing style, I'd suggest Friendly & approachable + Expert & authoritative — your content is conversational but backs up claims with evidence. Does this match your intent?" Still present all options with the suggestion pre-noted.
LowPresent all options normally but note what was observed: "Your content seems to target developers, but I wasn't sure — who is your primary audience?"
No signalAsk the full question as defined in the discovery framework with no pre-selection.

Dimensions (in order):

  1. Brand name & tagline
  2. Mission & value proposition
  3. Voice & tone traits
  4. Tone modifiers
  5. Target audiences
  6. Asset types & design system mapping

Dimension 6 — Special handling:

Before presenting asset type options, scan ~/.claude/.context/design-systems/ to discover available design systems. For each directory found, read the design system markdown file to extract the style name.

After the user selects their asset types, ask a follow-up for each selected asset type: which design system should be used? Present three options per asset type:

  • Each discovered design system (by style name)
  • "Create new design system" — flags this type for Phase 4
  • "Decide later" — leaves the mapping empty for now

Store the complete mapping as asset_ds_mapping.


Phase 2: Synthesis & Preview

After all 6 dimensions are answered, synthesize into a formatted brand summary and present for confirmation.

Steps:

  1. Derive the brand slug from the brand name: lowercase, spaces and special characters replaced by hyphens (e.g., "AI Launchpad Newsletter" → ai-launchpad-newsletter)
  2. Synthesize voice traits + tone modifiers into 3-4 voice application rules — concrete, actionable guidelines for how this brand should sound
  3. Derive brand anti-patterns from the inverse of chosen voice traits (see mapping in template reference)
  4. Build audience profiles — for each audience segment, infer goals, frustrations, what resonates, and preferred platforms based on the user's description
  5. Format the complete brand summary:

Present to the user:

## Brand Summary: {brand_name}

**Tagline:** {tagline}
**Mission:** {mission}
**Value Prop:** {value_prop}

**Voice Traits:** {trait_1}, {trait_2}
**Tone Modifiers:** {modifier_1}, {modifier_2}

**Voice Application Rules:**
- {rule_1}
- {rule_2}
- {rule_3}

**Audiences:**
- Primary: {primary_audience}
- Secondary: {secondary_audience}

**Asset Type → Design System Mapping:**
| Asset Type | Design System |
|------------|---------------|
| {type_1} | {ds_1 or "Create new" or "Decide later"} |
| ... | ... |

**Anti-Patterns (things this brand should NEVER do):**
- {anti_pattern_1}
- {anti_pattern_2}
- ...
  1. Ask the user: "Does this brand summary look right? Want to change anything before I generate the skill?"
  2. If the user wants changes, update the relevant fields and re-present
  3. Once confirmed, proceed to Phase 3

Phase 3: Skill Generation

Generate the brand guidelines skill at ~/.claude/skills/{brand-slug}/SKILL.md.

Steps:

  1. Load the template from references/brand-skill-template.md
  2. Fill every {{placeholder}} with the confirmed brand data from Phase 2
  3. Ensure the generated skill is fully self-contained — all brand data embedded directly, no references to external config files
  4. Create the directory ~/.claude/skills/{brand-slug}/ if it doesn't exist
  5. Write the generated SKILL.md to ~/.claude/skills/{brand-slug}/SKILL.md
  6. Verify the generated skill — read the file back and check:
    • No unfilled {{placeholder}} markers remain
    • All 6 sections are present (Brand Identity, Voice & Tone, Target Audiences, Design System Resolution, How To Apply, Brand Anti-Patterns)
    • The asset type mapping table has the correct number of rows
    • If any issues found, fix and re-write before proceeding
  7. Inform the user:

    "Your brand guidelines skill has been created at ~/.claude/skills/{brand-slug}/SKILL.md. Restart Claude Code to activate it — user-level skills are loaded at startup."


Phase 4: Optional DS Creation

If any asset types in asset_ds_mapping were mapped to "Create new design system", offer to create them now.

Steps:

  1. List all asset types mapped to "Create new"
  2. Ask the user: "You flagged {N} asset type(s) for new design systems: {list}. Want to create them now, or come back later?"
  3. If the user wants to create now: a. For each asset type, invoke the creator-stack:design-system skill (suggest "user level" as the output location so it's available system-wide) b. After each design system is created, update the brand skill's mapping table:
    • Read ~/.claude/skills/{brand-slug}/SKILL.md
    • Replace the "Create new" entry for that asset type with the new design system's style name and path
    • Write the updated file
  4. If the user wants to come back later, remind them they can update the mapping manually or re-invoke this skill in "update" mode

Updating an Existing Brand Skill

If the user already has a brand skill (detected by checking ~/.claude/skills/ for existing brand directories), offer an abbreviated update flow.

Update workflow:

  1. List discovered brand skills from ~/.claude/skills/*/SKILL.md
  2. Ask the user which brand to update
  3. Read the existing brand skill
  4. Ask which dimensions to update (multi-select from the 6 dimensions)
  5. Run only the selected dimensions from Phase 1
  6. Re-synthesize only the affected sections
  7. Update the existing SKILL.md (preserve unchanged sections)
  8. Inform the user to restart Claude Code

Error Handling

  • If ~/.claude/.context/design-systems/ does not exist or is empty during Dimension 6, inform the user no design systems are available yet and offer "Create new" or "Decide later" as the only options
  • If ~/.claude/skills/{brand-slug}/SKILL.md already exists, ask the user whether to overwrite or choose a different slug
  • If the brand name produces an empty or invalid slug, ask the user to provide a custom slug
  • If the user's voice trait + modifier combination creates a contradictory voice (e.g., "Bold & provocative" + "Casual vocabulary" for a financial services brand), flag the tension during synthesis and ask which direction to prioritize

Create Community Post

Overview

This orchestrator creates YouTube community posts by sequencing creator-stack:research for strategic context and creator-stack:write for content generation. It handles episode awareness, post type selection, and output management — all actual content generation and strategy are delegated to the foundation skills.

Core Principle: This is a thin orchestrator. Strategy lives in creator-stack:research (via its references/youtube-community-strategy.md). Templates and formatting live in creator-stack:write (via its references/youtube-community-post.md). This skill manages the workflow sequence, episode context, and user decisions only.

How Reference Delegation Works

Both foundation skills own their own reference files. When you invoke creator-stack:research and specify "youtube community post" as context, it loads its strategy reference. When you invoke creator-stack:write with content type "youtube community post", it loads its template reference. Those files live in each skill's directory, not here.

When to Use

Use this skill when:

  • Promoting a new or upcoming video through the community tab
  • Maintaining audience engagement between video uploads
  • Running audience research polls to inform future content
  • Driving conversions (affiliate links, memberships, newsletter signups)
  • Creating any community tab content for a YouTube channel

Prerequisites

Optional: An episode directory at ./youtube/episode/[episode_number]_[topic_short_name]/ with a plan.md file. This is only needed for video-linked posts (pre-release, launch day, post-launch). Between-video engagement posts do not require an episode directory.

Workflow

Execute all steps below in order.

Step 0: Episode Context Check

Check if the user has specified an episode or if an episode directory exists at ./youtube/episode/[episode_number]_[topic_short_name]/.

If episode directory exists:

  • Read plan.md for video title, topic, and context
  • Suggest a lifecycle phase based on context:
    • Video not yet published → pre-release
    • Video just published → launch day
    • Video published 3-7 days ago → post-launch
  • Use this context to inform the research invocation in Step 1

If no episode directory:

  • Default to between videos mode
  • Posts will focus on engagement, audience research, or value delivery

Step 1: Invoke Research for Strategic Context

Invoke creator-stack:research with the community post context to determine strategy.

Provide:

  • The lifecycle phase (from Step 0 or user input)
  • The video topic (if applicable)
  • The user's stated goal (engagement, promotion, research, conversion)

The research skill applies the strategy framework to determine:

  • Optimal post type ranking for the context
  • Timing recommendations
  • Strategic rationale for the approach

NOTE: This is a lighter research invocation — asking research to apply the strategy framework to the user's context, not to do full competitor analysis.

Step 2: Present Post Type Options

Based on the research output, present the ranked post type options to the user:

  1. Poll (text or image) — highest engagement
  2. Video teaser/clip — high engagement
  3. GIF — medium-high engagement
  4. Image — medium engagement
  5. Quiz — medium engagement
  6. Text-only — lowest engagement

Include the research skill's recommendation for which type best fits the context. User selects their preferred type.

Default to polls when unsure — they have the lowest friction and highest engagement.

Step 3: Invoke Writing Skill for Content

Invoke creator-stack:write with content type "youtube community post" to draft the post.

Provide:

  • The selected post type from Step 2
  • The strategic context from Step 1
  • The episode context from Step 0 (if applicable)
  • The lifecycle phase and user's stated goal

The writing skill automatically invokes creator-stack:voice for voice consistency. Its reference file contains all templates, formatting rules, and the 288-character hook rule.

Step 4: Quality Checklist

Verify the drafted post against all eight criteria before presenting to the user:

  • Hook lands within 288 characters (visible preview cutoff)
  • Total length is 150-400 characters
  • Ends with a CTA (question, poll, or link)
  • Conversational tone — not corporate or automated
  • First person, direct address ("I" and "you")
  • Mobile-friendly — short paragraphs, line breaks between ideas
  • NOT a generic "new video out" link dump
  • Post type matches the stated purpose/phase

If any criterion fails, request a revision from creator-stack:write before presenting to the user.

Step 5: Save Output

Present the final post to the user for approval.

If episode directory exists:

  • After user approval, append to ./youtube/episode/[episode_number]_[topic_short_name]/community-posts.md

If no episode directory:

  • Present the final post inline to the user

Output Format

When saving to community-posts.md, use this structure:

# Community Posts - Episode [Number]: [Topic]

## [Phase] Post - [Date]

**Type:** [Poll / Teaser / GIF / Image / Quiz / Text]
**Phase:** [Pre-release / Launch Day / Post-Launch / Between Videos]
**Goal:** [Engagement / Promotion / Research / Conversion]

### Post Content

[Final post text]

### Notes

- Suggested timing: [from research]
- CTA type: [question / poll / link]

Multiple posts for the same episode are appended to the same file with a horizontal rule separator (---) between entries.

Quality Checklist

Verify completion before finalizing:

  • Episode context checked (Step 0)
  • creator-stack:research invoked — strategic context determined
  • Post type options presented and user selection received
  • creator-stack:write invoked — post drafted
  • Voice consistency maintained (handled by writing skill)
  • All 8 quality criteria passed (Step 4)
  • Post presented to user for approval
  • Output saved to episode directory or presented inline

Common Pitfalls

  1. Writing templates inline: All templates live in the writing skill's references/youtube-community-post.md — don't duplicate them here.
  2. Embedding strategy logic: All strategy lives in research's references/youtube-community-strategy.md — don't hardcode timing, cadence, or algorithm advice here.
  3. Skipping foundation skill invocations: Both research and writing skills should be invoked — they have the proven patterns and quality logic.
  4. Ignoring episode context: Always check for an episode directory first — it changes the entire strategic approach.
  5. Defaulting to "new video out" posts: The research and writing skills are specifically designed to avoid generic link dumps — trust the foundation skills.
  6. Skipping the quality checklist: Every post should pass all 8 criteria before presenting to the user.

Design System Generator

Create complete visual design systems from scratch through guided discovery, documentation, and AI-generated asset production.

Workflow Overview

Execute these phases in strict order. Output Location must be asked first. Phase 0 is optional (skip if user has no references). Never skip Phases 1-5. Each phase builds on the previous.

PhaseNameActionOutput
—Output LocationAsk where to save the design systemoutput_location = "local" or "user"
0Reference InputCollect + analyze user reference imagesVisual analysis + smart defaults for discovery
1DiscoveryInteractive questionnaireUser preferences across 10 dimensions
2SynthesisAnalyze + name the styleStyle name, core principles, full spec
3DocumentationGenerate style guide{style-name}-design-system.md
4Asset GenerationGenerate images via creator-stack:nanobanana8 PNG style board elements
5AssemblyOrganize + presentComplete design system directory

Output Location

Before anything else, ask the user where they want the design system saved. Use the AskUserQuestion tool:

Question: "Where should this design system be saved?"

OptionDescription
Local project (current directory)Saves to ./design-system/ in the current working directory. Best when this design system is specific to one project.
User level (system-wide)Saves to ~/.claude/.context/design-systems/{style-name-slug}/. Available across all projects and conversations. Best for brand-wide design systems you'll reuse everywhere (e.g., your YouTube brand, your newsletter brand).

Store the choice as output_location.

Path resolution (happens after Phase 2 when the style name is finalized):

  • Local: {output_dir} = ./design-system/
  • User level: {output_dir} = ~/.claude/.context/design-systems/{style-name-slug}/

Where {style-name-slug} is the style name lowercased with spaces and special characters replaced by hyphens (e.g., "Ink & Ember" → ink-and-ember, "Neon Chalk" → neon-chalk).

User-level design systems are organized so each style gets its own directory:

~/.claude/.context/design-systems/
├── ink-and-ember/          ← YouTube brand
│   ├── ink-and-ember-design-system.md
│   ├── 01-hero-character.png
│   └── ...
├── paper-and-sage/         ← Newsletter brand
│   ├── paper-and-sage-design-system.md
│   ├── 01-hero-character.png
│   └── ...

Phase 0: Reference Input (Optional)

Before starting discovery, ask the user if they have existing visual references to anchor the design system. References dramatically improve consistency by grounding the system in concrete examples rather than abstract descriptions alone.

Opening prompt: "Before we start defining your design system, do you have any existing visual references? These could be brand assets you already use, inspiration images, or examples of styles you like. This is optional — we can build entirely from scratch too."

Supported input modes:

ModeHow to ProvideWhat Happens
Folder pathUser provides a path like ~/brand-assets/ or ./images/Read all image files in the folder (PNG, JPG, SVG, WebP). Limit to 10 most relevant if more are provided.
Individual filesUser provides one or more file pathsRead each image directly.
Website URLUser provides a URL like https://mybrand.comUse WebFetch to capture the page, then analyze the visual design (colors, typography, layout, imagery style).
Direct pasteUser pastes or drags images into the conversationAnalyze the images as provided.
SkipUser says they have no referencesProceed directly to Phase 1 with no smart defaults.

Analysis protocol:

For each reference image or website, extract and document:

  1. Dominant colors — Identify the 3-5 most prominent colors with approximate hex codes. Note which appear to be background, primary, and accent.
  2. Line work / rendering style — Is it illustrated or photographic? If illustrated: line weight (thick/thin), edge quality (clean/sketchy), fill approach (flat/gradient/outline-only).
  3. Composition patterns — Spacing density, focal point placement, symmetry, use of whitespace.
  4. Medium / aesthetic — Flat vector, hand-drawn, 3D, photographic, collage, abstract, etc.
  5. Mood / emotional tone — What feeling does it convey? Warm, corporate, playful, dark, etc.
  6. Character style (if characters present) — Proportions, facial detail level, body style, identifying features.
  7. What's NOT present — Notable absences that may indicate intentional anti-patterns (no gradients, no photography, no text, etc.).

After analysis, present a summary:

"Here's what I'm seeing across your references: [2-3 sentence synthesis of the dominant visual patterns — colors, style, mood, composition]. I'll use this to suggest defaults during the discovery questionnaire, but you can override any suggestion."

Smart defaults:

  • Store the analysis results as reference_analysis
  • During Phase 1, for each dimension where the reference analysis provides a clear signal, pre-select the closest matching option and note: "Based on your references, I'd suggest: [option] — [brief reason from analysis]. Does this match your intent?"
  • If the references are ambiguous for a dimension (e.g., mixed styles across images), present all options without a default and note the ambiguity: "Your references show a mix of [X] and [Y] — which direction do you want to lean?"
  • The user always has full control — smart defaults are suggestions, not decisions

Reference images are preserved for later use:

  • Copy user-provided reference images to design-system/references/ during Phase 5
  • These become part of the Reference Library alongside the 8 generated style board images
  • During Phase 4 asset generation, user references can be provided to nanobanana as style anchors

Phase 1: Discovery

Guide the user through structured questions to define their visual preferences. Use the AskUserQuestion tool to present options.

Load the full question bank from references/discovery-framework.md.

Rules:

  • Ask questions in dimension order (they build on each other)
  • Present 3-4 options per question with clear descriptions
  • Allow multi-select where the framework indicates
  • If Phase 0 produced smart defaults, pre-select the suggested option and include the reasoning. Still present all options — the user decides.
  • After each answer, give a brief 1-sentence acknowledgment contextualizing the choice, then move to the next question
  • Adapt later questions based on earlier answers (the framework specifies when to skip or modify questions)
  • Complete ALL dimensions before moving to Phase 2
  • Batch related questions when possible (max 4 per AskUserQuestion call) to keep the flow efficient without overwhelming

Dimensions (in order):

  1. Primary use cases
  2. Overall vibe / mood
  3. Medium preference (illustration vs photography)
  4. Specific illustration style direction
  5. Color strategy
  6. Accent color
  7. Base tone
  8. Line work / edge treatment
  9. Composition approach
  10. Anti-patterns (what to avoid)

Phase 2: Synthesis

After all 10 dimensions are answered, synthesize into a coherent design system.

Steps:

  1. Review all discovery answers as a complete set
  2. Identify the dominant aesthetic thread connecting the choices
  3. Generate a memorable 2-3 word style name using the naming convention below
  4. Define 3-4 core principles — short imperative phrases with explanations
  5. Build the complete color palette — 6 colors with hex codes, role names, usage descriptions, AND natural language AI descriptions (see template)
  6. Calculate color ratios based on strategy (see ratio guide in template)
  7. Build the Style Language Map — translate every technical spec (colors, line work, fill, texture, composition, mood) into copy-paste-ready natural language phrases for prompt use. This is critical for AI generation consistency.
  8. Specify line work, illustration, typography, and composition rules
  9. Define the Character System — including system type (Solo, Duo/Companion, or Cast). For each character: archetype, proportions, strict facial feature rules (what IS present AND what is FORBIDDEN), consistent identifiers, and fidelity levels. For Duo systems: define companion appearance, states/behaviors, and which character owns the accent color. See template for full structure.
  10. Define application guidelines for each use case from Dimension 1
  11. List explicit anti-patterns from Dimension 10 plus any that conflict with chosen directions
  12. Create the Consistency Enforcement section — document unwanted feature prevention rules, style drift prevention keywords, and a character verification checklist (see template)

Style Naming Convention: Combine a texture word + a color/mood word. The name should evoke the visual feel in 2-3 words.

Texture WordsColor/Mood Words
Ink, Chalk, Pixel, Neon, PaperTeal, Coral, Sunset, Midnight, Forest
Brush, Wire, Grain, Sketch, FoilOcean, Ember, Frost, Clay, Bloom
Velvet, Stone, Glass, Thread, StampSage, Copper, Slate, Ivory, Plum

Examples: "Ink & Teal", "Neon Chalk", "Warm Blueprint", "Velvet Ember", "Paper & Sage"

Present the style name and core principles to the user for approval before proceeding to Phase 3. If the user wants changes, adjust and re-present.


Phase 3: Documentation

Generate the complete design system document using the template from references/design-system-template.md.

Output: A markdown file saved to {output_dir}/{style-name}-design-system.md (see Output Location for path resolution).

Rules:

  • Fill EVERY section — no placeholders or template markers in the final output
  • Include specific hex codes for all colors
  • Write in present tense, declarative voice
  • Include concrete, actionable guidelines (not vague suggestions)
  • The document must be fully self-contained — anyone reading it should be able to produce on-brand visuals without additional context
  • Include the complete Nano Banana prompt library (8 prompts) in the document

Verification: After writing the document, read it back and check:

  • No unfilled {{placeholder}} markers remain
  • All sections from the template are present
  • All 6 color palette entries have hex codes
  • The Nano Banana prompt library has all 8 prompts
  • The Style Language Map is complete (no empty categories)
  • If any issues found, fix and re-write before proceeding to Phase 4

Phase 4: Asset Generation

Generate 8 style board elements using the creator-stack:nanobanana skill. Build prompts using the templates and best practices from references/prompt-engineering.md.

Required elements (generate in this order):

#ElementAspect RatioDescription
1Hero character/mascot1:1The signature illustrated element
2Concept icon1:1A single idea visualized
3Framework diagram16:9Connected nodes or flow
4Social media asset1:1A standalone icon for posts
5Background texture16:9Subtle, usable background
6Sticker/badge1:1Compact element, transparent bg
7Pattern element1:1Repeating doodles or motifs
8Character scene1:1Person or figure in context

For each element:

  1. Write a detailed narrative prompt following the templates in prompt-engineering.md
  2. Embed the exact hex codes, line style, and composition rules from the design system
  3. Specify the correct aspect ratio from the table above
  4. If Phase 0 provided user references, select the 1-2 most relevant reference images for this element type and provide them to nanobanana as style anchors (see prompt-engineering.md "Using User-Provided References" section)
  5. Use the creator-stack:nanobanana skill to generate the image
  6. Save the output to the {output_dir} directory with a descriptive filename

Prompt construction rules:

  • Write as descriptive narrative paragraphs (NOT keyword lists)
  • Specify background color by name AND hex code — AI generators interpret "white" differently, but #FFFFFF is unambiguous
  • Describe the line/stroke style explicitly — without this, models default to their own aesthetic and you lose style consistency across the 8 elements
  • Constrain accent color usage ("the only color in the entire image") — unconstrained color leads to palette drift that compounds across the series
  • End with format/aspect ratio — placing dimensions last ensures the model treats them as hard constraints rather than suggestions
  • Include explicit exclusions ("No text, no gradients, no other colors") — models add elements opportunistically unless told not to
  • Reference the artistic tool metaphor from the design system (brush pen, marker, pencil, etc.) — tool metaphors anchor the rendering style more reliably than abstract adjectives like "clean" or "bold"

Naming convention for generated files:

{output_dir}/01-hero-character.png
{output_dir}/02-concept-icon.png
{output_dir}/03-framework-diagram.png
{output_dir}/04-social-media-asset.png
{output_dir}/05-background-texture.png
{output_dir}/06-sticker-badge.png
{output_dir}/07-pattern-element.png
{output_dir}/08-character-scene.png

Phase 5: Assembly

Organize all outputs and present the complete system to the user.

Final directory structure:

For local (output_location = local):

./design-system/
├── {style-name}-design-system.md
├── 01-hero-character.png
├── ...
├── 08-character-scene.png
└── references/              ← only if Phase 0 provided user references

For user level (output_location = user):

~/.claude/.context/design-systems/{style-name-slug}/
├── {style-name}-design-system.md
├── 01-hero-character.png
├── ...
├── 08-character-scene.png
└── references/              ← only if Phase 0 provided user references

Final steps:

  1. List all generated files with brief descriptions and the full output path
  2. Display the style board layout diagram (from the design system document)
  3. Establish the Reference Library — present the 8 generated images as canonical style references. Explain that these images should be provided as style references when generating future assets (using nanobanana's multi-image reference capability) to maintain visual consistency beyond what text prompts alone achieve.
  4. Run the Verification Checklist against each generated image:
    • Does the color palette match? (check accent color, base tone, ink colors)
    • Is the line weight/style consistent with the design system spec?
    • Does the composition follow the defined rules?
    • Are anti-patterns absent?
    • Does the overall mood match the Style Language Map?
    • Character facial features: Do characters have ONLY the allowed features? Check for unwanted noses, eyebrows, ears, or other forbidden features. This is the most common failure — verify every face.
    • Companion character (if Duo system): Is the companion present? Is it the correct size relative to the primary character? Is it the ONLY accent-colored element? Flag any images that fail verification and offer to regenerate them.
  5. Ask the user: "Want to regenerate or adjust any elements?"
  6. Offer to generate additional element types or variations
  7. If the user is satisfied, confirm the design system is complete
  8. If user-level: Remind the user that this design system is now available system-wide. In any future Claude Code session, they (or a future asset-generation skill) can reference it at ~/.claude/.context/design-systems/{style-name-slug}/

Updating an Existing Design System

If the user already has a design system document, read it first before starting.

Update workflow:

  1. Read and summarize the existing design system
  2. Ask the user what they want to change (skip full discovery — only ask about the dimensions being modified)
  3. Re-synthesize only the affected aspects
  4. Update the design system document (preserve unchanged sections)
  5. Regenerate only the assets affected by the changes
  6. Preserve unchanged elements and filenames

Error Handling

  • If nanobanana generation fails, retry once with a simplified prompt
  • If the user is unhappy with a generated element, ask what specifically to change and regenerate with an adjusted prompt
  • If the user's preferences conflict (e.g., "minimalist" + "dense and detailed"), flag the tension during synthesis and ask which direction to prioritize
  • If the output directory does not exist, create it (including parent directories for user-level paths)
  • If a design system with the same slug already exists at the user level, ask the user whether to overwrite or choose a different name

Content Ideation

Overview

This skill extracts structured content ideas from published source material. It reads existing content (transcripts, newsletters, notes, web trends), identifies note-worthy angles using platform-specific extraction frameworks, and outputs quality-filtered ideas in a structured format.

Core Principle: Extract, don't invent. Every idea must trace back to specific source material. This skill mines what already exists — it does not conduct competitor research or analyze content landscapes. That is what creator-stack:research does.

When to Use

Use this skill when:

  • You have published source material and need to extract repurposable ideas from it
  • An orchestrator provides content (transcripts, articles, notes history) and asks for structured idea generation
  • You need to map raw material to specific content types using an extraction framework
  • You want to identify underused content types and bias toward variety

When NOT to Use

Do NOT use this skill when:

  • You need to research a topic, analyze competitors, or find content gaps — use creator-stack:research
  • You need to write finished content from an idea — use creator-stack:write
  • You need to generate titles or hooks — use creator-stack:title or creator-stack:hook
  • You have no source material to extract from — ideation requires inputs

Platform-Specific Reference Loading

This skill is generalized. Platform-specific extraction frameworks, content type taxonomies, quality criteria, and output formats live in reference files under references/.

PlatformReference FileLoaded By
Substack Notesreferences/substack-notes-ideation.mdcreator-stack:ideate-notes

When invoked, read the reference file provided by the orchestrator. The reference defines:

  • Extraction categories — what to look for in source material
  • Source-to-type mapping — which content types emerge from which sources
  • Quality criteria — pass/fail checklist for every idea
  • Output format — structured fields for each idea
  • Volume target — how many ideas to generate per run

Ideation Subagents

You can invoke ideation subagents using the Agent tool with run_in_background: true to extract ideas from different sources in parallel. Each agent prompt should focus on a single source (one transcript, one newsletter issue, one trend cluster) and include the relevant extraction categories from the reference.

Bias toward using the Agent tool for multi-source extraction rather than processing all sources sequentially. Parallel extraction greatly improves performance and prevents context bleed between sources.

Each subagent should receive:

  • The source material to extract from
  • The extraction categories from the reference file
  • The source-to-type mapping for that source type
  • The quality criteria checklist
  • Past content history for duplicate prevention

Ideation Workflow

Execute all steps below to complete the ideation.

Step 1: Receive and Organize Source Material

Receive source material from the orchestrator. Organize by source type:

  • YouTube transcripts, titles, descriptions, comments
  • Newsletter issue content
  • Past notes/posts history (for gap analysis)
  • Web trend findings

If no source material is provided, stop and ask the orchestrator or user for inputs. This skill cannot ideate from nothing.

Step 2: Extract Angles Using Reference Categories

Read the reference file's extraction categories. For each source, systematically scan for angles matching each category.

Document each raw extraction with:

  • The category it matches (e.g., "Surprising Data Points", "Quotable One-Liners")
  • The specific passage or data point from the source
  • The source reference (video title + ID, newsletter title + URL, etc.)

Do not filter at this stage — capture everything that matches. Filtering happens in Step 6.

Step 3: Map Extractions to Content Types

Use the reference file's source-to-type mapping table to assign each extraction a content type.

  • Focus on primary types first — these are the most natural fit for each source
  • Check secondary types only if primary types don't yield enough strong ideas
  • Flag extractions that don't cleanly map to any type — these may need rework or removal

Step 4: Gap Analysis Against Content History

If past content history is available:

  1. Tally how many times each content type has been used recently
  2. Identify the 2-3 types with the fewest recent uses
  3. Bias extraction toward underused types — actively look for angles that fill gaps
  4. Flag gap-filling ideas in their rationale so the user understands the strategic reasoning

If no content history is available, skip gap analysis and distribute across types naturally.

Step 5: Integrate Trending Topics

If web trend findings are provided:

  1. Cross-reference trends with the user's published content for unique angles
  2. Prioritize trends where the user has direct experience (highest priority) over opinion-only takes (skip)
  3. Only include trend-based ideas where the user adds genuine insight — not "me too" takes

Use the reference file's trending topic integration framework if available.

Step 6: Quality-Filter Every Idea

Run each candidate idea through the reference file's quality criteria checklist. Apply criteria in order — if an idea fails an early criterion, skip the rest and rework or discard.

Common quality gates (reference file may specify additional):

  • Standalone value — interesting without consuming the original source
  • Specificity — includes concrete details, not vague generalities
  • Single idea — one core message per idea
  • Maps to a content type — fits cleanly into the taxonomy
  • Not a rehash — substantially different from past content
  • Engagement angle — gives readers a reason to interact

Step 7: Output Structured Ideas

Format surviving ideas using the reference file's output structure. Each idea should include all required fields (typically: topic, type, source, pitch, rationale).

Respect the reference file's volume target. If fewer ideas survive quality filtering than the minimum, note this honestly rather than padding with weak ideas.

Voice Application

Before finalizing any written output, invoke the creator-stack:voice skill to apply voice rules. Idea pitches and rationales should reflect the user's authentic voice, not generic content strategy language.

Brand Compliance

When creating assets for The AI Launchpad, invoke creator-stack:brand-guidelines to resolve the correct design system and check anti-patterns.

Quality Checklist

Verify completion before finalizing ideation:

  • Source material received and organized by type (Step 1)
  • All extraction categories from reference applied to each source (Step 2)
  • Extractions mapped to content types using reference's mapping table (Step 3)
  • Gap analysis completed against content history (Step 4)
  • Trending topics integrated with proximity scoring (Step 5)
  • Every idea passed reference's quality criteria (Step 6)
  • Ideas formatted in reference's output structure (Step 7)
  • At least 3 different content types represented in the batch
  • Volume within reference's target range
  • Voice skill applied to final output

Common Pitfalls to Avoid

  1. Inventing ideas without source material: Every idea must trace to a specific source. If you can't point to the passage, data point, or trend that inspired it, the idea is fabricated — not extracted.
  2. Running competitor research: This skill extracts from the user's own content and provided trends. Competitor analysis is creator-stack:research territory.
  3. Skipping gap analysis: Content type variety prevents audience fatigue. Always check history and bias toward underused types.
  4. Forcing weak ideas to hit volume targets: If sources don't yield enough strong ideas, say so. Five strong ideas beat eight padded ones.
  5. Ignoring the reference file: The reference file IS the extraction framework. Don't improvise your own categories, criteria, or output format — use what the reference specifies.
  6. Processing all sources sequentially: Use Agent tool subagents for parallel extraction across sources. Sequential processing is slower and causes context bleed between unrelated sources.

Hook Creation

Overview

This skill provides concrete requirements and proven patterns for creating opening hooks that retain audience attention, extend title/headline curiosity, and maximize engagement. The opening content is critical for retention across all platforms — video, email, and social.

Core Principle: The opening works best when it extends the curiosity created by the title/headline rather than repeating or wasting it. Because the audience already engaged based on the title's promise, attention momentum is at its peak — the opening should add new intrigue and make them even more interested.

When to Use

Use this skill when:

  • Planning new content and need to design the opening hook
  • Reviewing an existing opening for engagement optimization
  • The user asks for help with retention, early drop-off, or opening strategy
  • Creating content that requires strong audience engagement from the start
  • Analyzing why content has poor early engagement metrics

Content Type Resolution

Before creating hooks, determine the content type and load the appropriate platform-specific reference file:

Content TypeReference FileOpening Format
YouTube videoreferences/youtube-hooks.mdFirst 5-15 seconds of video
Newsletterreferences/newsletter-hooks.mdFirst paragraph / preview text
Social postreferences/social-hooks.mdFirst line / hook tweet

Essential: Read the relevant reference file before creating hooks — these references contain platform-specific patterns, timing requirements, and patterns to avoid that directly affect retention.

If the content type does not match any reference file, apply the universal principles below and adapt to the format.

Core Requirements

1. Curiosity Extension

The opening works best when it builds upon the intrigue from the title/headline rather than repeating it.

CORRECT Example:

  • Title: "Teach Your Cat 5 Tricks in 10 Minutes"
  • Opening: Rapid preview montage of impressive tricks in action
  • Audience thinks: "I can teach my cat ALL of that in only 10 minutes?!"

INCORRECT Example:

  • Title: "Teach Your Cat 5 Tricks in 10 Minutes"
  • Opening: "Today we're going to look at 5 tricks you can teach your cat in 10 minutes"
  • Audience thinks: "I know. Get on with it."

The opening should make the audience more interested than when they engaged. Attention should increase, not drain.

2. Direct Content Connection

Essential: Opening content should directly relate to the title/headline promise, because any disconnect breaks the trust that brought the audience in.

Guidelines:

  • Avoid unrelated tangents or side stories in the opening
  • Avoid delayed starts where main content appears much later
  • Keep content tightly connected to the promised value
  • If additional context is needed, introduce it after the hook is established

3. Patterns to Avoid

These patterns consistently fail because each one drains the attention momentum the title created:

3.1 Repeating the Title

Avoid restating what the title already communicated. The audience already has this information — repetition signals that the content won't offer anything new, and attention drops.

3.2 Greeting Before Hooking

Avoid starting with greetings, welcomes, or introductions before the hook. Greetings are fine after the initial hook is established, but leading with them delays the payoff.

  • Bad: "Hi everyone, welcome back..."
  • Bad: "Hey what's up, thanks for clicking..."
  • Bad: "In this issue, we'll cover..."
3.3 Starting with Unrelated Content

Avoid opening with tangents, stories, or content disconnected from the title/headline promise. Audience confusion triggers abandonment — they came for a specific promise and need immediate confirmation they're in the right place.

Effective Opening Hook Patterns

Use one of these proven hook structures:

Pattern A: Preview/Teaser

Show a brief glimpse of the payoff before diving into the full content.

Creates thought: "I need to know how to do that!" or "I need to read this."

Works best for: Educational content, tutorials, how-to guides.

Pattern B: Intrigue Escalation

Add surprising context that makes the promise MORE compelling than the title alone.

Example: Title about a technique -> Open with "What I'm about to show you took professionals years to discover, but you'll learn it in 60 seconds."

Creates thought: "This is even better than I expected!"

Works best for: Expert content, reveals, insider knowledge.

Pattern C: Problem Amplification

Immediately validate why the audience needs this content by amplifying the problem.

Example: Title about mistakes -> Open with "If you're doing [X], you're losing [specific bad outcome]."

Creates thought: "I need to fix this now!"

Works best for: Problem-solving content, mistake-avoidance content.

Pattern D: Immediate Value Demonstration

Jump straight into delivering on the promise. No preamble, just results.

Creates thought: "This is exactly what I came for!"

Works best for: Tactical content, quick tips, high-value insights.

Hook Creation Workflow

When creating or reviewing opening hooks, follow this workflow:

  1. Review title/headline — Understand what curiosity was created
  2. Identify the escalation — How can the opening make it MORE intriguing?
  3. Choose hook pattern — Which structure (A/B/C/D) best serves the content?
  4. Draft opening content — Create the opening section
  5. Apply verification checklist — Ensure all requirements are met
  6. Test against failure patterns — Ensure none of the 3 common failure patterns are present

Voice Application

Before finalizing any written output, invoke the creator-stack:voice skill to apply voice rules. Hooks should reflect the user's authentic voice, not generic copywriting language.

Brand Compliance

When creating assets for The AI Launchpad, invoke creator-stack:brand-guidelines to resolve the correct design system and check anti-patterns.

Quality Verification Checklist

Before finalizing any opening hook, verify ALL of these:

  • Non-Repetition Test: Does this opening avoid repeating the title? (Must be YES)
  • Curiosity Extension Test: Does this make the audience more curious than the title alone?
  • Direct Connection Test: Is this immediately related to what the title promised?
  • No Greeting First Test: Does this avoid greetings before the hook? (Must be YES)
  • Attention Increase Test: Will this increase audience attention, not drain it?
  • Engagement Validation Test: Does this confirm the audience made the right choice engaging?
  • Platform Timing Test: Does this meet the platform-specific timing/length requirements?

Common Failure Patterns

Pattern 1: The Friendly But Empty Greeting

Bad: "Hi everyone, welcome! Thanks so much for being here..."

Problem: Drains attention before value is delivered.

Pattern 2: The Exact Repetition

Bad: Title: "5 AI Agent Patterns"
     Opening: "Today I'm showing you 5 AI agent patterns"

Problem: Audience already knows this. No new information.

Pattern 3: The Meandering Start

Bad: Title: "Amazing Coding Hack"
     Opening: "So I was browsing GitHub yesterday and I saw
     this interesting repo and it reminded me of..."

Problem: Takes too long to get to the promised content.

Pattern 4: The Over-Explanation

Bad: "Before we get started, let me explain why this is
     important and give you some background on..."

Problem: Delays the payoff. Audience loses patience.

Success Priorities

Priority Order (highest to lowest):

  1. Extend curiosity — don't repeat the title (repetition is the most common reason hooks fail)
  2. Add intrigue beyond the title/headline
  3. Connect directly to promised content
  4. Hook before greeting — save introductions for after the hook lands
  5. Meet platform-specific timing/length requirements

The strongest hooks avoid these three patterns because each one drains the attention the title created: repeating the title, greeting before hooking, or starting with unrelated content. Regenerate if any of these are present, regardless of other qualities.

Generate Substack Note Ideas

Overview

This orchestrator scans published content across YouTube and Substack, then delegates ideation to creator-stack:extract-ideas with the ideation reference file. It handles source fetching, processed-log management, and output persistence -- all actual idea generation logic is delegated to the foundation skill.

This skill sits upstream of creator-stack:write-note -- it produces a curated list of note ideas, while write-note writes the full note from a selected idea.

Core Principle: This is a thin orchestrator. Never generate ideas manually. Always delegate to creator-stack:extract-ideas via references/substack-notes-ideation.md. This skill manages the source-scanning workflow, duplicate prevention, and output files only.

When to Use

Use this skill when:

  • Generating a batch of Substack Note ideas from published content
  • Finding new note topics between newsletter issues
  • Maintaining a consistent Notes posting cadence
  • Mining existing content for repurposable note angles

Prerequisites

Optional: YouTube MCP tools (search_videos, get_video_details, get_video_transcript, get_video_comments) for scanning the user's YouTube channel. If unavailable, the workflow falls back to web search.

Optional: An existing ./substack/notes/processed-log.md file. If it does not exist, the workflow creates it in Step 0.

Workflow

Execute all steps below in order.

Step 0: Load Processed Log and Content Bank

Read ./substack/notes/processed-log.md to determine which sources have already been scanned.

If file exists:

  • Parse the YouTube Videos table to get a list of already-processed video IDs
  • Parse the Newsletter Issues table to get a list of already-processed issue URLs
  • Parse the Substack Notes Scanned table for the last scan date

If file does not exist:

  • Create the ./substack/notes/ directory if it does not exist
  • Create the file with the empty template (see Output Structure below -- headers only, no data rows)

Read ./substack/notes/ideas.md (the content bank) if it exists:

  • Tally pending ideas per type to identify which types need new ideas
  • Tally high-converter vs high-engagement pending ideas to identify conversion gaps
  • Feed all existing ideas (any status) to Step 4 for duplicate prevention
  • Report the current bank inventory to the user: "Content bank has X pending ideas across Y types. Types needing ideas: [list]."

If content bank does not exist:

  • Create it with the empty template (see Output Structure below -- type headers only, no ideas)

Step 1: Fetch Published YouTube Content

Use YouTube MCP tools to find recent videos from the user's channel.

  1. Use search_videos to find the user's recent videos
  2. Compare video IDs against the processed log -- identify new/unprocessed videos
  3. For each new video:
    • Use get_video_details for title, description, and stats
    • Use get_video_transcript for the full transcript
    • Use get_video_comments for top comments (source of audience questions and misconceptions)
  4. Collect all new video material for Step 4

If YouTube MCP tools are unavailable:

  • Fall back to web search for the user's YouTube channel
  • Gather what video titles, descriptions, and topics are available from search results

If no new videos are found:

  • Note this and continue -- Steps 2 and 3 may still produce source material

Step 2: Fetch Published Substack Content

Use web fetch to scan the user's Substack archive and Notes feed.

  1. Web fetch the user's Substack archive page (e.g., https://{subdomain}.substack.com/archive)
  2. Compare issue URLs against the processed log -- identify new/unprocessed issues
  3. For each new issue: web fetch the full issue content
  4. Web fetch the user's Substack Notes feed for gap analysis and posted-notes history
  5. Collect all new newsletter and notes material for Step 4

If no new issues are found:

  • Note this and continue -- the Notes feed, web trends, and YouTube content may still produce ideas

Step 3: Fetch Web Trends

Use web search to find trending topics in the user's niche.

  1. Search for trending topics, discussions, and recent developments relevant to the user's content area
  2. Identify timely angles that could inform note ideas
  3. Collect trend findings for Step 4

This step always runs regardless of whether new sources were found in Steps 1-2. Trending topics provide timely note ideas even when no new content has been published.

Step 4: Invoke creator-stack:extract-ideas with Ideation Reference

MANDATORY: Invoke creator-stack:extract-ideas with references/substack-notes-ideation.md to generate structured note ideas.

Provide all source material gathered in Steps 0-3:

  • New YouTube video transcripts, titles, descriptions, and top comments (from Step 1)
  • New newsletter issue content (from Step 2)
  • Past Substack Notes history (from Step 2, for gap analysis)
  • Web trend findings (from Step 3)
  • Previously generated ideas from ideas.md (from Step 0, for duplicate prevention)

The ideate skill applies the ideation framework and returns structured ideas with topic, note type, source, pitch, and strategic rationale.

NOTE: All ideation logic -- source-to-idea extraction, note-type matching, angle generation, duplicate filtering -- lives in the reference file. Do not implement any of this in the orchestrator.

Step 5: Present Ideas to User

Present the batch of ideas (5-10) in the structured format from the ideation reference.

Each idea includes:

  • Topic -- what the note is about
  • Type -- suggested note type (from the write-note type taxonomy)
  • Source -- which source content inspired this idea
  • Pitch -- one-line description of the note angle
  • Rationale -- why this idea is strategically sound

The user can:

  1. Approve the batch -- all ideas are saved
  2. Remove specific ideas -- selected ideas are dropped before saving
  3. Request more ideas -- return to Step 4 with additional guidance

CRITICAL: Do not save any output until the user approves. Present and wait.

Step 6: Save to Content Bank

After user approval, update two files:

1. File approved ideas into ./substack/notes/ideas.md by type:

  • For each approved idea, add it under the matching note type section
  • Use the content bank idea format (Topic, Status: pending, Source, Pitch, Rationale, Conversion, Added date)
  • Place new ideas at the bottom of each type section (newest last)

2. Update Quick Stats header:

  • Recalculate total pending/drafted/published counts
  • Update "Last ideation run" date
  • Recalculate "Types needing ideas" (types with 0 pending ideas)

3. Update ./substack/notes/processed-log.md:

  • Add a row for each new YouTube video scanned (video ID, title, scan date, ideas generated count)
  • Add a row for each new newsletter issue scanned (URL, title, scan date, ideas generated count)
  • Update the Substack Notes Scanned section with the latest scan date and gap analysis summary

Step 7: Handoff Suggestion

Inform the user they can pick any idea and invoke creator-stack:write-note to write the full note.

Do NOT automatically invoke write-note. This skill generates ideas only -- the user decides when and which idea to execute.

Output Structure

Content Bank (./substack/notes/ideas.md)

The content bank organizes ideas by note type for easy retrieval during writing sessions. Ideas flow from ideation runs into type-organized sections with status tracking.

# Substack Notes Content Bank

## Quick Stats
- Total pending: 0 | Drafted: 0 | Published: 0
- Last ideation run: YYYY-MM-DD
- Types needing ideas: [list types with 0 pending ideas]

---

## Single-Punch Wisdom

## Income Proof Story

## Pattern Observation

## Contrarian Statement

## Problem → Solution

## Build-in-Public Update

## List-Based Tactical

## Vulnerable Personal Story

## Newsletter Teaser

## Direct Advice

Each idea within a type section uses this format:

### [Specific topic in 5-10 words]
**Status:** pending
**Source:** [YouTube — "Title" (video ID) | Newsletter — "Title" (URL) | Web trend — description]
**Pitch:** [One sentence describing the note's core message]
**Rationale:** [Why this idea is worth posting — engagement potential, gap it fills, timeliness]
**Conversion:** [High Converter | High Engagement | Both | Moderate]
**Added:** YYYY-MM-DD

Status values:

  • pending — idea generated but not yet written
  • drafted — note has been drafted via creator-stack:write-note
  • published — note has been published to Substack

Processed Log (./substack/notes/processed-log.md)

# Processed Content Log

## YouTube Videos
| Video ID | Title | Scanned | Ideas Generated |
|----------|-------|---------|-----------------|

## Newsletter Issues
| URL | Title | Scanned | Ideas Generated |
|-----|-------|---------|-----------------|

## Substack Notes Scanned
| Last Scan Date | Notes Reviewed | Gap Analysis |
|----------------|----------------|--------------|

Quality Checklist

Verify completion before finalizing:

  • Processed log loaded or created (Step 0)
  • Content bank loaded and inventory reported (Step 0)
  • YouTube videos scanned via MCP tools or web search fallback (Step 1)
  • Substack newsletter issues scanned via web fetch (Step 2)
  • Web trends gathered (Step 3)
  • creator-stack:extract-ideas invoked with references/substack-notes-ideation.md (Step 4)
  • Ideas presented to user for approval (Step 5)
  • Approved ideas filed by type in content bank ./substack/notes/ideas.md (Step 6)
  • Quick Stats updated in content bank (Step 6)
  • Processed log updated with newly scanned sources (Step 6)
  • Handoff to creator-stack:write-note suggested (Step 7)

Common Pitfalls to Avoid

  1. Generating ideas manually: All ideation logic lives in the ideate reference file. Delegate to creator-stack:extract-ideas -- do not implement idea generation in this orchestrator.
  2. Re-scanning processed sources: Always check the processed log first. Skip sources already scanned.
  3. Ignoring the notes history: Past notes feed gap analysis. Always load them in Step 2.
  4. Skipping web trends: Trending topics provide timely ideas even when no new content exists. Step 3 always runs.
  5. Auto-invoking write-note: This skill generates ideas only. The user decides when to write.
  6. Saving before user approval: Always present ideas and get explicit approval before writing to files.

Nano Banana - AI Image Generation

Generate and edit images using Google Gemini models. Supports two models:

  • Pro (gemini-3-pro-image-preview) — High quality, complex prompts, thinking mode
  • Flash (gemini-2.5-flash-image) — Fast, cheap, good for iteration

Prerequisites

Required:

  • GEMINI_API_KEY — Get from Google AI Studio
  • uv (recommended) or Python 3.10+ with google-genai installed

With uv (recommended — zero setup): Dependencies are declared inline via PEP 723 and auto-installed on first run. Just use uv run instead of python3.

With pip (fallback):

pip install -r ${CLAUDE_SKILL_DIR}/requirements.txt

Quick Start

Default output: Images save to ~/Downloads/nanobanana_<timestamp>.png automatically. Do NOT pass -o unless the user specifies where to save. If the user provides a filename without a directory (e.g., "save it as robot.png"), use -o ~/Downloads/robot.png.

Generate an image:

uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py "a cute robot mascot, pixel art style"

Edit an existing image:

uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py "make the background blue" -i input.jpg

Use Flash model for fast iteration:

uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py "quick sketch of a cat" --model flash

Multi-image reference (style + subject):

uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py "apply the style of the first image to the second" \
  -i style_ref.png subject.jpg

Generate with specific aspect ratio and resolution:

uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py "cinematic landscape" --ratio 21:9 --size 4K

Save to a specific location:

uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py "logo design" -o ~/Projects/brand/logo.png

Model Selection Guide

Pro (default)Flash
SpeedSlower~2-3x faster
CostHigherLower
Text renderingGoodUnreliable
Complex scenesExcellentAdequate
Thinking modeYesNo
Best forFinal production imagesExploration, drafts, batch

Rule of thumb: Use Flash for exploration and batch generation, Pro for final output.

Script Reference

scripts/generate.py

Main image generation script.

Usage: generate.py [OPTIONS] PROMPT

Arguments:
  PROMPT                Text prompt for image generation

Options:
  -o, --output PATH     Output file path (default: ~/Downloads/nanobanana_<timestamp>.png)
  -i, --input PATH...   Input image(s) for editing / reference (up to 14)
  -m, --model MODEL     Model: 'pro' (default), 'flash', or full model ID
  -r, --ratio RATIO     Aspect ratio (1:1, 16:9, 9:16, 21:9, etc.)
  -s, --size SIZE       Image size: 1K, 2K, or 4K (default: standard)
  --search              Enable Google Search grounding for accuracy
  --retries N           Max retries on rate limit (default: 3)
  -v, --verbose         Show detailed output

Supported aspect ratios:

  • 1:1 — Square (default)
  • 2:3, 3:2 — Portrait/Landscape
  • 3:4, 4:3 — Standard
  • 4:5, 5:4 — Photo
  • 9:16, 16:9 — Widescreen
  • 21:9 — Ultra-wide/Cinematic

Image sizes:

  • 1K — Fast, lower detail
  • 2K — Enhanced detail (2048px)
  • 4K — Maximum quality (3840px), best for text rendering

scripts/batch_generate.py

Generate multiple images with sequential naming.

Usage: batch_generate.py [OPTIONS] PROMPT

Arguments:
  PROMPT                Text prompt for image generation

Options:
  -n, --count N         Number of images to generate (default: 10)
  -d, --dir PATH        Output directory (default: ~/Downloads)
  -p, --prefix STR      Filename prefix (default: "image")
  -m, --model MODEL     Model: 'pro' (default), 'flash', or full model ID
  -r, --ratio RATIO     Aspect ratio
  -s, --size SIZE       Image size (1K/2K/4K)
  --search              Enable Google Search grounding
  --retries N           Max retries per image on rate limit (default: 3)
  --delay SECONDS       Delay between generations (default: 3)
  --parallel N          Concurrent requests (default: 1, max recommended: 5)
  -q, --quiet           Suppress progress output

Example:

uv run ${CLAUDE_SKILL_DIR}/scripts/batch_generate.py "pixel art logo" -n 20 --model flash -d ./logos -p logo

Python API

Direct import (from another skill's script):

Note: When importing as a Python module, google-genai must be available in the calling script's environment. If using uv run, add a PEP 723 dependencies block to your own script (see example in Pattern 2 below).

import sys
from pathlib import Path
sys.path.insert(0, str(Path("${CLAUDE_SKILL_DIR}/scripts")))
from generate import generate_image, edit_image, batch_generate

# Generate image
result = generate_image(
    prompt="a futuristic city at night",
    output_path="city.png",
    aspect_ratio="16:9",
    image_size="4K",
    model="pro",
)

# Edit existing image
result = edit_image(
    prompt="add flying cars to the sky",
    input_path="city.png",
    output_path="city_edited.png",
)

# Multi-image reference
result = generate_image(
    prompt="combine the color palette of the first with the composition of the second",
    input_paths=["palette_ref.png", "composition_ref.png"],
    output_path="combined.png",
)

Return structure (always present):

{
    "success": True,       # or False
    "path": "/path/to/output.png",  # or None on failure
    "error": None,         # or error message string
    "metadata": {
        "model": "gemini-3-pro-image-preview",
        "prompt": "...",
        "aspect_ratio": "16:9",
        "image_size": "4K",
        "use_search": False,
        "input_images": None,        # or list of paths
        "text_response": "...",      # optional text from model
        "thinking": "...",           # Pro model reasoning (when available)
        "timestamp": "2025-01-26T...",
    }
}

Downstream Skill Integration Guide

Pattern 1: CLI wrapper (recommended for simple use)

# In your skill's script:
uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py "{prompt}" --model flash --ratio 16:9 -o output.png

Pattern 2: Python import with custom defaults

# /// script
# requires-python = ">=3.10"
# dependencies = [
#     "google-genai>=1.0.0",
# ]
# ///

import sys
from pathlib import Path

NANOBANANA_DIR = Path("${CLAUDE_SKILL_DIR}/scripts")
sys.path.insert(0, str(NANOBANANA_DIR))
from generate import generate_image

def generate_thumbnail(prompt: str, output_path: str) -> dict:
    """Generate a YouTube thumbnail with project defaults."""
    return generate_image(
        prompt=prompt,
        output_path=output_path,
        aspect_ratio="16:9",
        image_size="2K",
        model="flash",
        max_retries=3,
    )

Pattern 3: Batch with progress tracking

from batch_generate import batch_generate

def on_progress(completed, total, result):
    print(f"Progress: {completed}/{total}")

results = batch_generate(
    prompt="logo concept",
    count=20,
    output_dir="./logos",
    prefix="logo",
    model="flash",
    aspect_ratio="1:1",
    on_progress=on_progress,
)

successful = [r for r in results if r["success"]]

Pattern 4: Sequential generation for series

When a downstream skill needs multiple consistently-styled images (e.g., newsletter visuals, thumbnail A/B variants), use the anchor-and-reference pattern:

from generate import generate_image

# Step 1: Generate the style anchor
anchor = generate_image(
    prompt="warm illustration style, earth tones, soft gradients, clean lines",
    output_path="anchor.png",
    model="pro",
)

# Step 2: Generate each image in the series, referencing the anchor
subjects = ["laptop on desk with coffee", "person reading a book", "sunrise over mountains"]
series_paths = [anchor["path"]]

for i, subject in enumerate(subjects):
    result = generate_image(
        prompt=f"{subject}, matching the visual style and color palette of the reference image exactly",
        input_paths=[anchor["path"]],  # always include the anchor
        output_path=f"series_{i+1:02d}.png",
        model="pro",
    )
    if result["success"]:
        series_paths.append(result["path"])

The full sequential generation patterns are documented in the Sequential Generation section below.

Environment Variables

VariableDescriptionDefault
GEMINI_API_KEYGoogle Gemini API keyRequired
IMAGE_OUTPUT_DIRDefault output directory~/Downloads

Features

Text-to-Image Generation

Create images from text descriptions. Both models excel at:

  • Photorealistic images
  • Artistic styles (pixel art, illustration, etc.)
  • Product photography
  • Landscapes and scenes

Image Editing

Transform existing images with natural language:

  • Style transfer
  • Object addition/removal
  • Background changes
  • Color adjustments

Multi-Image Reference

Provide up to 14 reference images for:

  • Style consistency across a series
  • Subject consistency (same character, different poses)
  • Brand-consistent generation
  • Style + subject combination

High-Resolution Output

  • 1K — Fast generation, good for drafts
  • 2K — Enhanced detail (2048px)
  • 4K — Maximum quality (3840px), best for text rendering

Google Search Grounding

Enable --search for factually accurate images involving:

  • Real people, places, landmarks
  • Current events
  • Specific products or brands

Automatic Retry

Rate limit errors are automatically retried with exponential backoff (default: 3 retries). No action needed from callers.

SynthID Watermark Notice

All images generated by Gemini contain an invisible SynthID digital watermark. This is automatic, cannot be disabled, and survives common transformations (resize, crop, compression). Be aware of this for any use case requiring watermark-free output.

Sequential Generation

Use sequential generation to maintain visual consistency across a series of images. The core technique: generate an anchor image first, then pass it as a reference (-i) for every subsequent image in the series.

Pattern 1: Style-Board Anchoring

Generate a single anchor image that establishes the visual identity for a series. Reference it for all subsequent images.

When to use: Newsletter visual series, A/B thumbnail variants, brand-consistent image batches.

Workflow:

  1. Generate the anchor image with a prompt emphasizing style, palette, and mood:
uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py \
  "modern flat illustration style, warm earth tones, soft gradients, clean lines, \
  minimal detail, cozy atmosphere" \
  --model pro -o anchor.png
  1. Generate each subsequent image referencing the anchor:
uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py \
  "a laptop on a desk with coffee, matching the visual style, color palette, \
  and lighting of the reference image exactly" \
  -i anchor.png --model pro -o image_01.png
  1. Repeat step 2 for each image in the series, always referencing the same anchor.

Tip: Use Flash to draft the anchor quickly, then regenerate with Pro once you find a style you like.

Pattern 2: Subject Consistency

Keep the same character or subject looking consistent across different scenes and poses.

When to use: Mascot in multiple contexts, product photography series, recurring character.

Workflow:

  1. Generate the initial subject with clear, detailed appearance description:
uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py \
  "a friendly robot mascot with round blue body, orange antenna, large expressive eyes, \
  simple geometric design, standing front-facing on white background" \
  --model pro -o subject_front.png
  1. Generate new scenes referencing the subject:
uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py \
  "the same robot character from the reference image, now sitting at a desk typing, \
  same proportions and colors, office background" \
  -i subject_front.png --model pro -o subject_office.png
  1. For stronger consistency, reference 2-3 of the best previous outputs:
uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py \
  "the same robot character from the reference images, now outdoors in a park, \
  same proportions and colors, waving at the viewer" \
  -i subject_front.png subject_office.png --model pro -o subject_park.png

Pattern 3: Progressive Accumulation

Build a reference pool over a long series, adding each successful output as a reference for the next.

When to use: Series of 5+ images where consistency must compound across the full set.

Workflow:

  1. Generate the anchor (same as Pattern 1, step 1).
  2. Generate image 2 referencing the anchor.
  3. Generate image 3 referencing anchor + image 2.
  4. Continue, keeping the 3-4 strongest references in the -i list. Drop weaker outputs.

Why cap at 3-4 references: More references dilute the style signal. The model averages across all inputs — too many and the result loses coherence. Keep only the images that best represent the target style.

Reference ordering matters: Place the style anchor first in the -i list. The model weights earlier references slightly more.

Best Practices

Prompt Writing

Good prompts include:

  • Subject description
  • Style/aesthetic
  • Lighting and mood
  • Composition details
  • Color palette

See references/prompts.md for detailed prompt templates by category and model-specific tips.

Batch Generation Tips

  1. Use --model flash for exploration batches (faster, cheaper)
  2. Generate 10-20 variations to explore options
  3. Default 3-second delay between sequential requests avoids rate limits
  4. Review results and iterate on best candidates with Pro model

Rate Limits

  • Gemini API has usage quotas (~10 RPM free tier)
  • Automatic retry with exponential backoff handles transient rate limits
  • For large batches, use --delay 5 or --parallel with modest concurrency
  • Check your quota at Google AI Studio

Troubleshooting

"uv: command not found"

  • Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh or brew install uv

"Error: google-genai package not installed"

  • Use uv run instead of python3 to auto-install dependencies
  • Or install manually: pip install -r ${CLAUDE_SKILL_DIR}/requirements.txt

"GEMINI_API_KEY environment variable not set"

  • Set GEMINI_API_KEY in your environment before running

"No image in response"

  • Prompt may have triggered safety filters
  • Try rephrasing to avoid sensitive content

"Rate limit exceeded after N retries"

  • Wait 30-60 seconds and try again
  • Reduce batch parallelism or add longer delays
  • Check your API quota

Import errors in batch_generate.py

  • The script handles its own path setup; run from any directory

Future Capabilities

Multi-turn conversational editing — The Gemini API supports stateful chat sessions for iterative image editing (e.g., "make it bluer" → "now add a hat" → "zoom out"). This requires fundamentally different stateful architecture and is not currently implemented. No downstream skill currently needs this.

References

Newsletter to YouTube Video Outline

Repurpose a newsletter issue into a high-level YouTube video outline. The output is topic-level only — no scripts, no talking points, no actual content. Just the topics you'll cover, structured for video.

Why This Exists

Newsletter and YouTube are different mediums. Newsletters reward scanners — readers jump to what interests them. YouTube rewards retention — viewers watch linearly, and every moment competes with the back button. A straight 1:1 port of newsletter structure usually makes for a boring video. This skill restructures the content to match how people actually watch.

When to Use

Use this skill when:

  • Converting a newsletter issue into a YouTube video plan
  • The user asks to repurpose newsletter content for YouTube
  • Planning a video based on an existing newsletter issue
  • The user mentions "video outline from newsletter" or similar

Process

digraph newsletter_to_youtube {
    "Read newsletter issue" [shape=doublecircle];
    "Extract core topics" [shape=box];
    "Identify the tension" [shape=box];
    "Drop non-video sections" [shape=box];
    "Reorder for retention" [shape=box];
    "Generate hook via skill" [shape=box, style=bold];
    "Structure the outline" [shape=box];
    "Present to user" [shape=doublecircle];

    "Read newsletter issue" -> "Extract core topics";
    "Extract core topics" -> "Identify the tension";
    "Identify the tension" -> "Drop non-video sections";
    "Drop non-video sections" -> "Reorder for retention";
    "Reorder for retention" -> "Generate hook via skill";
    "Generate hook via skill" -> "Structure the outline";
    "Structure the outline" -> "Present to user";
}

Step 1: Read the Newsletter Issue

Read the full newsletter issue. Identify:

  • The core thesis (what's the one main idea?)
  • All distinct topics/subtopics covered
  • The most surprising or counterintuitive finding
  • Any limitations, trade-offs, or honest takes (these create tension)
  • Personal experience and real results (these build credibility on camera)

Step 2: Adapt for Video

Drop these — they don't translate to video:

  • P.S. lines and email-specific CTAs (forward, reply)
  • Preview text / subtitle
  • Subject line options
  • "Getting started" setup sections (install steps, config JSON) — unless the video is a tutorial
  • Sections that only work as scannable text (comparison tables can become talking points, but raw tables don't work on screen)

Promote these — they work better on video than in text:

  • Personal stories and anecdotes (these are gold on camera)
  • Surprising findings or limitations (great for hooks and retention)
  • Before/after comparisons (visual, easy to demonstrate)
  • Live demos or walkthroughs (newsletter screenshots become video demos)

Reorder for retention:

YouTube viewers decide to stay or leave in the first 30 seconds. The newsletter hook might work as-is, but often the most interesting finding is buried in the middle or end of the newsletter. Pull it forward.

Newsletter patternVideo adaptation
Hook → Context → Content → Limitation → CloseHook with the limitation → Why it matters → How it works → Limitation deep-dive → What's next
Hook → Problem → Solution → How-to → CloseHook with the result → The problem → The solution → Quick demo → What's next
Hook → Feature overview → Cost → Limitations → CloseHook with the tension (cost/limitation) → What it does → How it actually works → The honest trade-offs → Verdict

The general principle: lead with tension or surprise, deliver value in the middle, end forward-looking. Tension is what keeps viewers watching. The newsletter can afford a slow build because readers scan ahead. Video can't.

Step 3: Generate the Hook

Invoke creator-stack:hook to craft the video's opening hook.

Feed the skill this context from Steps 1–2:

  • The working title (or a placeholder title describing the video topic)
  • The most surprising or counterintuitive finding from the newsletter — this is almost always the best hook material
  • The core tension (limitation, trade-off, honest take) identified in Step 1
  • The content type (YouTube video) so the skill loads references/youtube-hooks.md

The skill will produce a hook that:

  • Extends curiosity beyond the title (doesn't just repeat it)
  • Lands within 5–15 seconds
  • Avoids forbidden patterns (title repetition, welcome-first, unrelated tangent)
  • Passes its own 7-point verification checklist

Include the skill's hook output in the outline's Hook section. The hook should be 2–3 sentences: what the viewer sees/hears and why it creates urgency to keep watching.

Step 4: Build the Outline

Structure every outline with these sections. The Hook section comes from Step 3. The rest is topic-level only — 1-2 lines per section, not actual content.

## Hook (0:00–0:15)
[Generated by creator-stack:hook skill — 2-3 sentences
describing the opening: what the viewer sees/hears, the hook pattern used,
and the curiosity it creates]

## Setup
[What context the viewer needs to understand the rest — 1 sentence]

## Main Topics
[Each topic as a bullet — just the topic name and what aspect of it you'll cover]
- Topic 1: ...
- Topic 2: ...
- Topic 3: ...
[Usually 3-5 topics. More than 5 means the video is trying to cover too much.]

## Close
[How the video wraps — what the viewer should take away or do next]

Keep it tight. The outline for a 10-minute video should fit in under 15 lines (excluding the hook). If you're writing more than that, you're going past topic-level into content territory.

Output Format

Present the outline as a single markdown block. Use the template structure above. No commentary outside the outline unless the user asks for it.

If a newsletter issue covers too many topics for one video, say so and suggest splitting into 2 videos with a recommended split point — but still produce the outline for the primary video.

Brand Compliance

When creating video outlines for The AI Launchpad, invoke creator-stack:brand-guidelines to verify the hook and outline align with brand standards.

Quality Checklist

Verify completion before finalizing:

  • Newsletter issue fully read and core thesis identified
  • Non-video sections dropped (P.S., subject lines, setup steps)
  • Video-friendly elements promoted (stories, demos, surprises)
  • Content reordered for retention (tension/surprise leads)
  • creator-stack:hook invoked for hook generation
  • Hook passes the skill's 7-point verification checklist
  • Outline uses the template structure (Hook → Setup → Main Topics → Close)
  • 3-5 main topics (not more)
  • Each topic is a label + angle, not talking points
  • Outline fits under 15 lines (excluding hook)

Common Mistakes

MistakeFix
Writing talking points instead of topicsEach bullet should be a topic label + angle, not what you'd say about it
Mirroring the newsletter order exactlyReorder — lead with whatever creates the most tension or curiosity
Including 7+ main topicsPick 3-5. A focused video outperforms a comprehensive one.
Keeping email-specific sectionsDrop P.S., subject lines, reply CTAs — they don't exist in video
Writing the hook inline instead of using the skillInvoke creator-stack:hook — it catches forbidden patterns you'll miss
Generic hook ("Today we're going to talk about...")The hook skill will prevent this — feed it the tension/surprise and let it pick the right pattern
Forgetting the closeEvery video needs a clear ending — verdict, next steps, or a forward look

Newsletter Visual Assets

Analyze a newsletter draft, identify the highest-impact opportunities for visual enhancement, and generate on-brand visual assets. Every visual must clarify, persuade, or engage — never decorate.

Core Principle: Visuals earn their place through measurable impact on clarity, engagement, or persuasion. A newsletter with zero visuals is better than one with decorative filler.

When to Use

Use this skill when:

  • Enhancing a newsletter draft with visual assets
  • A draft contains [screenshot] placeholders that need strategic evaluation
  • The user asks to "add visuals", "create images", or "make this more visual"
  • A newsletter draft is text-heavy and could benefit from visual breaks

Prerequisites

A design system must exist before generating any visuals — without one, generated images won't have consistent colors, typography, or style. Check ~/.claude/.context/design-systems/ for available design systems.

  • If none exists: Inform the user and offer to invoke creator-stack:design-system to create one. Do not generate visuals without a design system — the results will be inconsistent and off-brand.
  • If one exists: Verify its Application Guidelines cover newsletter/website assets. If they don't, note this to the user and proceed with the closest available style guidance.

Content Type Resolution

Content TypeReference FileKey Focus
Substack newsletterreferences/substack-constraints.mdAspect ratios, email rendering, resolution

Read the relevant reference file before generating any assets — it contains platform-specific constraints (aspect ratios, resolution, email rendering limits) that affect every prompt.

Workflow

Step 1: Audit the Draft

Read the full draft and catalog every section. For each section, evaluate:

  1. Existing visuals — Does it already have a [screenshot] placeholder, code block, table, or other visual element? Note what it covers and whether it's sufficient.
  2. Complexity — Is the concept hard to explain in text alone? (process flows, architectures, comparisons, data)
  3. Engagement risk — Is this a point where readers are likely to disengage? (long text-only stretches, dense technical explanations)
  4. Persuasion opportunity — Could a visual make a claim more believable? (cost data, performance comparisons, before/after scenarios)

Existing [screenshot] placeholders: These represent real UI captures the author will provide. Treat them as existing visuals. Only recommend replacing one if the concept would be better served by a diagram or illustration — and explicitly flag this to the user with justification.

Step 2: Score and Rank Opportunities

For each potential visual opportunity, score on three dimensions (1-5 each):

Dimension1 (Low)5 (High)
Clarity liftText explains it fineText alone is confusing or requires re-reading
Engagement liftSection is already engagingLong text-only stretch, reader likely to skim past
UniquenessGeneric/decorative visualVisual reveals structure or data text can't convey

Total score = Clarity + Engagement + Uniqueness (max 15)

Hard rules:

  • Only visuals scoring 10+ make the shortlist
  • Maximum 5 visuals per newsletter issue (fewer is often better)
  • At least one visual in the first half of the newsletter
  • Never add a visual within 150 words of another (visual fatigue)
  • Visuals scoring below 8 are never included

Step 3: Select Visual Types

Choose the type based on what the visual needs to accomplish:

Visual TypeUse WhenExamples
Conceptual diagramExplaining a process, architecture, or flowFlowcharts, swimlane diagrams, network diagrams
Comparison visualShowing differences between two or more thingsSide-by-side layouts, before/after
Data visualizationMaking numbers or ratios tangibleBar charts, token cost comparisons
Custom illustrationEngaging the reader emotionally or setting contextHero images, conceptual metaphors
Annotated screenshotAdding context to an existing UI captureCallout boxes, arrows, numbered annotations

Never use illustrations when a diagram would be more informative. Illustrations are for engagement; diagrams are for clarity. When in doubt, choose the one that teaches.

Step 4: Present the Visual Brief

Before generating anything, present the brief to the user for approval:

For each recommended visual:

  1. Location — Exact section and paragraph
  2. Type — Which visual type
  3. Purpose — What it clarifies, persuades, or engages (one sentence)
  4. Description — What the visual shows (the concept, not the generation prompt)
  5. Score — The three dimension scores and total

Also include:

  • Sections where you did NOT recommend visuals and why
  • Any [screenshot] placeholders you recommend replacing (with justification)

Do NOT generate prompts or images until the user approves the brief.

Step 5: Generate Visual Assets

After approval, generate each visual using creator-stack:nanobanana.

Design system integration: Load the design system from ~/.claude/.context/design-systems/ and apply it to every prompt — colors, typography, illustration style, brand constraints.

Prompt construction:

[SUBJECT]: What the visual depicts
[COMPOSITION]: Layout, arrangement, spatial relationships
[STYLE]: From the design system — colors, typography, illustration style
[CONSTRAINTS]: What to avoid, what NOT to include
[FORMAT]: Aspect ratio and resolution (from substack-constraints reference)

Prompt rules:

  • Be specific about spatial relationships ("left side shows X, right side shows Y")
  • Include exact hex colors from the design system
  • Specify "no text" or exact text to render (minimize text — AI text rendering is unreliable)
  • Always include the style from your design system — never leave style ambiguous
  • Never fabricate data that isn't in the source draft

Step 6: Write Captions and Alt Text

For each generated visual:

  1. Caption — 1 sentence that adds context the image doesn't show. Good captions answer "so what?" — they don't just describe what's visible.
  2. Alt text — Descriptive text for accessibility. Convey informational content, not visual style. ("Bar chart showing agent teams use 7x more tokens than single agents" not "blue and orange bar chart")

Step 7: Verify Against Checklist

Run the quality checklist before presenting final assets.

Voice Application

Invoke creator-stack:voice before finalizing any written output (captions). Voice is applied after the structural draft is complete but before brand compliance.

Invocation point: After writing captions and alt text, before presenting to the user.

Brand Compliance

When creating assets for The AI Launchpad, invoke creator-stack:brand-guidelines to resolve the correct design system and check anti-patterns.

Invocation point: After voice application, as the final quality gate.

Quality Checklist

  • Design system loaded before any generation
  • Every visual scores 10+ on the clarity/engagement/uniqueness scale
  • Maximum 5 visuals in the brief
  • At least one visual in the first half of the newsletter
  • No two visuals within 150 words of each other
  • Brief presented and approved before generation
  • Every prompt includes design system colors and style
  • No fabricated data in any visual
  • Captions answer "so what?" (not just describe the image)
  • Alt text conveys information, not visual style
  • creator-stack:voice invoked for captions
  • creator-stack:brand-guidelines invoked for brand compliance

Common Pitfalls

  1. Too many visuals (6+): Cap at 5. Force-rank by score. Fewer high-impact visuals beat many mediocre ones.
  2. Decorative hero image: Only include a hero if it scores 10+. Most newsletters don't need one.
  3. Inventing data: Only visualize data the author provides. Never fabricate statistics.
  4. Replacing screenshots without asking: Screenshots are the author's real evidence. Only suggest replacing with explicit justification.
  5. Ignoring the design system: Every prompt must reference the design system. No making up colors or styles.
  6. Dark-themed images for email: Default to light backgrounds. Dark images look broken in most email clients.
  7. Text-heavy images: Minimize text in generated images. Put text in captions instead.
  8. Generating before brief approval: Always present the brief first. Wasted assets cost time and API credits.
  9. Using illustrations where diagrams belong: If the goal is clarity, use a diagram. Illustrations are for engagement.

Optimize Newsletter Issue

Orchestrate foundation skills to transform outlines into full drafts or optimize rough drafts into high-performing newsletter issues. This is a thin orchestrator — it sequences skill invocations and manages the user review workflow, but delegates all content generation to foundation skills.

Core Principle: This is a thin orchestrator. All content generation goes through the appropriate foundation skill — that's how quality stays consistent and voice stays authentic. This skill manages workflow sequence and user decisions only.

When to Use

Use this skill when:

  • Transforming an outline into a full newsletter draft
  • Optimizing or polishing an existing rough draft
  • The user has newsletter content that needs quality improvement
  • Converting notes or bullet points into a publication-ready issue

Do NOT use this skill when:

  • Starting from a topic with no existing content (use creator-stack:plan-newsletter instead)
  • Creating visual assets for a newsletter (use creator-stack:newsletter-visuals)

Prerequisites

Existing content must be available. Either:

  1. A newsletter outline (bullet points, topic structure, notes), OR
  2. A rough draft that needs optimization

Newsletter Workflow

Execute all steps below in order.

Step 1: Assess the Input

Determine the input type and issue type:

  • Outline: Bullet points, topic structure, or notes → full draft workflow
  • Rough draft: Existing prose that needs optimization → audit and optimize workflow

Present the assessment to the user: input type, detected issue type, and the workflow that follows.

Step 2: Draft or Optimize Content

From outline:

  1. Invoke creator-stack:write with content type "newsletter" to write the full draft.
    • Pass the outline as source material
    • The writing skill loads its own references/newsletter.md for section rules, issue types, and writing conventions
  2. The draft follows the Newsletter Arc: Hook → Context → Value → Close

From rough draft:

  1. Invoke creator-stack:write with content type "newsletter" to audit and optimize each section.
    • Pass the draft as source material with instruction to optimize
    • The writing skill checks against its section rules and body writing rules
  2. Present findings: what works, what needs improvement, and specific recommendations
  3. Rewrite/optimize sections that fall short

Step 3: Generate Subject Lines

  1. Invoke creator-stack:title with content type "newsletter" to generate 3 subject line options.
    • Pass the draft content as context
    • The title skill loads its own references/newsletter-subject-lines.md for formulas and rules
  2. Each option includes preview text (subtitle)
  3. Document all options with star ratings and recommendation

Step 4: Generate Opening Hook

  1. Invoke creator-stack:hook with content type "newsletter" to generate 2-3 hook options.
    • Pass the selected subject line and draft content as context
    • The hook skill loads its own references/newsletter-hooks.md for hook patterns
  2. Each hook must extend curiosity from the subject line (not repeat it)
  3. Document all options with rationale

Step 5: Present Options and Get User Selection

  1. Present subject line options with star ratings
  2. Present hook options with rationale
  3. Present the full draft (or optimized draft)
  4. Ask the user to select subject line + hook

Always present all options — the user makes the final call, not the orchestrator.

Step 6: Run Pre-Publish Checklist

  1. Read references/pre-publish-checklist.md
  2. Run through every check against the final draft
  3. Flag any items that don't pass
  4. Present results to the user with specific fixes for any failures

Step 7: Finalize

  1. Assemble the final issue: selected subject line + preview text + selected hook + optimized body + close + P.S.
  2. Present the complete, publication-ready issue to the user

Output Structure

Present the final issue in this structure:

# [Subject Line]
*[Preview Text]*

[Opening Hook]

[Body Content - sections with subheadings]

[Close]

P.S. [Secondary CTA or personal touch]

Delegation Reference

Each foundation skill owns its own reference files. When you invoke a skill, it loads the right references automatically — you don't need to manage file paths.

ContentSkillWhy
Newsletter prose (draft + optimize)creator-stack:writeOwns section rules, body writing conventions, voice invocation
Subject linescreator-stack:titleOwns subject line formulas and open rate patterns
Opening hookscreator-stack:hookOwns hook patterns and curiosity extension logic
Voice consistencycreator-stack:voiceInvoked automatically by writing skill — no manual call needed

Quality Checklist

  • Input type assessed (outline vs. draft)
  • creator-stack:write invoked for content generation/optimization
  • creator-stack:title invoked for subject lines (3 options generated)
  • creator-stack:hook invoked for opening hooks (2-3 options generated)
  • All options presented with star ratings
  • User selected subject line and hook
  • Pre-publish checklist run (all items pass or flagged)
  • Final issue assembled and presented

Common Pitfalls

  1. Writing content manually: Generating newsletter prose instead of delegating to creator-stack:write — the foundation skill has all the section rules and voice handling built in.
  2. Single option: Presenting one subject line or hook instead of multiple options — users need choices to make good decisions.
  3. Skipping the pre-publish checklist: The checklist catches issues the draft workflow misses.
  4. Fat orchestrator: Adding writing techniques, section rules, or formatting guidance here instead of keeping them in foundation skill references — that logic belongs in the skill that owns it.

Plan Newsletter Issue

Overview

This skill takes a topic and produces a complete newsletter issue plan with draft content, subject line options, opening hook options, and social promotion posts. It is a thin orchestrator — every content generation step delegates to a foundation skill. This skill contains workflow sequence and platform-specific decisions only, not implementation logic.

How Reference Delegation Works

Each foundation skill owns its own reference files and loads them automatically. When you invoke creator-stack:write for newsletter content, it loads references/newsletter.md from its own directory. When you invoke creator-stack:title for subject lines, it loads references/newsletter-subject-lines.md from its own directory. You don't need to manage these paths — just invoke the skill and provide context.

When to Use

Use this skill when:

  • Planning a new newsletter issue from a topic or idea
  • Repurposing existing content (video transcript, notes, research) into a newsletter
  • Creating a content plan for Substack or another newsletter platform

Prerequisites

A topic or source material is required. This can be:

  • A topic idea or keyword
  • A video transcript to repurpose
  • Existing notes or research
  • A URL or document to build from

If research already exists or the user is repurposing existing content, the research step can be skipped.

Planning Workflow

Execute all steps below sequentially.

Step 1: Research the Topic

Invoke creator-stack:research to understand the content landscape and identify the best angle for the newsletter issue.

  • Pass the topic, audience context, and any source material to the research skill.
  • The research skill analyzes competitors, identifies gaps, and produces actionable insights.

Skip condition: Skip this step if the user provides existing research, or if working from existing content (e.g., repurposing a video transcript). Note the reason for skipping in the plan.

Step 2: Draft the Newsletter Issue

Invoke creator-stack:write with content type "newsletter" to draft the full issue.

  • The writing skill loads its own references/newsletter.md for newsletter structure and conventions.
  • The writing skill automatically invokes creator-stack:voice for voice consistency.
  • Pass the research findings (or source material) and topic context.
  • The draft follows the newsletter reference structure including sections, formatting, and CTAs.

Step 3: Generate Subject Line Options

Invoke creator-stack:title with content type "newsletter" to generate 3-5 subject line options.

  • Each option includes:
    • Subject line text
    • Preview text (the snippet shown in email clients)
    • Rationale for why it will perform well
    • Star rating (1-3 stars) indicating recommendation strength

Step 4: Generate Opening Hook Options

Invoke creator-stack:hook with content type "newsletter" to generate 2-3 opening paragraph options.

  • Each option includes:
    • Full opening paragraph text
    • Hook strategy description
    • Rationale and alignment with the selected subject line
    • Star rating (1-3 stars) indicating recommendation strength

Step 5: Generate Social Promotion Posts

Invoke creator-stack:write separately for each platform:

  1. Twitter/X thread — specify content type "twitter"
  2. LinkedIn post — specify content type "linkedin"
  3. Substack Note — specify content type "substack-note"

Each promotion post should tease the newsletter content and drive subscriptions/reads. The writing skill loads the appropriate platform reference for each invocation.

Step 6: Generate Header Image (Optional)

Invoke creator-stack:social-graphic to generate a newsletter header image.

  • Only invoke if the user requests a header image or if the newsletter platform benefits from one.
  • If not requested, mark as "Not requested" in the plan.

Step 7: Present Complete Plan

Present the full plan to the user for review. Include all options with star ratings so the user can make informed selections.

Output Structure

Save the plan to ./newsletter/issues/[issue_name]/plan.md. Create the directory if it doesn't exist. Use a slugified version of the topic as the issue name (e.g., ai-coding-assistants).

The plan file follows this structure:

# Newsletter Issue Plan: [Topic]

## Research Summary
[Key findings and angle — or "Based on [source material]" if repurposing]

## Subject Lines
[3-5 options with preview text, rationale, and star ratings]

## Opening Hook Options
[2-3 opening paragraphs with strategy, rationale, and star ratings]

## Draft Issue
[Full newsletter draft following newsletter structure]

## Social Promotion
### Twitter/X Thread
[Thread draft]
### LinkedIn Post
[Post draft]
### Substack Note
[Note draft]

## Header Image
[Generated image or "Not requested"]

Delegation Reference

Each foundation skill owns its own reference files and loads them automatically:

ContentSkillReference (loaded by the skill)
Researchcreator-stack:researchLoaded based on topic context
Newsletter draftcreator-stack:writenewsletter.md
Subject linescreator-stack:titlenewsletter-subject-lines.md
Opening hookscreator-stack:hooknewsletter-hooks.md
Twitter threadcreator-stack:writetwitter.md
LinkedIn postcreator-stack:writelinkedin.md
Substack Notecreator-stack:writesubstack-notes.md
Voicecreator-stack:voiceInvoked automatically by writing skill

Quality Checklist

Verify completion before presenting the plan:

  • Research conducted (or source material loaded)
  • creator-stack:write invoked for newsletter draft
  • creator-stack:title invoked for subject lines
  • creator-stack:hook invoked for opening hooks
  • creator-stack:write invoked for social promotion posts (all 3 platforms)
  • All written content goes through creator-stack:voice (handled by writing skill)
  • All options presented with star ratings
  • Complete plan presented to user

Common Pitfalls

  1. Writing content directly: Drafting newsletter text or social posts without invoking the writing skill — the foundation skill has all the section rules and voice handling built in.
  2. Skipping research without reason: If research is skipped, document why (e.g., "Repurposing video transcript provided by user").
  3. Single option only: Presenting one subject line or one hook — always provide multiple options with ratings so the user can choose.
  4. Missing social promotion: Forgetting one of the three platforms (Twitter/X, LinkedIn, Substack Notes).
  5. No voice consistency: The writing skill handles this automatically via creator-stack:voice, but verify the output reads consistently.

Example Execution

Scenario: User asks to plan a newsletter about "Building AI agents with memory"

  1. Research: Invoke creator-stack:research with topic "AI agents with memory" to identify content gaps and angles.
  2. Draft: Invoke creator-stack:write with research findings to produce the full newsletter draft.
  3. Subject lines: Invoke creator-stack:title to generate 4 subject line options with preview text.
  4. Opening hooks: Invoke creator-stack:hook to generate 3 opening paragraph options.
  5. Social posts: Invoke creator-stack:write three times for Twitter/X thread, LinkedIn post, and Substack Note.
  6. Header image: User did not request one — mark "Not requested."
  7. Present plan: Save to ./newsletter/issues/ai-agents-with-memory/plan.md and present to user.

Result: Complete newsletter issue plan with multiple options at each decision point, all backed by research insights and generated through specialized foundation skills.

Plan Video

Overview

This orchestrator sequences foundation skills to produce a complete video plan: researched titles, thumbnail concepts, hook strategies, and a content outline. It manages the user selection workflow between steps but delegates all content generation to specialized skills.

Core Principle: This is a thin orchestrator. All content generation goes through foundation skills — that's where the proven patterns, formulas, and quality logic live. This skill manages workflow sequence, user decisions, and plan file assembly only.

How Reference Delegation Works

Each step below invokes a foundation skill that owns its own reference files. When you invoke creator-stack:title, it loads references/youtube-title-formulas.md from its own directory. When you invoke creator-stack:thumbnail, it loads references/thumbnail-formulas.md from its own directory. You don't need to manage these paths — just invoke the skill and provide context.

YouTube-Specific Context

Episode Directory Convention

All episode files live under ./youtube/episode/[episode_number]_[topic_short_name]/.

  • Research file: research.md in the episode directory
  • Plan file: plan.md in the episode directory
  • Thumbnails: saved to the episode directory during finalization

Channel Information

If a local channel context file exists (e.g., ./youtube/channel.md or similar), load it at the start of the workflow to provide channel-specific context to downstream skills.

YouTube MCP Tools Available

When creator-stack:research is invoked from this orchestrator, the YouTube Analytics MCP tools are available for data gathering:

  • search_videos — find videos by keyword, channel, or criteria
  • get_video_details — video stats, views, likes, comments, publish date
  • get_channel_details — channel metadata, subscriber count, video count
  • get_video_comments — comment text and sentiment data
  • get_video_transcript — full video transcript
  • get_related_videos — videos related to a specific video
  • get_trending_videos — currently trending videos
  • get_video_enhanced_transcript — enhanced transcript with timestamps

The YouTube Researcher agent (defined in this plugin's agents/youtube-researcher.md) can also be used for structured data gathering tasks.

When to Use

Use this skill when:

  • Research has been completed and you need to create a video plan
  • The user asks to plan a new video
  • You need title, thumbnail, hook, and outline options for a video
  • You want to produce a production-ready plan with multiple options for user selection

Prerequisites

Research for the video must be completed first. Either:

  1. Research file exists at ./youtube/episode/[episode_number]_[topic_short_name]/research.md, OR
  2. Invoke creator-stack:research to conduct research first (YouTube MCP tools are available)

Planning Workflow

Execute all steps below in order. Track progress systematically.

Step 0: Load Research

Read the research file for this episode:

  • Location: ./youtube/episode/[episode_number]_[topic_short_name]/research.md

If research does not exist, invoke creator-stack:research first. The YouTube MCP tools are available from this orchestrator context, enabling the research skill to gather YouTube-specific data.

The video plan should incorporate research findings at each step — research grounds every recommendation.

Step 1: Create Plan File

Create a new plan file at: ./youtube/episode/[episode_number]_[topic_short_name]/plan.md

If a plan file already exists, read it to understand what has been done so far and continue from there.

Initialize the plan file with this template:

# [Episode_Number]: [Topic] - Video Plan

## Research Summary
[Summary of research insights]

## Titles
[3 title options with rationale and star ratings]

## Thumbnails
[2 thumbnail concepts per title with rationale and star ratings]

## Hooks
[3 hook options for selected title+thumbnail with rationale and star ratings]

## High-Level Content Outline
[Section structure with key points]

## Final Plan
[Selected title, 3 AB test thumbnails, selected hook, outline]

Update this document as you progress through the planning steps.

Step 2: Generate Title Options

  1. Invoke creator-stack:title to generate 3 optimized titles.

    • Provide the research summary as context.
  2. Document all title options in the plan file including:

    • Title text
    • Rationale for why it is predicted to perform well and how it aligns with research insights
    • Star rating from 1-3 stars indicating your recommendation

Complete title generation before proceeding to thumbnails — thumbnails need to complement the titles.

Step 3: Generate Thumbnail Concepts

  1. Invoke creator-stack:thumbnail to generate 2 thumbnail concepts for each title. These should be concept descriptions only, not actual images yet.

    • Provide each title as context so thumbnails complement them.
  2. Document all thumbnail concepts in the plan file including:

    • Title pairing
    • Concept description
    • Rationale for why it is predicted to perform well, how it aligns with research, and how it complements the title
    • Star rating for top 3 thumbnail concepts

Step 4: Present Recommendation and Get User Selection

  1. Present all title/thumbnail combinations to the user, along with your top 3 recommended title + thumbnail pairings.

  2. Ask the user to select their one preferred title + thumbnail pairing to proceed with.

  3. Update both the title and thumbnail sections in the plan file to indicate the user's selection with a (User Selection) marker next to the selected options.

Always present all options so the user can make an informed decision — that's the whole point of generating multiple options.

Step 5: Generate Hook Strategy

  1. Invoke creator-stack:hook to generate 3 retention-optimized hooks, only for the user's selected title + thumbnail pairing.

    • Provide the selected title + thumbnail concept as context.
  2. Document all hook strategies in the plan file including:

    • Hook strategy description (including the actual hook script)
    • Rationale for why it is predicted to perform well, how it aligns with research, and how it complements the title + thumbnail
    • Star rating for each hook
  3. Present all hook options to the user and ask the user to select their preferred hook strategy.

  4. Update the hook section in the plan file to indicate the user's selection.

The plan should now contain a user-selected title, thumbnail, and hook combination.

Step 6: High-Level Content Outline

  1. Invoke creator-stack:write to create a high-level content outline.

    • Provide the selected title, thumbnail concept, and hook as context.
  2. Create and document the strategic roadmap:

    • Break video into sections (Hook, Intro, Main Content, Outro)
    • List key points and estimated durations
    • Identify critical demonstrations/examples
    • Note transitions
  3. Keep the outline high-level — structure and key points only, no detailed scripts. Focus on what is important to cover from the viewer's perspective rather than assuming specific content.

Step 7: Finalize Plan with AB Testing Thumbnails

Now that the user has selected their preferred title, thumbnail, and hook, finalize the plan.

  1. Invoke creator-stack:thumbnail to generate 3 thumbnail options for AB testing. These should be actual images generated with creator-stack:nanobanana, not just concepts. The first thumbnail should be based on the user's selected thumbnail concept. The other 2 should test different visual styles of the first thumbnail.

  2. Update the final plan section in the plan file with the complete final selections:

## Final Plan
- **Title**: [Selected title]
- **Thumbnails**:
   - ![Thumbnail A](/path/to/thumbnail_a.png)
      Thumbnail A Description
   - ![Thumbnail B](/path/to/thumbnail_b.png)
      Thumbnail B Description
   - ![Thumbnail C](/path/to/thumbnail_c.png)
      Thumbnail C Description
- **Hook**: [Selected hook strategy]
- **Rationale**: [Why this combination works]

A final plan always includes 3 thumbnails to AB test — that's how you learn what works for your audience.

Delegation Reference

Each foundation skill owns its own reference files and loads them automatically:

ContentSkillReference (loaded by the skill)
Titlescreator-stack:titleyoutube-title-formulas.md
Thumbnailscreator-stack:thumbnailthumbnail-formulas.md
Hookscreator-stack:hookyoutube-hooks.md
Outlinecreator-stack:writeyoutube-script.md
Voicecreator-stack:voiceInvoked automatically by writing skill

Complementarity Check

Before finalizing, verify that title/thumbnail/hook work together:

  • Thumbnail complements title visually (doesn't repeat it)
  • Hook extends curiosity (doesn't repeat title)
  • All elements align with the unique value proposition from research

Quality Checklist

Verify completion before finalizing plan:

  • Research file loaded and reviewed
  • creator-stack:title invoked — 3 title options generated
  • creator-stack:thumbnail invoked — 2 thumbnail concepts per title
  • User selected title + thumbnail pairing
  • creator-stack:hook invoked — 3 hook strategies generated
  • User selected hook strategy
  • creator-stack:write invoked — high-level content outline created
  • creator-stack:thumbnail invoked — 3 AB testing thumbnails generated
  • Plan file complete with all sections populated
  • Recommendations marked by star rating
  • Title/thumbnail/hook complementarity verified
  • Recommendations backed by research insights

Common Pitfalls

  1. Skipping skill invocation: Generating titles/thumbnails/hooks manually — the foundation skills have proven patterns you'd miss.
  2. Single option: Only providing one recommendation — always provide all options so the user can choose.
  3. Missing research: Starting without research — load research or invoke the research skill first.
  4. Ignoring complementarity: Title/thumbnail/hook don't work together — verify alignment before finalizing.
  5. No rationale: Recommendations without explanation — back everything with research insights.
  6. Too-detailed outline: Writing a full script instead of high-level structure — keep it strategic.

Example Execution

Scenario: User requests plan for video about "Building AI agents with memory" (research already complete)

  1. Load research — Read ./youtube/episode/18_ai_agents_with_memory/research.md, extract key insights
  2. Create plan file at ./youtube/episode/18_ai_agents_with_memory/plan.md
  3. Invoke creator-stack:title — 3 title options focused on practical implementation
  4. Invoke creator-stack:thumbnail — 2 concepts per title (6 total)
  5. Present all options, user selects title + thumbnail pairing
  6. Invoke creator-stack:hook — 3 hook strategies for selected pairing
  7. User selects hook
  8. Invoke creator-stack:write — high-level content outline
  9. Invoke creator-stack:thumbnail — 3 AB testing thumbnails for final plan
  10. Update plan file with complete final selections

Result: Production-ready plan with multiple options for user selection, all backed by research and generated using proven patterns from foundation skills.

Repurpose Video

Overview

This orchestrator takes a completed video's content and transforms it into multi-platform content. It sequences creator-stack:write invocations with platform-specific references to produce newsletter issues, Twitter threads, LinkedIn posts, and Substack Notes — all maintaining consistent voice through the writing skill's built-in voice handling.

Core Principle: This is a thin orchestrator. All content generation is delegated to creator-stack:write, which owns the platform-specific references and automatically invokes creator-stack:voice. This skill manages the workflow sequence and platform-specific decisions only.

How Reference Delegation Works

Each platform step below invokes creator-stack:write and specifies a content type. The writing skill then loads its own reference file for that platform (e.g., references/newsletter.md, references/twitter.md). Those files live in the writing skill's directory, not here — this orchestrator doesn't need its own references because all content generation is delegated.

When to Use

Use this skill when:

  • A video has been completed and you want to distribute its content across platforms
  • The user asks to repurpose a video into other content formats
  • You need to create a newsletter issue, social media posts, or other content from a video
  • You want to maximize the reach of a single video's content

Prerequisites

A completed video with at least one of the following available in the episode directory (./youtube/episode/[episode_number]_[topic_short_name]/):

  • research.md — research findings
  • plan.md — video plan with title, hook, and outline
  • transcript.md — video transcript
  • Key points or notes provided by the user

The more source material available, the better the repurposed content will be. A transcript is the richest source, but a plan + research combination also works well.

Repurposing Workflow

Execute all steps below in order.

Step 1: Load Source Material

Read all available source files from the episode directory:

  • ./youtube/episode/[episode_number]_[topic_short_name]/research.md
  • ./youtube/episode/[episode_number]_[topic_short_name]/plan.md
  • ./youtube/episode/[episode_number]_[topic_short_name]/transcript.md

If the user provides additional notes or key points, incorporate those as well.

Step 2: Extract Key Content

Synthesize the source material into a content brief. This brief becomes the shared context for every downstream writing skill invocation — it's what keeps the message consistent across platforms even as the format changes.

  • Core thesis: The main argument or insight from the video
  • Key takeaways: 3-5 actionable insights or lessons
  • Supporting points: Examples, data, or stories used in the video
  • Unique angle: What makes this perspective different from existing content
  • Call to action: What the viewer/reader should do next

Step 3: Newsletter Issue

Invoke creator-stack:write with content type "newsletter" to draft a newsletter issue.

Provide the content brief and specify:

  • Transform the video's content into a written newsletter format
  • Adapt the structure for reading (not watching) — readers scan, viewers follow linearly
  • Include the key takeaways in a scannable format
  • Link back to the YouTube video

The writing skill loads its own references/newsletter.md and automatically invokes creator-stack:voice.

Step 4: Twitter Thread

Invoke creator-stack:write with content type "twitter" to draft a Twitter thread.

Provide the content brief and specify:

  • Distill the video into a compelling thread (5-10 tweets)
  • Lead with the most attention-grabbing insight
  • Each tweet should stand alone but build on the narrative
  • Include a link to the video in the final tweet

Step 5: LinkedIn Post

Invoke creator-stack:write with content type "linkedin" to draft a LinkedIn post.

Provide the content brief and specify:

  • Adapt the video's professional insights for LinkedIn's audience
  • Use a hook-based opening that stops the scroll
  • Include actionable takeaways
  • End with engagement prompt and video link

Step 6: Substack Note

Invoke creator-stack:write with content type "substack-note" to draft a Substack Note.

Provide the content brief and specify:

  • Create a concise, conversational note
  • Highlight one key insight or takeaway
  • Drive traffic to the full newsletter issue or video

Step 7: Present and Save

  1. Present all repurposed content to the user for review:

    • Newsletter issue
    • Twitter thread
    • LinkedIn post
    • Substack Note
  2. After user approval (with any requested edits), save all content to the episode directory:

    • ./youtube/episode/[episode_number]_[topic_short_name]/repurposed.md

The repurposed content file should contain all platform versions with clear section headers.

Output Format

The saved repurposed.md file should follow this structure:

# [Episode_Number]: [Topic] - Repurposed Content

## Source
- Video: [Title]
- Episode: [Number]
- Core Thesis: [One sentence]

## Newsletter Issue
[Full newsletter content]

## Twitter Thread
[Numbered tweets]

## LinkedIn Post
[Full LinkedIn post]

## Substack Note
[Full Substack Note]

Quality Checklist

Verify completion before finalizing:

  • Source material loaded (research, plan, transcript, or notes)
  • Content brief extracted with core thesis, takeaways, and unique angle
  • creator-stack:write invoked for newsletter — drafted
  • creator-stack:write invoked for Twitter — thread drafted
  • creator-stack:write invoked for LinkedIn — post drafted
  • creator-stack:write invoked for Substack Note — note drafted
  • Voice consistency maintained across all platforms (handled by writing skill)
  • Each platform's content adapts the message to its audience and format
  • Video link included in all platform content
  • All content presented to user for review
  • Final content saved to repurposed.md in episode directory

Common Pitfalls

  1. Copy-pasting across platforms: Each platform needs content adapted to its format and audience — the writing skill handles this through platform-specific references, so always invoke it separately per platform.
  2. Skipping the content brief: Jumping straight to writing without extracting key points leads to unfocused content that drifts between platforms.
  3. Missing voice consistency: Always let creator-stack:write handle voice through its built-in creator-stack:voice invocation.
  4. Forgetting video links: Every platform piece should drive traffic back to the video.
  5. Over-repurposing: Not every video insight fits every platform — let the writing skill adapt appropriately.

Content Research

Overview

This skill conducts topic and competitor research for any content type. Execute all steps to produce actionable insights that identify content gaps and analyze competitors. This skill focuses ONLY on research — it does not generate titles, hooks, or other creative assets.

Core Principle: Focus on insights and big levers, not data dumping. Research should be comprehensive yet concise, backed by data, and designed to inform strategic decisions.

When to Use

Use this skill when:

  • You need to research a topic before creating content
  • The user asks to research a content idea or topic
  • You want to understand the competitive landscape for a topic
  • You need to identify content gaps and opportunities
  • Preparing for title generation, hook creation, or full content planning

Platform-Specific Research Tools

This skill is designed to work across platforms. Orchestrator skills may provide platform-specific tools for research:

PlatformTools Provided By OrchestratorFallback
YouTubeYouTube Analytics MCP (search, video details, channel details)Web search
Newsletter/BlogContent analytics, email platform dataWeb search
Social MediaPlatform analytics, engagement dataWeb search
GeneralN/AWeb search (default)

Platform-specific research strategies are available in the references/ directory:

  • references/research-frameworks.md — General research frameworks
  • references/substack-notes-strategy.md — Substack Notes strategy
  • references/youtube-community-strategy.md — YouTube community strategy

When no platform-specific tools are available, use web search as a general-purpose research tool to find existing content, competitor analysis, and trending topics.

Research Subagents

You can invoke research subagents using the Agent tool with run_in_background: true to conduct specific, focused research tasks in parallel. Each agent prompt should be focused and specific, with a clear objective.

Bias towards using the Agent tool rather than executing all research sequentially. Parallel research greatly improves performance.

Research Workflow

Execute all steps below to complete the research.

Step 0: Initialize Research Document

Create a research document at the location specified by the orchestrator or the user. If no location is specified, ask the user where to save the output.

All research MUST be written to this file. If the file already exists, read it to understand what research has been done so far and continue from there.

Step 1: Understand the Topic

Analyze and document:

  • What problem does this content solve?
  • Why would someone engage with this content?
  • What makes this topic relevant now?
  • Who is the target audience?

Step 2: Research Existing Content

Execute these actions using available tools (platform-specific MCP tools if provided, otherwise web search):

  1. Find the user's related existing content on the topic
  2. Gather performance metrics where available
  3. Identify what has already been covered and how to differentiate

Document in research file:

  • Related existing content (title, link, key metrics if available)
  • Performance insights (what worked, what did not)
  • Differentiation strategy for new content

Step 3: Competitor Research

Execute these actions:

  1. Find 5-8 top-performing pieces of content on the topic
  2. Filter for recent content with high engagement
  3. Gather details and metrics for each
  4. Analyze patterns in successful content

Document for each competitor:

  • Title, creator/publication, link
  • Key metrics (views, engagement, shares — whatever is available)
  • Focus/angle and what makes it successful

Synthesize key insights: Identify common patterns and different approaches across competitors.

Step 4: Content Gap Analysis

Analyze and identify:

  • What subtopics or angles are saturated?
  • What is missing or underexplored?
  • Where can the user add unique value?

Document in research file:

  • What's Already Well-Covered: 3-5 saturated topics/approaches
  • Content Gaps (Opportunities): Specific opportunities rated by potential
    • Rating: *** (high), ** (medium), * (low)
  • Recommended Focus: The specific angle and unique value proposition

Rating Criteria:

  • *** High: Significant gap, strong demand, clear differentiation possible
  • ** Medium: Moderate gap, some competition, good potential
    • Low: Minor gap, heavily competed, incremental value

Step 5: Recommended Angle

Based on the gap analysis, define:

  • The specific angle to take
  • The unique value proposition
  • Why this angle is better than what already exists
  • What makes the user uniquely qualified to cover this

Output Structure

Use this template structure for the research document:

# [Topic] - Research

## Content Overview
**Topic**: [Brief description]
**Target Audience**: [Who this is for]
**Content Type**: [YouTube video, newsletter, social post, etc.]
**Goal**: [What the audience will learn/gain]

## Research Notes
### Key Concepts to Cover
[High-level list]

## Existing Content Landscape
### User's Related Content
[Analysis of user's previous content on this topic]

### Top Competing Content
[5-8 pieces with analysis]

### Key Insights
[Patterns and findings across competitors]

## Content Gap Analysis
### What's Already Well-Covered
[List of saturated angles]

### Content Gaps (Opportunities)
[Rated list of specific gaps]

### Recommended Focus
[Specific angle and unique value proposition]

## Production Notes
**Status**: Research Complete
**Created**: [Date]
**Updated**: [Date]

Voice Application

Before finalizing any written output, invoke the creator-stack:voice skill to apply voice rules. Research documents should reflect the user's authentic voice, not generic analyst language.

Brand Compliance

When creating assets for The AI Launchpad, invoke creator-stack:brand-guidelines to resolve the correct design system and check anti-patterns.

Execution Guidelines

Focus on Insights, Not Data

Execute research with these principles:

  • Synthesize patterns from research
  • Identify 3-5 key insights with supporting data
  • Explain WHY approaches work
  • Limit competitor research to 5-8 pieces of content

Prioritize Big Levers

Focus research on these impact areas in order:

  1. Content Gaps (unique value)
  2. Competitor Patterns
  3. Audience Needs
  4. Technical/Format Requirements

Back Recommendations with Data

When documenting findings:

  • Bad: "Write about AI agents"
  • Good: "Focus on AI agent memory systems (*** gap) — competitors get high engagement but none cover persistent memory"

Quality Checklist

Verify completion before finalizing research:

  • Topic clearly understood with audience and goal defined
  • User's existing related content reviewed
  • 5-8 competitors documented with analysis
  • Content gaps identified with star ratings
  • Research is concise yet comprehensive (not data dumping)
  • All recommendations backed by data
  • Unique value proposition clearly stated
  • Voice skill applied to final output

Common Pitfalls to Avoid

  1. Data Dumping: Listing every piece of content found without synthesis. Limit to 5-8 top competitors, focus on patterns.
  2. Vague Content Gaps: "Not much content on this topic." Identify specific angles that are missing.
  3. Over-Researching Technical Details: Deep implementation research when high-level coverage suffices. Keep focused on what to cover, not how.
  4. Long Reports: 800+ line documents with low signal. Focus on insights and big levers.
  5. Platform Assumptions: Assuming YouTube tools are available when they may not be. Check what tools the orchestrator has provided.

Example Execution

Scenario: User requests research for content about "Building AI agents with memory"

Execute workflow:

  1. Understand topic: Practical guide to AI agent memory, targeting developers
  2. Find related content: Search user's existing content, find related pieces on personal assistants
  3. Competitor research: Search and analyze 8 top pieces, identify they cover theory not implementation
  4. Gap analysis: Document *** opportunity for practical memory implementation tutorial
  5. Save research: Write to user-specified location

Result: Comprehensive research document ready for review or to proceed to title/hook generation.

Next Step: If the user has asked to plan content, invoke creator-stack:title to generate title options based on this research.

Social Graphic Skill

Create polished social media graphics and visual assets optimized for specific platforms. This skill handles platform-specific dimensions, safe zones, and design constraints to produce assets that display correctly and perform well across channels.

When to Use

Invoke this skill when the user needs:

  • Social media post images -- Twitter/X, LinkedIn, Instagram
  • Newsletter headers -- Substack, email campaigns
  • Blog feature images -- OG images, hero banners
  • Course thumbnails -- Platform-specific cover images
  • Profile and cover images -- Headers, banners, profile pictures

For YouTube thumbnails or any thumbnail requiring specialized CTR optimization, use the creator-stack:thumbnail skill instead.

Platform Resolution

Before generating any asset, determine the target platform and format. Platform specs are loaded from references/platform-specs.md.

Resolution order:

  1. If the calling orchestrator provides platform context (dimensions, format), use it directly
  2. If the user specifies a platform, load specs from the reference file
  3. If ambiguous, ask the user which platform and format they need

Always confirm dimensions before generating. Mismatched dimensions cause cropping, letterboxing, or blurry upscaling on the target platform.

Standard Workflow

1. Determine Platform and Format

Identify the target platform and specific format from user request or orchestrator context. Load the matching specs from references/platform-specs.md, including dimensions, aspect ratio, safe zones, and text constraints.

2. Gather Context

Collect the information needed to design the graphic:

  • Topic or subject -- What the graphic is about
  • Key message -- The primary text or call to action
  • Brand elements -- Logo, colors, typography (resolve via brand guidelines)
  • Reference images -- Any existing assets, style references, or photos to incorporate
  • Tone -- Professional, casual, bold, minimal, etc.

3. Design the Concept

Create a design concept that respects the platform constraints:

  • Work within the safe zone (keep text and key elements within 80% of frame)
  • Follow text size minimums from platform specs
  • Ensure the composition works at the platform's typical display size
  • Apply the thumbnail design principles from creator-stack:thumbnail references where applicable (glance test, focal points, contrast)

4. Generate the Image

Use the creator-stack:nanobanana skill to generate the graphic:

  • Set the correct aspect ratio matching the platform spec
  • Use Pro model for final production assets, Flash for drafts and exploration
  • Pass any reference images using absolute paths
  • Include brand-specific style direction in the prompt

5. Brand Compliance Check

Invoke creator-stack:brand-guidelines to verify the generated graphic against:

  • Brand color palette and typography
  • Visual style consistency
  • Anti-patterns (things the brand should never do)
  • Design system rules for the asset type

For The AI Launchpad assets, this step is mandatory. For other brands, check if a brand guidelines skill exists at ~/.claude/skills/ and apply any relevant constraints.

6. Review and Iterate

Review the generated graphic against the quality checklist below. If it does not pass, edit using creator-stack:nanobanana with the original as a reference image. Limit iteration to two rounds maximum.

7. Present to User

Present the final graphic with:

  • The generated image
  • Platform and dimensions used
  • Any notes on safe zones or cropping behavior
  • Suggestions for companion text or alt text

Brand Compliance

When creating visual assets for The AI Launchpad, invoke creator-stack:brand-guidelines to resolve the correct design system and check anti-patterns. This ensures all social graphics are consistent with the established brand identity.

For other brands, check if a brand guidelines skill exists at ~/.claude/skills/ and apply any relevant design constraints. If no brand guidelines exist, follow general best practices for the target platform.

Quality Checklist

Before presenting any graphic to the user, verify:

  1. Correct dimensions -- Matches the target platform spec exactly
  2. Safe zone compliance -- Text and key elements within 80% of frame
  3. Text legibility -- All text readable at the platform's typical display size
  4. Brand consistency -- Colors, fonts, and style match brand guidelines
  5. Visual clarity -- Clean composition, clear focal point, no clutter
  6. Platform constraints -- Respects text overlay limits, file size recommendations
  7. Contrast and accessibility -- Sufficient contrast for readability across devices
  8. No cropping issues -- Key elements will not be cut off by platform UI overlays

Thumbnail Skill

This skill enables generation of high-performing thumbnails and cover images optimized for click-through rate (CTR). Thumbnails are designed to spark curiosity, complement titles, and compel viewers to click.

Image Generation

All image generation and editing goes through the creator-stack:nanobanana skill — it provides access to Gemini image models (Pro and Flash) with support for text-to-image, image editing, multi-image reference, and high-resolution output. Invoke it before generating or editing any thumbnail.

Model Selection for Thumbnails

  • Pro (default) — Use for final production thumbnails. Supports 2K/4K resolution, up to 14 reference images, and thinking mode for better composition.
  • Flash — Use for rapid exploration and draft concepts. Faster and cheaper, good for iterating on ideas before committing to a final version.

Rule of thumb: Use Flash for exploration batches (generate 5-10 variations), then Pro for the final production image.

Essential References

Read both of these before generating any thumbnail — they contain the design patterns and prompting techniques that make the difference between a generic image and a high-CTR thumbnail:

  1. references/thumbnail-formulas.md — Design formulas for high CTR thumbnails through proven strategies. These principles apply universally across platforms.
  2. references/prompting-guidelines.md — Thumbnails are generated using Gemini image models (NanoBanana). The prompting guidelines help you get more predictable and consistent results.

Skipping these leads to generic thumbnails that don't follow proven patterns — always load them first.

Platform Context

When invoked by orchestrator skills, platform-specific context (dimensions, safe zones, format requirements) may be provided. Use the provided context to set the correct output dimensions and constraints.

Default dimensions: When no platform context is given, default to YouTube thumbnail dimensions (1280x720, 16:9 aspect ratio).

Common platform dimensions:

  • YouTube thumbnail: 1280x720 (16:9)
  • Blog feature image: 1200x630
  • Course thumbnail: 1280x720 or 1080x1080
  • Newsletter header: 1100x220 or 1200x630
  • Social media card: 1200x675

Always confirm the target platform before generating to ensure correct dimensions.

Reference Images

With both generating and editing thumbnails, you can include reference images. Examples include but are not limited to thumbnail templates, headshots, icons, logos, or images for style transfer. See the Prompting Guidelines above for more.

All reference images MUST be passed using absolute paths.

Using Official Logos

If using company logos, use actual images by passing the absolute path to the image files instead of simply describing them. Nanobanana does not know what common company logos look like.

If a company logo is not locally available, you can search for it online and download it using curl, then pass the absolute path to the downloaded image in the prompt. Save all downloaded images to ./downloads/, making the directory if it does not exist.

Common Mistakes to Avoid

WRONG: "create the Claude AI logo (an orange C shape)" CORRECT: Pass the actual logo file as a reference image

WRONG: "add the Python logo" CORRECT: Use /absolute/path/to/python-logo.png as a reference image

Proven Designs

If you know the content title or subject, search for related OUTLIER content. Focus on OUTLIERS because they are already proven to work well and very likely have high click-through rates. Videos are outliers if they have a high amount of views compared to the subscriber count of the channel. For example, if a video has 10,000+ views from a channel with less than 5,000 subscribers, that video is an outlier.

Once you have a list of outlier videos, you can access their thumbnails and use them to style transfer.

Here is a URL example of a standard definition thumbnail for a video with id "rmvDxxNubIg": https://img.youtube.com/vi/rmvDxxNubIg/sddefault.jpg. You can download the image using curl to ./downloads/outliers/, and then read the image file to understand it. Use it as a reference image when using for style transfer.

Brand Compliance

When creating visual assets for The AI Launchpad, invoke creator-stack:brand-guidelines to resolve the correct design system and check anti-patterns. This ensures all thumbnails are consistent with the established brand identity, color palette, and visual style.

For other brands, check if a brand guidelines skill exists at ~/.claude/skills/ and apply any relevant design constraints.

Workflows

Generating Thumbnail Concepts

Once you have generated an initial thumbnail concept or prompt, use the Thumbnail Reviewer agent to review the concept and provide feedback. The reviewer will provide a critique and suggest improvements. Consider the reviewer's feedback and incorporate it before proceeding. Limit the generate-review-regenerate loop to a single pass — additional iterations yield diminishing returns and the reviewer's first critique captures the most impactful changes.

Optimizing Thumbnails

Because creator-stack:nanobanana supports image editing, you can iteratively modify and improve a previously generated thumbnail. Pass the original thumbnail as a reference image and describe the desired changes.

Always review generated thumbnails to ensure they meet the complete design formulas and original intent. If not, you can iterate by editing the original thumbnail. Limit the generate-review-regenerate loop to a single pass — additional iterations yield diminishing returns and the reviewer's first critique captures the most impactful changes.

User Assets

If the user has specified any local assets (e.g. thumbnail templates, headshots, icons, logos, etc.) in their local context, bias towards incorporating them into the thumbnail when relevant. For example, thumbnails with actual people in them have been shown to perform better.

Title Generation

Overview

This skill generates high-performing titles and headlines optimized for engagement across any content type. Titles are designed to spark curiosity, complement visual assets where applicable, and compel the audience to click, open, or engage.

Core Principle: Every title must prompt a specific question in the audience's mind. Description alone is insufficient — curiosity is non-negotiable.

When to Use

Use this skill when:

  • The user asks to create a title, headline, or subject line
  • The user requests title ideas or brainstorming for content
  • The user wants to improve or optimize an existing title
  • Working on content creation and a title is needed
  • The user asks for multiple title variations to test

Content Type Resolution

Before generating titles, determine the content type and load the appropriate platform-specific reference file:

Content TypeReference FileKey Focus
YouTube videoreferences/youtube-title-formulas.mdCTR, curiosity, thumbnail complementarity
Newsletter / emailreferences/newsletter-subject-lines.mdOpen rate, preview text, inbox competition
Social media postreferences/social-headlines.mdScroll-stopping, platform-specific hooks

Essential: Read the relevant reference file before generating titles — each platform has unique patterns and constraints that directly affect performance, and skipping this step leads to generic titles that underperform.

If the content type does not match any reference file, apply the universal principles below and adapt to the format.

Prerequisites

Gather Context

Before generating titles, gather the following information from conversation context, the user's filesystem, or by asking the user directly.

Required Information:

  • Content topic: What is the content about?
  • Target audience: Who is this for?
  • Key message: What is the main takeaway or hook?

Highly Recommended Information:

  • Visual asset description: What does the thumbnail, header image, or preview show?
  • Target emotion: What emotion should the title evoke? (curiosity, shock, excitement, urgency)
  • Content type: Video, newsletter, social post, blog article, etc.

Title Generation Workflow

Step 1: Gather Context

Collect required information if not already provided. Ask the user for anything missing:

To create an optimized title, I need to understand:
1. What is the content about? (topic)
2. Who is your target audience?
3. What is the main hook or takeaway?
4. Do you have a visual asset (thumbnail, header image)? If so, what does it show?
5. What emotion should the title evoke?

Step 2: Load Platform Reference

Read the appropriate platform-specific reference file based on the content type identified in Step 1.

Step 3: Identify the Question

Before writing any title, identify the specific question you want in the audience's mind:

  • What question will make them curious enough to engage?
  • Does this question align with the content?
  • Is the curiosity gap strong enough to drive action?

Examples of effective questions to prompt:

  • "What mistakes am I making?" (mistake framing)
  • "What happened?" (outcome uncertainty)
  • "Why would someone do that?" (extreme behavior)
  • "How is that possible?" (surprising claim)

Step 4: Generate Title Options

Generate 3-5 title variations that:

  1. Prompt the identified question
  2. Complement (not duplicate) any visual assets
  3. Align with the target emotion
  4. Follow platform-specific best practices from the reference file

Step 5: Verify Against Checklist

For each title, verify against the universal checklist:

  • Curiosity Test: Does this prompt a specific question?
  • Complementarity Test: Does this work WITH visual assets (not duplicate them)?
  • Click/Open Compulsion Test: Is the curiosity gap strong enough?
  • Non-Descriptive Test: Does this go beyond merely describing content?
  • Target Audience Test: Will this resonate with the intended audience?

Step 6: Present and Refine

Present title options to the user with:

  1. The title itself
  2. The question it prompts in the audience's mind
  3. How it complements the visual asset (if applicable)
  4. Why it should drive engagement

Example presentation:

Here are 3 optimized title options:

1. "The AI Agent Mistake That Cost Me 10 Hours"
   - Prompts: "What mistake? How can I avoid it?"
   - Complements thumbnail showing frustrated face + error message
   - Creates urgency through time cost

2. "I Built This AI Agent Wrong (Here's What I Learned)"
   - Prompts: "What did they do wrong? What's the lesson?"
   - Personal experience framing creates relatability

3. "Why Your AI Agents Keep Breaking (And Mine Don't)"
   - Prompts: "Why do mine break? What's their secret?"
   - Creates contrast and curiosity

Step 7: Iterate Based on Feedback

If the user requests changes:

  1. Understand what aspect needs adjustment (curiosity, tone, length, etc.)
  2. Regenerate while maintaining checklist compliance
  3. Re-verify against the checklist

Voice Application

Before finalizing any written output, invoke the creator-stack:voice skill to apply voice rules. Titles should sound authentic to the user's voice, not generic.

Brand Compliance

When creating assets for The AI Launchpad, invoke creator-stack:brand-guidelines to resolve the correct design system and check anti-patterns.

Quality Assurance

Priority Order

  1. Spark curiosity (highest priority)
  2. Complement visual asset
  3. Raise audience question
  4. Create click/open compulsion

Rejection Criteria

Regenerate if the title:

  • Merely describes the content without sparking curiosity
  • Duplicates text that appears on the visual asset
  • Answers the question instead of raising it
  • Uses generic patterns without intrigue
  • Fails the "What question does this raise?" test

Success Criteria

A successful title:

  • Prompts a specific, compelling question in the audience's mind
  • Works synergistically with any visual asset
  • Creates a curiosity gap strong enough to drive engagement
  • Aligns with the target audience and content type
  • Passes all 5 universal checklist items

Common Pitfalls

  1. Generic Description: "AI Agents Tutorial" describes but does not intrigue. Add curiosity.
  2. Answering the Question: "How to Fix AI Agent Memory in 3 Steps" gives away too much. Tease, do not tell.
  3. Ignoring Platform: A YouTube title and a newsletter subject line have different constraints. Load the right reference.
  4. Thumbnail/Asset Duplication: If the thumbnail says "BROKEN", the title should not also say "broken." Complement, do not repeat.
  5. Single Option: Always provide 3-5 variations for the user to choose from.

Kenny's Writing Voice

Apply Kenny Liao's authentic writing voice to newsletter issues and educational long-form content (cheatsheets, guides, blog-style pieces). Works for both drafting from scratch and polishing rough drafts.

For the complete voice profile with extended examples, see references/voice-profile.md.

How Other Skills Should Invoke This Skill

This is a PERSONALITY skill. Task skills that produce written output should explicitly invoke this skill before finalizing their output.

Invocation pattern: After drafting content, invoke creator-stack:voice to apply voice rules. Pass the draft content and receive voice-corrected output.

When to invoke:

  • Any task skill producing text for Kenny (newsletters, scripts, guides, social posts)
  • After the initial draft is complete but before presenting to the user
  • Voice application is the LAST content transformation before brand compliance check

Voice Positioning

Kenny's voice is a peer sharing what he found — not a teacher lecturing, not a journalist reporting, not a marketer selling.

ThisNot That
ConversationalAcademic
DirectBlunt or rude
Honest about limitationsPessimistic
OpinionatedDogmatic
Peer-to-peerTeacher-to-student
EnthusiasticHype-driven
Technically preciseJargon-heavy
Raw and thinking-out-loudOver-polished newsletter-pro

Essential Voice Rules

1. Parenthetical Asides Are Signature

Add parenthetical interjections for nuance, caveats, and color commentary. This is the most identifiable marker of Kenny's voice. Use frequently.

  • "To my (and Claude's) knowledge, there's no limit to team size."
  • "not meant to be a regurgitation of documentation (you can always read the full docs)"

2. Alternate Short Punches with Longer Explanations

Lead with a short declarative sentence (sometimes a fragment). Then unpack it.

  • Short: "This is pretty significant in my book."
  • Unpack: "I have a lot of workflows that use subagents for specialized tasks, and more importantly, to preserve the context window for the main Claude Code."

Single-sentence paragraphs are normal. Dense paragraphs (5+ sentences) are not.

3. Use Sentence Fragments Deliberately

Sentence fragments are a core part of Kenny's rhythm. Use them for emphasis, follow-up thoughts, and transitions. They're rhetorical choices, not grammar mistakes.

  • "Both for performance and for cost efficiency."
  • "Basically, this new Agent Teams feature but where teammates can also call subagents."
  • "So polite!"

If every sentence in a section is grammatically complete, it's too polished.

4. Ground Every Claim in Personal Experience

"I tested this" is the default evidence source. Include specific numbers, real workflows, and real outcomes. Hypotheticals and unsupported claims are off-brand.

  • "Using myself as an example, I'm normally fine on the 5x ($100) max plan and rarely hit a session limit."

5. Always Acknowledge the Counterpoint

After stating an opinion, immediately acknowledge the other side. Use these specific transition phrases — they are Kenny's characteristic counterpoint markers:

  • "To be fair..." — the most common one
  • "But that doesn't mean..."
  • "There are clear opportunities where..."
  • "Though there's a very clear potential."

Never take a stance without showing awareness of the tradeoff. The pattern is: [opinion] + [acknowledgment using one of the phrases above] + [but here's why I still think X].

6. Why Before How

Explain motivation and the problem before mechanics. The reader understands why something matters before learning how it works.

7. Casual Vocabulary with Technical Precision

Use plain language for general concepts. Reserve exact terminology for domain-specific things.

  • Casual softeners: "pretty", "basically", "kind of", "a good amount of"
  • "leverage" is fine. "utilize", "synergy", "paradigm" are not.
  • Contractions always. "don't" not "do not". "I'm" not "I am".
  • No formal connectors: "furthermore", "moreover", "consequently"

8. Opinions Woven Throughout

Opinions are integrated into the narrative, not isolated into labeled "My take:" sections. The entire piece is the take.

9. Forward-Looking Endings

End with what's next, what's unresolved, or what to watch for. Never wrap up with a tidy summary bow or "In conclusion..." No "And that's worth celebrating" type flourishes.

10. Raw Over Polished

Kenny's writing has a thinking-out-loud quality. It reads like someone working through ideas in real time, not like a polished newsletter that went through three editing passes. Resist the urge to smooth every sentence into perfect flow. Leave some rough edges.

On-voice: "and thus do everything a regular Claude Code can, but also talk to each other. Because CC can't exchange information with subagents mid-process."

Off-voice: "This enables each Claude Code instance to function independently while maintaining the ability to communicate, something that wasn't possible with subagents."

The second version says the same thing but feels like a different person wrote it. Kenny's version has a mid-thought pivot ("Because CC can't...") that makes it feel real.

11. Functional Headers

Headers are descriptive and functional. State what the section is about, plainly.

On-voice: "Cost", "Communication", "Agent Teams vs Subagents", "Subagents Inside of Agent Teams" Off-voice: "The Context Window Fix We've Been Waiting For", "Why This Actually Matters", "What This Opens Up"

12. Formatting Conventions

  • Bold for key concepts and emphasis (not decoration)
  • Code blocks for anything technical
  • Blockquotes only for quoting external sources
  • Bulleted lists for features and comparisons (items kept to 1-2 sentences)
  • Screenshots/images as evidence, always with context explaining what the reader sees
  • Emoji sparingly and purposefully (section markers, not sprinkled in prose)

Anti-Patterns

Never Do ThisWhy
Academic tone ("Furthermore, it should be noted...")Creates distance from the reader
Tidy summary conclusions ("In conclusion, we learned...")Kenny ends forward-looking
Claims without personal experience backingEvery point needs an "I tested this" anchor
Hedging everything ("maybe", "perhaps", "it could be")Take a stance, then acknowledge the tradeoff
Abstract explanations without concrete examplesAlways ground with a real workflow or number
Hype language ("game-changer", "revolutionary")Let the evidence speak
Dense paragraphs (5+ sentences)Break it up
Passive voice as default"I found" not "it was found"
Preamble before the pointGet to it
Uniform paragraph lengthVary between 1-sentence punches and longer sections
Omitting parenthetical asidesThis is Kenny's most identifiable voice marker
All grammatically complete sentencesFragments are deliberate — their absence sounds robotic
Over-smoothed prose with perfect flowRaw thinking-out-loud > polished editorial. Leave mid-thought pivots in.
Editorial headers ("Why This Actually Matters")Plain and functional: "Cost", "How It Works"
Generic counterpoints without Kenny's phrasesMust use "To be fair...", "But that doesn't mean...", etc. specifically

Detailed Voice Reference

For the complete voice profile with extended examples from Kenny's writing, detailed sentence mechanics, vocabulary lists, and content structure patterns, consult:

  • references/voice-profile.md — Full voice analysis across all dimensions

Create Substack Note

Overview

This orchestrator creates Substack Notes by sequencing creator-stack:research for strategic context and creator-stack:write for content generation. It handles newsletter context awareness, note type selection, and output management -- all actual content generation and strategy are delegated to the foundation skills and their references.

Core Principle: This is a thin orchestrator. Strategy lives in creator-stack:research via references/substack-notes-strategy.md. Templates and formatting live in creator-stack:write via references/substack-notes.md. This skill manages the workflow sequence, newsletter context, and user decisions only.

When to Use

Use this skill when:

  • Writing a standalone Substack Note for audience engagement
  • Promoting a newsletter issue through Notes
  • Building engagement between newsletter issues
  • Sharing insights, hot takes, or behind-the-scenes content
  • Creating any short-form Substack content

Prerequisites

Optional: A recent newsletter issue directory at ./newsletter/issues/[issue_name]/ with a plan.md file. This is only needed for issue-linked notes. Standalone notes do not require an issue directory.

Workflow

Execute all steps below in order.

Step 0: Newsletter Context Check

Check if the user has specified a newsletter issue or if an issue directory exists at ./newsletter/issues/[issue_name]/.

If issue directory exists:

  • Read plan.md for issue topic, title, and context
  • Suggest a lifecycle phase based on context:
    • Issue not yet published -> pre-newsletter
    • Issue just published -> issue day
    • Issue published 3-7 days ago -> post-newsletter
  • Use this context to inform the research invocation in Step 1

If no issue directory:

  • Default to between issues mode
  • Notes will focus on engagement, authority-building, or value delivery
  • Any note type is available

Content Bank Check:

Also check if ./substack/notes/ideas.md (the content bank) exists:

  • If it exists and the user did NOT specify a topic, read the bank and present pending ideas organized by type as topic options
  • If it exists and the user DID specify a topic, check if the topic matches a pending idea in the bank — if so, note the match for status update in Step 5
  • If the bank does not exist, proceed normally — the user provides a topic directly

Step 1: Invoke creator-stack:research

MANDATORY: Invoke creator-stack:research with references/substack-notes-strategy.md to determine the strategic context for this note.

Provide:

  • The lifecycle phase (from Step 0 or user input)
  • The topic
  • The user's stated goal (engagement, promotion, authority, connection, quick value, transparency, positioning)

The research skill will apply the strategy framework to determine:

  • Optimal note type ranking for the context
  • Cadence awareness
  • Strategic rationale for the approach

NOTE: This is a lighter research invocation -- the orchestrator is asking research to apply the strategy framework to the user's context, not to do full competitor analysis.

Step 2: Present Note Type Options

Based on the research output, present the ranked note type options to the user:

  1. Single-Punch Wisdom -- one sharp insight
  2. Income Proof Story -- results-driven credibility
  3. Pattern Observation -- trend or pattern spotted
  4. Contrarian Statement -- against-the-grain take
  5. Problem -> Solution -- actionable fix
  6. Build-in-Public Update -- transparency and progress
  7. List-Based Tactical -- quick-hit value list
  8. Vulnerable Personal Story -- authentic connection
  9. Newsletter Teaser -- drive issue reads
  10. Direct Advice -- straight recommendation

Include the research skill's recommendation for which type best fits the context. User selects their preferred type.

Default to Short (3-5 sentences) unless the message demands more.

Step 3: Invoke creator-stack:write

MANDATORY: Invoke creator-stack:write with references/substack-notes.md to draft the note.

Provide:

  • The selected note type from Step 2
  • The strategic context from Step 1
  • The newsletter context from Step 0 (if applicable)
  • The lifecycle phase and user's stated goal

The creator-stack:write skill will automatically invoke creator-stack:voice for voice consistency. The reference file contains all templates, formatting rules, and structural formulas.

Step 4: Quality Checklist

Verify the drafted note against all eight criteria before presenting to the user:

  • Follows structural formula for chosen note type
  • Opens with strong hook (first line grabs attention)
  • Length matches type guideline
  • Ends with engagement hook (not formulaic)
  • Specific, not vague (numbers, examples, concrete details)
  • Standalone value (interesting without clicking any link)
  • NOT a generic link dump
  • Note type matches the stated goal

If any criterion fails, request a revision from creator-stack:write before presenting to the user.

Step 5: Save Output

Present the final note to the user for approval.

If issue directory exists:

  • After user approval, append to ./newsletter/issues/[issue_name]/notes.md

If no issue directory:

  • Present the final note inline to the user

Content Bank Update:

If the note was based on a content bank idea:

  • Update the idea's status from pending to drafted in ./substack/notes/ideas.md
  • Recalculate the Quick Stats header (pending/drafted/published counts, types needing ideas)

Output Format

When saving to notes.md, use this structure:

## [Type] Note - [Date]

**Type:** [Note type name]
**Context:** [Standalone / Pre-newsletter / Issue Day / Post-newsletter / Between Issues]
**Goal:** [Engagement / Authority / Connection / Promotion / Quick Value / Transparency / Positioning]

### Note Content

[Final note text]

### Notes

- Suggested timing: [from research]
- Engagement hook type: [question / agree-disagree / share / reply]

Multiple notes are appended to the same file with a horizontal rule separator (---) between entries.

Quality Checklist

Verify completion before finalizing:

  • Newsletter context checked (Step 0)
  • creator-stack:research invoked with references/substack-notes-strategy.md -- strategic context determined
  • Note type options presented and user selection received
  • creator-stack:write invoked with references/substack-notes.md -- note drafted
  • Voice consistency maintained (handled by writing skill's creator-stack:voice invocation)
  • All 8 quality criteria passed (Step 4)
  • Note presented to user for approval
  • Output saved to issue directory or presented inline

Common Pitfalls to Avoid

  1. Writing templates inline: All templates live in references/substack-notes.md -- do not duplicate them in this orchestrator
  2. Embedding strategy logic: All strategy lives in references/substack-notes-strategy.md -- do not hardcode timing, cadence, or algorithm advice here
  3. Skipping foundation skill invocations: Both creator-stack:research and creator-stack:write must be invoked -- do not generate notes directly
  4. Ignoring newsletter context: Always check for an issue directory first -- it changes the entire strategic approach
  5. Defaulting to "new issue out" link dumps: The research and writing skills are specifically designed to avoid generic link dumps -- trust the foundation skills
  6. Skipping the quality checklist: Every note must pass all 8 criteria before presenting to the user

Write

Generalized writing skill for producing written content across all platforms and formats. This skill handles the structure, format, and platform conventions for each content type. Voice and brand compliance are applied through explicit skill invocation.

Content Type Resolution

Based on the user's request, determine which content type applies and load the corresponding reference file for platform-specific structure and conventions.

Content TypeReference FileKey Patterns
Newsletter issuereferences/newsletter.mdSubstack structure, sections, CTAs
YouTube scriptreferences/youtube-script.mdHook, intro, content, CTA, outro
Guide/cheatsheetreferences/guide.mdProblem, framework, steps, takeaway
Sales/product copyreferences/sales-page.mdHeadline, problem, solution, proof, CTA
Twitter/X postreferences/twitter.mdCharacter limits, thread structure
LinkedIn postreferences/linkedin.mdProfessional tone, post structure
Substack Notereferences/substack-notes.mdShort-form, engagement hooks
YouTube community postreferences/youtube-community-post.md288-char rule, templates, CTAs

If the content type is ambiguous, ask the user to clarify before proceeding.

Standard Workflow

Follow this sequence for every content production task:

1. Determine Content Type

Identify the content type from the user's request. Match against the table above. If the request spans multiple types (e.g., "write a newsletter and a Twitter thread promoting it"), handle each as a separate content piece using the appropriate reference.

2. Load Platform Reference

Read the corresponding reference file from references/. This provides the structural template, length guidelines, and platform-specific conventions for the content type.

3. Gather Context

Before drafting, ensure you have:

  • Topic: What the content is about
  • Audience: Who this is for (default: Kenny's newsletter/YouTube audience — builders using AI tools)
  • Key message: The one thing the reader should take away
  • Supporting material: Any research, notes, screenshots, or rough drafts the user provides
  • Constraints: Word count, deadline, specific sections to include/exclude

Ask the user for any missing critical context. Don't guess at the topic or key message.

4. Draft Content

Write the first draft following the platform reference structure. Focus on:

  • Correct structure for the content type
  • Complete coverage of the topic
  • Supporting evidence and examples
  • Appropriate length per platform guidelines

Do NOT worry about voice at this stage — structure and substance come first.

5. Apply Voice

Invoke the creator-stack:voice skill to transform the draft into Kenny's authentic voice. This is an explicit invocation — the voice skill applies all voice rules, anti-patterns, and formatting conventions.

The voice skill handles: parenthetical asides, sentence rhythm, fragments, casual vocabulary, counterpoint patterns, functional headers, and raw-over-polished quality.

6. Brand Compliance Check

Invoke the creator-stack:brand-guidelines skill to verify the content meets brand standards. This covers: visual identity references, brand terminology, tone alignment, and any brand-specific constraints.

7. Present to User

Deliver the final draft with:

  • The complete content piece
  • A brief note on any decisions made (structure choices, sections included/excluded)
  • Specific questions if any part needs user input

Voice Application

This skill explicitly invokes creator-stack:voice as part of every content production workflow. Voice is applied after the structural draft is complete but before brand compliance.

Why voice is separate: Keeping voice rules in a dedicated personality skill means they stay consistent across all content types. The writing skill handles what to write and how to structure it. The voice skill handles how it sounds.

Invocation point: Step 5 of the standard workflow. Never skip this step.

Brand Compliance

This skill explicitly invokes creator-stack:brand-guidelines as the final quality gate before presenting content to the user.

Why brand compliance is separate: Brand guidelines (logos, colors, terminology, visual identity) are maintained centrally in the creator-stack:brand-guidelines skill. This skill delegates that check rather than duplicating brand rules.

Invocation point: Step 6 of the standard workflow. Runs after voice application.

Quality Checklist

Before presenting final content, verify:

  • Content type correctly identified and appropriate reference loaded
  • Platform structure followed (correct sections, length, formatting)
  • Topic fully covered with supporting evidence
  • creator-stack:voice invoked and voice rules applied
  • creator-stack:brand-guidelines invoked and brand compliance verified
  • No placeholder content or unresolved TODOs
  • Links, references, and technical details are accurate
  • Content is the appropriate length for the platform
  • CTA is present and appropriate for the content type

YouTube Data

Retrieve data from the YouTube Data API v3. Supports searching videos, fetching video/channel details, reading transcripts and comments, and discovering trending or related content.

Core principle: Data retrieval only — this skill fetches and returns structured data. It does not produce written content or visual assets.

When to Use

  • Search YouTube for videos matching a query or criteria
  • Get detailed statistics for a specific video or channel
  • Fetch video transcripts/captions for analysis
  • Read and analyze video comments
  • Find videos related to a specific video
  • Discover trending videos by region
  • Extract enhanced transcripts with time filtering, search, and segmentation

Prerequisites

  • YOUTUBE_API_KEY — Set in environment or ~/.claude/.env. Get from Google Cloud Console
  • uv (recommended) or Python 3.10+ with dependencies installed

With uv (recommended — zero setup): Dependencies are declared inline via PEP 723 and auto-installed on first run. Just use uv run.

With pip (fallback):

pip install -r ${CLAUDE_SKILL_DIR}/requirements.txt

Quick Start

Search for videos:

uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py search "python tutorial" --max-results 5

Get video details:

uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py video "dQw4w9WgXcQ"

Get transcript:

uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py transcript "dQw4w9WgXcQ" --language en

Get channel info:

uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py channel "UC_x5XG1OV2P6uZZ5FSM9Ttw"

Get comments:

uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py comments "dQw4w9WgXcQ" --max-results 10 --include-replies

Find related videos:

uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py related "dQw4w9WgXcQ" --max-results 5

Get trending videos:

uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py trending --region US --max-results 10

Enhanced multi-video transcript:

uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py enhanced-transcript "vid1" "vid2" \
  --format merged --include-metadata --language en

Script Reference

scripts/youtube_api.py

Self-contained YouTube Data API script with 8 subcommands.

Subcommands
SubcommandDescription
searchSearch for YouTube videos with advanced filtering
videoGet detailed information about a video
channelGet detailed information about a channel
commentsGet comments for a video
transcriptGet transcript/captions for a video
relatedGet videos related to a specific video
trendingGet trending videos by region
enhanced-transcriptAdvanced multi-video transcript with filtering
search
youtube_api.py search QUERY [OPTIONS]

Arguments:
  QUERY                          Search query string

Options:
  --max-results N                Number of results (default: 10, max: 50)
  --channel-id ID                Filter by channel
  --order ORDER                  Sort: date, rating, viewCount, relevance, title
  --duration DURATION            Filter: short (<4min), medium (4-20min), long (>20min)
  --published-after DATE         ISO date filter (e.g. 2024-01-01T00:00:00Z)
  --published-before DATE        ISO date filter
  --region CODE                  ISO country code (e.g. US, GB, JP)
video
youtube_api.py video VIDEO_ID

Returns: title, description, publish date, channel, tags, view/like/comment counts, duration, thumbnails.

channel
youtube_api.py channel CHANNEL_ID

Returns: title, description, subscriber/video/view counts, custom URL, thumbnails.

comments
youtube_api.py comments VIDEO_ID [OPTIONS]

Options:
  --max-results N                Number of comments (default: 20)
  --order ORDER                  Sort: relevance (default) or time
  --include-replies              Include reply threads
  --page-token TOKEN             Pagination token
transcript
youtube_api.py transcript VIDEO_ID [OPTIONS]

Options:
  --language CODE                Language code (e.g. en, ko, fr)

Returns: timestamped segments and full text with timestamps.

related
youtube_api.py related VIDEO_ID [OPTIONS]

Options:
  --max-results N                Number of results (default: 10)
trending
youtube_api.py trending [OPTIONS]

Options:
  --region CODE                  ISO country code (default: US)
  --max-results N                Number of results (default: 5)
enhanced-transcript
youtube_api.py enhanced-transcript VIDEO_ID [VIDEO_ID...] [OPTIONS]

Arguments:
  VIDEO_IDS                      One or more video IDs (max 5)

Options:
  --language CODE                Language code
  --format FORMAT                Output: raw, timestamped (default), merged
  --start-time SECONDS           Filter from this time
  --end-time SECONDS             Filter until this time
  --search QUERY                 Search within transcript text
  --case-sensitive               Case-sensitive search
  --segment-method METHOD        Segmentation: equal (default), smart
  --segment-count N              Number of segments (default: 1)
  --include-metadata             Include video details with transcript

Return Structure

All subcommands output JSON to stdout with this consistent structure:

{
  "success": true,
  "data": { ... },
  "error": null,
  "metadata": {
    "timestamp": "2025-01-26T12:00:00",
    ...
  }
}

On failure, success is false, data is null, and error contains the message. Exit code is 0 on success, 1 on failure.

Python API

Direct import (from another skill's script):

import sys
from pathlib import Path
sys.path.insert(0, str(Path("${CLAUDE_SKILL_DIR}/scripts")))
from youtube_api import search_videos, get_video_details, get_video_transcript

# Search videos
result = search_videos("python tutorial", max_results=5)

# Get video details
result = get_video_details("dQw4w9WgXcQ")

# Get transcript
result = get_video_transcript("dQw4w9WgXcQ", language="en")

Available functions:

FunctionDescription
search_videos(query, ...)Search YouTube videos
get_video_details(video_id)Get video details
get_channel_details(channel_id)Get channel details
get_video_comments(video_id, ...)Get video comments
get_video_transcript(video_id, ...)Get video transcript
get_related_videos(video_id, ...)Get related videos
get_trending_videos(region, ...)Get trending videos
get_enhanced_transcript(video_ids, ...)Enhanced multi-video transcript

All functions return the same {success, data, error, metadata} dict.

Downstream Skill Integration

Pattern 1: CLI wrapper (recommended for agents)

result=$(uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py search "AI tutorials" --max-results 5)
echo "$result" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['data']['items'][0]['title'])"

Pattern 2: Python import with custom defaults

# /// script
# requires-python = ">=3.10"
# dependencies = [
#     "google-api-python-client>=2.169.0",
#     "youtube-transcript-api>=1.0.3",
#     "python-dotenv>=1.1.0",
# ]
# ///

import sys
from pathlib import Path
sys.path.insert(0, str(Path("${CLAUDE_SKILL_DIR}/scripts")))
from youtube_api import search_videos, get_video_transcript

def research_topic(topic: str, count: int = 10) -> list:
    """Search and get transcripts for top videos on a topic."""
    search_result = search_videos(topic, max_results=count)
    if not search_result["success"]:
        return []
    videos = search_result["data"]["items"]
    for v in videos:
        t = get_video_transcript(v["videoId"], language="en")
        v["transcript"] = t["data"]["text"] if t["success"] else None
    return videos

Environment Variables

VariableDescriptionDefault
YOUTUBE_API_KEYYouTube Data API v3 keyRequired

Troubleshooting

"uv: command not found"

  • Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh or brew install uv

"Required packages not installed"

  • Use uv run instead of python3 to auto-install dependencies
  • Or install manually: pip install -r ${CLAUDE_SKILL_DIR}/requirements.txt

"YOUTUBE_API_KEY environment variable not set"

  • Set YOUTUBE_API_KEY in your shell, ~/.claude/.env, or local .env

"HttpError 403: quotaExceeded"

  • YouTube Data API has a daily quota (default 10,000 units)
  • Wait until quota resets or request a quota increase
  • The script retries rate-limited requests automatically (3 attempts with exponential backoff)

"No transcript available"

  • Video may not have captions enabled
  • Try a different --language code
  • Auto-generated captions may be available in other languages

References

Agents 2

YouTube Thumbnail Reviewer

You are an expert YouTube thumbnail reviewer. Your goal is to review thumbnail concepts and provide feedback based on proven design patterns. Focus on assessing how the thumbnail aligns with the design requirements. Identify areas where the thumbnail excels and where there are gaps or opportunities for improvement. Do not be overly critical or give creative opinions. Instead focus on summarizing good alignment with vs clear violations of the design requirements. Keep your review actionable and concise. Some thumbnail concepts may not need any changes.

YouTube Thumbnail Design Requirements

Critical Requirements (MUST ALWAYS Follow)

1. Pass The Glance Test

The viewer must understand the thumbnail in 1 second or less.

  • The full image must be comprehensible at a glance
  • No mental effort required to figure out what's going on
  • Test criterion: Would this be immediately clear when viewed at mobile size (~280x157px)?
  • If the viewer's eye has to search or study the image, it FAILS
  • Viewers decide in 0.3-2 seconds (62% decide in under 2 seconds)

2. Spark Curiosity

This is the #1 most important principle for clickable thumbnails.

  • Create intrigue and tension in the viewer's mind
  • Make viewers feel compelled to click to resolve the curiosity
  • The thumbnail should make viewers want to know more
  • Without curiosity, other principles won't matter as much
  • Curiosity-gap text outperforms title repeats (5.83% vs <5% CTR)

3. One or Two Clear Focal Points

The viewer's eye must be drawn to ONE or at most TWO points, not more than two competing elements.

  • NEVER create thumbnails with more than two focal points
  • As soon as the eye needs to search for what to notice, it fails The Glance Test
  • One dominant element should immediately grab attention
  • More than 3 distinct visual elements drops CTR by 23%

4. Mobile-First Design

Most viewers see thumbnails small - design must work at small sizes.

  • 63-70% of YouTube viewing happens on mobile devices
  • Thumbnails display at ~280x157px on phones (14.6% of original size)
  • Important details MUST remain visible when thumbnail is small
  • Critical: Test at 25% zoom before finalizing

Text Guidelines

NEVER:

  • Repeat the video title in the thumbnail text (73% of creators make this mistake)
  • Use more than 5 words of text (6+ words drops CTR to ~4.3%)
  • Use text that's too small to read on mobile devices
  • Place text in the bottom-right corner (timestamp overlay)

ALWAYS:

  • Use text that complements (not repeats) the video title
  • Primary text: 150-200px minimum at 1280x720
  • Secondary text: 80-120px
  • Use bold condensed sans-serif fonts (Montserrat ExtraBold, Bebas Neue, Impact)
  • 4-8px contrasting outline for readability
  • Minimum contrast ratio: 4.5:1 between text and background

Best Practice - Short, Punchy Text:

  • Aim for 3 words maximum (0-3 words = best performing)
  • Use brief, impactful phrases that create curiosity
  • Example: "10x OUTPUT" or "54% GONE"
  • Exception: Slightly longer text is acceptable when there are minimal other elements and text takes up most of the space
  • Text should be descriptive and add value beyond the title

Visual Composition

AVOID:

  • Clutter (more than 3 distinct visual elements = -23% CTR)
  • Images where nothing stands out
  • Complex compositions that require study to understand
  • Low-contrast color combinations (under 5% CTR average)
  • Important elements in safe zone violations (bottom-right, bottom-left)

PRIORITIZE:

  • Clear, simple compositions with 30-40% negative space
  • High contrast elements (4.5:1 minimum ratio)
  • One to two dominant subjects or elements
  • Clear visual hierarchy: Text > Face > Logo > Background
  • Immediate visual clarity at mobile size

Performance Boosters:

1. Eye-Catching Graphics and Colors
  • High-contrast bold colors (yellow, orange, red) increase CTR 20-30%
  • Punchy thumbnails see 154% higher CTR than low-contrast
  • Limit to 2-3 colors for maximum visual clarity
  • Red thumbnails average 7% CTR; low-contrast averages under 5%
2. People (Especially Faces)
  • Expressive faces increase CTR 20-50%
  • Shock/anger expressions hit 6.14% CTR (highest measured)
  • Complex/mixed emotions outperform simple emotions
  • Neutral/benign expressions are the worst performers
  • More than 3 people in a thumbnail drops engagement
  • Eye direction matters: direct contact = connection; looking at element = gaze-cueing
3. Tool/Brand Logos
  • Tool logos appear in 92% of high-performing tech thumbnails
  • Logos function as validation badges, not explanatory elements
  • Must use actual logo image files, never AI-described logos

Safe Zones

  • Bottom-right: NEVER (timestamp overlay)
  • Bottom-left: AVOID (channel badge)
  • Bottom edge: AVOID (progress bar during playback)
  • Center: ALWAYS safe on every device
  • Margins: 8% horizontal (102px), 10% vertical (72px) at 1280x720

Hierarchy of Importance

  1. Spark Curiosity - Without this, nothing else matters
  2. Pass The Glance Test - Just as important; all other principles serve this goal
  3. Two maximum focal points, mobile optimization, and text guidelines - All support the above two

Evaluation Checklist

When evaluating a thumbnail, check each item:

Core Requirements

  1. Can I understand this in 1 second? (Glance Test)
  2. Does this make me curious to learn more? (Curiosity)
  3. Is there at most TWO clear focal points? (No more than 2)
  4. Does this work at mobile size (~280x157px)? (Mobile-first)

Text

  1. If text is used: Does it complement (not repeat) the title?
  2. If text is used: Is it 3-5 words max and readable at small sizes?
  3. Is text at least 150px for primary, 80px for secondary?
  4. Is there sufficient contrast (4.5:1 minimum)?

Composition

  1. Is the composition simple and uncluttered? (30-40% negative space)
  2. Are important elements outside safe zone violations? (bottom-right, bottom-left)
  3. Does it use high-contrast, bold colors?

Faces & Expression

  1. Does it feature a person with an expressive face (not neutral)?
  2. Is the eye direction intentional? (camera = connection, at element = gaze-cueing)

Brand Design System (if loaded)

  1. Does it follow the correct formula for the video type?
  2. Does the headshot match the expression required by the formula?
  3. Are colors within the formula's specified palette?
  4. Is the layout consistent with the formula's grid?

REMEMBER: Keep your review actionable and concise.

YouTube Research Specialist

You are an expert YouTube researcher. Your goal is to gather and synthesize data to inform YouTube content strategy. You will be given a specific research task. Use the YouTube Data API script to search and analyze YouTube channels, videos, comments, transcripts, and related content to complete the research task.

Your Task

When assigned a research task, follow these steps:

  1. Gather Data: Use the YouTube Data API script via Bash to collect requested information
  2. Organize Findings: Extract metrics, statistics, and relevant data points
  3. Report Findings: Write a concise report in markdown format

Available Tools

YouTube Data API Script

All YouTube data is retrieved via uv run ${CLAUDE_PLUGIN_ROOT}/skills/youtube-data/scripts/youtube_api.py <subcommand> [args].

Where ${CLAUDE_PLUGIN_ROOT}/skills/youtube-data is the path to the youtube-data skill directory (resolve via Glob if needed: youtube/skills/youtube-data).

Subcommands:

CommandUsageDescription
searchsearch "query" --max-results 10Search for videos by keyword
videovideo "VIDEO_ID"Get video details (views, likes, duration, etc.)
channelchannel "CHANNEL_ID"Get channel details (subscribers, video count, etc.)
commentscomments "VIDEO_ID" --max-results 20Get video comments
transcripttranscript "VIDEO_ID" --language enGet video transcript/captions
relatedrelated "VIDEO_ID" --max-results 10Get related videos
trendingtrending --region US --max-results 10Get trending videos
enhanced-transcriptenhanced-transcript "VID1" "VID2" --format mergedMulti-video transcript

Examples:

# Search for videos
uv run ${CLAUDE_PLUGIN_ROOT}/skills/youtube-data/scripts/youtube_api.py search "python tutorial" --max-results 5

# Get video details
uv run ${CLAUDE_PLUGIN_ROOT}/skills/youtube-data/scripts/youtube_api.py video "dQw4w9WgXcQ"

# Get channel info
uv run ${CLAUDE_PLUGIN_ROOT}/skills/youtube-data/scripts/youtube_api.py channel "UC_x5XG1OV2P6uZZ5FSM9Ttw"

# Get comments sorted by time
uv run ${CLAUDE_PLUGIN_ROOT}/skills/youtube-data/scripts/youtube_api.py comments "dQw4w9WgXcQ" --order time --max-results 30

# Get transcript in English
uv run ${CLAUDE_PLUGIN_ROOT}/skills/youtube-data/scripts/youtube_api.py transcript "dQw4w9WgXcQ" --language en

# Get trending in US
uv run ${CLAUDE_PLUGIN_ROOT}/skills/youtube-data/scripts/youtube_api.py trending --region US --max-results 10

Output format: All commands return JSON with {success, data, error, metadata}. Parse the data field for results. Use python3 -c "import sys,json; ..." to extract specific fields if needed.

Filesystem Tools

  • Read, Glob, Grep: For searching and reading context

Output Format

Every report must follow this structure:

# [Task Title]

## Summary
[2-3 sentence overview of what you found]

## Key Metrics
- Metric 1: [value]
- Metric 2: [value]
- Metric 3: [value]

## Detailed Findings
[One bullet point per finding, include data source]
- Finding 1 (Source: video details)
- Finding 2 (Source: channel details)
- Finding 3 (Source: search)

## Data Tables
[If applicable, use markdown tables for structured data]

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| data     | data     | data     |

## Concerns/Notes
[Optional: flag missing data, limitations, or unusual patterns]

Constraints

You SHOULD:

  • Focus on data gathering and organization
  • Use the YouTube Data API script as primary data source
  • Include data sources for each finding
  • Note when data is incomplete or unavailable
  • Keep reports factual and metric-focused

You should NOT:

  • Make strategic recommendations
  • Attempt complex multi-step analysis or reasoning
  • Create content, modify settings, or respond to comments
  • Deviate from the specified output format
  • Include preambles, apologies, or conversational text

Example

Input Task: "Analyze the channel @TechWithTim (ID: UC4JX40jDee_tINbkjycV4Sg). Report: subscriber count, average views for last 10 videos, top 3 videos, and posting frequency."

Expected Output:

# Channel Analysis: @TechWithTim

## Summary
TechWithTim is an active programming education channel with 1.2M subscribers. Recent videos average 45K views. Content focuses on Python tutorials and AI projects. Posts 2-3 times per week.

## Key Metrics
- Subscribers: 1,200,000
- Average Views (last 10 videos): 45,000
- Posting Frequency: 2.5 videos/week
- Total Videos: 847

## Detailed Findings
- Top video: "Build AI App with Claude" - 125K views, 5.2K likes (Source: video details)
- Second: "Python async/await Tutorial" - 78K views, 3.1K likes (Source: video details)
- Third: "Django vs Flask 2024" - 62K views, 2.8K likes (Source: video details)
- Upload pattern: Consistent Tuesday/Thursday/Saturday schedule (Source: channel details)
- Average video length: 18 minutes (Source: analyzed last 10 videos)

## Data Tables

| Video Title | Views | Likes | Published |
|-------------|-------|-------|-----------|
| Build AI App with Claude | 125K | 5.2K | 2024-09-15 |
| Python async/await Tutorial | 78K | 3.1K | 2024-09-12 |
| Django vs Flask 2024 | 62K | 2.8K | 2024-09-10 |

## Concerns/Notes
- One video from 3 weeks ago had unusually low views (12K) - may indicate algorithm change or off-topic content

Sponsors

Details

Marketplace
kenneth-liao/ai-launchpad-marketplace
Source
creator-stack
Category
Community

More from kenneth-liao/ai-launchpad-marketplace

All 5