| name | newsletter-builder |
| description | Creates complete newsletters from editorial brief to final visual layout, planning content in Notion and generating the designed version in Canva. Use when a user needs to produce a recurring newsletter issue, build a newsletter from scratch, or transform raw ideas into a polished send-ready newsletter. |
| allowed-tools | Read Write Glob mcp__claude_ai_Notion__notion-create-pages mcp__claude_ai_Notion__notion-search mcp__claude_ai_Notion__notion-fetch mcp__claude_ai_Canva__generate-design-structured mcp__claude_ai_Canva__list-brand-kits mcp__claude_ai_Canva__export-design mcp__claude_ai_Canva__get-export-formats mcp__claude_ai_Canva__get-design-thumbnail |
| metadata | {"author":"matthewhitcham","version":"1.0"} |
Newsletter Builder
When to Use This Skill
Use this skill when you need to:
- Produce a recurring newsletter issue from topic to send-ready output
- Build a new newsletter from scratch with structure, content, and visual design
- Transform raw notes or ideas into a polished newsletter with a designed layout
- Create both plain-text and visually designed PDF versions of a newsletter
DO NOT use for one-off promotional emails, social media content, or blog posts.
Core Principle
EVERY NEWSLETTER EARNS ITS OPEN WITH THE SUBJECT LINE, EARNS ITS READ WITH THE INTRO HOOK, AND EARNS ITS CLICK WITH ONE CLEAR CTA — IF ANY OF THESE THREE FAIL, THE NEWSLETTER FAILS.
Newsletter Structure Template
SUBJECT LINE: [Curiosity gap or specific benefit — under 50 chars]
PREVIEW TEXT: [Expands on subject — 40-90 chars, visible in inbox]
── HEADER ── Newsletter name, issue number, date
── INTRO HOOK ── 2-3 sentences. Bold claim, story beat, or question.
── SECTION 1 ── 200-300 words. Primary topic. Deepest value.
── SECTION 2 ── 150-250 words. Supporting angle or practical application.
── SECTION 3 ── 3-5 bullet points. Quick hits, links, tools. (optional)
── CTA ── One clear ask. Direct sentence, not buried in a paragraph.
── SIGN-OFF ── 1-2 personal sentences. First-name basis.
── FOOTER ── Unsubscribe placeholder, social links, legal line.
Phase 1: Editorial Brief
Collect before writing anything:
- Newsletter name — brand name (e.g., "The Growth Wire")
- Issue topic — theme for this issue
- Target audience — who reads it and what they care about
- Tone — casual, professional, witty, conversational (default: conversational)
- Sections — how many body sections (default: 2 + quick hits)
- Primary CTA — the one action readers should take
- Key links — any URLs, tools, or resources to include
- Recurring elements — standing segments (e.g., "Tool of the Week")
If the user provides items 1, 2, and 6, proceed with defaults for the rest.
Brief template for vague requests:
I'll build your newsletter. Quick details needed:
1. Newsletter name?
2. What's this issue about?
3. Who's your audience?
4. Tone? (default: conversational)
5. How many sections? (default: 2 + quick hits)
6. What's the ONE thing you want readers to do after reading?
7. Any links or resources to include?
8. Any recurring segments?
Compile into a structured brief:
## Editorial Brief — "The Growth Wire: Why Most Funnels Leak"
Newsletter: The Growth Wire
Audience: Solo founders and early-stage SaaS operators
Tone: Conversational, data-backed
Sections: Intro + 2 body + quick hits + CTA
CTA: Reply with their biggest funnel question
Links: [link1], [link2]
Recurring: "Tool of the Week" in quick hits
GATE: Present the editorial brief. Do not proceed until the user confirms or adjusts.
Phase 2: Write Content
Write the full newsletter following the structure template.
-
Subject line and preview text — provide 2 subject line options. Subject: curiosity gap or specific number, under 50 chars. Preview: expands on subject, 40-90 chars.
-
Intro hook (2-3 sentences) — open with a surprising stat, short story, or direct question. End by telling readers what they get from this issue.
-
Body sections:
- Section 1 (Primary): 200-300 words. Must include a specific example, number, or case study. Never abstract advice alone.
- Section 2 (Supporting): 150-250 words. Different angle, practical application, or contrarian take. Must feel distinct from Section 1.
- Section 3 (Quick Hits): 3-5 bullets with bolded lead-ins. Under 30 seconds to scan.
-
CTA section — one sentence, framed as a benefit to the reader. Example: "Hit reply and tell me your biggest funnel question — I'll answer the best ones next week."
-
Sign-off — 1-2 sentences. Example: "Talk next Tuesday. — Matt"
Save Brief to Notion
After writing, save the editorial brief:
- Call
notion-search for "Newsletter," "Editorial," or the newsletter name
- If found, call
notion-create-pages with title "{Newsletter} — {Topic}", content including topic, audience, tone, CTA, subject line, and status "Draft"
- If no database found, create a standalone page with the full brief in the body
GATE: Present the full newsletter copy. Do not proceed until approved. Maximum 3 revision rounds.
Phase 3: Design in Canva
Step 1: Load Brand Kit
- Call
list-brand-kits to retrieve kits
- Present names if multiple exist — let user choose
- Note brand colors, fonts, and logo for the design prompt
IF NO BRAND KIT: Ask for primary color, secondary color, and font preference. Embed directly in generation prompt.
Step 2: Generate Layout
Build a structured prompt including:
- Newsletter name and issue identifier
- All section headings and body text from approved copy
- Brand colors, fonts, and style
- Layout: single-column, 600px width, mobile-friendly
- CTA styled as a button or highlighted block
Example design prompt:
Professional email newsletter layout, single column, 600px width.
Newsletter: "The Growth Wire" — Issue #14
Header: Name with logo area, issue number, date. Color accent bar #F4A261.
Body: White background, #1A3D5C text. Section dividers between blocks.
Section 1: "The Three Places Every Funnel Breaks" — 200-300 words.
Section 2: "The Fix That Takes 20 Minutes" — 150-250 words.
Section 3: "Quick Hits" — 3-5 bullet items.
CTA button: #F4A261 background, white text.
Footer: Light gray, unsubscribe placeholder.
Font: Inter Bold headings, Inter Regular body. Clean, generous whitespace.
- Call
generate-design-structured with the prompt
- Call
get-design-thumbnail to preview
- Present thumbnail: "Does this look good, or would you like adjustments?"
- Wait for approval before exporting
IF DESIGN MISSES: Regenerate with adjusted prompt. Maximum 2 attempts. After 2, ask user for a reference image or specific layout description.
Phase 4: Export and Deliver
Step 1: Export PDF
- Call
get-export-formats to confirm formats
- Call
export-design with format pdf (default — preserves layout)
- Collect the export URL
Step 2: Save Plain-Text Version
Save as markdown to newsletter-output/{name}-{topic}.md (all lowercase, hyphens). Include subject line, preview text, all sections, CTA, sign-off, footer.
Step 3: Update Notion
Call notion-search to find the brief page, then notion-fetch for the page ID. Update status to "Designed" if supported, or add a note to the page body.
Step 4: Deliver
Newsletter complete: "The Growth Wire — Issue #14: Why Most Funnels Leak"
PLAIN-TEXT: newsletter-output/the-growth-wire-why-most-funnels-leak.md
DESIGNED PDF: [export URL] | Design ID: dsg_nl789abc
NOTION: "The Growth Wire — Why Most Funnels Leak" — Status: Designed
Subject: "Why most funnels leak (and a 20-min fix)"
Preview: "Plus 5 tools I found this week that actually help."
Example 1: Weekly Business Tips Newsletter
User: "I run 'Solo Ops' for solopreneurs. This week: 3 automations that saved me 10 hours. CTA: reply with their most time-consuming task. Casual tone."
Phase 1: Brief confirmed — Solo Ops, solopreneurs, casual/practical, 2 sections + quick hits.
Phase 2: Subject line options: A) "3 automations that gave me 10 hours back" B) "I automated my way out of busywork" — user picks A. Preview: "No code required. Just 3 tools and 30 minutes of setup."
Newsletter written:
- Intro hook: tracked tasks for a week, found 10 hours of automatable work
- Section 1 (280 words): three automations — client onboarding via Zapier (saved 3 hrs/mo), invoice reminders via Stripe (collections 82% to 96%), social scheduling via Buffer (saved 4 hrs/wk). Total setup: 90 minutes.
- Section 2 (180 words): why solopreneurs do not automate — the "I'll just do it quick" trap. Fix: track time for one week, automate top 3 by hours spent.
- Quick hits: Zapier vs Make comparison, HubSpot free CRM, podcast rec, quote of the week
- CTA: "Hit reply — what task eats most of your time?"
Notion page created: "Solo Ops — 3 Automations That Saved Me 10 Hours" (Draft).
Phase 3: Brand kit "Solo Ops" loaded (#222831 primary, #00ADB5 secondary, Space Grotesk). Design generated — dark header, teal accents, teal CTA button. User approves.
Phase 4: PDF exported. Plain-text saved to newsletter-output/solo-ops-3-automations-saved-10-hours.md. Notion status updated to "Designed."
Example 2: Monthly Product Update Newsletter
User: "Monthly product update called 'Buildlog' for paying customers. Shipped new dashboard, fixed export bug, launching beta for team collaboration. CTA: sign up for beta. Professional but friendly."
Phase 1: Brief confirmed — Buildlog, paying SaaS customers, professional-friendly, 3 sections (feature + fixes + beta). User provides beta URL.
Phase 2: Subject: "New dashboard is live + beta invite inside." Preview: "Plus we finally squashed that export bug."
Newsletter written:
- Intro hook: big build month — dashboard live, export bug gone, beta launching
- Section 1 (250 words): new analytics dashboard — real-time data (30-sec updates), custom date ranges, drag-and-drop widget layout
- Section 2 (150 words): bug fixes — CSV export UTF-8 fix, notification latency reduced to <15s, mobile sidebar overlap resolved
- Section 3 (200 words): team collaboration beta — shared workspaces with roles, comment threads with @mentions, activity audit log. First 500 spots.
- CTA: "Sign up for the beta — first 500 spots, no credit card required."
User approves after one edit (changed beta limit 200 to 500). Notion page created.
Phase 3: Brand kit "Buildlog" loaded (#0F172A, #3B82F6, #10B981, IBM Plex Sans). Design: dark header, blue accent, green CTA button. Approved.
Phase 4: PDF exported. Plain-text saved. Notion updated.
Anti-Patterns
- Walls of text — no paragraph over 4 lines. Readers scan, they do not read newsletters like articles.
- Skipping the CTA — every issue needs exactly one clear call to action. "Hope you enjoyed this" is not a CTA.
- Same-length sections — vary lengths (long, medium, scannable). Uniform 200-word sections feel monotonous.
- Generic subject lines — "Monthly Update" or "Newsletter #14" will not get opened. Create curiosity or promise a specific benefit.
- Burying the best content — strongest section goes first. Readers drop off after the intro.
- Multiple CTAs — "Reply AND follow AND check this link AND sign up." Pick one.
- No preview text — blank preview pulls "View in browser" or header code. Always write custom preview text.
- Writing for everyone — a newsletter for "anyone in business" is for no one. Each issue speaks to a specific reader with a specific problem.
Recovery
Notion search finds nothing: Ask user for a Notion page URL or create a standalone page. Notion is for records, not a blocker.
Notion page creation fails: Retry once simplified (title + plain text only). If still fails, save brief locally to newsletter-output/{name}-brief.md. Continue to Phase 3.
No Canva brand kit: Ask for primary color, secondary color, font preference. Embed in prompt. Suggest creating a brand kit for future issues.
Canva design generation fails: Simplify prompt (headline + colors + CTA only), retry once. If 2 attempts fail: deliver plain-text only and suggest manual Canva template.
Canva export fails: Verify design ID via get-design-thumbnail. Try PNG instead of PDF. If both fail, provide design ID for manual export from canva.com.
Custom sections requested: Add between last body section and CTA. Same length guidelines (100-250 words or 3-5 bullets). Include in Canva prompt.
If 3 attempts at any step fail: Stop and deliver what is complete. Brief only, plain-text only, or plain-text + brief without design. Explain which step failed.
Pre-Delivery Checklist
| Check | Verify |
|---|
| Subject line under 50 chars | Mobile inboxes truncate aggressively |
| Preview text written | Never blank or defaulted |
| Intro hook 2-3 sentences | Not a paragraph, not a single line |
| Clear heading on every section | Readers scan headings first |
| Section lengths vary | Mix long, medium, scannable |
| Exactly one CTA | Not zero, not three |
| CTA framed as reader benefit | "Get X" not "Help me by doing X" |
| No section over 300 words | Newsletters are not blog posts |
| Plain-text file saved | Pasteable into any email platform |
| Notion brief saved | Editorial record for future reference |
| Canva design approved | Thumbnail shown and confirmed |
| PDF exported | Designed version ready for sharing |
