>
Add this skill
npx mdskills install typefully/typefullyComprehensive social media management skill with detailed workflows, clear CLI integration, and strong setup guidance
1---2name: typefully3description: >4 Create, schedule, and manage social media posts via Typefully. ALWAYS use this5 skill when asked to draft, schedule, post, or check tweets, posts, threads, or6 social media content for Twitter/X, LinkedIn, Threads, Bluesky, or Mastodon.7last-updated: 2026-02-198allowed-tools: Bash(./scripts/typefully.js:*)9---1011# Typefully Skill1213Create, schedule, and publish social media content across multiple platforms using [Typefully](https://typefully.com).1415> **Freshness check**: If more than 30 days have passed since the `last-updated` date above, inform the user that this skill may be outdated and point them to the update options below.1617## Keeping This Skill Updated1819**Source**: [github.com/typefully/agent-skills](https://github.com/typefully/agent-skills)20**API docs**: [typefully.com/docs/api](https://typefully.com/docs/api)2122Update methods by installation type:2324| Installation | How to update |25|--------------|---------------|26| CLI (`npx skills`) | `npx skills update` |27| Claude Code plugin | `/plugin update typefully@typefully-skills` |28| Cursor | Remote rules auto-sync from GitHub |29| Manual | Pull latest from repo or re-copy `skills/typefully/` |3031API changes ship independently—updating the skill ensures you have the latest commands and workflows.3233## Setup3435Before using this skill, ensure:36371. **API Key**: Run the setup command to configure your API key securely38 - Get your key at https://typefully.com/?settings=api39 - Run: `<skill-path>/scripts/typefully.js setup` (where `<skill-path>` is the directory containing this SKILL.md)40 - Or set environment variable: `export TYPEFULLY_API_KEY=your_key`41422. **Requirements**: Node.js 18+ (for built-in fetch API). No other dependencies needed.4344**Config priority** (highest to lowest):451. `TYPEFULLY_API_KEY` environment variable462. `./.typefully/config.json` (project-local, in user's working directory)473. `~/.config/typefully/config.json` (user-global)4849### Handling "API key not found" errors5051**CRITICAL**: When you receive an "API key not found" error from the CLI:52531. **Tell the user to run the setup command** - The setup is interactive and requires user input, so you cannot run it on their behalf. Recommend they run it themselves, using the correct path based on where this skill was loaded:54 ```bash55 <skill-path>/scripts/typefully.js setup56 ```57582. **Stop and wait** - After telling the user to run setup, **do not continue with the task**. You cannot create drafts, upload media, or perform any API operations without a valid API key. Wait for the user to complete setup and confirm before proceeding.59603. **DO NOT** attempt any of the following:61 - Searching for API keys in macOS Keychain, `.env` files, or other locations62 - Grepping through config files or directories63 - Looking in the user's Trash or other system folders64 - Constructing complex shell commands to find credentials65 - Drafting content or preparing posts before setup is complete6667The setup command will interactively guide the user through configuration. Trust the CLI's error messages and follow their instructions.6869> **Note for agents**: All script paths in this document (e.g., `./scripts/typefully.js`) are relative to the skill directory where this SKILL.md file is located. Resolve them accordingly based on where the skill is installed.7071## Social Sets7273The Typefully API uses the term "social set" to refer to what users commonly call an "account". A social set contains the connected social media platforms (X, LinkedIn, Threads, etc.) for a single identity.7475**The CLI supports a default social set** - once configured, most commands work without specifying the social_set_id.7677**You can pass the social set either way**:78- Positional: `drafts:list 123`79- Flag: `drafts:list --social-set-id 123` (also supports `--social_set_id`)8081When determining which social set to use:82831. **Check for a configured default first** - Run `config:show` to see if a default is already set:84 ```bash85 ./scripts/typefully.js config:show86 ```87 If `default_social_set` is configured, the CLI uses it automatically when you omit the social_set_id.88892. **Check project context** - Look for configuration in project files like `CLAUDE.md` or `AGENTS.md`:9091 ```markdown92 ## Typefully93 Default social set ID: 1234594 ```95963. **Single social set shortcut** - If the user only has one social set and no default is configured, use it automatically97984. **Multiple social sets, no default** - Ask the user which to use, then **offer to save their choice as the default**:99 ```bash100 ./scripts/typefully.js config:set-default101 ```102 This command lists available social sets and saves the choice to the config file.1031045. **Reuse previously resolved social set** - If determined earlier in the session, use it without asking again105106## Common Actions107108| User says... | Action |109|--------------|--------|110| "Draft a tweet about X" | `drafts:create --text "..."` (uses default social set) |111| "Post this to LinkedIn" | `drafts:create --platform linkedin --text "..."` |112| "Post to X and LinkedIn" (same content) | `drafts:create --platform x,linkedin --text "..."` |113| "X thread + LinkedIn post" (different content) | Create one draft, then `drafts:update` to add platform (see [Publishing to Multiple Platforms](#publishing-to-multiple-platforms)) |114| "What's scheduled?" | `drafts:list --status scheduled` |115| "Show my recent posts" | `drafts:list --status published` |116| "Schedule this for tomorrow" | `drafts:create ... --schedule "2025-01-21T09:00:00Z"` |117| "Post this now" | `drafts:create ... --schedule now` or `drafts:publish <draft_id> --use-default` |118| "Add notes/ideas to the draft" | `drafts:create ... --scratchpad "Your notes here"` |119| "Check available tags" | `tags:list` |120| "Show my queue for next week" | `queue:get --start-date YYYY-MM-DD --end-date YYYY-MM-DD` |121122## Workflow123124Follow this workflow when creating posts:1251261. **Check if a default social set is configured**:127 ```bash128 ./scripts/typefully.js config:show129 ```130 If `default_social_set` shows an ID, skip to step 3.1311322. **If no default, list social sets** to find available options:133 ```bash134 ./scripts/typefully.js social-sets:list135 ```136 If multiple exist, ask the user which to use and offer to set it as default:137 ```bash138 ./scripts/typefully.js config:set-default139 ```1401413. **Create drafts** (social_set_id is optional if default is configured):142 ```bash143 ./scripts/typefully.js drafts:create --text "Your post"144 ```145 Note: If `--platform` is omitted, the first connected platform is auto-selected.146147 **For multi-platform posts**: See [Publishing to Multiple Platforms](#publishing-to-multiple-platforms) — always use a single draft, even when content differs per platform.1481494. **Schedule or publish** as needed150151## Working with Tags152153Tags help organize drafts within Typefully. **Always check existing tags before creating new ones**:1541551. **List existing tags first**:156 ```bash157 ./scripts/typefully.js tags:list158 ```1591602. **Use existing tags when available** - if a tag with the desired name already exists, use it directly when creating drafts:161 ```bash162 ./scripts/typefully.js drafts:create --text "..." --tags existing-tag-name163 ```1641653. **Only create new tags if needed** - if the tag doesn't exist, create it:166 ```bash167 ./scripts/typefully.js tags:create --name "New Tag"168 ```169170**Important**: Tags are scoped to each social set. A tag created for one social set won't appear in another.171172## Publishing to Multiple Platforms173174If a single draft needs to be created for different platforms, you need to make sure to create **a single draft** and not multiple drafts.175176When the content is the same across platforms, create a single draft with multiple platforms:177178```bash179# Specific platforms180./scripts/typefully.js drafts:create --platform x,linkedin --text "Big announcement!"181182# All connected platforms183./scripts/typefully.js drafts:create --all --text "Posting everywhere!"184```185186**IMPORTANT**: When content should be tailored (e.g., X thread with a LinkedIn post version), **still use a single draft** — create with one platform first, then update to add the other:187188```bash189# 1. Create draft with the primary platform first190./scripts/typefully.js drafts:create --platform linkedin --text "Excited to share our new feature..."191# Returns: { "id": "draft-123", ... }192193# 2. Update the same draft to add another platform with different content194./scripts/typefully.js drafts:update draft-123 --platform x --text "🧵 Thread time!195196---197198Here's what we shipped and why it matters..." --use-default199```200201So make sure to NEVER create multiple drafts unless the user explicitly wants separate drafts for each platform.202203## Commands Reference204205### User & Social Sets206207| Command | Description |208|---------|-------------|209| `me:get` | Get authenticated user info |210| `social-sets:list` | List all social sets you can access |211| `social-sets:get <id>` | Get social set details including connected platforms |212213### Drafts214215All drafts commands support an optional `[social_set_id]` - if omitted, the configured default is used.216**Safety note**: For commands that take `[social_set_id] <draft_id>`, if you pass only a single argument (the draft_id) while a default social set is configured, you must add `--use-default` to confirm intent.217218| Command | Description |219|---------|-------------|220| `drafts:list [social_set_id]` | List drafts (add `--status scheduled` to filter, `--sort` to order) |221| `drafts:get [social_set_id] <draft_id>` | Get a specific draft with full content (single-arg requires `--use-default` if a default is configured) |222| `drafts:create [social_set_id] --text "..."` | Create a new draft (auto-selects platform) |223| `drafts:create [social_set_id] --platform x --text "..."` | Create a draft for specific platform(s) |224| `drafts:create [social_set_id] --all --text "..."` | Create a draft for all connected platforms |225| `drafts:create [social_set_id] --file <path>` | Create draft from file content |226| `drafts:create ... --media <media_ids>` | Create draft with attached media |227| `drafts:create ... --reply-to <url>` | Reply to an existing X post |228| `drafts:create ... --community <id>` | Post to an X community |229| `drafts:create ... --share` | Generate a public share URL for the draft |230| `drafts:create ... --scratchpad "..."` | Add internal notes/scratchpad to the draft |231| `drafts:update [social_set_id] <draft_id> --text "..."` | Update an existing draft (single-arg requires `--use-default` if a default is configured) |232| `drafts:update [social_set_id] <draft_id> --tags "tag1,tag2"` | Update tags on an existing draft (content unchanged) |233| `drafts:update ... --share` | Generate a public share URL for the draft |234| `drafts:update ... --scratchpad "..."` | Update internal notes/scratchpad |235| `drafts:update [social_set_id] <draft_id> --append --text "..."` | Append to existing thread |236237### Scheduling & Publishing238239**Safety note**: These commands require `--use-default` when using the default social set with a single argument (to prevent accidental operations from ambiguous syntax).240241| Command | Description |242|---------|-------------|243| `drafts:delete <social_set_id> <draft_id>` | Delete a draft (explicit IDs) |244| `drafts:delete <draft_id> --use-default` | Delete using default social set |245| `drafts:schedule <social_set_id> <draft_id> --time next-free-slot` | Schedule to next available slot |246| `drafts:schedule <draft_id> --time next-free-slot --use-default` | Schedule using default social set |247| `drafts:publish <social_set_id> <draft_id>` | Publish immediately |248| `drafts:publish <draft_id> --use-default` | Publish using default social set |249250### Queue251252All queue commands support an optional `[social_set_id]` - if omitted, the configured default is used.253254The queue is a **social-set-specific timeline** made of:255- Queue slots generated from that social set's queue schedule256- Scheduled drafts/posts that belong to that same social set257258Use `queue:get` when the user asks what is already scheduled (or free) for a given account in a date range.259260| Command | Description |261|---------|-------------|262| `queue:get [social_set_id] --start-date <YYYY-MM-DD> --end-date <YYYY-MM-DD>` | Get the queue timeline for one social set: free queue slots plus scheduled drafts/posts in a date range |263| `queue:get ... --start_date <YYYY-MM-DD> --end_date <YYYY-MM-DD>` | Snake case aliases for date flags (copied from API docs) |264| `queue:schedule:get [social_set_id]` | Get queue schedule rules |265| `queue:schedule:put [social_set_id] --rules '[{"h":9,"m":30,"days":["mon","wed","fri"]}]'` | Replace queue schedule rules (full replacement) |266267### Tags268269| Command | Description |270|---------|-------------|271| `tags:list [social_set_id]` | List all tags |272| `tags:create [social_set_id] --name "Tag Name"` | Create a new tag |273274### Media275276| Command | Description |277|---------|-------------|278| `media:upload [social_set_id] <file_path>` | Upload media, wait for processing, return ready media_id |279| `media:upload ... --no-wait` | Upload and return immediately (use media:status to poll) |280| `media:upload ... --timeout <seconds>` | Set custom timeout (default: 60) |281| `media:status [social_set_id] <media_id>` | Check media upload status |282283### Setup & Configuration284285| Command | Description |286|---------|-------------|287| `setup` | Interactive setup - prompts for API key, storage location, and default social set |288| `setup --key <key> --location <global\|local>` | Non-interactive setup for scripts/CI (auto-selects default if only one social set) |289| `setup --key <key> --default-social-set <id>` | Non-interactive setup with explicit default social set |290| `setup --key <key> --no-default` | Non-interactive setup, skip default social set selection |291| `config:show` | Show current config, API key source, and default social set |292| `config:set-default [social_set_id]` | Set default social set (interactive if ID omitted) |293294## Examples295296### Set up default social set297```bash298# Check current config299./scripts/typefully.js config:show300301# Set default (interactive - lists available social sets)302./scripts/typefully.js config:set-default303304# Set default (non-interactive)305./scripts/typefully.js config:set-default 123 --location global306```307308### Create a tweet (using default social set)309```bash310./scripts/typefully.js drafts:create --text "Hello, world!"311```312313### Create a tweet with explicit social_set_id314```bash315./scripts/typefully.js drafts:create 123 --text "Hello, world!"316```317318### Create a cross-platform post (specific platforms)319```bash320./scripts/typefully.js drafts:create --platform x,linkedin,threads --text "Big announcement!"321```322323### Create a post on all connected platforms324```bash325./scripts/typefully.js drafts:create --all --text "Posting everywhere!"326```327328### Create and schedule for next slot329```bash330./scripts/typefully.js drafts:create --text "Scheduled post" --schedule next-free-slot331```332333### Create with tags334```bash335./scripts/typefully.js drafts:create --text "Marketing post" --tags marketing,product336```337338### List scheduled posts sorted by date339```bash340./scripts/typefully.js drafts:list --status scheduled --sort scheduled_date341```342343### Get queue view for a date range344```bash345./scripts/typefully.js queue:get --start-date 2026-02-01 --end-date 2026-02-29346```347348### Get queue schedule349```bash350./scripts/typefully.js queue:schedule:get351```352353### Replace queue schedule rules354```bash355./scripts/typefully.js queue:schedule:put --rules '[{"h":9,"m":30,"days":["mon","wed","fri"]}]'356```357358### Reply to a tweet359```bash360./scripts/typefully.js drafts:create --platform x --text "Great thread!" --reply-to "https://x.com/user/status/123456"361```362363### Post to an X community364```bash365./scripts/typefully.js drafts:create --platform x --text "Community update" --community 1493446837214187523366```367368### Create draft with share URL369```bash370./scripts/typefully.js drafts:create --text "Check this out" --share371```372373### Create draft with scratchpad notes374```bash375./scripts/typefully.js drafts:create --text "Launching next week!" --scratchpad "Draft for product launch. Coordinate with marketing team before publishing."376```377378### Upload media and create post with it379```bash380# Single command handles upload + polling - returns when ready!381./scripts/typefully.js media:upload ./image.jpg382# Returns: {"media_id": "abc-123-def", "status": "ready", "message": "Media uploaded and ready to use"}383384# Create post with the media attached385./scripts/typefully.js drafts:create --text "Check out this image!" --media abc-123-def386```387388### Upload multiple media files389```bash390# Upload each file (each waits for processing)391./scripts/typefully.js media:upload ./photo1.jpg # Returns media_id: id1392./scripts/typefully.js media:upload ./photo2.jpg # Returns media_id: id2393394# Create post with multiple media (comma-separated)395./scripts/typefully.js drafts:create --text "Photo dump!" --media id1,id2396```397398### Add media to an existing draft399```bash400# Upload media401./scripts/typefully.js media:upload ./new-image.jpg # Returns media_id: xyz402403# Update draft with media (456 is the draft_id)404./scripts/typefully.js drafts:update 456 --text "Updated post with image" --media xyz --use-default405```406407### Setup (interactive)408```bash409./scripts/typefully.js setup410```411412### Setup (non-interactive, for scripts/CI)413```bash414# Auto-selects default social set if only one exists415./scripts/typefully.js setup --key typ_xxx --location global416417# With explicit default social set418./scripts/typefully.js setup --key typ_xxx --location global --default-social-set 123419420# Skip default social set selection entirely421./scripts/typefully.js setup --key typ_xxx --no-default422```423424## Platform Names425426Use these exact names for the `--platform` option:427- `x` - X (formerly Twitter)428- `linkedin` - LinkedIn429- `threads` - Threads430- `bluesky` - Bluesky431- `mastodon` - Mastodon432433## Draft URLs434435Typefully draft URLs contain the social set and draft IDs:436```437https://typefully.com/?a=<social_set_id>&d=<draft_id>438```439440Example: `https://typefully.com/?a=12345&d=67890`441- `a=12345` → social_set_id442- `d=67890` → draft_id443444## Draft Scratchpad445446**When the user explictly asked to add notes, ideas, or anything else in the draft scratchpad, use the `--scratchpad` flag—do NOT write to local files!**447448The `--scratchpad` option attaches internal notes directly to the Typefully draft. These notes:449- Are visible in the Typefully UI alongside the draft450- Stay attached to the draft permanently451- Are private and never published to social media452- Are perfect for storing thread expansion ideas, research notes, context, etc.453454```bash455# CORRECT: Notes attached to the draft in Typefully456./scripts/typefully.js drafts:create 123 --text "My post" --scratchpad "Ideas for expanding: 1) Add stats 2) Include quote"457458# WRONG: Do NOT write notes to local files when the user wants them in Typefully459# Writing to /tmp/scratchpad/ or any local file is NOT the same thing460```461462## Automation Guidelines463464When automating posts, especially on X, follow these rules to keep accounts in good standing:465466- **No duplicate content** across multiple accounts467- **No unsolicited automated replies** - only reply when explicitly requested by the user468- **No trending manipulation** - don't mass-post about trending topics469- **No fake engagement** - don't automate likes, reposts, or follows470- **Respect rate limits** - the API has rate limits, don't spam requests471- **Drafts are private** - content stays private until published or explicitly shared472473When in doubt, create drafts for user review rather than publishing directly.474475**Publishing confirmation**: Unless the user explicitly asks to "publish now" or "post immediately", always confirm before publishing. Creating a draft is safe; publishing is irreversible and goes public instantly.476477## Tips478479- **Smart platform default**: If `--platform` is omitted, the first connected platform is auto-selected480- **All platforms**: Use `--all` to post to all connected platforms at once481- **Character limits**: X (280), LinkedIn (3000), Threads (500), Bluesky (300), Mastodon (500)482- **Thread creation**: Use `---` on its own line to split into multiple posts (thread)483- **Scheduling**: Use `next-free-slot` to let Typefully pick the optimal time484- **Cross-posting**: List multiple platforms separated by commas: `--platform x,linkedin`485- **Draft titles**: Use `--title` for internal organization (not posted to social media)486- **Draft scratchpad**: Use `--scratchpad` to attach notes to the draft in Typefully (NOT local files!) - perfect for thread ideas, research, context487- **Read from file**: Use `--file ./post.txt` instead of `--text` to read content from a file488- **Sorting drafts**: Use `--sort` with values like `created_at`, `-created_at`, `scheduled_date`, etc.489
Full transparency — inspect the skill content before installing.