/substack-writer

Substack Article Writer

name: substack-writer
description: >
  Writes long-form Substack articles - benchmarks, how-tos, opinion pieces, explainers,
  product-led content, and personal essays. Handles the full lifecycle from draft
  through review and self-improvement.
triggers:
  - substack article
  - write an article about
  - long-form post
  - newsletter article
arguments:
  - draft: Create a new article from scratch or from user notes
  - refine: Edit and improve an existing draft
  - title: Generate title options for a draft
  - insights: Review performance and update _insights.md

---

MCP connectors

| Connector | Purpose | |-----------|---------| | Substack | Publish articles (via browser or API) |

Publication Context

Fill this in for your Substack:

publication_name: "[Your Publication Name]"
publication_url: "[your-substack].substack.com"
audience: "[Who reads this - roles, interests, level]"
cadence: "[How often you publish]"
topics: "[Core topics the publication covers]"

---

Format Library

| Format | When to Use | Typical Length | |--------|------------|---------------| | **Benchmark** | You have data comparing tools, approaches, or outcomes | 1500-2500 words | | **How-to** | Teaching a specific process with steps | 1200-2000 words | | **Opinion** | Taking a stance on an industry trend or practice | 800-1500 words | | **Explainer** | Breaking down a complex topic for your audience | 1200-2000 words | | **Product-led** | Showing your product solving a real problem | 1000-1800 words | | **Personal** | Leadership journey, lessons learned, reflections | 800-1500 words |

---

Universal Article Structure

Every article follows this skeleton, regardless of format:

[Title - specific, benefit-oriented or curiosity-driven]

[Subtitle - one sentence that expands the title]

[Opening - 2-3 paragraphs max, hook + context + thesis]

[Body - 3-5 sections with H2 headers]

[Closing - key takeaway + forward look + CTA]

Opening Rules

• First sentence must create tension, state a finding, or ask a question
• By paragraph 2, the reader should know what they'll learn
• By paragraph 3, you should be into the substance
• Never open with a dictionary definition
• Never open with "In today's fast-paced world..."

Section Rules

• Each H2 section should have a clear purpose
• Use H3 sparingly - only when a section genuinely has subsections
• Each section should be 200-500 words
• Transition between sections should feel natural, not forced

Closing Rules

• Restate the key takeaway in one sentence
• Add a forward-looking statement (what's next, what to watch for)
• End with a CTA: subscribe, try it, share, reply with your experience

---

Format-Specific Rules

Benchmark Articles

• Always state the methodology upfront: what you tested, how, and what the constraints were
• Present data in tables or clear lists - not buried in paragraphs
• Include your raw results or link to them
• Address obvious objections ("But what about X?")
• State limitations honestly
• Compare fairly - don't set up strawmen

How-to Articles

• Number the steps
• Each step should be independently actionable
• Include code blocks, screenshots, or examples where relevant
• Start with prerequisites (what the reader needs before starting)
• End with the expected outcome (what success looks like)
• Add a "Troubleshooting" section for common issues

---

Voice Principles

Do

• Write in first person ("I tested...", "We built...")
• Be direct - get to the point fast
• Lead with evidence, then interpret
• Be honest about limitations, failures, and unknowns
• Address the reader as a peer, not a student
• Use specific numbers over vague claims
• Write for your community - reference shared context

Don't

• Use "In conclusion" or "To summarize" - the reader can see it's the end
• Use passive voice when active is clearer ("The data was analyzed" -> "I analyzed the data")
• Use em dashes (--) or en dashes - use hyphens (-) or colons (:)
• Use "game-changing", "revolutionary", "groundbreaking"
• Use "unpack", "deep dive", "landscape"
• Use "leverage" when you mean "use"
• Hedge excessively ("It could potentially maybe...")
• Use "learnings" - use "lessons" or "what we learned"

---

Formatting Rules

• **Bold** for emphasis, not italics (bold is scannable, italics are not)
• Use bullet lists for 3+ items
• Use numbered lists only for sequential steps
• Code blocks for any code, commands, or technical output
• Tables for comparisons and structured data
• One image per major section maximum
• Pull quotes sparingly - only for genuinely striking lines
• Break up any paragraph longer than 4 sentences

---

Draft Structure Rules

When working from user-provided notes or an existing draft:

1. **Stay close to the user's narrative arc.** Don't reorganize their structure unless it's genuinely broken. 2. **Improve, don't rewrite.** Tighten language, strengthen transitions, add evidence - but keep their voice. 3. **Don't invent angles.** If the user wrote about X, don't pivot to Y because it seems more interesting. 4. **Don't shoehorn product positioning.** If the user didn't mention their product, don't add it. 5. **Don't expand short sections the user intentionally kept short.** If it's one paragraph, they probably want one paragraph.

---

Frontmatter Template

---
date: YYYY-MM-DD
channel: substack
topic: short-topic-slug
format: benchmark | how-to | opinion | explainer | product-led | personal
status: draft
title: "The Article Title"
subtitle: "One sentence subtitle"
performance:
  views:
  reads:
  read_ratio:
  likes:
  comments:
  shares:
  new_subscribers:
notes:
---

---

Review Checklist

Before presenting the draft, verify:

• [ ] Title is specific and either benefit-oriented or curiosity-driven
• [ ] Subtitle expands the title meaningfully
• [ ] Opening creates tension or states a finding in the first sentence
• [ ] Reader knows what