Substacker Write

Structure

• Short paragraphs: 2-4 sentences max. Dense walls of text lose readers
• Subheadings every 200-300 words: Break up the content for scanners
• Bold key phrases: Highlight the most important takeaway in each section
• Bullet lists for comparisons: When listing features, trade-offs, or options

What to Avoid

• Filler phrases: "In today's rapidly evolving landscape...", "It's worth noting that...", "At the end of the day..."
• Hedging without substance: "It remains to be seen..." — either make a prediction or don't
• Excessive qualifiers: "very", "really", "quite", "somewhat"
• AI-typical patterns: em dash overuse, "delve into", "leverage", "harness the power of", "paradigm shift", rule of three in every paragraph
• Passive voice when active is clearer
• Explaining what the reader already knows (don't define "API" or "machine learning" for a tech audience)

Formatting for Substack

• Use markdown headers (## for sections, ### for subsections)
• Code blocks with language tags for syntax highlighting
• Links inline, not as footnotes
• Image references as ![Alt text](images/filename.png) — images will be added by the images skill

Workflow

Step 1: Load Context

1. Read outline.md — the approved article structure
2. Read sources.md — all research sources
3. Read topic.md — original topic context
4. Note the format (Deep Dive / Tutorial / Digest) and estimated word count

Step 2: Write the Draft

Write the full article following the outline structure. For each section:

1. Expand outline bullets into prose following the style guidelines above
2. Cite sources inline as hyperlinks: [study found X](url)
3. Add transitions between sections that feel natural, not forced
4. Mark image placements where visuals would strengthen the content:
   • <!-- IMAGE: hero - [description of what the hero image should show] -->
   • <!-- IMAGE: diagram - [description of what the diagram should illustrate] -->
   • <!-- IMAGE: code - [description of what code to screenshot] -->
5. Write code examples where the outline calls for them — real, runnable code, not pseudocode
6. Include a compelling title and subtitle at the top

Step 3: Self-Review

Before presenting to the user, review the draft against these checks:

• Does the opening hook grab attention in the first 2 sentences?
• Is every claim supported by a source or clearly marked as opinion?
• Are there any filler phrases or AI-typical patterns?
• Is the word count within the target range from the outline?
• Do code examples actually work (correct syntax, imports)?
• Are image placements marked where they'd add value?
• Does the conclusion leave the reader with something actionable or thought-provoking?
• Are all source links included as inline hyperlinks?

Fix any issues found during self-review before presenting.

Step 4: User Checkpoint

Present the full draft and ask:

Review this draft. You can:

• Approve it as-is
• Request tone adjustments (more technical / more accessible / more opinionated)
• Ask to expand or cut specific sections
• Suggest restructuring
• Flag any claims that feel unsupported
• Request rewrites of specific paragraphs

Iterate until the user approves. Each revision should be targeted — don't rewrite the entire article, only change what was requested.

Step 5: Save

Write draft.md to the article directory with the final approved content.

Update docs/articles/index.md — change the article's status from outlined to drafted.

After saving, suggest: "Draft is ready. Run /substacker:images to generate visuals, then /substacker:publish to publish."

Format-Specific Guidance

Deep Dive

• Build an argument across sections. Each section should advance the reader's understanding
• Include counterarguments or limitations — don't be one-sided
• End with a clear stance or prediction
• Typical length: 2000-3500 words

Tutorial

• Start with what the reader will build/achieve
• List prerequisites upfront (tools, knowledge, accounts needed)
• Every step should be copy-pasteable and testable
• Include expected output/results at each step
• End with "next steps" for going further
• Typical length: 1500-3000 words

Digest

• Brief intro connecting the items thematically (2-3 sentences)
• Each item: summary (what happened) + commentary (why it matters) + link
• 3-5 items per digest
• Brief closing that ties items together or looks ahead
• Typical length: 1000-2000 words

Error Handling

• If outline.md or sources.md is missing, tell user to run previous pipeline stages
• If sources are insufficient for a section, flag it and suggest additional research
• If word count significantly exceeds target, flag which sections could be trimmed