Skip to main content
skill CX Codex

substack — Claude Code skill: read and publish on Substack

Drives your real Substack account from login cookies: shows the primary publication, lists published posts with stats, and publishes a new one.

Apache-2.0 207 installs ★ 17 updated 2026-10-25

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

What substack does

The skill acts on your own Substack account. Cookies you captured with the ACE extension reach the script through SUBSTACK_COOKIES. There is no public write API on Substack, so requests go to the same internal web endpoints the site itself calls.

One file does the work: scripts/substack.py, standard library only. whoami returns the account and its main publication, articles --limit 20 lists published posts with stats, and publish converts Markdown into Substack's ProseMirror blocks. Headings, lists, code fences and links arrive as real formatting.

Writes stay gated. Unless --confirm is the last argument, the command prints a plan and touches nothing, so start with the dry run. --draft-only leaves the post in the dashboard and hands back an edit_url. Going live emails nobody until you pass --send-email, and that send cannot be undone. Expired cookies show up as 401 or 403; reconnect at studio.acedata.cloud/console/connectors. Never print SUBSTACK_COOKIES — it is full account access.

What it helps with

  • confirm which Substack account the saved cookies belong to
  • pull published posts with stats into the chat
  • turn a Markdown file into a draft with an edit link
  • push a post live without emailing subscribers
  • send a newsletter when explicitly asked

Example prompts for the agent

  • Who am I on Substack, and which publication is primary?
  • List my last 20 published posts with stats.
  • Publish post.md as a draft only, don't send anything.

How to install substack

1Skills CLI (Vercel)

npx skills add AceDataCloud/Skills --skill substack -a claude-code

2Manually: put the files in place

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

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

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

Questions about substack

How do I install substack in Claude Code?

Run npx skills add AceDataCloud/Skills --skill substack -a claude-code, then the skill sits at ~/.claude/skills/substack/SKILL.md.

What does substack do?

It shows your account and main publication, lists published posts with stats, and publishes new Markdown content. Everything runs as you, through the captured cookie.

What happens when the cookie expires?

Reads fail with 401 or 403 and you reconnect at studio.acedata.cloud/console/connectors. The script never retries a write.

Source text

SKILL.md · Apache-2.0
---
name: substack
description: Read and publish on Substack (substack.com) with the user's own login cookies (BYOC) — show who they are and their primary publication, list their published posts with stats, and publish a new post / newsletter. Use when the user mentions Substack, "my Substack", their newsletter, or publishing a post to Substack.
when_to_use: |
  Trigger for anything on the user's Substack account driven by their own login
  cookie: show who they are and their primary publication, list their published
  posts, or publish a new post / newsletter. This acts as the user's real
  account, so writes are gated behind an explicit confirmation and never email
  subscribers unless asked.
connections: [substack]
allowed_tools: [Bash]
license: Apache-2.0
metadata:
  author: acedatacloud
  version: "1.0"
---

# substack — read & publish on Substack via your own cookies

Drives the user's **real** Substack account through the same internal web API
the site uses (Substack has no official public write API), authenticated by the
login cookie they captured with the ACE extension. No browser, no third-party
deps — just `urllib`. The publish flow mirrors the community `python-substack`
library: **create draft → prepublish → publish**.

The connector injects the cookie jar as an env var:

- `SUBSTACK_COOKIES` — a JSON array of cookies (`substack.sid`, `substack.lli`,
  …). **Secret — never echo or print it.** Substack authenticates writes with
  the session cookie alone (no CSRF token header needed).

## CLI

The skill ships [`scripts/substack.py`](scripts/substack.py) — self-contained, stdlib only.

```sh
# $SKILL_DIR can point at another skill loaded this turn — anchor on our own
# script, and re-run this at the top of every Bash block (fresh shell each time).
SUB="$SKILL_DIR/scripts/substack.py"; [ -f "$SUB" ] || SUB=$(find /tmp -maxdepth 8 -path '*/skills/*/scripts/substack.py' 2>/dev/null | head -1)
[ -f "$SUB" ] || { echo "substack script not found (SKILL_DIR=$SKILL_DIR)" >&2; exit 1; }
python3 "$SUB" whoami                     # who is logged in + primary publication
python3 "$SUB" articles --limit 20        # my published posts + stats
```

## Verify the connection first

```sh
SUB="$SKILL_DIR/scripts/substack.py"; [ -f "$SUB" ] || SUB=$(find /tmp -maxdepth 8 -path '*/skills/*/scripts/substack.py' 2>/dev/null | head -1)
python3 "$SUB" whoami
# → {"user_id": ..., "name": "...", "handle": "...", "publication": "...", "publication_url": "https://<sub>.substack.com"}
```

On an auth error the cookie is expired — have the user reconnect at
<https://studio.acedata.cloud/console/connectors>. Do **not** loop-retry.

## Publishing — GATED (dry-run unless trailing `--confirm`)

`publish` writes to the user's real account. Content is **Markdown**, converted
to Substack's ProseMirror blocks: `#`..`######`→heading, ```` ``` ````→code
block, `>`→blockquote, `-`/`*`/`1.`→lists, `---`→horizontal rule, everything else
→paragraphs. Inline **bold**, *italic*, `code`, ~~strike~~, and `[links](url)`
render as real Substack formatting; bare `https://…` URLs are auto-linked.

Without a trailing `--confirm` it dry-runs. `--confirm` is honored **only as the
last argument**. Always show the dry-run, get an explicit "yes", then re-run.

```sh
SUB="$SKILL_DIR/scripts/substack.py"; [ -f "$SUB" ] || SUB=$(find /tmp -maxdepth 8 -path '*/skills/*/scripts/substack.py' 2>/dev/null | head -1)
# dry-run (shows the plan, writes nothing)
python3 "$SUB" publish --title "Title" --content-file post.md

# private draft (visible only in the user's dashboard)
python3 "$SUB" publish --title "Title" --content-file post.md --draft-only --confirm

# go LIVE on the web (does NOT email subscribers)
python3 "$SUB" publish --title "Title" --content-file post.md --confirm

# go LIVE and email subscribers (use only when the user explicitly asks)
python3 "$SUB" publish --title "Title" --content-file post.md --send-email --confirm
```

- `--draft-only` stops at a draft — **default to this** unless the user asked to
  go live. Returns an `edit_url` to review in the Substack editor.
- Publishing **does NOT email subscribers** unless `--send-email` is passed.
  Emailing a newsletter is irreversible and hits every subscriber's inbox —
  never add `--send-email` without an explicit request.
- `--subtitle` sets the post subtitle; `--audience` is one of
  `everyone` (default, free/public), `only_paid`, `founding`, `only_free`.

## Gotchas

- **This is the user's real Substack account.** Confirm before any publish, and
  keep `--draft-only` as the safe default.
- **`--send-email` blasts the whole subscriber list** and cannot be undone — opt
  in only on explicit request.
- Substack sits behind Cloudflare; an occasional 403/429 on a read is transient —
  the CLI auto-retries reads once. A *persistent* 401/403 means the cookie is
  genuinely expired (reconnect); the CLI never retries a write.
- **Never print `SUBSTACK_COOKIES`** — it is full account access.
- **ToS**: acts only on the user's own account with their own captured cookie.


## Record the output

After you successfully publish and obtain the live result URL, call the built-in
`publish_artifact` tool ONCE so the user can track this deliverable in **My Outputs**:

```
publish_artifact(kind="article", channel="substack", title="<title>", url="<the REAL returned URL>", status="delivered")
```

Use the real returned URL — never fabricate one. Call it once per published item,
only after delivery is confirmed; skip it (or use `status="failed"`) if publishing failed.
See `_shared/artifacts.md`.

© acedatacloud · Apache-2.0 · AceDataCloud/Skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set67

The whole set →

Project sponsors

Companies that keep this analytics open