Agent SkillsAgent Skills
chekos

substack-post-crafter

@chekos/substack-post-crafter
chekos
3
2 forks
Updated 4/12/2026
View on GitHub

Craft Substack newsletter posts optimized for engagement, open rates, and subscriber growth. Use when writing headlines/subject lines, structuring posts, crafting hooks, writing teasers for next issues, or adapting content between newsletter and Notes. Includes email-first optimization, the cliff-hanger technique, SEO integration, and Spanish-language patterns.

Installation

$npx agent-skills-cli install @chekos/substack-post-crafter
Claude Code
Cursor
Copilot
Codex
Antigravity

Details

Pathtdd-growth/skills/substack-post-crafter/SKILL.md
Branchmain
Scoped Name@chekos/substack-post-crafter

Usage

After installing, this skill will be available to your AI coding assistant.

Verify installation:

npx agent-skills-cli list

Skill Instructions


name: substack-post-crafter description: | Craft Substack newsletter posts optimized for engagement, open rates, and subscriber growth. Use when writing headlines/subject lines, structuring posts, crafting hooks, writing teasers for next issues, or adapting content between newsletter and Notes. Includes email-first optimization, the cliff-hanger technique, SEO integration, and Spanish-language patterns.

Substack Post Crafter Skill

The Email-First Mindset

Substack is primarily email. Every design decision should optimize for:

  1. Subject line (determines open)
  2. Preview text (first 40-90 chars of subtitle)
  3. Hook (determines if they keep reading)
  4. Mobile readability (80% of email opens are on mobile)

Subject Line Mastery

Your subject line = your post title. It determines everything.

The 7-Word Rule

Studies show 7 words hit the sweet spot between too short and too long. Aim for 30-50 characters to fit mobile screens.

Subject Line Formulas

Curiosity Gap:

"The mistake everyone makes with [topic]"
"Why [common belief] is wrong"
"I finally figured out [thing]"

Value-Forward:

"How to [achieve result] in [timeframe]"
"[Number] ways to [accomplish goal]"
"The complete guide to [topic]"

Story Hook:

"What happened when I [did thing]"
"I almost gave up on [thing]. Then..."
"The day everything changed"

Direct/Clear:

"[Topic]: What you need to know"
"Your weekly [topic] update"
"[Specific thing] explained"

What NOT to Do

  • Clickbait that doesn't deliver
  • ALL CAPS or excessive punctuation!!!
  • Vague titles that could be anything
  • Too clever/cute (clarity > cleverness)

A/B Testing

Available for publications with 200+ subscribers. Substack tests two titles with a portion of your list, then sends the winner to the rest.

Open Rate Benchmarks

Open RateAssessment
70%+Exceptional
50%+Great (platform average)
40%+Good, solid engagement
30%+Needs improvement
<20%Deliverability or relevance issues

Caveat: Apple Mail Privacy Protection inflates open rates. Focus on click-through rates and replies for accurate signals.

Post Structure

The Anatomy of a High-Performing Post

TITLE (Subject Line)
↓
SUBTITLE (Preview text — first 40-90 chars visible)
↓
HOOK (First 1-2 paragraphs — stops the scroll)
↓
BODY (The value — structured, scannable)
↓
TEASER (Cliffhanger for next issue)
↓
CTA (What you want them to do)

The Hook

80% of readers never get past the headline. Your hook determines if they read the body.

Hook Strategies:

  1. Start with the payoff

    • Don't bury the lead
    • "Here's the thing no one tells you about [X]..."
  2. Open with story

    • Immediate scene, not setup
    • "Last Tuesday, I almost deleted everything..."
  3. Provocative question

    • Challenge assumptions
    • "What if everything you know about [X] is wrong?"
  4. Bold statement

    • Take a clear position
    • "[Common practice] is killing your [outcome]."

Common mistake: Your best hook is often buried 3-5 paragraphs in. During revision, ask: "Where does this get interesting?"

Body Structure

For Scanners (Most Readers):

  • Short paragraphs (2-3 sentences max)
  • Subheadings every 200-300 words
  • Bullet points for lists
  • Bold key phrases
  • Pull quotes for emphasis

Formatting Best Practices:

  • One idea per paragraph
  • White space is your friend
  • Use horizontal rules to separate sections
  • Images break up long text
  • Consider mobile first

The Cliff-Hanger Technique

One creator accidentally discovered that ending posts with specific previews of upcoming content increased their next issue's open rate from 34% to 74%.

How to Implement

Instead of:

See you next week!

Do this:

Next week: I'm breaking down the exact system I used to
[achieve result] — including the template I use every day.

You won't want to miss this one.

Template

Coming next [day]:

→ [Specific, compelling preview of content]
→ [What they'll learn or get]
→ [Why it matters to them]

Make sure you don't miss it.

This creates anticipation and primes subscribers to open.

Notes vs Newsletter

Notes and newsletters serve different purposes:

NewsletterNotes
Deep valueQuick visibility
Builds trustBuilds reach
1-3x per week1-3x per day
Long-formSnackable
Email-firstFeed-first

Repurposing Content

Newsletter → Notes:

  • Pull key insight as standalone Note
  • Share a provocative quote
  • Ask a question the newsletter answers
  • Post "teaser" with link to full issue

Notes → Newsletter:

  • Expand well-received Notes into full posts
  • Compile related Notes into a newsletter
  • Use Notes engagement to validate topics

SEO Integration

Substack posts can rank on Google. For tacosdedatos (educational content), this matters.

SEO Basics for Substack

  1. Target long-tail keywords

    • Not: "pandas tutorial"
    • Yes: "pandas groupby tutorial español paso a paso"
  2. Keyword placement

    • Title (subject line)
    • Subtitle
    • First paragraph
    • Subheadings
    • Naturally throughout
  3. Connect Google Search Console

    • Monitor rankings
    • Identify opportunities
  4. Evergreen vs Timely

    • Evergreen content = long-term SEO value
    • Balance with timely/news content

Substack SEO Reality

  • Google now crawls Substack posts within hours (median: 3 hours)
  • Custom domains may rank slightly better than .substack.com
  • High-quality, specific content performs best

Spanish-Language Patterns

For tacosdedatos

Headline Style:

"Cómo [lograr resultado] con [herramienta]"
"La guía completa de [tema] en español"
"[Número] errores que cometes con [tema]"
"Lo que nadie te dice sobre [tema]"

Hook Style:

Directo al grano. Sin rodeos.

[Primera oración impactante que establece el tema]

En este newsletter vamos a ver:
→ [Punto 1]
→ [Punto 2]
→ [Punto 3]

Closing Style:

La próxima semana:

Vamos a profundizar en [tema específico] — incluyendo
[algo concreto y valioso].

Nos vemos el [día].

— [Nombre]

LATAM Considerations

  • Spanish-speaking Substack community is small but growing (+1,514% growth possible)
  • Platform is Anglo-centric but opportunity exists
  • Collaborate with other Hispanic creators
  • Use Mexican Spanish for tacosdedatos audience

Welcome Email Optimization

The most-opened email you'll ever send.

Best Practices

  • Length: 50-125 words optimal (50% response rates)
  • Tone: Sounds like YOU, not corporate
  • Include: Upgrade CTA above the fold (for free tier)
  • Ask: Reply with why they subscribed
  • Guide: Link to best posts or "Start Here"
  • Deliverability: Ask to move to Primary tab / add to contacts

Template Structure

Subject: Bienvenido/a a tacosdedatos

[1-2 sentence personal greeting]

[What they can expect: frequency, topics]

[1 specific CTA — reply, read this post, etc.]

[Brief upgrade mention if applicable]

[Sign-off]

Post Checklist

Before publishing:

## Pre-Publish Checklist

### Title/Subject Line
- [ ] Under 50 characters / 7 words
- [ ] Clear value or curiosity hook
- [ ] Would I open this?

### Subtitle/Preview
- [ ] First 40-90 chars compelling
- [ ] Expands on title, doesn't repeat

### Hook (First 1-2 paragraphs)
- [ ] Immediately engaging
- [ ] Best hook not buried
- [ ] Clear what post is about

### Body
- [ ] Short paragraphs
- [ ] Subheadings for scanning
- [ ] Mobile-friendly formatting
- [ ] Key points bolded

### Teaser (End)
- [ ] Specific preview of next issue
- [ ] Creates anticipation

### CTA
- [ ] Clear next step
- [ ] Upgrade mention (if appropriate)

### SEO (if applicable)
- [ ] Keyword in title
- [ ] Keyword in first paragraph
- [ ] Descriptive subtitle

Output Format

When crafting Substack posts:

## Newsletter Post: [Topic]

### Title (Subject Line)
[Under 50 chars, 7 words]

### Subtitle (Preview Text)
[First 40-90 chars will show in inbox]

### Hook
[Opening 1-2 paragraphs]

### Body Outline
- [Section 1]
- [Section 2]
- [Section 3]

### Teaser for Next Issue
[Specific, compelling preview]

### CTA
[What you want readers to do]

### Specs
- **Word count**: [Target]
- **Reading time**: [X minutes]
- **SEO keywords**: [If applicable]
- **Publish day**: [Optimal day]

### Notes Version
[Snackable version for Notes feed]

References

For algorithm research, source links, and detailed tactics, see references/REFERENCES.md.

More by chekos

View all
bluesky-growth-strategy
3

Plan and execute Bluesky growth strategy for audience building on the decentralized platform. Use when developing starter pack strategy, creating custom feeds, building community presence, or planning cross-platform promotion. Includes the three-feed system, starter pack tactics (43% of follows at peak), and authentic engagement strategies for this conversation-first platform.

image-validator
3

Validate images against tacosdedatos illustration style guide. Use this skill when reviewing generated images, checking uploaded images for brand consistency, providing quality feedback on visual assets, or deciding if an image is ready for publication. Returns pass/fail with specific actionable feedback.

fact-checker
3

Verify claims in tacosdedatos content before publication. Use this skill when reviewing drafts for factual accuracy, checking code examples work correctly, validating statistics and sources, or verifying quotes and attributions. Produces a structured fact-check report with verdicts for each claim. For deep verification requiring extended research, delegate to the fact-checker subagent instead.

tacosdedatos-illustrator
3

Create complete post banner illustrations for tacosdedatos from concept to final image. Use this skill when you need to create a banner image for a new post, generate an illustration that matches the tacosdedatos visual style, or produce publication-ready artwork. This is the main creative orchestration skill that handles the full workflow.