Typefully

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

Source: github.com/typefully/agent-skills API docs: typefully.com/docs/api

Update methods by installation type:

| Installation | How to update | |--------------|---------------| | CLI (npx skills) | npx skills update | | Claude Code plugin | /plugin update typefully@typefully-skills | | Cursor | Remote rules auto-sync from GitHub | | Manual | Pull latest from repo or re-copy skills/typefully/ |

API changes ship independently—updating the skill ensures you have the latest commands and workflows.

Setup

Before using this skill, ensure:

1. API Key: Run the setup command to configure your API key securely

• Get your key at https://typefully.com/?settings=api
• Run: /scripts/typefully.js setup (where `` is the directory containing this SKILL.md)
• Or set environment variable: export TYPEFULLY_API_KEY=your_key

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

Config priority (highest to lowest):

1. TYPEFULLY_API_KEY environment variable
2. ./.typefully/config.json (project-local, in user's working directory)
3. ~/.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:

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 /scripts/typefully.js setup ``

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

1. 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 socialsetid.

You can pass the social set either way:

• Positional: drafts:list 123
• Flag: drafts:list --social-set-id 123 (also supports --social_set_id)

When determining which social set to use:

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 defaultsocialset` is configured, the CLI uses it automatically when you omit the socialsetid.

1. Check project context - Look for configuration in project files like CLAUDE.md or AGENTS.md:

``markdown ## Typefully Default social set ID: 12345 ``

1. Single social set shortcut - If the user only has one social set and no default is configured, use it automatically

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

1. Reuse previously resolved social set - If determined earlier in the session, use it without asking again

Common Actions

| User says... | Action | |--------------|--------| | "Draft a tweet about X" | drafts:create --text "..." (uses default social set) | | "Post this to LinkedIn" | drafts:create --platform linkedin --text "..." | | "Mention a company on LinkedIn" | linkedin:organizations:resolve --organization-url "" then use returned mention_text in drafts:create | | "Post to X and LinkedIn" (same content) | drafts:create --platform x,linkedin --text "..." | | "X thread + LinkedIn post" (different content) | Create one draft, then drafts:update to add platform (see [Publishing to Multiple Platforms](#publishing-to-multiple-platforms)) | | "What's scheduled?" | drafts:list --status scheduled | | "Show my recent posts" | drafts:list --status published | | "Schedule this for tomorrow" | drafts:create ... --schedule "2025-01-21T09:00:00Z" | | "Post this now" | drafts:create ... --schedule now or drafts:publish --use-default | | "Add notes/ideas to the draft" | drafts:create ... --scratchpad "Your notes here" | | "Check available tags" | tags:list | | "Check my publishing quota" | social-sets:get and inspect publishing_quota | | "Show my X post analytics for last week" | analytics:posts:list --start-date YYYY-MM-DD --end-date YYYY-MM-DD | | "Show my X post analytics including replies" | analytics:posts:list --start-date YYYY-MM-DD --end-date YYYY-MM-DD --include-replies | | "Show my X follower growth" | analytics:followers:get --start-date YYYY-MM-DD --end-date YYYY-MM-DD | | "Show my queue for next week" | queue:get --start-date YYYY-MM-DD --end-date YYYY-MM-DD | | "List comments on this draft" | comments:list | | "Comment on the phrase 'exciting news'" | comments:create --post-index 0 --selected-text "exciting news" --text "..." | | "Reply to that comment thread" | comments:reply --text "..." | | "Resolve / delete a comment thread" | comments:resolve / comments:delete | | "Get the draft without comment annotations" | drafts:get --exclude-comment-markers |

Workflow

Follow this workflow when creating posts:

1. Check if a default social set is configured:

``bash ./scripts/typefully.js config:show ` If defaultsocialset` shows an ID, skip to step 3.

1. 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 ``

1. Create drafts (socialsetid 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](#publishing-to-multiple-platforms) — always use a single draft, even when content differs per platform.

1. Schedule or publish as needed

Working with Tags

Tags help organize drafts within Typefully. Always check existing tags before creating new ones:

1. List existing tags first:

``bash ./scripts/typefully.js tags:list ``

1. 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 ``

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

``bash ./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.

LinkedIn Mentions

LinkedIn mentions are supported via text syntax inside post content:

@[Company Name](urn:li:organization:123456)

Use the resolver command to convert a public LinkedIn organization URL into ready-to-paste mention syntax:

# Resolve a LinkedIn URL into mention metadata
./scripts/typefully.js linkedin:organizations:resolve --organization-url "https://www.linkedin.com/company/typefullycom/"
# Returns mention_text like: @[Typefully](urn:li:organization:86779668)

Then include that mention_text in your LinkedIn draft text:

./scripts/typefully.js drafts:create --platform linkedin --text "Thanks @[Typefully](urn:li:organization:86779668) for the support."

Comments on Drafts

Drafts can have comment threads anchored to a selected span or to a whole paragraph. drafts:get returns posts[*].text with inline `` anchors by default so agents can preserve those anchors during edits.

Core rules for agents:

1. Preserve every comment anchor when patching draft text. Span anchors wrap selected text; self-closing anchors at the start of a paragraph are live comments on the whole following paragraph, not empty/resolved comments. When rewriting, move each anchor to the most semantically equivalent span or paragraph. Do not silently strip or drop anchors.
2. Do not resolve or delete comments without explicit user instruction. After editing text that may address feedback, ask whether to resolve the specific thread(s). Never infer that "clean up", "tidy", or "looks addressed" means resolve/delete.
3. Talk to users about comments, not marker syntax. Describe anchors in plain English, such as "comment on the word 'constraint'" or "comment on the paragraph starting with ...". Only mention marker syntax when explaining marker-related API errors or when the user asks how anchors work.

Default edit flow for drafts with comments: get the draft with anchors enabled, rewrite while preserving/repositioning every anchor, patch with drafts:update --text ... without force flags, then ask whether to resolve any addressed comments. Use comments:list --status all when you need thread ids, comment bodies, authors, or resolved status.

Use drafts:get --exclude-comment-markers only for display, LLM context, export, or preview text that will not be patched back.

Force Overwrite And Accepting Comments

--force-overwrite-comments is destructive: every unresolved thread whose anchor is missing from the submitted text is resolved server-side and stripped, including unrelated threads. Default: do not use it. If a PATCH fails because anchors do not match, fetch the draft with anchors, preserve every `` anchor, and patch again without force.

Only use --force-overwrite-comments when anchors truly cannot be preserved, such as a user-requested wholesale rewrite or an anchor with no reasonable new location. Before using it, run comments:list --status unresolved, tell the user which threads will be resolved and stripped (selected text + top comment), state that this cannot be undone via the API, and wait for an explicit "yes, proceed". Do not confirm and PATCH in the same turn.

When the user asks to accept/apply/address a comment, fetch without --exclude-comment-markers, identify the target thread, edit only that anchor's text (or the paragraph after a self-closing paragraph anchor), preserve every other anchor and unrelated text, then drafts:update without force flags. Ask before resolving the thread. If feedback is open-ended, propose wording or ask instead of inventing silently. For "accept all comments", batch only changes whose anchors can all be preserved.

| Command | Purpose | |---------|---------| | comments:list | List comment threads. Filters: --platform, --status (unresolved default / resolved / all), --limit, --offset | | comments:create --post-index --selected-text "..." --text "..." | Create a comment thread anchored on exact selected text. Optional: --platform, --occurrence | | comments:reply --text "..." | Add a reply to a thread | | comments:resolve | Resolve a thread, only after explicit user confirmation | | comments:update --text "..." | Edit a comment's text; comment-author only | | comments:delete [comment_id] | Delete a thread or one comment, only after explicit user instruction |

comments:create requires selected_text to exactly match the post text. If it repeats, pass zero-based --occurrence; for LinkedIn mentions, select the entire @[Name](urn:li:...) substring or stay outside it. Pass --platform only when the draft has multiple commentable platforms.

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 | Get social set details including connected platforms and publishing_quota | | linkedin:organizations:resolve [social_set_id] --organization-url | Resolve LinkedIn company/school URL into mention metadata (mention_text, urn) |

social-sets:get returns a publishing_quota object when available:

• used - published drafts already counted in the current quota window
• remaining - remaining publish slots, or "unlimited"
• resets_at - when the current quota window resets

Use it before publishing/scheduling when the user asks about remaining posting capacity or when a publish/schedule request fails with quota copy.

Analytics

All analytics commands support an optional [social_set_id] - if omitted, the configured default is used.

The public API currently supports X analytics only on these endpoints. The CLI defaults --platform to x, so you can usually omit it.

Replies are now excluded by default so the result set matches the main published-post view more closely. Add --include-replies when you explicitly want reply posts included.

Analytics responses return post-level metrics for the requested inclusive date range, including:

• impressions
• engagement totals and breakdowns like likes, comments, shares, quotes, saves, profile_clicks, and link_clicks

Follower analytics returns current_followers_count plus daily data points with date and followers_count. If you omit dates, the API returns the default recent range.

| Command | Description | |---------|-------------| | analytics:posts:list [social_set_id] --start-date --end-date | List X posts with normalized analytics metrics for an inclusive date range | | `analytics:posts:list ... --st

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: typefully
• Source: typefully/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.