Rajat Kapoor
051a266090
## What Adds planned-drafts support to the Typefully skill, matching the API v2 write support shipping in typefully-backend#1785. A **planned draft** sits on the queue/calendar at its date but is inert — it never auto-publishes until confirmed into a real schedule. ## Changes - **`--plan <iso|next-free-slot>`** on `drafts:create` and `drafts:update` → sends `plan_at`. Mutually exclusive with `--schedule` (friendly CLI error before hitting the API). On update, literal `null` clears the plan and returns the draft to plain draft status (same convention as `--cover-media-id null`). - **New `drafts:plan <social_set_id> <draft_id> --time <...>`** command mirroring `drafts:schedule`, including the `--use-default` single-arg safety gate. - **`drafts:list --status planned`** documented (the filter was already passed through; help text and docs now include it). - **SKILL.md**: planned lifecycle in the Schedule & publish section (confirm via `drafts:schedule`, publish via `drafts:publish`, lapsed planned dates are *not* failures — replan or confirm), a Common-actions row, flag/command table entries, and planned-aware `queue:get` description. - **CHANGELOG.md**: user-facing entry. ## Tests 6 new tests in `tests/drafts.test.js` covering: `drafts:plan` payload + missing `--time`, create with `--plan` (and no `publish_at` leak), the `--schedule`+`--plan` mutual-exclusion error, update with `--plan`, and `--plan null` sending `plan_at: null`. Full suite: **130 passed**. ## Notes - The backend PR (typefully-backend#1785) should merge/deploy first; until then `plan_at` is rejected by the API. - Not included (possible follow-up): an unschedule command (`publish_at: null`) — the CLI never had one and it's orthogonal to planned drafts. https://claude.ai/code/session_01267PabjVxa2EQueJ9oZoT9
Typefully Skills
AI agent skills for drafting, scheduling, and managing social media posts across X, LinkedIn, Threads, Bluesky, Mastodon, and Substack Notes. Give your AI agent the ability to manage your social media scheduling directly from your IDE or terminal.
Built on the Typefully API. Typefully is a writing and scheduling app used by 200k+ top creators and teams to grow on X, LinkedIn, Threads, and Bluesky.
What Are Skills?
Skills are markdown files that give AI agents specialized knowledge and workflows for specific tasks. Add this to your project and your AI agent will be able to create, schedule, and publish social media content.
Setup
1. Install the skill
CLI (works with Claude Code, Cursor, Windsurf, and many other agents):
npx skills add typefully/agent-skills
Other installation methods
Claude Code Plugin:
/plugin marketplace add typefully/agent-skills
Then:
/plugin install typefully@typefully-skills
Cursor:
- Open Settings (Cmd+Shift+J)
- Go to "Rules & Command" → "Project Rules"
- Click "Add Rule" → "Remote Rule (GitHub)"
- Enter:
https://github.com/typefully/agent-skills.git
Manual:
Clone this repository and copy skills/typefully/ to your project's .cursor/skills/ or .claude/skills/ directory.
2. Copy your API Key
You'll need a Typefully API key for the setup command. Copy an existing key or create a new one at https://typefully.com/?settings=api
3. Run the setup command
This configures your API key and default social set:
./scripts/typefully.js setup
Tip
The path depends on how you installed the skill, but you can ask your agent "Help me set up the Typefully skill" to get the correct path.
You can also set the API key as an environment variable instead:
export TYPEFULLY_API_KEY=your_key_here
4. Start using it
Ask your AI agent things like:
- "Draft a tweet about [topic]"
- "Create a LinkedIn post announcing [news]"
- "Schedule my draft for tomorrow morning"
- "Show my scheduled posts"
- "Create a thread about [topic]"
- "Post this to X and LinkedIn"
Local Development
To test this skill locally, install it from the repo root:
npx skills add .
Then test it in your agent to verify the latest local changes behave as expected.
Supported Platforms
- X (formerly Twitter)
- Threads
- Bluesky
- Mastodon
- Substack Notes
Troubleshooting
"TYPEFULLY_API_KEY environment variable is not set"
Run the setup command:
./scripts/typefully.js setup
Or set the environment variable manually:
export TYPEFULLY_API_KEY=your_key_here
To persist the environment variable across sessions, add it to your shell profile (~/.bashrc, ~/.zshrc, etc.).
"Node.js is required"
The CLI is a zero-dependency Node.js script and requires Node.js 18+ (for built-in fetch).
Install a recent Node.js version, then retry your command.
API errors (401, 403)
- Verify your API key is correct
- Check that your key has the required permissions at https://typefully.com/?settings=api
Drafts not appearing
- Make sure you're using the correct
social_set_id(run./scripts/typefully.js social-sets:listto list them) - Check the draft status with
./scripts/typefully.js drafts:list <social_set_id>
Alternative: MCP Server
For deeper integration with Claude Code, you can also use the Typefully MCP Server which provides native tool access:
https://support.typefully.com/en/articles/13128440-typefully-mcp-server
Links
License
MIT