| name | newsletter-visuals |
| description | Audit a newsletter draft for visual opportunities and generate on-brand visual assets. Use when enhancing a newsletter draft with visuals, when a draft has [screenshot] placeholders, or when the user says 'add visuals', 'create images for this issue', 'make this more visual', or 'add diagrams to the newsletter'. |
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 Type | Reference File | Key Focus |
|---|
| Substack newsletter | references/substack-constraints.md | Aspect 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:
- 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.
- Complexity — Is the concept hard to explain in text alone? (process flows, architectures, comparisons, data)
- Engagement risk — Is this a point where readers are likely to disengage? (long text-only stretches, dense technical explanations)
- 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):
| Dimension | 1 (Low) | 5 (High) |
|---|
| Clarity lift | Text explains it fine | Text alone is confusing or requires re-reading |
| Engagement lift | Section is already engaging | Long text-only stretch, reader likely to skim past |
| Uniqueness | Generic/decorative visual | Visual 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 Type | Use When | Examples |
|---|
| Conceptual diagram | Explaining a process, architecture, or flow | Flowcharts, swimlane diagrams, network diagrams |
| Comparison visual | Showing differences between two or more things | Side-by-side layouts, before/after |
| Data visualization | Making numbers or ratios tangible | Bar charts, token cost comparisons |
| Custom illustration | Engaging the reader emotionally or setting context | Hero images, conceptual metaphors |
| Annotated screenshot | Adding context to an existing UI capture | Callout 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:
- Location — Exact section and paragraph
- Type — Which visual type
- Purpose — What it clarifies, persuades, or engages (one sentence)
- Description — What the visual shows (the concept, not the generation prompt)
- 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:
- Caption — 1 sentence that adds context the image doesn't show. Good captions answer "so what?" — they don't just describe what's visible.
- 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
Common Pitfalls
- Too many visuals (6+): Cap at 5. Force-rank by score. Fewer high-impact visuals beat many mediocre ones.
- Decorative hero image: Only include a hero if it scores 10+. Most newsletters don't need one.
- Inventing data: Only visualize data the author provides. Never fabricate statistics.
- Replacing screenshots without asking: Screenshots are the author's real evidence. Only suggest replacing with explicit justification.
- Ignoring the design system: Every prompt must reference the design system. No making up colors or styles.
- Dark-themed images for email: Default to light backgrounds. Dark images look broken in most email clients.
- Text-heavy images: Minimize text in generated images. Put text in captions instead.
- Generating before brief approval: Always present the brief first. Wasted assets cost time and API credits.
- Using illustrations where diagrams belong: If the goal is clarity, use a diagram. Illustrations are for engagement.
