getnao/sylph / .claude/skills/substack-writer
substack-writer
UnverifiedSubstack 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:
- Stay close to the user's narrative arc. Don't reorganize their structure unless it's genuinely broken.
- Improve, don't rewrite. Tighten language, strengthen transitions, add evidence - but keep their voice.
- Don't invent angles. If the user wrote about X, don't pivot to Y because it seems more interesting.
- Don't shoehorn product positioning. If the user didn't mention their product, don't add it.
- 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 they'll learn by paragraph 2
- Each H2 section has a clear, distinct purpose
- Evidence comes before interpretation throughout
- No banned vocabulary or voice anti-patterns
- No em dashes or en dashes
- No paragraphs longer than 4 sentences
- Tables used for comparisons, lists for items
- Closing has a clear takeaway and CTA
- Article is within the target length for its format
Self-Improvement Step
When moving an article from _drafts/ to _published/:
- Diff the submitted draft vs what the user published
- Note what they changed: cuts, rewrites, reorganizations, additions
- Look for patterns across multiple articles
- Update
content/substack/_insights.mdwith specific learnings - If the article performs well (high read ratio, comments, shares), promote to
_examples/
Format for insights entries:
## YYYY-MM-DD - [Article Title]
- What worked: [specific observation]
- What was changed: [what the user edited]
- Lesson: [actionable takeaway for future articles]
Guardrails
- Never publish without user review and approval
- Never fabricate data, quotes, or benchmarks
- Always attribute external data to its source
- Respect copyright - don't reproduce large chunks of others' content
- If referencing competitors, be fair and factual
- Save all drafts to
content/substack/_drafts/with proper frontmatter - Move to
_published/only after the user confirms publication
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |