newsletter
Write publication-ready newsletter editions, roundup, deep-dive, personal essay, curated links, news briefing, or hybrid, in the brand's voice, sourced from live pages, and informed by the list's own click data when an ESP key exists. Use it to draft an edition, pick a format, or answer newsletter strategy questions (platform, growth, monetization).
boringmarketer · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add boringmarketer/boring-marketing-skills --skill newsletterAbout this skill
name: newsletter description: Write publication-ready newsletter editions, roundup, deep-dive, personal essay, curated links, news briefing, or hybrid, in the brand's voice, sourced from live pages, and informed by the list's own click data when an ESP key exists. Use it to draft an edition, pick a format, or answer newsletter strategy questions (platform, growth, monetization). when_to_use: write my newsletter, newsletter edition about X, weekly roundup, news briefing on X, curated links edition, draft this week's edition, newsletter format, newsletter strategy, newsletter monetization, which newsletter platform argument-hint: "[topic, or 'strategy: '; optionally an archetype name]" metadata: boring: version: 4.1.1 layer: execution reads: [voice-profile, audience#segments, audience#desires-buying-triggers, learnings] writes: [] optional-keys: [BEEHIIV_API_KEY, BEEHIIV_PUBLICATION_ID, KIT_API_KEY, GHOST_ADMIN_API_KEY, GHOST_URL, EXA_API_KEY, FIRECRAWL_API_KEY]
Newsletter
Write the edition a subscriber would miss if it didn't arrive. Done means a publication-ready draft saved to disk: subject lines deduped against the list's own history, every cited source actually fetched, structure from a deliberate archetype, voice from the brand's voice profile, never from a template. The judgment: which archetype fits the job, which sources deserve a reader's click, and what the list's own click data says to do differently. This is the floor, not the ceiling. When the situation argues for a better path, take it and say why.
Context
Only if ./brand/, ./brands/ or MARKETING.md exists (nothing to load otherwise), run:
python3 ${CLAUDE_SKILL_DIR}/../start-here/scripts/brand_context.py --for newsletter
(If the script or python3 is unavailable, read the files named in reads: directly,
section-anchored where specified. If none exist, proceed standalone: ask only for what the
task strictly requires.)
The Segments and Desires & Buying Triggers sections are the read that matters.
The job is knowing what this list cares about and how sophisticated it is. If
./campaigns/newsletters/ exists, list the last 3 editions (filenames + first heading + opening
line, ignoring the notes/ subfolder); they feed subject dedup and the anti-template check
in Phase 4.
Modes
- Edition (default): Phases 1-5. The actual job.
- Strategy question ("which platform", "how do I monetize", "growth ideas"): load
references/newsletter-strategy.md(refresh if past TTL), answer directly from it plus the brand context, and stop. No edition-phase walkthrough, no quoting its illustrative numbers as guarantees. - Format design ("help me design my newsletter", "what should my format be"): define the
recurring format once so every future edition starts from it. Pick the archetype (Phase 1
judgment +
references/archetype-patterns.md), then write./campaigns/newsletters/format.md: the reader promise in one sentence, archetype, the recurring sections and each one's job, cadence, target length, and the one CTA type. Future edition runs read this file as the brief's starting point; the anti-template check treats its sections as fixed and everything sentence-level as variable. - Quick Mode: the user pastes content and says "turn this into my newsletter" → pick the obvious archetype, skip sourcing, draft, gate, save. Deliver, then a one-line what's-next.
Phase 1. Archetype and brief
Load references/archetype-patterns.md before structuring anything. If
./campaigns/newsletters/format.md exists, it sets the default archetype and section anatomy:
deviate only when the user asks or the edition's job genuinely doesn't fit it.
Pick the archetype from the job this edition does for the reader, not from habit:
| The edition's job | Archetype |
|---|---|
| Catch readers up on what mattered in the niche this week | roundup |
| Teach one thing thoroughly enough to act on | deep-dive |
| Build the relationship; say the thing only this writer can say | personal-essay |
| Save readers hours of filtering; taste is the product | curated-links |
| Daily/fast-cycle "what happened + why it matters" | news-briefing |
| One original idea plus the week's worth-knowing links | hybrid |
If the user named an archetype, use it. If their past editions are consistently one archetype, default to it: format consistency is a retention asset; switching formats is a decision the user makes, not a variety bonus.
The voice rule: the archetype supplies structure: section jobs, ratio, pacing. The voice
comes from voice-profile.md, never from the archetype. No stock openers, greeting formulas,
sign-off personas, or emoji conventions unless the voice profile itself contains them. If
there is no voice profile, write in plain, specific, first-person prose and say so: do not
substitute a famous newsletter's voice.
Confirm a 3-line brief before drafting (skip in Quick Mode): topic + angle, archetype + why, target length from the archetype's band. One confirmation, not an interview.
Phase 2. The list's own data
Newsletters are the one channel where the customer's real numbers are usually one API call away. Use them.
If BEEHIIV_API_KEY, KIT_API_KEY, or GHOST_ADMIN_API_KEY (with GHOST_URL) is set
(check .env and the environment directly; the shared capability check doesn't list Ghost),
pull the last 5-10 sends' stats: subject line, send date, recipients, opens, total clicks,
and per-link clicks where the API exposes them. Endpoint shapes live in
references/newsletter-strategy.md → "ESP API notes" (dated; refresh per its header). If the
call fails, say so in one line in the note and continue without it. Never block the edition
on an API.
How to read the numbers:
- Clicks are the truth. Apple MPP auto-fires opens, so open rate is a direction-only proxy. Rank past editions by CTR and clicks-per-link; never conclude anything from opens alone, an