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
npx skills add fabricioctelles/skills --skill substack-expert -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/substack-expert/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/substack-expert/
1Skills CLI (Vercel)
npx skills add fabricioctelles/skills --skill substack-expert -a codex2Manually: put the files in place
.agents/skills/substack-expert/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add fabricioctelles/skills --skill substack-expert -a cursor2Manually: put the files in place
.cursor/skills/substack-expert/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install fabricioctelles/skills skills/substack-expert2Manually: put the files in place
.github/skills/substack-expert/SKILL.md1Skills CLI (Vercel)
npx skills add fabricioctelles/skills --skill substack-expert -a gemini-cli2Platform CLI
gemini skills install https://github.com/fabricioctelles/skills --path skills/substack-expertManually: put the files in place
.devin/skills/substack-expert/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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