CommunityEscrita e Ediçãogithub.com

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).

O que é newsletter?

newsletter is a Claude Code agent skill that 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).

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/boringmarketer/boring-marketing-skills/tree/HEAD/skills/newsletter

Installed? Explore more Escrita e Edição skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que newsletter faz?

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 jobArchetype
Catch readers up on what mattered in the niche this weekroundup
Teach one thing thoroughly enough to act ondeep-dive
Build the relationship; say the thing only this writer can saypersonal-essay
Save readers hours of filtering; taste is the productcurated-links
Daily/fast-cycle "what happened + why it matters"news-briefing
One original idea plus the week's worth-knowing linkshybrid

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:

- 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

# {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)

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Habilidades Relacionadas