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.

1. API Key: Run the setup command to configure your API key securely
   • Get your key at https://typefully.com/?settings=api
   • Run:

     <skill-path>/scripts/typefully.js setup

     (where

     <skill-path>

     is the directory containing this SKILL.md)
   • Or set environment variable:

     export TYPEFULLY_API_KEY=your_key

2. Requirements: Node.js 18+ (for built-in fetch API). No other dependencies needed.

1. TYPEFULLY_API_KEY

   environment variable

2. ./.typefully/config.json

   (project-local, in user's working directory)

3. ~/.config/typefully/config.json

   (user-global)

1. 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:
   bash

   <skill-path>/scripts/typefully.js setup

2. 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.
3. DO NOT attempt any of the following:
   • Searching for API keys in macOS Keychain,

     .env

     files, or other locations
   • Grepping through config files or directories
   • Looking in the user's Trash or other system folders
   • Constructing complex shell commands to find credentials
   • Drafting content or preparing posts before setup is complete

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.

1. Check for a configured default first - Run

   config:show

   to see if a default is already set:
   bash

   ./scripts/typefully.js config:show

   If

   default_social_set

   is configured, the CLI uses it automatically when you omit the social_set_id.
2. Check project context - Look for configuration in project files like

   CLAUDE.md

   or

   AGENTS.md

   :
   markdown

   ## Typefully
   Default social set ID: 12345

3. Single social set shortcut - If the user only has one social set and no default is configured, use it automatically
4. Multiple social sets, no default - Ask the user which to use, then offer to save their choice as the default:
   bash

   ./scripts/typefully.js config:set-default

   This command lists available social sets and saves the choice to the config file.
5. Reuse previously resolved social set - If determined earlier in the session, use it without asking again

1. Check if a default social set is configured:
   bash

   ./scripts/typefully.js config:show

   If

   default_social_set

   shows an ID, skip to step 3.
2. If no default, list social sets to find available options:
   bash

   ./scripts/typefully.js social-sets:list

   If multiple exist, ask the user which to use and offer to set it as default:
   bash

   ./scripts/typefully.js config:set-default

3. Create drafts (social_set_id is optional if default is configured):
   bash

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

   Note: If

   --platform

   is omitted, the first connected platform is auto-selected.
   For multi-platform posts: See Publishing to Multiple Platforms — always use a single draft, even when content differs per platform.
4. Schedule or publish as needed

1. List existing tags first:
   bash

   ./scripts/typefully.js tags:list

2. Use existing tags when available - if a tag with the desired name already exists, use it directly when creating drafts:
   bash

   ./scripts/typefully.js drafts:create --text "..." --tags existing-tag-name

3. Only create new tags if needed - if the tag doesn't exist, create it:
   bash

   ./scripts/typefully.js tags:create --name "New Tag"

--platform

• x

  - X (formerly Twitter)

• linkedin

  - LinkedIn

• threads

  - Threads

• bluesky

  - Bluesky

• mastodon

  - Mastodon

https://typefully.com/?a=<social_set_id>&d=<draft_id>

https://typefully.com/?a=12345&d=67890

• a=12345

  → social_set_id

• d=67890

  → draft_id

--scratchpad

--scratchpad

• Are visible in the Typefully UI alongside the draft
• Stay attached to the draft permanently
• Are private and never published to social media
• Are perfect for storing thread expansion ideas, research notes, context, etc.

undefined

• No duplicate content across multiple accounts
• No unsolicited automated replies - only reply when explicitly requested by the user
• No trending manipulation - don't mass-post about trending topics
• No fake engagement - don't automate likes, reposts, or follows
• Respect rate limits - the API has rate limits, don't spam requests
• Drafts are private - content stays private until published or explicitly shared

• Smart platform default: If

  --platform

  is omitted, the first connected platform is auto-selected
• All platforms: Use

  --all

  to post to all connected platforms at once
• Character limits: X (280), LinkedIn (3000), Threads (500), Bluesky (300), Mastodon (500)
• Thread creation: Use

  ---

  on its own line to split into multiple posts (thread)
• Scheduling: Use

  next-free-slot

  to let Typefully pick the optimal time
• Cross-posting: List multiple platforms separated by commas:

  --platform x,linkedin

• Draft titles: Use

  --title

  for internal organization (not posted to social media)
• Draft scratchpad: Use

  --scratchpad

  to attach notes to the draft in Typefully (NOT local files!) - perfect for thread ideas, research, context
• Read from file: Use

  --file ./post.txt

  instead of

  --text

  to read content from a file
• Sorting drafts: Use

  --sort

  with values like

  created_at

  ,

  -created_at

  ,

  scheduled_date

  , etc.