Skip to main content
skill CX Codex

substack-expert — Claude Code skill: what it does, setup

substack-expert — a skill for shaping Substack newsletters, from post structure and SEO fields to reader engagement and free-to-paid conversion.

Apache-2.0 ★ 141 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add fabricioctelles/skills --skill substack-expert -a claude-code
Open on GitHub

What substack-expert does

substack-expert supports Substack newsletter work from an early draft through publication planning. It lays out H1, H2, and H3 sections, then prepares a title, URL slug, meta description, and image alt text. It can also place subscription prompts, polls, and comment requests at suitable points in a post.

The growth workflow covers Notes, comments on related publications, and rotating recommendations based on Analytics. Monetization guidance includes a gated bonus, targeted messages to highly engaged subscribers, a customized welcome email, and navigation built from Tags. Its SEO rules call for a 3–5 keyword slug with no dates or numbers, so that constraint matters when you choose the post URL.

What it helps with

  • outline a Substack post with H1–H3 sections
  • create a keyword-focused title and URL slug
  • write a meta description and image alt text
  • place a poll or subscription prompt in a draft
  • plan a free-to-paid newsletter path

Example prompts for the agent

  • Build a Substack post outline and include its SEO fields.
  • Rewrite this draft for Substack with a title, URL slug, meta description, and image alt text.
  • Create a growth plan using Notes and a gated bonus for paid subscribers.

How to install substack-expert

1Skills CLI (Vercel)

npx skills add fabricioctelles/skills --skill substack-expert -a claude-code

2Manually: put the files in place

~/.claude/skills/substack-expert/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/substack-expert/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about substack-expert

How do I install substack-expert in Claude Code?

Run npx skills add fabricioctelles/skills --skill substack-expert -a claude-code, then check ~/.claude/skills/substack-expert/SKILL.md.

What does substack-expert do?

It helps create and format Substack posts, produce SEO metadata, add native engagement elements, and plan free-to-paid conversion tactics.

Can I use substack-expert with Codex?

A Codex installation is provided: run npx skills add fabricioctelles/skills --skill substack-expert -a codex, then use .agents/skills/substack-expert/SKILL.md.

Source text

SKILL.md · Apache-2.0
---
name: substack-expert
description: This skill should be used when creating, formatting, or optimizing content for a Substack newsletter. Covers post structure, SEO metadata (titles, slugs, meta descriptions), native engagement features (Notes, Polls, Chat), monetization tactics, and free-to-paid conversion strategies.
metadata:
  author: ft.ia.br
  version: "1.1"
  date: 2026-03-05
  repository: https://github.com/fabricioctelles/skills
  license: Apache 2.0
  category: library-and-api-reference
---

# Substack Expert

## Parameters

| Parameter     | Description                                            | Default                          |
|---------------|--------------------------------------------------------|----------------------------------|
| `topic`       | Subject or draft content to work with                  | Infer from the conversation      |
| `goal`        | Primary objective: `format`, `seo`, `growth`, `monetize` | `format` + `seo` if unspecified |
| `language`    | Output language                                        | Match the user's message language |

## Workflow

### 1. Clarify Scope

Identify which goals apply (formatting, SEO, growth, monetization) and confirm the topic. If the request is ambiguous, default to producing SEO metadata and a formatted structure outline simultaneously.

### 2. Visual Formatting

- Structure content with `Heading 1`, `Heading 2`, and `Heading 3` to improve readability and facilitate search-engine crawling.
- Apply the centering and styling techniques described in `references/formatting-best-practices.md`.
- Insert native engagement tools (Subscribe button, polls, Leave a comment) at natural breakpoints in the post.

### 3. SEO and Metadata

Produce the following fields for every post:

- **Title**: 40–60 characters. Use clear modifiers, keywords, and authority signals (e.g., "Tested", "Complete Guide"). Avoid vague or clickbait phrasing.
- **URL Slug**: 3–5 main keywords only, no auto-generated numbers, no dates (keeps the post evergreen). Example: `/substack-seo-strategy`.
- **Meta Description**: 155–160 characters, includes the primary keyword and an implicit call to action.
- **Image Alt Text**: Describe the image for accessibility; incorporate article keywords organically.

Consult `references/seo-output-example.md` for a worked example.

### 4. Growth Strategies

- **Substack Notes**: Publish short snippets derived from the post to Notes immediately after publishing. Leave authentic comments on related publications to build name recognition.
- **Recommendations rotation**: Review Analytics monthly to identify which partner newsletters drive inbound traffic. Rotate recommended partners every 30–60 days to maintain reciprocal growth.

### 5. Monetization (Free → Paid Conversion)

- **Tease & Convert**: Publish the core article freely, but gate a utility bonus (template, spreadsheet, prompt set, audio) behind the paywall. Prove value before asking for payment.
- **VIP outreach**: In the Dashboard, filter subscribers by engagement score (4–5 stars), then send a targeted direct message offering a special rate or exclusive invite to the paid tier.
- **Welcome email**: Customize the automated welcome email to introduce the author, set publishing cadence expectations, and link to the three best existing articles. Never leave the platform default.
- **Homepage taxonomy**: Group posts into Tags (equivalent to newspaper sections) and add them to the navigation bar via *Website Themes* for advanced content discovery.

## Quality Checklist

Before delivering output, verify:

- [ ] Title is 40–60 characters and contains the primary keyword.
- [ ] URL slug has 3–5 words, no numbers, no dates.
- [ ] Meta description is 155–160 characters with a keyword and implicit CTA.
- [ ] All images have alt text.
- [ ] Subject line (if applicable) is under 50 characters and free of spam triggers.
- [ ] At least one native engagement element (button, poll, or comment prompt) is included.
- [ ] Paywall placement follows the Tease & Convert model (not a mid-sentence cut).
- [ ] Welcome email customization is recommended if the post is the first in a new publication.

© ft.ia.br · Apache-2.0 · fabricioctelles/skills

Similar skills

All skills for Writing and docs →

From the same set46

The whole set →
agent-ready-auth-md agent-ready-auth-md publishes an auth.md file and OAuth metadata so agents can discover how to register with a service. Kicks in when a scanner flags the authMd check as failing. CX Codex +1 ★ 141repo stars agent-ready-ard The agent-ready-ard skill guides you through publishing /.well-known/ai-catalog.json so agents can discover MCP servers, A2A agents, skills, and API tools. Use it to add resource discovery to a project. CX Codex +1 ★ 141repo stars agent-ready-scan-site agent-ready-scan-site scans a website and validates compliance with AI agent standards. Evaluates 23 checks across five categories: discoverability, content accessibility, bot rules, API/auth discovery, and commerce. CX Codex +1 ★ 141repo stars ultimate-design-system-master ultimate-design-system-master guides users through an 18-step briefing questionnaire to produce design systems, brand assets, and UI code across 10 specialized generators. CX Codex +1 ★ 141repo stars pier-cloud A skill for calling the Pier Cloud (Lighthouse) API: JWT auth, contexts, workspaces and FinOps view data through ready-made Python scripts. CX Codex +1 ★ 141repo stars geo-optimization geo-optimization optimizes site content for LLM citations and answer engines like ChatGPT, Perplexity, Claude, and Google AI Overview. CX Codex +1 ★ 141repo stars human-ai human-ai reworks English prose to remove canned AI wording and stiff structure while keeping the source facts, meaning, and authorial voice. CX Codex +1 ★ 141repo stars design-md-validator design-md-validator is a Claude Code skill that checks DESIGN.md against Google's specification with the @google/design.md CLI linter. It flags broken token references and computes WCAG contrast ratios. CX Codex +1 ★ 141repo stars

Project sponsors

Companies that keep this analytics open