Skip to main content
skill CX Codex

Newsletter · boringmarketer — Claude Code skill: what it does, how to install

The newsletter skill for Claude Code drafts publication-ready content and assists with newsletter strategy. It adapts to brand voice while using ESP click data to optimize subscriber engagement.

MIT ★ 778 updated 2026-11-16

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add boringmarketer/boring-marketing-skills
/plugin install boring-marketing@boring-marketing-skills
Open on GitHub

What newsletter does

This skill generates newsletter editions, deep-dive articles, and curated roundups tailored to a specific brand voice. It scans existing campaigns within ./campaigns/newsletters/ to prevent content overlap and selects an appropriate structure based on predefined archetypes. Integrating API keys from services like Beehiiv, Kit, or Ghost enhances performance with real click-data analysis.

If specific brand context files are missing, the agent requests necessary information during execution. The process covers everything from initial brief confirmation and archetype selection to subject line deduplication and link-performance analysis. Without API access or existing brand files, the tool operates as a standalone drafting assistant.

What it helps with

  • selecting newsletter archetypes
  • analyzing link click-through rates
  • drafting publication-ready content
  • auditing growth strategies
  • structuring recurring newsletter formats

Example prompts for the agent

  • Write a weekly roundup about AI coding
  • How do I monetize my newsletter?
  • Help me design my newsletter format

How to install newsletter

1Plugin marketplace

/plugin marketplace add boringmarketer/boring-marketing-skills
/plugin install boring-marketing@boring-marketing-skills

This installs the whole boring-marketing plugin with all its skills

2Skills CLI (Vercel)

npx skills add boringmarketer/boring-marketing-skills --skill newsletter -a claude-code

3Manually: put the files in place

~/.claude/skills/newsletter/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/newsletter/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about newsletter

How to install newsletter in Claude Code?

Run the command npx skills add boringmarketer/boring-marketing-skills --skill newsletter -a claude-code in your terminal.

What does newsletter do?

It generates newsletter drafts based on your brand voice, chosen archetypes, and historical campaign data.

What is required for newsletter to work?

You need context files in ./brand/ or ./campaigns/newsletters/ and optionally BEEHIIV_API_KEY, KIT_API_KEY, or GHOST_ADMIN_API_KEY with GHOST_URL.

Source text

SKILL.md · MIT
---
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: <question>'; 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, and
  never recommend a subject-line test that's judged on opens.
- **Per-link clicks tell you what the list actually wants.** If the tool links out-click the
  essays 3:1, the curation is carrying the edition: weight the draft accordingly (one line in
the note).
- **Subject-line dedup:** collect the last 10-20 subjects (API history plus
  `./campaigns/newsletters/` metadata). No new variant may reuse a prior subject's structure
  AND topic. Same formula on a new topic is fine; same formula on an adjacent topic two sends
  running is not.

**Priors:** if `learnings.md` has newsletter entries, apply them. When one changed the
draft, give it a single line in the note ("Curated editions outperformed essays 1.6x on
clicks in May, so the links lead"); otherwise say nothing about it. If this pull surfaces a
pattern stable across 3+ sends, hand it over in learnings format in the note,
`- [date] [newsletter] deep-dive editions outperform roundups ~1.8x on clicks (n=6 sends,
source: beehiiv-api)`, and route it to `/performance-review`, which owns writing learnings.
This skill reads the file; it never appends to it.

**No keys:** skim past edition files for topics and opening moves (anti-repeat), mention in
the note that performance priors are unavailable, and move on. No ceremony.

## Phase 3. Sourcing (curated-links, news-briefing, roundup)

These archetypes live or die on what's in them. Deep-dive and personal-essay skip this phase
unless the user wants supporting data. Their content comes from the user's material; search
only to verify specific claims or pull a supporting stat.

Fan out **one subagent per content pillar** (3-5 pillars from the audience's interests and the
edition's topic) using the Task/Agent tool. WebSearch and WebFetch do this for free. We use
Exa to find sources a keyword search misses (free tier, then pay as you go) and Firecrawl to
read each page as clean text (free tier of 1,000 credits a month, no card). Without them,
WebSearch and WebFetch read what they can reach. Each subagent fetches actual pages and
returns an evidence pack, not prose. Save the packs to
`./campaigns/newsletters/notes/{YYYY-MM-DD}-{topic-slug}.md`, never into the chat:

```yaml
- headline: <as published>
  url: <the page actually fetched>
  published: <date from the page; "undated" if absent>
  source_type: primary | reporting | aggregator
  summary: <2 sentences, own words>
  why_it_matters: <1 sentence, framed for THIS audience>
  everyone_has_it: <true if every newsletter in the niche will cover it>
```

Search with "current year" / "this week" phrasing, never a hardcoded year string. Say what the
edition rests on once, in the note ("Based on 9 pages read live on Nov 13"). If web access is
down, say the sourced items come from model knowledge and ask before shipping a sourced format
on stale knowledge.

Selection judgment. This is where a curator earns subscribers:

- **Primary beats aggregator.** Link the paper, the changelog, the announcement, the original
  reporting, not the blog post summarizing it. If a subagent returns an aggregator, chase the
  primary source it cites.
- **Date-check everything.** A "this week" item that's four months old torches trust faster
  than a typo. Undated pages need corroboration before inclusion.
- **Never cite a page you haven't fetched.** No items from memory, no snippet-only inclusions.
  If it can't be fetched, it can't be in the edition.
- **Skip what everyone has, or out-angle it.** An `everyone_has_it` story earns its slot only
  with a take the other newsletters won't have. Otherwise the obscure-but-relevant find is
  worth more.
- **The forward test:** would the user send this one link to a smart friend in the niche? "Fine
  but not great" items get cut, even if it leaves 4 links instead of 6.

Attribution: link the original, name the reporter/author when known, summarize in your own
words, mark paywalls "(paywalled, worth it)". Commentary must add something the source doesn't
say. A link plus a restated headline is RSS, not curation.

## Phase 4. Draft

Write the full edition per the archetype's section anatomy, in the brand voice.

**Subject lines:** 3 variants (the default), deduped per Phase 2. Vary the *mechanism*:
specific-curiosity ("The pricing change nobody read past the headline"), a direct question the
reader is already asking, a contrarian claim the body cashes. Pay the subject off in the first
100 words (clickbait debt compounds as unsubscribes); the preheader extends, never repeats.

**The hook is a quarter of the work.** The first two sentences decide whether the rest gets
read. Open with the most interesting true thing in the edition. A specific observation, a
number that surprised you, the claim itself. Never open with throat-clearing ("In this week's
edition...", "Hope you're well") or a template move.

**Anti-template check:** compare this draft's opening move and section order
against the last 2 editions from Phase 2. If two editions in a row open the same way (same
device, same rhythm, same first-line shape), vary this one. Recurring *sections* are format
(good); recurring *sentences* are template rot (bad).

Craft rules worth stating once:

- Specific beats general everywhere: "last Tuesday" not "recently", "47%" not "a lot", the
  company's name not "a major player".
- Have a take. "I think X because Y" is the product; balanced summary is a commodity.
- Scannability: a header or visual break every 200-300 words, paragraphs of 1-3 sentences,
  bold only the genuinely surprising clause (if bolding exceeds ~30% of a section, nothing
  stands out), bullets for any list of 3+.
- **One CTA.** Decide the single action this edition asks for (reply, click the flagship link, or
  share) and cut competing asks to passing mentions at most.

## Phase 5. Quality gate

Score the draft 1-10 on five dimensions before presenting, silently:

1. **Open:** does the best subject variant earn an open from a busy subscriber?
2. **Hook:** do the first two sentences make stopping feel costly?
3. **Value:** will the reader know or be able to do something tomorrow they couldn't today?
4. **Forward:** is there at least one passage someone would screenshot or forward?
5. **Voice:** read three paragraphs against voice-profile.md; could any competitor have
   written them? If yes, the voice failed even if the prose is clean.

Any dimension below 7: rewrite that dimension's material (not the whole draft) and rescore.
~3 iterations is the practical ceiling; past that the material is the constraint, so say so in
one line in the note. The client sees the passing edition, never the scores or their history
(keep the history in the notes file). Before final, the default move is to cut ~20%, because
drafts run long and the cuts come from the middle of sections, not the ends.

## Output

Write the file first: `./campaigns/newsletters/{YYYY-MM-DD}-{topic-slug}.md`

```markdown
# {Title}
- archetype: {name} · date: {YYYY-MM-DD} · read time: ~{X} min
- subject: "{chosen}" · variants: "{v2}" / "{v3}" · preheader: "{text}"

{full edition body}

## Send notes
- A/B: variant 1 vs 2, judged on CLICKS (opens are MPP-inflated)
- send time: {from learnings/ESP data if known; otherwise the list's established slot}
- sources: {url list, primary-source flagged}
```

Append one line to `./brand/assets.md`. Then deliver in chat per `start-here/references/output-format.md`:
`## NEWSLETTER EDITION: {topic}` + one line of date and what it is for, subject variants with
one-line reasoning, the edition body, one short **Sources and assumptions** note (10 lines
max: what the edition rests on in a sentence, what to confirm, what is missing), **Files
saved**, **What's next**.

**Send checklist (run silently, show only a failure you could not fix):** subject/preheader
pair reads as one thought · every link fetched and live · one CTA · sender is a person's name
· mobile paragraph lengths · one-click unsubscribe compliant (full preflight:
`/email-sequences`) · A/B judged on clicks.

## When the user edits your work

Apply the edit, then make it stick: save a gold case to `./brand/gold/<this skill>/` and
one to three yes/no checks to `./brand/checks.md`, and confirm in one line. Before handing
over any work, answer the checks the context block loaded, silently, and fix every no.
How: `${CLAUDE_SKILL_DIR}/../start-here/references/taste-loop.md`.

## What's next

- `/content-atomizer`: turn this edition into platform-native social posts; the flagship
  insight is the hook (~10 min)
- `/performance-review`: after the send, pull the click data and commit what worked to
  learnings (~10 min)
- `/creative`: header image or social card for the flagship story (~15 min)
- `/email-sequences`: if new subscribers land cold, build the welcome sequence this edition
  deserves (~15 min)

© James Dickerson (@boringmarketer) · MIT · boringmarketer/boring-marketing-skills

Similar skills

All skills for Marketing and content →

newsletter by other authors comes first.

newsletter OpenClaudia Helps plan email newsletter content, grow subscribers, and set up monetization. Useful when building a newsletter on Substack or Beehiiv. CX Codex +1 499installs newsletter membrane Connects email newsletter services to Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode via Membrane. The agent creates drafts, handles subscriber lists, and runs campaigns from the terminal. CX Codex +1 167installs email-and-newsletter social-media-skills email-and-newsletter — a skill for newsletter strategy: build an owned subscriber list, plan editions, and loop email with social. CX Codex +1 1,100installs spark-recipe-newsletter-cleanup readdle spark-recipe-newsletter-cleanup audits your Spark newsletter subscriptions: blocks unwanted senders, unsubscribes from noisy lists, and turns on AI summaries for the ones worth keeping. CX Codex +1 362installs newsletter-generation bytedance newsletter-generation generates professional email digests and newsletters with topic research via web search, multi-source curation, and ready-to-publish markdown output. CX Codex +1 1,900installs newsletter-publishing jamditis newsletter-publishing guides newsletter setup, responsive HTML email formatting, and subscriber tracking workflows. CX Codex +1 292installs newsletter-creator travisjneuman newsletter-creator builds a company newsletter from a fixed outline: section order, a scoring pass over the links, and email layout rules to follow. CX Codex +1 140installs developer-newsletter jonathimer developer-newsletter is a Claude Code skill for planning and writing developer newsletters, including content strategy, audience growth, and deliverability. CX Codex +1 ★ 88repo stars

From the same set35

The whole set →
boring-marketing boring-marketing is a Claude Code plugin that adds 32 marketing skills for audience research, SEO, copywriting, paid ads, and local business promotion. Runs when called via slash commands like /start-here. ★ 778repo stars long-form-article long-form-article is a Claude Code skill that plans and drafts in-depth articles, guides, and playbooks. It activates for requests to create a substantial piece for a blog, newsletter, or publishing platform. CX Codex +1 ★ 778repo stars google-business-profile The google-business-profile skill for Claude Code audits local business profiles against top map pack competitors. It identifies growth gaps and generates four weeks of Google posts. CX Codex +1 ★ 778repo stars pitch-the-fix pitch-the-fix is a Claude Code skill that finds a local business owner and drafts a first email around one specific fix. It activates for prospect research and cold outreach. CX Codex +1 ★ 778repo stars ads-incrementality-check ads-incrementality-check is a Claude Code skill that tests whether an ad campaign brings extra phone calls. It compares the business call log before, during and after a planned campaign pause. CX Codex +1 ★ 778repo stars speed-to-lead The speed-to-lead skill for Claude Code identifies missed calls and slow lead response times. It analyzes call logs to establish a structured follow-up cadence. CX Codex +1 ★ 778repo stars service-area-pages service-area-pages is a Claude Code skill that writes local landing pages for towns a business can substantiate. It checks the page set for duplicates before publication. CX Codex +1 ★ 778repo stars reviews reviews is a Claude Code skill that audits Google reviews against the local map pack top 3. It spots stalls in recent feedback, drafts owner responses and sets post-job ask scripts. CX Codex +1 ★ 778repo stars

Project sponsors

Companies that keep this analytics open