typefully

Files (10)

• CHANGELOG.md
• SKILL.md
• comments.md · references/
• local-development.md · references/
• linkedin.md · references/platforms/
• x-articles.md · references/platforms/
• x.md · references/platforms/
• quotes.md · references/
• setup.md · references/
• typefully.js · scripts/

SKILL.md (first lines)

# Typefully Skill

Create, schedule, and publish social media content across X, LinkedIn, Threads, Bluesky, Mastodon, and Substack Notes using [Typefully](https://typefully.com). Run everything through `./scripts/typefully.js` (Node.js 18+, no dependencies). All commands output JSON.

> **Script paths** below are relative to this skill's directory. Resolve them based on where the skill is installed.
>
> **Freshness check**: If more than 30 days have passed since the `last-updated` date above, tell the user the skill may be outdated and point them to the update methods in [`references/setup.md`](references/setup.md).
>
> **Authentication failures**: If the CLI returns **"API key not found"**, **"Authentication failed"**, **"HTTP 401"**, or any invalid/expired-key message, tell the user to run `./scripts/typefully.js setup` or update `TYPEFULLY_API_KEY`, then stop. Do not hunt for credentials or fall back to the Typefully web UI, browser scraping, or a localhost dev server. See [`references/setup.md`](references/setup.md).

## Dropped Typefully draft URLs

When the user gives you a Typefully draft URL, use this skill instead of browsing or scraping the Typefully web UI.

- `https://typefully.com/?a=<social_set_id>&d=<draft_id>` maps to:

  ```bash
  ./scripts/typefully.js drafts:get <social_set_id> <draft_id>
  ```

- `https://typefully.com/?d=<draft_id>` can use the configured default social set:

  ```bash
  ./scripts/typefully.js drafts:get <draft_id> --use-default
  ```

For draft comments, replies, resolving, or edits on a dropped draft URL, first fetch the draft with the mapping above, then load [`references/comments.md`](references/comments.md) when comment workflow details are needed.

## Reference guides

Load these only when the task needs them:

| Guide | Use when you need to... |
|-------|-------------------------|
| [`references/setup.md`](references/setup.md) | Configure the API key, fix an "API key not found" error, set up CI, or check whether the skill is up to date |
| [`references/comments.md`](references/comments.md) | Add, reply to, resolve, or delete comments on a draft, or edit a draft that already has comments |
| [`references/quotes.md`](references/quotes.md) | Quote another post on X, Threads, Bluesky, or Mastodon, or restack one on Substack |
| [`references/platforms/x.md`](references/platforms/x.md) | Reply to an X (formerly Twitter) post, post to a community, or add disclosure labels |
| [`references/platforms/linkedin.md`](references/platforms/linkedin.md) | Mention a company or person on LinkedIn, or add a LinkedIn first comment |
| [`references/platforms/x-articles.md`](references/platforms/x-articles.md) | Write or edit a long-form X Article (standalone platform) |

---

## 1. Choose a social set

A "social set" is what users call an "account" — the connected platforms for one identity. Most commands work without a `social_set_id` once a default is configured. Pass it positionally (`drafts:list 123`) or as `--social-set-id 123`.

To decide which social set to use:

1. Run `config:show`. If `default_social_set` is set, the CLI uses it automatically — proceed.
2. Otherwise run `social-sets:list`. If only one exists, use it.
3. If multiple exist with no default, ask the user, then offer to save it: `config:set-default`.
4. Reuse a social set already resolved earlier in the session without asking again.

---

## 2. Create drafts

```bash
./scripts/typefully.js drafts:create --text "Your post"
```

- If `--platform` is omitted, the first connected platform is auto-selected. Named platforms: `x`, `linkedin`, `threads`, `bluesky`, `mastodon`, `substack` (Substack Notes), `x_article`.
- Split a thread with `---` on its own line. Exception: `substack` takes a single post per draft — no threads. For a thread plus a Substack Note, use the one-draft pattern below to give `substack` its own single-post content.
- Substack Notes media: up to 6 images/GIFs, or a single video on its own (max 512 MB, 15 min). A video can't be mixed with images or GIFs, or combined with `--quote-post-url` (restack).
- Attach media with `--media`, tags with `--tags`, internal notes with `--scratchpad`, an internal name with `--title`.
- Read content from a file with `--file ./post.txt` instead of `--text`.

### One draft per post — always

For the same content on several platforms, pass multiple platforms to a **single** draft:

```bash
./scripts/typefully.js drafts:create --platform x,linkedin --text "Big announcement!"
./scripts/typefully.js drafts:create --all --text "Posting everywhere!"   # all connected platforms
```

When content should differ per platform (e.g. an X thread plus a tailored LinkedIn post), **still use one draft** — create with the first platform, then `drafts:update` to add another with different content:

```bash
./scripts/typefully.js drafts:create --platform linkedin --text "Excited to share..."   # -> id draft-123
./scripts/typefully.js drafts:update draft-123 --platform x --text "🧵 Thread time!" --use-default
```

Never create multiple drafts unless the user explicitly wants separate drafts per platform.

> `--all` excludes `x_article`. X Articles are standalone and cannot be combined with any other platform — see [`references/platforms/x-articles.md`](references/platforms/x-articles.md).
>
> `--all` includes `substack` when connected. Since Substack Notes take a single post, `--all` with thread content errors — exclude `substack` via `--platform`, or give it its own single-post content with `drafts:update`.

### Scratchpad notes

When the user asks to add notes, ideas, or context to a draft, use `--scratchpad` — **do NOT write to local files.** Scratchpad notes attach to the draft in Typefully, are visible in the UI, stay private, and are never published.

```bash
./scripts/typefully.js drafts:create --text "My post" --scratchpad "Ideas: 1) Add stats 2) Include quote"
```

### Link previews

When a post contains a URL, Typefully automatically fetches Open Graph metadata for the last URL in the text and publishes a rich link-preview card on **LinkedIn, Threads, Bluesky, and Substack Notes**. No flag is needed — it just works. X and Mastodon unfurl links themselves after publishing. On Substack Notes the card is skipped when the note has images (images and the link card are mutually exclusive there).

To publish the URL as plain text with no card, pass `--hide-link-preview`. Suppression is supported on **LinkedIn, Threads, and Substack Notes only** (matching the Typefully editor); the flag errors if none of these platforms is targeted, and is ignored for other platforms in a mixed-platform draft:

```bash
./scripts/typefully.js drafts:create --platform linkedin,threads --text "Read this https://example.com" --hide-link-preview
./scripts/typefully.js drafts:update draft-123 --hide-link-preview --use-default   # hide the card on an existing draft
```

---

## 3. Schedule & publish

```bash
./scripts/typefully.js drafts:create --text "..." --schedule next-free-slot   # or an ISO time, or "now"
./scripts/typefully.js drafts:schedule <draft_id> --time next-free-slot --use-default
./scripts/typefully.js drafts:publish <draft_id> --use-default
./scripts/typefully.js drafts:create --text "..." --plan next-free-slot      # planned: dated but inert
./scripts/typefully.js drafts:plan <draft_id> --time next-free-slot --use-default

From typefully/agent-skills, MIT.