Create, schedule, and manage social media posts via Typefully. ALWAYS use this skill when asked to draft, schedule, post, or check tweets, posts, threads, or social media content for Twitter/X, LinkedIn, Threads, Bluesky, or Mastodon.
Create, schedule, and manage social media posts via Typefully. ALWAYS use this skill when asked to draft, schedule, post, or check tweets, posts, threads, or social media content for Twitter/X, LinkedIn, Threads, Bluesky, or Mastodon.
category
distribution
layer
distribution
tier
must-have
reads
["brand/voice-profile.md","brand/audience.md"]
writes
["marketing/social/typefully/"]
depends-on
["content-atomizer"]
triggers
["tweet","thread","X post","Twitter post","schedule a tweet","Typefully","LinkedIn post","Threads post","Bluesky post","social-set"]
last-updated
2026-03-20T00:00:00.000Z
allowed-tools
Bash(./scripts/typefully.js:*)
Typefully Skill
Create, schedule, and publish social media content across multiple platforms using Typefully.
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.
Keeping This Skill Updated
This skill is managed by mktg. Run mktg update to get the latest version.
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
Requirements: Node.js 18+ (for built-in fetch API). No other dependencies needed.
Config priority (highest to lowest):
TYPEFULLY_API_KEY environment variable
./.typefully/config.json (project-local, in user's working directory)
~/.config/typefully/config.json (user-global)
Handling "API key not found" errors
CRITICAL: When you receive an "API key not found" error from the CLI:
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:
<skill-path>/scripts/typefully.js setup
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.
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
The setup command will interactively guide the user through configuration. Trust the CLI's error messages and follow their instructions.
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.
Social Sets
The 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.
The CLI supports a default social set - once configured, most commands work without specifying the social_set_id.
drafts:create ... --schedule now or drafts:publish <draft_id> --use-default
"Add notes/ideas to the draft"
drafts:create ... --scratchpad "Your notes here"
"Check available tags"
tags:list
Brand Integration
Before writing post content, check for brand/voice-profile.md in the project. If it exists, calibrate tone and vocabulary to the brand voice. This skill handles the Typefully integration — voice guidance comes from brand context.
If no brand files exist, proceed normally — the user provides the content directly or another skill handles voice.
Workflow
Follow this workflow when creating posts:
Check if a default social set is configured:
./scripts/typefully.js config:show
If default_social_set shows an ID, skip to step 3.
If no default, list social sets to find available options:
./scripts/typefully.js social-sets:list
If multiple exist, ask the user which to use and offer to set it as default:
./scripts/typefully.js config:set-default
Create drafts (social_set_id is optional if default is configured):
Only create new tags if needed - if the tag doesn't exist, create it:
./scripts/typefully.js tags:create --name "New Tag"
Important: Tags are scoped to each social set. A tag created for one social set won't appear in another.
Publishing to Multiple Platforms
If a single draft needs to be created for different platforms, you need to make sure to create a single draft and not multiple drafts.
When the content is the same across platforms, create a single draft with multiple platforms:
# Specific platforms
./scripts/typefully.js drafts:create --platform x,linkedin --text "Big announcement!"# All connected platforms
./scripts/typefully.js drafts:create --all --text "Posting everywhere!"
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:
# 1. Create draft with the primary platform first
./scripts/typefully.js drafts:create --platform linkedin --text "Excited to share our new feature..."# Returns: { "id": "draft-123", ... }# 2. Update the same draft to add another platform with different content
./scripts/typefully.js drafts:update draft-123 --platform x --text "🧵 Thread time!
---
Here's what we shipped and why it matters..." --use-default
So make sure to NEVER create multiple drafts unless the user explicitly wants separate drafts for each platform.
Commands Reference
User & Social Sets
Command
Description
me:get
Get authenticated user info
social-sets:list
List all social sets you can access
social-sets:get <id>
Get social set details including connected platforms
Drafts
All drafts commands support an optional [social_set_id] - if omitted, the configured default is used.
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.
Command
Description
drafts:list [social_set_id]
List drafts (add --status scheduled to filter, --sort to order)
drafts:get [social_set_id] <draft_id>
Get a specific draft with full content (single-arg requires --use-default if a default is configured)
drafts:create [social_set_id] --text "..."
Create a new draft (auto-selects platform)
drafts:create [social_set_id] --platform x --text "..."
Safety note: These commands require --use-default when using the default social set with a single argument (to prevent accidental operations from ambiguous syntax).
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!
The --scratchpad option attaches internal notes directly to the Typefully draft. These notes:
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.
# CORRECT: Notes attached to the draft in Typefully
./scripts/typefully.js drafts:create 123 --text "My post" --scratchpad "Ideas for expanding: 1) Add stats 2) Include quote"# WRONG: Do NOT write notes to local files when the user wants them in Typefully# Writing to /tmp/scratchpad/ or any local file is NOT the same thing
Output Logging
After scheduling or creating drafts, log what was done to maintain a paper trail:
Write a summary to marketing/social/typefully-log.md (append, don't overwrite):
## [Date] — [Campaign/Context]
| # | Draft ID | Platform | Scheduled | Text Preview (first 60 chars) |
|---|----------|----------|-----------|-------------------------------|
| 1 | draft-123 | x,linkedin | 2026-03-25T09:00:00Z | "Here's what we learned..." |
This ensures continuity across sessions — the agent can check what's already been scheduled.
Anti-Patterns
Anti-Pattern
Why It Fails
Instead
Creating multiple drafts for the same cross-platform post
Clutters the Typefully queue, can't be managed as one unit
Always use a single draft — create with one platform, then update to add others
Publishing without user confirmation
Irreversible, goes public instantly
Default to drafts. Only publish when user explicitly says "post now"
Searching keychains or .env files for API keys
Wastes time, security risk, unreliable
Tell user to run the setup command and wait
Writing scratchpad content to local files
Notes get lost, not attached to the draft in Typefully
Use --scratchpad flag to attach notes to the draft
Automation Guidelines
When automating posts, especially on X, follow these rules to keep accounts in good standing:
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
When in doubt, create drafts for user review rather than publishing directly.
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.
Tips
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.
