Postey

Postey Skill

Create, schedule, and publish social media content across multiple platforms using Postey.

Capability Comes From the Server, Not From This File

postey://skill-manifest describes the live surface — every tool, resource, prompt and platform the server actually serves. When what you need is not obvious, read it rather than guessing from this document. Each tool entry carries three fields that settle routing on their own:

The rule: reach a capability through its canonical provider. If superseded_by is set, follow it — that field is why you do not need to parse [FALLBACK ONLY — READ … INSTEAD] out of a description. Where a resource and a tool serve one capability, the resource is canonical.

The one exception is a client that cannot read MCP resources. Then the superseded tool is correct precisely because the canonical provider is unreachable — that is what the fallbacks are for.

capability-snapshot.json in this directory is the same data, captured offline for the CLI and CI. Read the live resource when you can; the snapshot is a mirror, and a mirror can be one deploy stale.

Tool Routing — Read Before Any Tool Call

Two surfaces exist — MCP tools/resources and the CLI (postey.js) — and they are layers, not alternatives. MCP owns every read and every write. The CLI owns only what needs the user's machine, and it has no write command: its local-file commands upload and hand back the fields for an MCP write. A workflow uses whichever surface owns each step.

An installed skill is not a working setup. This file loads from disk whether or not the server is reachable. If the Postey tools are absent from your session, stop and say so. There is no command here that reaches Postey state, so looking for one wastes the user's time.

Say what to do next, rather than only that you are stuck. The server address is https://srvr.postey.ai/mcp, registered natively in your own client — never behind a local bridge. A client that can open a browser finishes OAuth. A browserless one (CI, container, cron) cannot: there is no client_credentials grant, so it needs an MCP key (mk_…) sent as X-API-Key, and you cannot create that key yourself. Per-client registration commands and config paths: https://raw.githubusercontent.com/posteyai/skills/main/setup.md. The key steps: references/mcp-authentication.md.

Decision Tree

1. Local file path involved (~/video.mp4, ./cover.jpg)? → CLI only — MCP cannot access the local filesystem.

2. Video transcription (yt-dlp + Whisper)? → node ${CLAUDE_SKILL_DIR}/scripts/postey.js video transcribe <url> — preferred wherever the CLI runs. Connector-only clients (no CLI) use the transcribe_video MCP tool instead.

3. Read-only state (accounts, teams, post content)? → MCP resource — fast, cached, no subprocess:

   • Accounts → postey://accounts
   • Teams → postey://teams
   • Post content → postey://posts/{id}/content/{platform}
   • Prefer a resource URI over the equivalent read tool (e.g. postey://accounts over get_accounts) whenever your client can read MCP resources; resource-blind clients (many hosted connectors) use the tools. Reads with no resource equivalent (post listings → get_posts) always use the tool.

4. Content validation or virality review before publishing? → MCP tools — validate_post_content, review_post — no CLI equivalent; do not skip these in any MCP-capable session.

5. All other writes (create, update, publish, schedule, delete, tag, upload by URL)? → MCP tools, in every environment — create_post, update_post, publish_draft, schedule_post, delete_draft. → There is no second path. Where no MCP server is reachable the write cannot be done at all — say so and stop; do not reach for a CLI command that does not exist.

Routing Table

Anti-Patterns

• Never call get_accounts when your client can read MCP resources — read postey://accounts instead. Resource-blind clients (many hosted connectors) may use the tool.
• Never call upload_media for a local file — it accepts URLs only.
• Never skip validate_post_content / review_post in any MCP-capable session.
• Never use CLI drafts:create / drafts:publish / drafts:schedule — these commands are removed; use MCP tools. The same holds in CI/CD, Cursor, Windsurf and SDK agents: without an MCP server there is no write path, not a CLI one.
• Never call REST endpoints directly (e.g. GET /accounts) — always use MCP resources or tools.
• Never guess or invent an account_id — always read the accounts (postey://accounts, or get_accounts for resource-blind clients) and confirm with the user.
• Never run postey.js accounts:list — that command does not exist; read postey://accounts (or call get_accounts).

Setup

1. MCP key — Ask the user to create one at https://app.postey.ai?settings=agents&section=advanced — that is AI & Agents → Advanced, and the key it mints never expires and works on every plan. ?settings=api opens Integrations instead, where the plan-gated general-purpose keys live. Then:

   ${CLAUDE_SKILL_DIR}/scripts/postey.js setup
   

   Or set env var: export POSTEY_API_KEY=your_key

2. Requirements — Node.js 18+. No other dependencies for the core CLI.

Config priority (highest to lowest):

1. POSTEY_API_KEY environment variable
2. POSTEY_AUTH_TOKEN environment variable — a bearer token the MCP server sets when it runs this CLI for an OAuth-authenticated caller. Not something you set by hand.
3. OAuth session from postey.js auth:login
4. A linked credential from postey.js auth:link — the CLI copying the access this connection already has. This is what setup.md Step 5 sets up.
5. ./.postey/config.json (project-local) — only honoured in the directory it was created for. A config that arrived by clone or copy is ignored, because a repo that commits one would otherwise supply the credential and the default account silently. Re-run setup --key <key> --location local there, or set POSTEY_TRUST_LOCAL_CONFIG=1.
6. ~/.config/postey/config.json (user-global)

When "API key not found" appears

If your client is already connected to the MCP server, run postey.js auth:link --begin and call the link_cli tool with the code it prints — that copies this connection's access to the CLI and needs no second sign-in. Otherwise tell the user to run the setup command interactively; you cannot run it on their behalf, so stop and wait. Never run bare setup unattended: it prompts on stdin. Do not look for credentials in keychains, .env files, or config directories.

Account Selection

Before any write operation, Claude must know which account to target. Follow this sequence every time:

1. Read postey://accounts — call the get_accounts tool only if your client cannot read MCP resources (many hosted connectors cannot).
2. One account → use it silently without prompting the user.
3. Multiple accounts → display them and ask the user which one to use.
4. Pass account_id to create_post, schedule_post, publish_draft, etc.

Account fields returned by postey://accounts:

The per-platform keys are lowercase slugs (twitter for X; otherwise the platform's own name). Read them from the payload — do not assume the set. This table listed seven and the server served nine, so two connected platforms were invisible to the skill.

Deriving a display handle (for showing to the user): each connected platform object carries its own identifier field — usually username, sometimes a platform-specific one (vanity_name on LinkedIn, handle on Bluesky). Read the object and use what is there rather than assuming a field name; a missing key means that platform is not connected, not that the handle is blank.

Hard rules:

• ✗ Never call get_accounts when your client can read MCP resources — read postey://accounts instead. Resource-blind clients may use the tool.
• ✗ Never invent or assume an account_id — always read the accounts (resource or tool) and confirm.
• ✗ Never call GET /accounts or any REST endpoint directly — use MCP only.
• ✗ Never run postey.js accounts:list — that CLI command does not exist.

Accounts & Defaults

• CLI commands that act on an account take a positional account_id (e.g. video post 123 --video ...). See command-reference.md for the full argument list.

Common Actions

Workflow

1. Check config: ${CLAUDE_SKILL_DIR}/scripts/postey.js config:show
2. Find account: MCP resource postey://accounts
3. Create draft: MCP create_post
4. Schedule or publish: MCP schedule_post or publish_draft

The full sequences — create/validate/tag/publish, partial draft updates, repurposing, media and video path selection, tagging, and the fields you must ask the user for rather than guess — are in references/mcp-workflows.md. That guidance used to be sent by the MCP server on every single request; it lives here now, loaded when you need it.

Working with Tags

Pass tag IDs via the tags field on MCP create_post. Use MCP add_tag to attach tags to an already-created post.

Publishing to Multiple Platforms

One post_id per topic — never create separate drafts for different platforms on the same content.

Same content across platforms

mcp create_post account_id=<id> platform=X additional_platforms=[LINKEDIN] contents=[{text: "..."}]

Different content per platform

# Step 1 — Create initial draft
mcp create_post account_id=<id> platform=INSTAGRAM contents=[{text: "<instagram_caption>"}]
# Returns post_id, e.g. 1234

# Steps 2–N — Attach each additional platform (same post_id)
mcp update_post post_id=1234 platform=LINKEDIN contents=[{text: "<linkedin_caption>"}]
mcp update_post post_id=1234 platform=X contents=[{text: "<twitter_caption>"}]

Platform Names

--platform takes the server's uppercase slug. Do not work from a list in this file — this table used to exist and silently drifted to seven entries while the server served nine, so the skill told users Facebook and Pinterest did not exist.

Resolve the set instead:

• Which platforms exist — postey://platform-limits, or capability-snapshot.json in this skill directory (generated from the server; the CLI reads the same file).
• Per-platform rules — postey://platforms/{platform}/rules for character limits, counting rules, threading and banned words. Never hardcode a limit; they change per platform.
• Which platforms this account can actually post to — read postey://accounts and use the connection status. A platform existing on the server does not mean it is connected here.

Direct Video Posting

Use video post when you have a caption ready and want the video (and its cover) uploaded in one command (no transcription). It returns media_urls, cover_url and the rest of the fields for MCP create_post — it does not create the draft itself, and it rejects --publish-now / --schedule because publishing and scheduling are MCP's.

No caption yet? Run video transcribe first — it returns a transcript and suggested_captions per platform. Refine those captions (see prompts.md) then pass the result to video post --text or create_post. Never paste a raw transcript as a caption.

Requires: ffmpeg on PATH for Instagram cover thumbnail extraction.

${CLAUDE_SKILL_DIR}/scripts/postey.js video post <account_id> \
  --video <local_path_or_https_url> \
  --text "<caption>" \
  --platforms INSTAGRAM,LINKEDIN,X \
  [--cover-time <seconds>]   # default: 3
  [--title "Draft title"]

Video → Captions → Cross-Post

Transcription is postey-video's — install that pack for it. Uploading a video or image from local disk is this skill's: see video-workflow.md. For platform-specific caption rules, see prompts.md.

Content Flows

This skill includes four guided content workflows. Offer them when the user connects for the first time, asks what you can do, or gives an open-ended content request. Load the flow's reference file only when the user picks it; never install or load all of them up front.

House rules for every flow (non-negotiable):

1. Know the accounts first, every session: read postey://accounts, or call get_accounts if your client cannot read MCP resources. Connected platforms are read, never assumed.
2. Everything is created as a DRAFT. Publishing needs the user's explicit instruction, and scheduling counts as publishing (a scheduled post publishes itself): propose times, call schedule_post only after the user approves both content and times, with times at least 10 minutes in the future in UTC ISO-8601.
3. Every platform gets its own hand-crafted caption. One idea, many voices. Use the documented per-platform sequence ("Publishing to Multiple Platforms" above): create_post for the primary platform with its caption, then one update_post per remaining platform with that platform's caption — same post_id throughout.
4. Verify each platform after creating — read postey://posts/{id}/content/{platform} (or call get_post_content if your client cannot read resources) — and run validate_post_content per platform, then fix before presenting.
5. End every flow by giving the user the draft's share link.
6. Tag agent-created posts: an agent tag (default Agent, ask the user once if they prefer another name) plus 2 or 3 topic tags. add_tag is get-or-create by exact name, so reusing the same spelling never creates a duplicate — keep tag names consistent across sessions and reuse the tag names visible on recent posts (get_posts returns each post's tags) instead of inventing near-duplicates. remove_tag undoes a mis-tag.

Ships in names the skill that carries each flow. A flow whose pack is not installed is not available — say so and offer the ones that are, rather than improvising the flow from memory. CI (scripts/check-pack-discovery.js) fails if this table advertises a pack that does not exist.

The craft layer always ships here, in the hub, because every flow cites it — wherever the flow itself lives: references/caption-playbook.md (universal rules and pre-upload checklist), references/platform-archetypes.md, references/post-structures.md (the 18 structures, each with the condition that selects it and the way it fails — read this when choosing a shape, before drafting), references/hook-formulas.md, references/x-algorithm.md, references/thread-and-video-formats.md, and references/brand-profile-template.md (the schema for the per-brand profile every flow reads before drafting).

First-run greeting: after verifying accounts, offer the flows this installation actually has in one short list and run whichever the user picks. Two minutes to a share link is the goal.

Automation Guidelines

• No duplicate content across multiple accounts
• No unsolicited automated replies
• No trending manipulation or fake engagement
• Respect API rate limits
• Never publish or schedule without the user's explicit yes in the current turn. Scheduling counts as publishing, because a scheduled post publishes itself. "Post this now" asks for a draft you then show them — it approves the intent, never text they have not seen. Show the exact per-platform copy and wait. Publishing is irreversible and public; drafts are private.

Tips

• Thread creation: use --- on its own line to split into multiple posts
• Scheduling: ISO 8601 UTC strings on MCP schedule_post — the CLI has no scheduling flag
• Draft titles: --title on video post is for internal organization, not posted publicly

Reference

• MCP workflow sequencing, media/video path choice, tagging, what to ask before you guess: references/mcp-workflows.md
• OAuth scopes, the MCP-key path and the agent-token mint endpoints: references/mcp-authentication.md
• Connecting the server itself — address, per-client registration, config paths: https://raw.githubusercontent.com/posteyai/skills/main/setup.md
• Full command reference: command-reference.md
• Video transcription workflow: video-workflow.md
• Platform caption templates: prompts.md
• Routing rules (extended): routing-guide.md
• Content flows and playbooks: references/ (see Content Flows above)
• Pack manifest for fetch-based install: pack.json
• One-paste agent setup: bootstrap-prompt.md