# postey

Adopt this skill: https://proskills.md/skills/other/posteyai-skills-skills-postey

Page: https://proskills.md/skills/other/posteyai-skills-skills-postey
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/postey/SKILL.md
size: 26338
sha: f5b53cfb85c0ec293bef0659b47d7d10110c838a
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/SKILL.md

````text
---
name: postey
version: 3.2.3
# No `platforms:` list. The platform set lives on the server and is mirrored into
# capability-snapshot.json by scripts/refresh-capability-snapshot.js. A copy here
# would be a fourth hand-maintained list agreeing with the other three and with
# nothing that ships (S9.5).
description: >
  Create, schedule, and manage social media posts via Postey across X, LinkedIn,
  Instagram, TikTok, YouTube, Threads, Bluesky, Facebook, and Pinterest. The hub:
  accounts, platform truth, the post lifecycle, and the shared craft layer that
  decides how a post is written — plus the local-file and large-upload paths the
  MCP server cannot reach. Content flows ship as optional packs that require this
  one: install `postey-video` to transcribe a video and turn it into per-platform
  posts, `postey-ideas` to decide what to post.
when_to_use: >
  Use when asked to: draft a tweet, post to LinkedIn, create a thread, schedule
  content, publish a post, check scheduled or published posts, upload a video or
  image from local disk to Instagram/TikTok/YouTube, cross-post to multiple
  platforms, manage social drafts, or any social media publishing task. Transcribing
  a video into captions belongs to `postey-video`; deciding what to post belongs to
  `postey-ideas`; confirming something actually went out belongs to `postey-ops`.
allowed-tools:
  - Bash(${CLAUDE_SKILL_DIR}/scripts/postey.js:*)
mcp-tools:
  resources:
    - postey://accounts
    - postey://teams
    - postey://posts/{post_id}/content/{platform}
    - postey://platform-limits
    - postey://platforms/{platform}/rules
    - postey://platforms/{platform}/actions
    - postey://posts/{post_id}/analytics
    - postey://accounts/{account_id}
    - postey://teams/{team_id}/members
    - postey://skill-manifest
  tools:
    # GENERATED from capabilities: by scripts/gen-mcp-tools.js — do not hand-edit.
    - add_tag
    - connect_account
    - convert_post_content
    - create_post
    - delete_draft
    - file_manager
    - get_posts
    - get_review_status
    - get_schedule
    - link_cli
    - list_files
    - publish_draft
    - read_file
    - remove_tag
    - review_post
    - schedule_post
    - transcribe_video
    - unschedule_post
    - update_post
    - update_schedule
    - upload_media
    - validate_post_content
    # Fallbacks only: each is superseded by a postey:// resource this skill
    # declares. Use them when the client cannot read MCP resources.
    - get_accounts
    - get_post_content
  prompts:
    - compose-post
    - review-for-virality
    - repurpose-content
    - improve-post
    - analyze-engagement
    - generate-captions-from-transcript
    - generate-captions-batch
# Capability-keyed ownership. Keys are `canonical` entries from
# capability-snapshot.json — the server's vocabulary, never raw tool names, so this
# cannot drift into a second hand-kept list (S9.5). `owns` is exclusive: exactly one
# skill may own a key. `reads` is shared. Contract: docs/skills-mcp-contract.md.
#
# Every capability the server exposes now has an owner; the unclaimed allowlist is
# empty and check-capability-contract keeps it that way. Claiming a key this skill
# does not actually document would defeat the coverage check.
capabilities:
  owns:
    # Accounts, platform truth, setup — the hub's operations layer
    - account.connect
    - account.list
    - account.read
    - account.tags
    - platform.limits
    - platform.rules
    - platform.actions
    - server.manifest
    - setup.read
    - cli.link
    # Authoring and the post lifecycle
    - post.create
    - post.read
    - post.list
    - post.update
    - post.delete
    - post.convert
    - post.review
    - post.review.status
    - post.validate
    - post.tag.add
    - post.tag.remove
    - publish.now
    - schedule.create
    - schedule.read
    - schedule.update
    - schedule.delete
    # Media and local files (the only capability the CLI may hold)
    - media.upload
    - file.list
    - file.read
    - file.upload
  reads:
    - media.transcribe
  prompts:
    - compose-post
    - review-for-virality

# Machine-readable routing rules (mirrors routing-guide.md; used by CI and agents).
# Values: a single path, or "primary > fallback" — use the fallback only when
# your client lacks the primary capability (cannot read MCP resources, or has
# no CLI/shell). Paths: mcp-resource | mcp-tool | cli
routing:
  read-only-state:     mcp-resource > mcp-tool  # postey://... resources; resource-blind clients use get_* read tools
  platform-limits:     mcp-resource  # postey://platform-limits / postey://platforms/{p}/rules
  analytics:           mcp-resource  # postey://posts/{id}/analytics
  validation:          mcp-tool      # validate_post_content (no CLI equivalent)
  virality-review:     mcp-tool      # review_post
  comment-read:        mcp-tool      # get_platform_comments / get_internal_comments
  convert-content:     mcp-tool      # convert_post_content
  write-post:          mcp-tool      # create/update/publish/schedule/delete → MCP tools, in EVERY environment
  local-file:          cli           # any local path → unconditional CLI (video post); the write that follows is still mcp-tool
  video-transcription: cli > mcp-tool  # postey.js video transcribe; connector-only clients use transcribe_video
  fallback:            mcp-tool      # unknown operations → MCP; the CLI only holds local-machine commands
---

# Postey Skill

Create, schedule, and publish social media content across multiple platforms using [Postey](https://postey.ai).

## 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:

| Field | Meaning |
|-------|---------|
| `capability` | What the tool is *for*, as `noun.verb` (`post.create`, `account.list`) |
| `canonical` | `true` = the intended way to reach that capability |
| `superseded_by` | On a non-canonical tool, the URI or tool you should call instead |

**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://mcp.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](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. `review_post` returns a `job_id` and runs 60-120 seconds; collect the result with `get_review_status` (by `job_id`, or `post_id` if the handle was lost), repeating while `status` is `running`.

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

| Trigger | Tool | Reason |
|---------|------|--------|
| `--file <local-path>` or `--video <local-path>` | CLI only (`video post`) | MCP has no filesystem access |
| Video transcription workflow | CLI preferred; `transcribe_video` MCP tool for connector-only clients | Local pipeline needs yt-dlp, ffmpeg, Whisper |
| Read accounts / teams / post content | MCP resource | Cached, no subprocess overhead |
| Validate content before posting | MCP tool | No CLI equivalent |
| Virality review | MCP tool | No CLI equivalent |
| Create / update / publish / schedule / delete | MCP tool | `create_post`, `update_post`, `publish_draft`, `schedule_post`, `delete_draft` |
| Get single draft content | MCP | `postey://posts/{id}/content/{platform}`, or `get_post_content` |
| Cursor, SDK agent, CI/CD environment | Same as above — unchanged | The environment decides whether the CLI is *available*, never who owns the operation |

### 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:
   ```bash
   ${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`:**

| Field | Type | Notes |
|-------|------|-------|
| `account_id` | int | Required by all write tools |
| `account_name` | str \| null | Human-readable label |
| `teams` | list[int] \| null | Team IDs this account belongs to |
| *one key per platform* | object \| null | Non-null = that platform is connected |

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](command-reference.md) for the full argument list.

## Common Actions

| User says… | Action |
|------------|--------|
| "Draft a tweet about X" | MCP `create_post` |
| "Post this to LinkedIn" | MCP `create_post` with `platform=LINKEDIN` |
| "Post to X and LinkedIn" (same content) | MCP `create_post` with multiple platforms |
| "X thread + LinkedIn post" (different content) | MCP `create_post` → MCP `update_post` per additional platform |
| "What's scheduled?" | MCP `get_posts` with `status=SCHEDULED` |
| "Show my recent posts" | MCP `get_posts` with `status=PUBLISHED` |
| "Schedule this for tomorrow" | MCP `create_post` then MCP `schedule_post` |
| "Post this now" | MCP `create_post` then MCP `publish_draft` |
| "Make captions from this reel: \<url\>" | `postey.js video transcribe <url>` → apply Caption Generation Guide → MCP `create_post` |
| "Upload video to Instagram/TikTok/YouTube" | `postey.js video post` (local file) or `postey.js video transcribe <url>` (remote URL) |
| User provides a video but no caption | Run `video transcribe` first → refine `suggested_captions` → `video post --text` or `create_post` |

## 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](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](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.

```bash
${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"]
```

| Platform | Video attached | Cover thumbnail |
|----------|---------------|-----------------|
| `INSTAGRAM` | Yes (Reel) | Yes — ffmpeg frame extraction |
| All others | No | No |

## 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](video-workflow.md).
For platform-specific caption rules, see [prompts.md](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.

| Flow | The user says something like | Ships in | Load |
|------|------------------------------|----------|------|
| Brand voice | "Learn my voice", "write like me", a handle or website | `postey-voice` | that pack's own flow file |
| Video everywhere | a video URL, "post this video everywhere" | `postey-video` | that pack's own flow file |
| Trends | "what should I post today?", "find something trending" | `postey-ideas` | that pack's own flow file |
| Idea to posts | one rough idea, "turn this into posts" | `postey-ideas` | that pack's own flow file |

**The craft layer always ships here**, in the hub, because every flow cites it — wherever the flow
itself lives: [references/caption-playbook.md](references/caption-playbook.md) (universal rules and
pre-upload checklist), [references/platform-archetypes.md](references/platform-archetypes.md),
[references/post-structures.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/hook-formulas.md), [references/x-algorithm.md](references/x-algorithm.md),
[references/thread-and-video-formats.md](references/thread-and-video-formats.md), and
[references/brand-profile-template.md](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](references/mcp-workflows.md)
- OAuth scopes, the MCP-key path and the agent-token mint endpoints:
  [references/mcp-authentication.md](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](command-reference.md)
- Video transcription workflow: [video-workflow.md](video-workflow.md)
- Platform caption templates: [prompts.md](prompts.md)
- Routing rules (extended): [routing-guide.md](routing-guide.md)
- Content flows and playbooks: [references/](references/) (see Content Flows above)
- Pack manifest for fetch-based install: [pack.json](pack.json)
- One-paste agent setup: [bootstrap-prompt.md](bootstrap-prompt.md)
````

## File: skills/postey/README.md
size: 2529
sha: 3136490fff27029a28b2b917d6faf402d0af5b98
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/README.md

```text
# Postey for Claude

Postey lets Claude draft, schedule and publish social media posts on X, LinkedIn, Instagram, TikTok, YouTube, Threads, Bluesky, Facebook and Pinterest from your Postey account (https://postey.ai).

Write one idea and Claude reshapes it for each network against that network's real limits. Everything stays a draft until you say publish. Scheduling counts as publishing, so Claude asks for an explicit yes before it schedules anything. Every task ends with a share link you can send to a reviewer.

## What's in the plugin

- **Postey MCP server**: the hosted, remote server at `https://mcp.postey.ai/mcp`. You sign in to your Postey account with OAuth in your browser the first time you use it. Nothing is installed locally.
- **`postey` skill** (`SKILL.md` and `references/`): accounts, platform limits, the post lifecycle, and the writing guidance (hooks, captions, post structures) Claude uses to shape each draft.
- **Optional CLI** (`scripts/postey.js`, plain readable Node.js): only used in Claude Code when you ask for something the hosted server can't reach, such as uploading a video or image from your local disk.

Optional packs that build on this plugin: `postey-video`, `postey-ideas`, `postey-ops`, `postey-analytics`, `postey-voice`, `postey-teams` and `postey-engagement`.

## Requirements

- A Postey account (https://app.postey.ai) with at least one social account connected.
- Claude with connectors enabled, or Claude Code.

## Example prompts

- "Draft a post about our launch and show me a version for each of my platforms."
- "What's scheduled this week?"
- "Upload ~/Videos/demo.mp4 as an Instagram Reel draft with a caption."

## What it runs, sends and fetches

- The MCP server and the CLI talk only to Postey's own services: `mcp.postey.ai`, `srvr.postey.ai` (API and sign-in) and `app.postey.ai`.
- The CLI signs in with OAuth: it opens your browser and listens on a localhost callback port. If you set `POSTEY_API_KEY` or `POSTEY_AUTH_TOKEN` in your environment, the CLI sends that Postey credential to `srvr.postey.ai` only.
- For video workflows the CLI can run `ffmpeg`/`ffprobe` locally, if they're installed, to check media and make a cover image.
- No data goes to any other service. The plugin doesn't read your chat history, or any file you haven't asked it to use.

## Privacy and support

- Privacy policy: https://postey.ai/policies/privacy
- Terms: https://postey.ai/policies/terms
- Support: support@postey.ai · https://postey.ai/policies/support

## License

MIT
```

## File: skills/postey/scripts/mediaValidator.js
size: 8124
sha: 43928c12b535f4d1c3270833eafe3c0bb78ba106
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/scripts/mediaValidator.js

```text
'use strict';

const fs = require('fs');
const path = require('path');
const { spawnSync } = require('child_process');

const MIME_TYPES = {
  '.mp4':  'video/mp4',
  '.mov':  'video/quicktime',
  '.avi':  'video/x-msvideo',
  '.webm': 'video/webm',
  '.mkv':  'video/x-matroska',
  '.3gp':  'video/3gpp',
  '.flv':  'video/x-flv',
  '.wmv':  'video/x-ms-wmv',
  '.m4v':  'video/mp4',
  '.jpg':  'image/jpeg',
  '.jpeg': 'image/jpeg',
  '.png':  'image/png',
  '.gif':  'image/gif',
  '.webp': 'image/webp',
};

// Per-platform media constraints (ported from MediaValidatorSingleton)
const PLATFORM_MEDIA_CONSTRAINTS = {
  X: {
    video: {
      maxSizeBytes: 512 * 1024 * 1024,
      maxDurationSeconds: 140,
      minDurationSeconds: 0.5,
      allowedMimeTypes: ['video/mp4', 'video/quicktime'],
      maxWidth: 1920, maxHeight: 1200,
      minWidth: 32,   minHeight: 32,
      maxFrameRate: 60,
    },
    image: {
      maxSizeBytes: 5 * 1024 * 1024,
      allowedMimeTypes: ['image/jpeg', 'image/png', 'image/gif', 'image/webp'],
    },
    gif: {
      maxSizeBytes: 15 * 1024 * 1024,
      allowedMimeTypes: ['image/gif'],
    },
  },
  INSTAGRAM: {
    video: {
      maxSizeBytes: 650 * 1024 * 1024,
      maxDurationSeconds: 90,
      minDurationSeconds: 3,
      allowedMimeTypes: ['video/mp4', 'video/quicktime'],
      maxWidth: 1920, maxHeight: 1920,
      minWidth: 320,  minHeight: 320,
      maxFrameRate: 60,
      minAspectRatio: 9 / 16,
      maxAspectRatio: 16 / 9,
    },
    image: {
      maxSizeBytes: 8 * 1024 * 1024,
      allowedMimeTypes: ['image/jpeg', 'image/png'],
      minAspectRatio: 4 / 5,
      maxAspectRatio: 1.91,
    },
  },
  TIKTOK: {
    video: {
      maxSizeBytes: 287 * 1024 * 1024,
      maxDurationSeconds: 600,
      minDurationSeconds: 3,
      allowedMimeTypes: ['video/mp4', 'video/webm', 'video/quicktime'],
      maxWidth: 4096, maxHeight: 4096,
      minWidth: 360,  minHeight: 360,
      maxFrameRate: 60,
    },
    image: {
      maxSizeBytes: 20 * 1024 * 1024,
      allowedMimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
    },
  },
  LINKEDIN: {
    video: {
      maxSizeBytes: 5 * 1024 * 1024 * 1024,
      maxDurationSeconds: 900,
      minDurationSeconds: 3,
      allowedMimeTypes: ['video/mp4', 'video/quicktime', 'video/x-msvideo', 'video/webm'],
      maxWidth: 4096, maxHeight: 2304,
      minWidth: 256,  minHeight: 144,
    },
    image: {
      maxSizeBytes: 100 * 1024 * 1024,
      allowedMimeTypes: ['image/jpeg', 'image/png', 'image/gif'],
    },
  },
  YOUTUBE: {
    video: {
      maxSizeBytes: 128 * 1024 * 1024 * 1024,
      maxDurationSeconds: 43200,
      minDurationSeconds: 1,
      allowedMimeTypes: [
        'video/mp4', 'video/quicktime', 'video/x-msvideo', 'video/webm',
        'video/x-matroska', 'video/3gpp', 'video/x-flv', 'video/x-ms-wmv',
      ],
      maxWidth: 7680, maxHeight: 4320,
      minWidth: 240,  minHeight: 144,
    },
    image: {
      maxSizeBytes: 2 * 1024 * 1024,
      allowedMimeTypes: ['image/jpeg', 'image/png', 'image/gif'],
    },
  },
  BLUESKY: {
    video: {
      maxSizeBytes: 50 * 1024 * 1024,
      maxDurationSeconds: 60,
      minDurationSeconds: 1,
      allowedMimeTypes: ['video/mp4', 'video/quicktime', 'video/webm'],
      maxWidth: 1920, maxHeight: 1920,
      minWidth: 240,  minHeight: 240,
      maxFrameRate: 60,
    },
    image: {
      maxSizeBytes: 1 * 1024 * 1024,
      allowedMimeTypes: ['image/jpeg', 'image/png', 'image/gif', 'image/webp'],
    },
  },
  THREADS: {
    video: {
      maxSizeBytes: 100 * 1024 * 1024,
      maxDurationSeconds: 90,
      minDurationSeconds: 1,
      allowedMimeTypes: ['video/mp4', 'video/quicktime'],
      maxWidth: 1920, maxHeight: 1920,
      minWidth: 320,  minHeight: 320,
    },
    image: {
      maxSizeBytes: 8 * 1024 * 1024,
      allowedMimeTypes: ['image/jpeg', 'image/png'],
    },
  },
};

function detectMediaCategory(mimeType) {
  if (mimeType === 'image/gif') return 'gif';
  if (mimeType.startsWith('image/')) return 'image';
  if (mimeType.startsWith('video/')) return 'video';
  return 'unknown';
}

function getVideoInfo(filePath) {
  const result = spawnSync('ffprobe', [
    '-v', 'quiet',
    '-print_format', 'json',
    '-show_streams',
    '-show_format',
    filePath,
  ], { encoding: 'utf8' });

  if (result.status !== 0 || !result.stdout) return null;
  try {
    return JSON.parse(result.stdout);
  } catch {
    return null;
  }
}

function validateMedia(filePath, platform, errorFn) {
  const constraints = PLATFORM_MEDIA_CONSTRAINTS[platform];
  if (!constraints) return;

  const stat = fs.statSync(filePath);
  const ext = path.extname(filePath).toLowerCase();
  const mimeType = MIME_TYPES[ext] || 'application/octet-stream';
  const category = detectMediaCategory(mimeType);
  const limits = constraints[category] || constraints.video;
  if (!limits) return;

  const issues = [];

  if (limits.maxSizeBytes && stat.size > limits.maxSizeBytes) {
    const mb = (stat.size / 1024 / 1024).toFixed(1);
    const maxMb = (limits.maxSizeBytes / 1024 / 1024).toFixed(0);
    issues.push(`File too large: ${mb} MB (max ${maxMb} MB for ${platform} ${category})`);
  }

  if (limits.allowedMimeTypes && !limits.allowedMimeTypes.includes(mimeType)) {
    const allowed = limits.allowedMimeTypes.map(m => m.split('/')[1]).join(', ');
    issues.push(`Unsupported format ${ext} (${mimeType}) for ${platform} ${category}. Allowed: ${allowed}`);
  }

  if (issues.length > 0) {
    errorFn('Media validation failed', { platform, category, file: path.basename(filePath), issues });
    return;
  }

  if (category !== 'video') return;

  // ffprobe availability check
  const probeCheck = spawnSync('ffprobe', ['-version'], { encoding: 'utf8' });
  if (probeCheck.status !== 0) return;

  const info = getVideoInfo(filePath);
  if (!info) return;

  const videoStream = (info.streams || []).find(s => s.codec_type === 'video');
  const format = info.format || {};
  const durationSeconds = parseFloat(format.duration || 0);
  const videoIssues = [];

  if (limits.maxDurationSeconds && durationSeconds > limits.maxDurationSeconds)
    videoIssues.push(`Duration too long: ${durationSeconds.toFixed(1)}s (max ${limits.maxDurationSeconds}s)`);
  if (limits.minDurationSeconds && durationSeconds > 0 && durationSeconds < limits.minDurationSeconds)
    videoIssues.push(`Duration too short: ${durationSeconds.toFixed(1)}s (min ${limits.minDurationSeconds}s)`);

  if (videoStream) {
    const w = videoStream.width || 0;
    const h = videoStream.height || 0;

    if (limits.maxWidth  && w > limits.maxWidth)  videoIssues.push(`Width too large: ${w}px (max ${limits.maxWidth}px)`);
    if (limits.maxHeight && h > limits.maxHeight) videoIssues.push(`Height too large: ${h}px (max ${limits.maxHeight}px)`);
    if (limits.minWidth  && w > 0 && w < limits.minWidth)  videoIssues.push(`Width too small: ${w}px (min ${limits.minWidth}px)`);
    if (limits.minHeight && h > 0 && h < limits.minHeight) videoIssues.push(`Height too small: ${h}px (min ${limits.minHeight}px)`);

    if (w > 0 && h > 0) {
      const aspect = w / h;
      if (limits.minAspectRatio && aspect < limits.minAspectRatio)
        videoIssues.push(`Aspect ratio too narrow: ${aspect.toFixed(2)} (min ${limits.minAspectRatio.toFixed(2)})`);
      if (limits.maxAspectRatio && aspect > limits.maxAspectRatio)
        videoIssues.push(`Aspect ratio too wide: ${aspect.toFixed(2)} (max ${limits.maxAspectRatio.toFixed(2)})`);
    }

    if (limits.maxFrameRate) {
      const fpsStr = videoStream.r_frame_rate || videoStream.avg_frame_rate || '';
      const [num, den] = fpsStr.split('/').map(Number);
      const fps = den && den > 0 ? num / den : num || 0;
      if (fps > limits.maxFrameRate)
        videoIssues.push(`Frame rate too high: ${fps.toFixed(1)} fps (max ${limits.maxFrameRate} fps)`);
    }
  }

  if (videoIssues.length > 0) {
    errorFn('Media validation failed', { platform, category, file: path.basename(filePath), issues: videoIssues });
  }
}

module.exports = { validateMedia, MIME_TYPES, PLATFORM_MEDIA_CONSTRAINTS };
```

## File: skills/postey/scripts/postey.js
size: 78199
sha: 53bad335ee02ebfbdec837ae85f51ae298c30415
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/scripts/postey.js

Content is not inlined in the catalog. Read the upstream file: https://github.com/posteyai/skills/blob/main/skills/postey/scripts/postey.js

## File: skills/postey/scripts/videoUtils.js
size: 5148
sha: ac8c20472a7bd9a805b9676d706301847311bf8c
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/scripts/videoUtils.js

```text
"use strict";

// Child processes echo the input URL into stderr, and for a presigned S3 / Drive
// / CDN link the query string IS the credential. This output is read by an agent
// and forwarded to a model provider, so strip it before it leaves.
function redactUrls(text) {
  if (!text) return text;
  return String(text).replace(/(https?:\/\/[^\s"']+?)\?[^\s"']*/g, "$1?<redacted>");
}

// yt-dlp, ffmpeg and whisper need none of Postey's credentials, and yt-dlp in
// particular loads config files and extractor plugins while fetching an
// attacker-chosen URL. Hand them an environment without the secrets.
function mediaEnv() {
  const {
    POSTEY_API_KEY, POSTEY_AUTH_TOKEN, // eslint-disable-line no-unused-vars
    ...rest
  } = process.env;
  return rest;
}

const fs = require("fs");
const path = require("path");
const { spawnSync } = require("child_process");

// Platforms that can receive a video file attachment
const _VIDEO_CAPABLE_PLATFORMS = new Set(["INSTAGRAM", "TIKTOK", "YOUTUBE"]);

// Per-platform caption character limits
const _VIDEO_CHAR_LIMITS = {
  X: 280, LINKEDIN: 3000, TIKTOK: 2200, INSTAGRAM: 2200,
  THREADS: 500, BLUESKY: 300, YOUTUBE: 5000,
};

function _which(cmd) {
  return spawnSync(
    process.platform === "win32" ? "where" : "which",
    [cmd],
    { encoding: "utf8" },
  ).status === 0;
}

function _detectWhisper() {
  return _which("mlx_whisper") ? "mlx_whisper" : _which("whisper") ? "whisper" : null;
}

function _gcd(a, b) { return b === 0 ? a : _gcd(b, a % b); }

function _vTruncate(text, lim) {
  if (!text) return "";
  return text.length <= lim ? text : text.slice(0, lim - 3) + "...";
}

function _sanitizeFname(t) {
  return (t || "").replace(/[^\w\s-]/g, "").trim().replace(/\s+/g, "_").slice(0, 80) || "video";
}

function _findVideoFile(dir) {
  const exts = [".mp4", ".mkv", ".webm", ".mov", ".avi", ".m4v"];
  const files = fs.readdirSync(dir).filter((f) => exts.includes(path.extname(f).toLowerCase()));
  if (!files.length) {
    console.log(JSON.stringify({ error: `No video file found in ${dir}` }, null, 2));
    process.exit(1);
  }
  return path.join(dir, files[0]);
}

function _vRun(cmd, args) {
  const r = spawnSync(cmd, args, { env: mediaEnv(), encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
  if (r.error) {
    console.log(JSON.stringify({ error: `Failed to run '${cmd}': ${r.error.message}` }, null, 2));
    process.exit(1);
  }
  if (r.status !== 0) {
    console.log(JSON.stringify({ error: `'${cmd}' exited with code ${r.status}`, stderr: redactUrls(r.stderr)?.slice(0, 500) }, null, 2));
    process.exit(r.status || 1);
  }
  return r;
}

function _buildThumbnail(videoFile, { thumbText, thumbTime, outDir }) {
  const rawThumb = path.join(outDir, "thumb_raw.jpg");
  const resized  = path.join(outDir, "thumb_resized.jpg");
  const final    = path.join(outDir, "thumb_final.jpg");

  let extracted = false;
  if (!thumbTime) {
    const r = spawnSync("ffmpeg", ["-i", videoFile, "-vf", "select=gt(scene\\,0.35)", "-vsync", "vfr", "-frames:v", "1", rawThumb, "-y"], { env: mediaEnv(), encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
    extracted = r.status === 0 && fs.existsSync(rawThumb) && fs.statSync(rawThumb).size > 0;
  }
  if (!extracted) {
    const t = thumbTime != null ? thumbTime : 3;
    const r = spawnSync("ffmpeg", ["-ss", String(t), "-i", videoFile, "-vframes", "1", rawThumb, "-y"], { env: mediaEnv(), encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
    if (r.status !== 0 || !fs.existsSync(rawThumb)) {
      process.stderr.write("Warning: thumbnail frame extraction failed\n");
      return null;
    }
  }

  const rr = spawnSync("ffmpeg", ["-i", rawThumb, "-vf", "scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2:color=black", resized, "-y"], { env: mediaEnv(), encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
  if (rr.status !== 0 || !fs.existsSync(resized)) {
    process.stderr.write("Warning: thumbnail resize failed\n");
    return null;
  }

  const imBin = _which("magick") ? "magick" : _which("convert") ? "convert" : null;
  if (thumbText && imBin) {
    const FONTS = ["/System/Library/Fonts/Supplemental/Arial Bold.ttf", "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf"];
    const fontArg = FONTS.find((f) => fs.existsSync(f)) || "Arial-Bold";
    const baseArgs = ["-font", fontArg, "-pointsize", "64", "-fill", "white", "-stroke", "black", "-strokewidth", "2", "-gravity", "South", "-annotate", "+0+120", thumbText];
    const imArgs = imBin === "magick" ? ["convert", resized, ...baseArgs, final] : [resized, ...baseArgs, final];
    const ir = spawnSync(imBin, imArgs, { env: mediaEnv(), encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
    if (ir.status === 0 && fs.existsSync(final) && fs.statSync(final).size > 0) return final;
    process.stderr.write("Warning: ImageMagick text overlay failed — using resized frame\n");
  }
  return resized;
}

module.exports = {
  _VIDEO_CAPABLE_PLATFORMS,
  _VIDEO_CHAR_LIMITS,
  _which,
  _detectWhisper,
  _gcd,
  _vTruncate,
  _sanitizeFname,
  _findVideoFile,
  _vRun,
  _buildThumbnail,
};
```

## File: skills/postey/references/brand-profile-template.md
size: 3378
sha: 08544c166d9548243602c5f1b3e1f079aa900ea4
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/references/brand-profile-template.md

````text
# Brand Profile Template

Part of the `postey` skill. Filled in once per brand by the brand-voice flow; every other
flow reads it before drafting.

Everything identity-specific lives in one per-brand profile, separate from this playbook. The profile is a single document with the six sections below, stored wherever your client persists things (memory, project knowledge, or a saved file). Fill in every field for each brand or creator the agent writes for (fields only; content is yours):

```
## Identity
  - Brand / creator name and one-line positioning
  - Target audience (who exactly reads this; what do they respect)
  - Content niche / beat
  - Connected platforms and any account tiers (e.g., X Premium: yes/no)
  - Default caption length preference (long-form vs punchy) per platform

## Voice
  - Voice adjectives (e.g., authoritative operator / curious builder / playful)
  - First-person stance (practitioner? commentator? curator?)
  - Banned topics (companies, people, or themes this account never names, e.g.
    due to business relationships; include approved indirect framings)
  - Banned phrases and patterns (beyond the universal AI-tells scrub)
  - Organic vs sponsored voice modes and how they differ
  - Disclosure rules for paid content (who decides on #ad etc.)

## Pillars
  - 3-5 content pillars with target percentage mix
    (e.g., problem awareness / product showcase / social proof /
     thought leadership / promotion)
  - Posting rhythm (weekly cadence per pillar; promo frequency cap)
  - Value-to-promotion ratio (e.g., 3:1 for SaaS)

## Hooks
  - 8-10 pre-approved hook templates in the brand voice
  - Approved trigger words for comment-CTA posts
  - Approved CTA destinations (links, lead magnets)

## Promotions
  - Current offers, codes, deadlines (keep dated; expire aggressively)

## Examples
  - Top-performing past posts with view counts and the archetype each used
    (the agent matches new topics to the closest proven archetype and
     writes fresh; never copies lines verbatim)
```

### The Conversion Stack (for brand accounts)

When the goal is signups rather than reach, layer these five elements:

1. **Bold number hook**: stops the scroll with specificity
2. **Low-barrier framing**: makes the outcome feel achievable
3. **Engagement-trigger CTA**: one-word comment trigger; frictionless, and the reply volume feeds the algorithm
4. **Free lead magnet**: delivered via DM; the lead magnet should BE the product demo (a template whose workflow naturally showcases the product)
5. **Value-to-promo rhythm**: never two conversion posts in a row; warm up with 2-3 value posts first

Conversion pitfalls: income-claim styles from info-product creators feel scammy for SaaS (use real product metrics); links in the main X post kill reach (first reply instead); max ~2 engagement-trigger posts per week or followers tune out; the trigger comment is worthless without the DM follow-up; text + link with no media is the lowest-reach combination.

### Repurposing workflow

One idea → every platform: write the longest version first (LinkedIn or blog) → extract the hook into short-form (X, Threads, Bluesky) → turn the structure into a carousel (Instagram) → record or cut a video (Reels, TikTok, Shorts) → propose a posting schedule and apply it only after the user approves the times; per-platform captions throughout.
````

## File: skills/postey/references/caption-playbook.md
size: 4635
sha: 60ef91f24a977015918ed49ee363f70103ffa668
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/references/caption-playbook.md

```text
# Caption Playbook

Part of the `postey` skill. Loaded on demand; see SKILL.md "Content Flows".

The shared rulebook every content flow cites. Read the universal rules before drafting;
consult the sibling references for platform specifics:

- `platform-archetypes.md`: per-platform caption structure, hashtags, lengths, CTA mapping
- `hook-formulas.md`: hook construction and quality gates
- `x-algorithm.md`: X ranking mechanics (public sources)
- `thread-and-video-formats.md`: thread, reel, carousel, and trend-content formats

## Universal Workflow Rules

These apply to every content task, on every platform.

1. **Verify connected platforms first.** Read `postey://accounts` (or call `get_accounts` if your client cannot read MCP resources) at the start of every session. Never assume a static platform list; platforms get connected and disconnected at any time. "All platforms" means the platforms currently connected to the target account, not a default set.
2. **Draft, never publish. Scheduling counts as publishing.** Create everything as a DRAFT. Publishing happens only after the user explicitly approves. A scheduled post publishes itself, so `schedule_post` is held to the same gate: propose times, schedule only after the user approves both content and times, with times at least 10 minutes in the future in UTC ISO-8601. First drafts are never final; present and wait for feedback.
3. **One caption per platform.** Never copy-paste the same text everywhere. Each connected platform gets a hand-crafted caption matching that platform's archetype (platform-archetypes.md). The idea carries across platforms; the voice and mechanics adapt.
4. **The transcript or source material is the seed, not the script.** Captions are written fresh in the platform voice, never copied verbatim from a transcript, brief, or source post.
5. **User instructions override archetypes.** If the user supplies a hook phrase, it becomes the literal first line, quirks and all. If the user says "short caption" or "3 punchy lines," obey literally: no CTA, no numbered sections, no hashtag block.
6. **Stay on the stated topic.** When the user narrows scope ("just write about X"), do not weave in adjacent products, campaigns, or topics you happen to know about.
7. **Verify and validate before presenting.** After creating a draft, fetch it back per platform: read `postey://posts/{id}/content/{platform}`, or call `get_post_content` if your client cannot read resources. Then check: caption present, media attached and correct, right account, right format (single post vs thread). Also run the `validate_post_content` tool per platform. Fix failures before presenting; never present a draft with known issues.
8. **Tag agent-created posts.** Apply a consistent agent tag (default `Agent`) to every post the agent creates, plus 2 or 3 topic tags. This lets the account owner filter agent-generated content later. `add_tag` is get-or-create by exact name, so reuse the same spelling every session (recent posts from `get_posts` show the names in use) so near-duplicate tags never accumulate.
9. **Freshness check before trend content.** Search the connected account's own recent posts before drafting news or trend content. Never repeat an angle the account already covered.
10. **End with the share link.** The final message contains the draft's share link, a one-line summary of platforms covered, and any flags worth knowing (e.g., video length affects placement). Never fabricate a share link; if one can't be generated, say so and point to the dashboard.
11. **Fact-check every claim.** Every stat, name, and number must trace to a source. Unverified claims get removed, not hedged.

## Pre-Upload Checklist (run on every draft)

- [ ] Connected platforms verified this session, not assumed
- [ ] First 2-3 lines pass the cold-read test
- [ ] Hook line under 10 words
- [ ] Zero em-dashes; no stacked period-rhythm; no banned buzzwords
- [ ] No branded mission-statement close; no engagement-bait close on long-form
- [ ] Platform limits respected (Threads <500, Bluesky <300, TikTok ~200 incl. hashtags, YT title ≤100; authoritative limits: `postey://platform-limits`)
- [ ] Hashtags per platform policy (X: 0, LinkedIn: 3-4, IG: 5-10, TikTok: 5-7, Threads: 0-2, Bluesky: 0-1)
- [ ] User-supplied hook preserved as the literal first line
- [ ] Every claim verified against a source
- [ ] Brand-profile banned topics and phrases respected
- [ ] Right voice mode (organic vs sponsored) with correct disclosure
- [ ] Media attached and verified per platform; placeholders flagged
- [ ] Draft status is DRAFT; share link ready to present
```

## File: skills/postey/references/hook-formulas.md
size: 2396
sha: a340dcc5b966a33f7ac86be3e277b7b4c2d03744
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/references/hook-formulas.md

````text
# Hook Formulas & Quality Gates

Part of the `postey` skill. Loaded on demand; see SKILL.md "Content Flows".

## Hook Formulas

### The pain + number 3-line formula

For conversion-oriented posts:

```
Line 1: The pain or fact, under 10 words, with a specific number
Line 2: The reward, what the reader GETS (a large value gap)
Line 3: The action, one clear CTA
```

Rules:
- Line 1 is a pain or fact, never a feature. "Agencies charge $3,000/month" beats "Our tool schedules posts."
- Line 2 is what the reader gets, not what the product does.
- Specific numbers beat vague claims: "saves 12 hours/week" stops the scroll; "saves time" is ignored.
- Number hooks outperform question hooks for conversion, because a number implies a repeatable system and makes the reader ask "how?"
- No filler trust-begging ("no credit card," "no catch," "no strings attached").

### The 10-variations rule

Never stop at one hook. Write 10 distinctly different hooks for the same post. The first 3 are the obvious ones; the best is usually #7-#10. When presenting direction options to a user, offer 5-10 distinct angles.

### The human test

Read the draft out loud. If it sounds like a marketing email, rewrite it. If it sounds like a friend making an offer or telling you something interesting, keep it.

### The cold-read test

The first 2-3 lines of every caption (and every post in a thread) must stand alone; readers arrive mid-scroll with zero context. Common failures: the hook depends on a setup sentence further down; the hook is generic ("Here are 5 things..."); the hook is a question the reader doesn't care about (reframe it as a claim).

### The AI-tells scrub (run on every draft)

- **No em-dashes.** Replace with a comma, a period + new sentence, or a colon.
- **No stacked period-rhythm phrases.** "Zero costs. Zero limits. Fully private." reads as AI cadence; merge or comma-join. One short standalone sentence is fine; three in a row is the tell.
- **Banned buzzwords:** unlock, unleash, leverage (verb), supercharge, 10x/100x (as modifier), game-changer, revolutionize, disrupt, paradigm shift, next-level, crushing it, move the needle. Replace with concrete language about what actually happens.
- **No branded mission-statement closers** ("The future of X is Y."). Cut entirely.
- **No dramatic filler** ("Nobody is talking about this," "This blew my mind"). State the insight directly.
````

## File: skills/postey/references/mcp-authentication.md
size: 8268
sha: 425f295f1ab46082ce335aba98accdee133f4436
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/references/mcp-authentication.md

````text
# MCP Authentication — Credentials, Scopes and Mint Paths

This file is the new home for the auth detail that used to live in the **MCP server's
instruction block** — the scope list, the mint endpoints and the browser-less path
(mcp-northstar N1.4). It loads on demand, so it costs nothing on a request that is not
about authentication.

**It lives in the hub, and only in the hub.** `postey` carries the routing, the accounts,
the write path and the craft layer; the optional packs are add-ons that cannot be
installed without it. So auth is documented once here and every pack reads it. A pack
that documented its own credentials would be a second copy of this file, free to drift.

**Why it had to leave the instruction block, and why it had to land somewhere fetchable.**
The block is delivered on `initialize`, and `initialize` needs a credential — `POST /mcp`
with none answers `401` with a `WWW-Authenticate` header. A client that cannot
authenticate therefore never reads the block at all. The block is the wrong surface for
teaching a client how to get its *first* credential, whatever else it is good for. This
file and [`setup.md`](../../../setup.md) are fetched over plain HTTPS with no Postey
credential, so they are the right one.

**What stayed on the server** and is therefore *not* repeated here: the three credential
headers, permission levels, rate limits and the response envelope. Read those from the
server's instructions.

## Pick by track

[`setup.md`](../../../setup.md) sorts every client into one of three tracks in Step 0, and
the track decides the credential. Do not choose a credential before you know the track.

| Track | Client | Credential | Header |
|---|---|---|---|
| A, local | anything that can open a browser | OAuth 2.1 access token | `Authorization: Bearer <jwt>` |
| B, web | a web client that added Postey as a connector | none of your own — the connector authorized in Step 2B | — |
| C, headless | CI, containers, cron, SDK callers | MCP key, `mk_*` | `X-API-Key: <key>` |

A fourth credential exists and is not a track: an **agent token**, `pat_*`, sent as
`Authorization: Bearer <token>`. Existing installs only. See [Agent tokens](#agent-tokens).

**Track B needs nothing from you.** The connector holds the grant, the host attaches it,
and there is no key to mint, store or ask for. If a web client asks you for a credential,
it is on the wrong track — send it back to Step 2B rather than minting one.

Every mint path below needs an **already-authenticated session**. None of them bootstraps
a client that holds no credential at all. For that client there is exactly one path, and
it is a human one: the user creates an MCP key in a signed-in browser and hands it over.
See [API key](#api-key).

---

## OAuth scopes

The interactive path, track A. Discovery is at
`https://srvr.postey.ai/.well-known/oauth-authorization-server`; the flow is standard
Authorization Code with PKCE, and the token goes back as `Authorization: Bearer <jwt>`.

Trigger your own client's MCP login rather than driving the flow by hand — `claude mcp
login postey`, `codex mcp login postey`, `hermes mcp login postey`. [`setup.md`](../../../setup.md)
Step 3 carries the per-agent commands and the Hermes ordering trap.

Twelve scopes drive the consent screen:

```
post:read          post:edit          post:delete
publishing:read    publishing:edit
scheduling:read    scheduling:edit    scheduling:delete
analytics:read
comments:read      comments:edit      comments:delete
```

These scope strings decide **what the consent screen offers**, not what the grant stores.
A grant issued by the consent bridge always persists the full permission matrix —
resource × verb × account or team — so a grant is narrower than its scope list whenever
the user restricted it to particular accounts. Read the effective answer from a `403` or
`insufficient_scope` on a real call; do not infer it from the scopes you asked for.

**Installed packs do not widen a grant.** The scope list is the server's and is fixed.
Installing `postey-analytics` does not add the analytics scope to a token that was granted
without it. A pack whose calls all answer `403` is an auth problem, not a missing install.

---

## API key

An MCP key is the credential for track C — a client that cannot open a browser. It starts
with `mk_`, it never expires, and it works on every plan including the free one. There is
no cap on how many exist: the MCP key type sits outside both the paid API-key entitlement
and the five-key limit that every other key type carries.

**You cannot create one for yourself.** Creating a key needs a signed-in browser. Stop
and give the user these steps.

1. Open <https://app.postey.ai?settings=agents&section=advanced>
2. Choose **New MCP key**
3. Name it, then pick what it may do. **Read only** is enough to connect and read;
   **Publishing** is what a posting agent needs
4. Choose **Create API Key**, then copy the key and send it back

Send that whole address. `?settings=api` opens Integrations instead, where the
general-purpose API keys live, and those are plan-gated.

Then export it and send it as a header:

```
export POSTEY_API_KEY=<the key>
```

```json
{ "headers": { "X-API-Key": "<the key>" } }
```

`POST /v1/keys` mints one over the API, but it authenticates the caller first, so it
helps a client that already has a credential and not one that is trying to get its first.

**The same key authenticates the CLI.** The hub ships `scripts/postey.js`, which reads
`POSTEY_API_KEY` first, then `POSTEY_AUTH_TOKEN`, then a stored OAuth session. Setting
the environment variable covers both surfaces at once; an OAuth-only track A install has
no `POSTEY_API_KEY`, which is why local-file commands fail there until Step 5 sets one.

The plan still decides what a key can *do*. Publishing, scheduling and analytics
are gated one at a time, so a free-plan key connects and reads, then answers `402` on the
call that needs a paid feature. That is a limit on the action, not on the key.

Never write a key into a file a repository tracks. A container or a CI job injects it as
a secret. The store holds it in plain text; if it leaks, revoke it and create another.

---

## Agent tokens

An older headless install may hold an agent token instead, starting with `pat_`, sent as
`Authorization: Bearer <token>`. The app no longer offers these and an MCP key replaces
them, but the server still accepts every token already issued.

Two mint paths remain on the API, and **both authenticate the caller first**:

| Endpoint | Needs | Lifetime |
|---|---|---|
| `POST /v1/auth/mcp/agent-tokens` | an existing grant of the caller's, from the browser consent flow | 90 days |
| `POST /v1/auth/mcp/self-issued-agents` | nothing but the caller's own session — it creates the grant too | does not expire |

The second exists because a token needs a grant and grants only came from a consent
screen the browser-less agent cannot render, which left the credential unreachable on a
fresh account. It is re-runnable: the client id is derived from the agent name, so
connecting the same agent again updates its grant instead of adding a duplicate row to
the user's agent list.

[`setup.md`](../../../setup.md) Step 3 says a lapsed `pat_` token has "no way to mint a
replacement". That is wrong — both endpoints above still mint. What is true is that
neither helps the client whose only credential just expired, because both need a session
it no longer has.

Both tokens inherit their grant's scopes and die when that grant is revoked. Revoking the
grant kills every key under it.

A 90-day token fails as `401` when it lapses, which reads as a broken setup rather than
an expiry. Prefer an MCP key.

---

## Three rules that bind every credential

1. Never print a credential back to the user, and never write one anywhere except the
   config file [`setup.md`](../../../setup.md) names for your client.
2. Never read one out of a config file, a keychain or a process environment in order to
   call Postey yourself. The client sends it. You do not handle it.
3. Never call the REST API at `srvr.postey.ai/v1` to check whether auth works. It is a
   different surface, and a result from it says nothing about whether MCP works.
````

## File: skills/postey/references/mcp-workflows.md
size: 10409
sha: bc75a058524fe3027abab1321dc14bbca9c3c96c
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/references/mcp-workflows.md

```text
# MCP Workflows — Sequencing, Etiquette and Judgment

This file is the new home for guidance that used to live in the **MCP server's instruction
block** — the text every MCP client receives on every request. It was 22,457 characters, and
most of it was craft: what order to call things in, when to ask the user, which media path to
take, how to phrase a caption. None of that is contract, so none of it needed to be paid for on
every request. It moved here, where it loads only when you are actually doing the work
(mcp-ax S9.7).

**What stayed on the server** and is therefore *not* repeated here: rate limits, permission
levels, the response envelope and its error codes, the post lifecycle, and the resource-first
rule. Read those from the server's instructions.

**What never belonged in either place:** character limits, media caps, cardinality. Those live
in `postey://platform-limits` and `postey://platforms/{platform}/rules`. Never hardcode one —
a limit copied is a limit that drifts, which is how this skill once told users that Facebook and
Pinterest did not exist.

---

## Create and Publish

The default sequence for a new post. Steps 2 and 5 are the ones agents skip; both exist because
the failure they prevent is invisible until after publication.

1. **Resolve the account** — read `postey://accounts`. See
   [Account Selection](../SKILL.md#account-selection) for the etiquette; it is not optional even
   when there is only one account.
2. **Get writing guidance** — the `compose-post` prompt, or the caption references
   ([caption-playbook.md](caption-playbook.md), [hook-formulas.md](hook-formulas.md)).
3. **Create the draft** — `create_post`. Returns `post_id`.
   - Multi-platform goes in **one** call via `additional_platforms`, each platform carrying its
     own hand-written content. See
     [Publishing to Multiple Platforms](../SKILL.md#publishing-to-multiple-platforms).
4. **Tag it** — see [Tagging](#tagging) below. Needs ADMIN on the account; skip it if you only
   have WRITE or PUBLISH.
5. **Validate** — `validate_post_content`, once per target platform.
   - Pass `account_id`. It is what selects the account's real limit rather than the default one;
     on X the two tiers differ by two orders of magnitude, so validating without it can pass
     content the platform will reject.
6. **Publish or schedule** — `publish_draft` or `schedule_post`, only after the user says yes in
   the current turn. Scheduling counts as publishing.

## Updating a Draft

1. `get_posts(account_id, social=<PLATFORM>, status=DRAFT)` to find it.
2. Read `postey://posts/{post_id}/content/{platform}` to see what is there now.
3. `update_post(post_id, ...)`.

**Partial updates are safe.** Send only the fields you are changing. Omitted media, `post_type`
and platform config fields are preserved from the existing post — you do not need to re-send the
whole post. Pass `media_urls=[]` to actually remove media, which is different from omitting it.

**Two exceptions.** YouTube and Pinterest each require their title field on *every* call
(`contents[0].youtube_title`, `contents[0].pinterest_title`), and allow exactly one content item.
The server refuses the call and names the field if you forget, so this is a convenience note, not
a rule you have to remember.

## Repurposing Across Platforms

`convert_post_content` auto-adapts existing content. **Use it only when the user explicitly asks
for that** — "convert this to LinkedIn", "adapt it for Bluesky". It rewrites, and rewriting loses
intentional formatting.

It is *not* the way to do multi-platform creation. For that, write each platform's caption
yourself in the `create_post` / `update_post` flow above.

When you do convert:

1. Read `postey://posts/{post_id}/content/{source_platform}`.
2. `convert_post_content(post_id, source_platform, target_platforms=[...])` — this attaches the
   targets to the **same** `post_id`. Do not call `create_post` for them.
3. `validate_post_content` per target.
4. `update_post` per target to refine what was generated.

## Attaching Media

Four ways in, and the right one depends on where the bytes are and what your client is:

| You have | Use | Notes |
|---|---|---|
| A public URL | `upload_media(source_type='url')` | Works everywhere, including the hosted server |
| A small inline file | `upload_media(source_type='base64')` | Small files only; the cap is on the tool's description |
| A file on the user's machine, any client | `file_manager()` then `list_files()` | Opens a drag-and-drop widget; bytes go straight to the CDN and never enter your context |
| A local path, CLI available | `upload_media(source_type='local_path')` | Needs this skill installed **and** API-key auth. Not available on the hosted server or to OAuth clients |

Sequence, whichever you pick: upload first, take `cdn_url` from the response, then pass it in
`contents[].media_urls` on `create_post` / `update_post`. A media URL is not valid until its
upload succeeds, and there is never a reason to construct one by hand.

**Prefer `file_manager` over `local_path`** for a file on the user's machine. It works for OAuth
clients and on the hosted server, which `local_path` does not.

**Do not use `read_file` to fetch media bytes.** It returns metadata and the `cdn_url` by design.
Media does not belong in a context window.

## Local Files and Large Uploads

The table above assumes this skill is installed. It often is not, and the difference is not
cosmetic: **the MCP server cannot see the user's disk.** Every path that reads a local file is the
CLI's, and the CLI ships with this skill. Work out which side of that line you are on before you
promise the user an upload.

| Path | Needs this skill | What it is for |
|---|---|---|
| `upload_media(source_type='url')` | no | A public URL, fetched server-side. Works everywhere, including the hosted server |
| `upload_media(source_type='base64')` | no | Inline bytes, small files only — the cap is on the tool's own description |
| `file_manager()` then `list_files()` | no | A file on the user's machine, any client. Drag-and-drop; the bytes go straight to the CDN and never enter your context |
| `upload_media(source_type='local_path')` | **yes** | A local path read directly. Also needs API-key auth, so it is unavailable to OAuth clients and on the hosted server |
| `media:upload` above 50 MB | **yes** | The CLI switches to the chunked path on its own — init, parallel chunks with retry, complete. There is no MCP equivalent |
| `video transcribe` on a local file | **yes** | Runs ffmpeg on the user's machine |

**Without the skill, `file_manager` is the answer for a local file** — not an apology. It reaches
every client, it works on the hosted server, and it is the only credential-agnostic path that takes
a file too large to inline. `upload_media` with `url` or `base64` covers the rest.

Only the last three rows are a reason to install anything. Install it the way
[`setup.md`](../../../setup.md) Step 4 names for the client — the bare
`npx skills add posteyai/skills` installs the hub, every optional pack and this repository's skill
template alongside it, which is why every documented form carries `-s postey`.

Never ask the user to paste a large file's contents, and never reach for `read_file` to get media
bytes when a path is missing. It returns metadata and the `cdn_url` by design.

## Video: Choosing a Path

Three paths. Pick on what you have, not on what is fastest.

| You have | Path | How |
|---|---|---|
| Video **and** a finished caption | **A** | `postey.js video post` — upload, cover-frame extraction, chunked upload for large files, then draft. See [video-workflow.md](../video-workflow.md#workflow-a--upload-video--create-draft) |
| A video **URL**, no caption | **B** | `postey.js video transcribe` where the CLI runs; connector-only clients use the `transcribe_video` MCP tool. Then generate captions per platform, then `create_post` |
| A **local** video, no caption | **C** | The `local-video-multiplatform` flow — Whisper transcription, thumbnail extraction, per-platform captions, draft |

**Default when the user gives you a video and no caption: B or C, never "ask them to write one".**
Transcribe first. Then write captions from the transcript — and never paste a raw transcript in as
a caption; it reads like a transcript.

Paths A and C need this skill installed locally (`npx skills add posteyai/skills`) plus its
prerequisites. Path B's MCP tool works without it.

Full command reference: [video-workflow.md](../video-workflow.md).

## Tagging

Add **2–3 tags** after creating a post, and reuse before you invent:

1. Read the account's existing tags — `postey://accounts/{account_id}/tags`.
2. Reuse the exact existing **name** when one matches. Names are case-sensitive: `Marketing` and
   `marketing` are two different tags, so match the casing the user uses.
3. Only pass a new tag spec for a genuinely new name.

Tags are passed as specs (`{tag, color, account_id}`) — there is no `tag_id` on the request. The
server enforces uniqueness per account and reuses via get-or-create, so passing a duplicate spec
returns the existing tag rather than creating a row. That means duplicates are *not* dangerous —
but near-duplicates are, because `Marketing` and `marketing` are both "unique" and the account
ends up with both. Consistency is yours to keep, not the server's.

`add_tag` needs ADMIN on the account. `remove_tag` undoes a mis-tag.

## Platform-Specific Asks

Some fields cannot be guessed, and guessing them produces a post the user did not want rather
than an error they can see. Ask, every time:

- **Instagram** — ask for `post_type` before creating or updating. Never assume `FEED`. The
  choice between feed, reel and story changes the aspect ratio, the duration budget and whether
  text is allowed at all.
- **TikTok** — confirm the post type before creating, even though there is only one supported
  value today.
- **YouTube** — ask for the video title. It is required, it cannot be empty, and it is not the
  caption. Omit the description unless the user wants one.
- **Pinterest** — ask for the Pin title, and for the destination link if the Pin should link out.

The exact allowed values and limits for each of these are in
`postey://platforms/{platform}/rules`. Read them; do not carry them in your head or in this file.
```

## File: skills/postey/references/platform-archetypes.md
size: 6758
sha: 6b0968ecea4d322f5a41902ab6793483268d4a7f
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/references/platform-archetypes.md

```text
# Per-Platform Caption Archetypes

Part of the `postey` skill. Loaded on demand; see SKILL.md "Content Flows".

Style authority for captions: where another file disagrees on style (hashtag counts, CTA
style, thread length), this file wins. Hard limits (character caps, media specs) come from
the `postey://platform-limits` MCP resource; the numbers here are working targets.

### X (Twitter)

- **Archetype:** long-form narrative post in an authoritative, informed-commentator voice. Full flowing paragraphs. No bullet points or numbered lists in organic posts (those belong in threads).
- **Hook:** first line under 10 words, ideally with a specific number or a stand-taking claim. Never open with a time anchor ("Yesterday...", "On Friday...").
- **Body:** conclusions first, evidence second. Real names, real dollar figures, real timelines. Every paragraph must teach something new.
- **Close:** land on a non-obvious insight the reader will quote, or a "future-moment bookmark" close: *"Bookmark this. You'll want it the next time [specific future moment the reader will hit]."* Never generic engagement bait ("What do you think?").
- **Hashtags:** none. **Emojis:** none in organic posts.
- **Length:** know the account's tier. Standard accounts cap at 280 characters; Premium accounts allow long-form (up to 25K). Don't pad; cut anything that doesn't earn its place.
- **Video-forward variant:** when the video is the content, write 3 punchy lines max (scene-setting, one hard stat, short close). No CTA, no hashtags.
- **External links:** never in the main post (see x-algorithm.md). Put the link in the first reply.
- **Quote posts:** append the original post URL at the end of the text so it renders as an embed.

### LinkedIn

- **Archetype:** operator how-to. Professional but punchy; "here's a workflow that works," less oracular than X.
- **Structure:** surprising stat or claim (1 sentence) → one-line setup ("Here's why it matters if you actually do X") → 3-4 numbered shifts, 1-2 sentences each → stakes paragraph ("Most teams treat X like Y. The ones who treat it like Z will pull ahead.") → soft CTA ("Comment 'WORD' if you want the guide").
- **Hashtags:** 3-4 lightweight ones at the end. Heavy hashtag blocks hurt reach.
- **Length:** 3,000 char limit; sweet spot 1,000-1,500.

### Instagram (Reels)

- **Archetype:** native creator voice with a comment-mechanic hook: "Comment 'WORD' and I'll send you the guide." If the video has a spoken hook, that spoken line becomes the first line of the caption.
- **Structure:** comment-mechanic hook → one-line setup ("Most people don't realize you can...") → 3-step numbered body → close ("That's it. [Outcome]." + "Follow for more [topic]") → hashtag block.
- **Hashtags:** 5-10, mixing broad and specific.
- **Length:** 2,200 char limit (rarely a constraint). Reels have a hard 90-second video maximum; vertical 9:16 performs best.

### TikTok

- **Archetype:** short native voice. One-line hook, one-line value prop, optional comment CTA, hashtag block.
- **Hashtags:** 5-7, topic-led (#fyp counts toward the total, not on top of it).
- **Length:** sweet spot under 200 characters total including hashtags.

### YouTube

- **Regular videos:** title ≤100 chars (front-load the first 70; search results truncate), pattern "[Verb] [Subject] [Qualifier] ([Hook in parens])". Description mirrors the Instagram caption and ends with 3-5 hashtags. 8-15 comma-separated tags (video metadata, distinct from description hashtags) mixing broad and specific. Pick the category to match the content.
- **Shorts (≤60s):** punchier title ≤60 chars, no parentheticals, lead with the most surprising fact. Description under 500 chars.
- Flag it when a video's length changes its placement (over 60s means it publishes as a regular video, not a Short).

### Threads

- **Archetype:** the long-form idea compressed into a single post. Casual, slightly more energetic than X.
- **Structure:** compressed hook → one-line core insight → compressed steps in 1-2 sentences (not numbered) → one-line why-it-matters → "Save this." close (never "before it disappears"; that reads as small-creator bait).
- **Hashtags:** 0-2. **Length:** 500 hard cap; aim 400-450. **Media:** one video max per post.

### Bluesky

- **Archetype:** the tightest version of the message. Plain prose: hook sentence, core insight sentence, one-sentence compression of the steps, optional "Save this."
- **Hashtags:** typically none; the culture is hashtag-light.
- **Length:** 300 hard cap; aim ~250. **Media:** video ≤15MB and ≤60s; prepare a dedicated small encode.

### Facebook

- **Archetype:** the story version. Facebook tolerates length that X and Bluesky do not, so let the narrative breathe — but the hook still has to win before the fold.
- **Structure:** hook → the situation in plain language → what changed → the takeaway → CTA.
- **Hashtags:** 0-2; they carry little reach here and read as spammy in quantity.
- **Length:** 63,206 hard cap, but only **~477 characters show before "See more"** — front-load the hook inside that window. **Media:** multiple images; video up to 10GB, 1s-4h.

### Pinterest

- **Not a caption platform — a *title + description* platform.** Treat it as search, not feed: people arrive with intent, so write for what they are looking for rather than for a scroll-stopping hook.
- **Title:** required, **100 max**, plain text, **no hashtags**. The single highest-leverage field.
- **Description:** **500 max**; hashtags and @mentions count toward it. The title and the description's first line are what show in-feed.
- **Structure:** keyword-led title → description that expands the promise and names the outcome → CTA to the linked page.
- **Also set:** `pinterest_link` (destination URL — a Pin without one wastes the click), `pinterest_board_id` (omit for the default board), `pinterest_alt_text`. **Media:** one image or video, or up to 5 images for a carousel Pin.

### CTA mapping across platforms

The intent of a CTA carries; the mechanic adapts:

| Platform | CTA mechanic |
|---|---|
| Instagram | "Comment 'WORD' and I'll send you the guide" (literal) |
| YouTube | Same as Instagram, in the description |
| LinkedIn | "Comment 'WORD' if you want the full guide." |
| Threads | "Save this." (comment-DM mechanics die here) |
| X | Future-moment bookmark close (comment-DM mechanics die here) |
| TikTok | "Comment 'WORD' for the guide" or skip |
| Bluesky | "Save this." or omit |
| Facebook | "Comment 'WORD' and I'll send it over" — comment-DM mechanics work here |
| Pinterest | No comment CTA; the Pin's destination link IS the CTA |

Never port the Instagram comment-DM mechanic verbatim onto X; it kills the long-form voice.
```

## File: skills/postey/references/post-structures.md
size: 11269
sha: ceeb4e49e05bf39de99be90d190af6402131efd5
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/references/post-structures.md

```text
# Post Structures

Part of the `postey` skill. Loaded on demand; see SKILL.md "Content Flows".

Eighteen structures, each with the condition that selects it, the shape it takes, its length
rule, and the way it usually fails. Derived from measured top-vs-bottom quintile analysis of
high-performing operator accounts on X.

**Pick the structure from the material, not from preference.** Every entry starts with WHEN
because that is the decision. If no WHEN matches what the user actually has, the post is not
ready — go back for material rather than forcing a shape onto thin content.

Pair this with [hook-formulas.md](hook-formulas.md) for the opening line and the AI-tells scrub,
and [platform-archetypes.md](platform-archetypes.md) for how the chosen structure is dressed per
network.

## Contents

- The density rule — why most drafts fail before structure matters
- Structures 1–18
- Porting a structure off X
- Self-check before returning a draft

## The density rule

Two lengths perform. Under ~140 characters, where every word is load-bearing. Or over ~600,
where genuinely new facts appear on every line.

**Between 200 and 500 characters is a dead zone** — long enough to look like effort, short
enough to carry nothing new. A draft that lands there is either a sentence padded out or a real
post cut short. Fix it by compressing to one line or by adding actual material. Never by
trimming to "about the right length".

Length is not the variable. Density is.

---

## 1. The Aphorism

**WHEN** the material reduces to one true sentence that most people would dispute, and you have
no new facts to add.
**SHAPE** One sentence. Symmetry, reversal, or a both-halves-true structure. No explanation, no
follow-up line.
**LENGTH** Under 20 words. In the sampled corpus, top aphorism posts averaged ~84 characters
against ~168 for the same account's bottom quintile.
**FAILURE MODE** Adding a second sentence that explains the first. It roughly halves
performance. If it needs explaining, you want structure 3.

## 2. The Label Stack

**WHEN** you have one piece of advice and three to six concrete instances of it.
**SHAPE** `[Label]: [claim].` then rapid-fire fragments, each a real instance, then a closer that
names the underlying principle.
**LENGTH** ~250 characters as ONE dense block. Winners averaged 1.7 lines against 3.5 for
losers.
**FAILURE MODE** Breaking each fragment onto its own line. The density is the point; a vertical
list reads as filler.

## 3. The Mechanism Explainer

**WHEN** you have a claim about behaviour and can explain *why* the mind or the market produces
it.
**SHAPE** Claim → the mechanism → the instruction that follows from the mechanism.
**LENGTH** 200–400 characters, ONE paragraph. Winners averaged 1.2 lines; losers ran 9.2 lines
and 844 characters.
**FAILURE MODE** Explaining the mechanism at essay length. The instruction is what gets saved.

## 4. The Gap Post

**WHEN** you can name two to four facts that are individually known but collectively imply
something nobody has said.
**SHAPE** Fact fragments, often a bare list → the tension between them → a closing line handing
the reader the opportunity or the unanswered question.
**LENGTH** 300–450 characters, three or four short paragraphs.
**FAILURE MODE** Answering your own question in the last line. Leave the gap open.

## 5. The Operator Confession

**WHEN** something in your own business is risky, went wrong, or contradicts what you sell.
**SHAPE** Name the risk or the miss in the first clause, with no cushion. Then the specifics.
Then what you are doing about it, or the trade-off you accept.
**LENGTH** 150–500 characters.
**FAILURE MODE** Burying the admission below line one, or resolving it too neatly. A confession
that ends in a win is an ad.

## 6. The Sourced Observation

**WHEN** you talked to someone, ate with someone, or asked someone who actually knows.
**SHAPE** The provenance in the first clause → what they said, compressed → what it changed for
you.
**LENGTH** 200–450 characters.
**FAILURE MODE** Name-dropping without a transferable insight. The reader should be able to use
it without knowing the person.

## 7. The Build Log

**WHEN** you are mid-problem and thinking out loud, with real numbers.
**SHAPE** First person, chronological, unpolished. State the numbers. Say which one is weak and
why. Include the thing you do not know yet. Pre-empt the obvious criticism.
**LENGTH** 800–1,500 characters. Winners averaged ~1,246 characters and 10.8 lines against ~222
and 2.7 for losers — a 5.6x length advantage.
**FAILURE MODE** Polishing it. The unresolved part is what draws replies.

## 8. The Receipts List

**WHEN** you spent money, time or effort learning something the reader would otherwise learn
expensively.
**SHAPE** A framing line naming the cost → bullets, each with a **reason attached**, written as
if texting a friend.
**LENGTH** No ceiling. The highest-bookmark structure in the corpus.
**FAILURE MODE** Bullets without reasons. "Hire slowly" is a platitude; "hire slowly because the
first bad hire sets the bar for the next five" is a receipt.

## 9. The Timeline

**WHEN** a chapter is ending — a launch, an exit, a role change, a year in review.
**SHAPE** Year or phase blocks with bullets under each. **Mix the enormous with the human** in
the same list. End on one word.
**LENGTH** Long, no ceiling.
**FAILURE MODE** All milestones, no texture. The small human entries are what make it readable.

## 10. The Contrast Open

**WHEN** two actors are responding to the same problem in opposite ways.
**SHAPE** "While A is doing X, B is doing Y" → the mechanism, explained plainly → a closing line
locating what is actually new, which is usually a decision rather than a technology.
**LENGTH** 600–1,000 characters.
**FAILURE MODE** Picking a side in line one. The contrast does the work; the verdict comes last
or not at all.

## 11. The Reframe Hook

**WHEN** everyone is reading an event one way and you think it is about something else.
**SHAPE** "X didn't do A. It did B." in line one → a line naming what coverage is missing → the
evidence, with names, quotes, filings → the real point.
**LENGTH** 400–3,000 characters. Earn the length with facts on every line.
**FAILURE MODE** Contrarianism without evidence. If the reframe rests on opinion, it reads as a
take, and takes do not get bookmarked.

## 12. The Demo Drop

**WHEN** a tool did something that would have been a company two years ago.
**SHAPE** One line of framing → **the actual prompt or artifact, verbatim** → a flat,
understated verdict.
**LENGTH** Short frame, long artifact, three-word close.
**FAILURE MODE** Describing the output instead of showing it. The artifact is the post.

## 13. The Ship Note

**WHEN** you shipped something.
**SHAPE** What it does now. Who benefits. Stop.
**LENGTH** Under 25 words. No thread, no "excited to announce", no rocket emoji.
**FAILURE MODE** Turning it into a launch announcement. The restraint is the signal.

## 14. The Two-Types Split

**WHEN** the same situation produces opposite outcomes depending on one variable.
**SHAPE** "Two kinds of people [do X]:" → the losing behaviour → the winning behaviour → a rule
in two mirrored lines.
**LENGTH** 200–350 characters.
**FAILURE MODE** Making one type a strawman. Both must be recognisable, or the reader is not in
the post.

## 15. The Number Compression

**WHEN** a price, cost or capability moved further than people realise.
**SHAPE** The number in line one → the source, named → a line relocating it into its real
category → historical analogies that make the scale land.
**LENGTH** 600–900 characters.
**FAILURE MODE** An unsourced number. One unverifiable figure discredits the rest.

## 16. The Human Post

**WHEN** an anniversary, a team moment, a person you admire, a loss.
**SHAPE** The occasion in one line → **specific small details about named real people** → what
that says about the thing that lasts. Warmth is allowed here and nowhere else.
**LENGTH** 300–700 characters.
**FAILURE MODE** Generic gratitude. Without specific detail it reads as performance.

## 17. The Zero Stack

**WHEN** the reader believes they are too far behind to start.
**SHAPE** A vertical stack of zeros or nulls → one line naming the only real difference.
**LENGTH** Under 40 words.
**FAILURE MODE** Explaining the stack. The visual carries it.

## 18. The Genuine Question

**WHEN** you actually want the answer and will act on it.
**SHAPE** One question. One line of why you are asking. Nothing else.
**LENGTH** Under 25 words.
**FAILURE MODE** Engagement bait. A question you already know the answer to reads as one, and
replies punish it.

---

## Porting a structure off X

> **Untested — this section is reasoning, not measurement.** Everything above comes from
> top-vs-bottom quintile analysis of real posts. Nothing below does: the corpus is X-only, so
> no data here says how these structures behave on LinkedIn, Instagram or TikTok. Treat it as a
> starting hypothesis, and say so if a user asks why a structure was chosen for a non-X platform.
> When the account has its own cross-platform history, `postey-analytics` on that account beats
> this table — use it instead.

One thing here **is** grounded: on Instagram and TikTok the structure governs the **spoken** hook,
not the caption. The caption follows its platform archetype
([platform-archetypes.md](platform-archetypes.md)), and the structure only shapes the first line.

The rest is inference from what each structure depends on:

| Structure depends on | So it likely needs | Structures |
|---|---|---|
| Value-per-line alone | nothing platform-specific | Receipts List, Two-Types Split, Mechanism Explainer |
| Room to develop a thought | a long-form surface | Operator Confession, Timeline, Human Post, Build Log |
| Compression to a single line | works as a spoken hook | Aphorism, Zero Stack, Two-Types Split |
| Reply culture, or pasting a raw artifact | a conversational text feed | Ship Note, Genuine Question, Demo Drop |
| A reader who follows a dense argument | X or LinkedIn behaviour | Reframe Hook, Number Compression |

Read the middle column, not the platform names — the dependency is the durable part, and it is
what tells you whether a structure survives a surface this table never anticipated.

## Self-check before returning a draft

1. Which structure is this, and does it obey that structure's length rule?
2. Is there a tension, surprise, or reversal? Name it in one clause. If you cannot, it is not
   ready.
3. Does every line make a claim the line above did not?
4. Density: is it under ~140 characters, or over ~600 with new facts throughout? If it is in the
   200–500 dead zone, cut it to a line or add material.
5. What makes someone reply? What makes someone bookmark? Answer both.
6. Run the AI-tells scrub in [hook-formulas.md](hook-formulas.md) — em-dashes, stacked
   period-rhythm, buzzwords, mission-statement closers.
7. Is every number and name verified?
8. Is there one detail only this author could have written?
9. Does the last line land on the non-obvious part?
10. Is any external link moved to the first reply? See [x-algorithm.md](x-algorithm.md).
```

## File: skills/postey/references/thread-and-video-formats.md
size: 8887
sha: 688e6caf1fabc6ed16ad64665f43777117bdd4a2
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/references/thread-and-video-formats.md

```text
# Thread, Reel, Carousel & Trend Formats

Part of the `postey` skill. Loaded on demand; see SKILL.md "Content Flows".

## Thread Formats (6-15 posts)

Classify before writing. If the content fits none of these, it's probably a single post, not a thread.

| # | Format | When to use |
|---|---|---|
| 1 | **Launch Breakdown** | Major product drop, model release, keynote, roadmap |
| 2 | **Challenger Upset** | An underdog product genuinely beats established incumbents (use sparingly, 1-2x/month) |
| 3 | **Builder Profile** | A founder or builder whose story is genuinely remarkable |
| 4 | **Video Gallery** | 6-15 striking clips on one shocking topic |
| 5 | **Resource Roundup** | 5-10 free tools/resources that solve an expensive problem |
| 6 | **Learning Roadmap** | Step-by-step how-to or free learning path |

**Audience filter:** before writing, ask "would a senior operator or investor find this insightful, or roll their eyes?" Punchy is fine; hype and fan energy get rewritten.

**Hook patterns (fill in the blanks):**
- Launch Breakdown: `BREAKING: [Company] just [bold transformation verb]. / [What launched, one plain sentence.] / [Stakes escalation.] / Here's the full breakdown:`: or the trend variant: `[CATEGORY] is taking over in [YEAR]. [Company] just announced [Product]. Here are [N] wild examples:`
- Challenger Upset: `[Challenger] just dropped [product] that beats [Leader 1], [Leader 2], and [Leader 3]. / [Two specific capabilities + one number.] / Here's everything:`: body tweet 1 introduces the product with a sourced, verifiable result (cite where it comes from; never invent a first-person test you did not run); tweet 2 contrasts the incumbent on the same sourced task.
- Builder Profile: `This is [Name], [Title] at [Company]. / [N] years ago, [dramatic surprising action]. / The journey: 👇`: body is chronological chapters: origin, first inflection, the bold bet (with a number), the setback, the breakthrough (with a metric), where they are now, one-sentence lesson without moralizing.
- Video Gallery: authentic disbelief opener, lowercase and raw, no "BREAKING:". One clip per post, one sentence of context max; the clip is the post.
- Resource Roundup: `Everyone pays $[Y] for [Z], but [problem]. / I found [N] FREE [things] that [specific outcome].`: one resource per post: name, URL, what it does, how to use it, result.
- Learning Roadmap: `[N] things I learned [doing X] that nobody teaches you:`: each post is one actionable, copy-pasteable step.

**Body building blocks:** numbered feature (name + what it does + how to use + proof); numbered announcement with arrow sub-points (→); numbered demo with the exact prompt used. Around post 10, include a proof beat: a benchmark, a named quote, or a counter-take. Close with a follow CTA + bookmark line (curation formats only; keep it out of authoritative long-form voice).

**Universal thread voice rules:** first 3 words must grab; line break after every sentence; verbs over adjectives ("DEFEATED" not "amazing"); specific numbers only; every claim followed by immediate proof; short sentences; max 1-2 emojis per post; no buzzwords, em-dashes, or hashtags; no moralizing close; media on nearly every post (write `[ATTACH: description]` placeholders and flag missing media).

**One documented framing mechanic, use judiciously:** when a company isn't widely known, category- or region-level framing in the hook ("[Country]'s robots just...") often outperforms the company name; name the specific company later in the thread for credibility. Keep the company name when the company itself is the story.

## Reel and Carousel Formats (Instagram)

**Core principle: optimize for Sends** (people DMing the post to a friend), the highest-signal engagement, ahead of views or likes. Saves are a close second. Every format below is engineered to be worth sending.

### Reel types

**1. Timely News Reel**: industry news from the last 24 hours only. "Just announced" must mean today or yesterday; verify recency before writing, or reword. Script: `[0-3s] hook (visual + one-line shock) → [3-15s] what it is → [15-40s] why it matters → [40-55s] personal take or prediction → [55-60s] CTA ("Send this to someone who needs to see it")`.

**2. Brand Storytelling Reel**: for product content, tell stories about the problem, never demo features. The audience should barely notice it's a product post. Frameworks: Before → After → Result (with numbers); The Moment I Realized (the frustration that led to the discovery); Team Pain Point (conflict → fix); The Number (funnel numbers → lesson). Script: hook (relatable pain) → the problem, vividly → the solution shown on screen → the result with a specific number → soft CTA. Cap product promos at roughly 1 in 5 posts.

**3. Top-10 Curation Reel**: the proven follower-growth format. Curated lists (tools, repos, resources) people save and send. Script counts down 10→1 with fast cuts, demos for the strong picks, and a "Save this. Send it to someone who needs it." close. Caption lists all 10 with one-line descriptions plus "Which one are you trying first?". Not too niche: broad enough that a large audience can use the list.

**4. Hot Take Reel**: a contrarian opinion stated bluntly to drive comment debates. Script: the take → 2-3 supporting facts → why the consensus is wrong → prediction → "Agree or disagree? Drop your take." Raw talking-head delivery beats polished editing for opinion content.

### Carousel types

**1. Top-10 List**: cover slide with the promise, one item per slide counting down, CTA slide. Design: 4:5 portrait (1080x1350), dark background, bold type; the ranking number must be one of the largest elements on the slide (it IS the curiosity hook); every slide carries a subtle swipe cue at bottom right.

**2. Step-by-Step Tutorial**: cover ("How to [result] in [N] steps") → one step per slide with a screenshot and instruction → result slide → CTA. Caption repeats the steps in text with "Save this for later."

**3. Comparison**: "[A] vs [B], honest review." Overview slide, 3 feature-round slides, pricing slide, clear-verdict slide, CTA. Honesty is the differentiator: name real cons for both sides, pick a winner, say why.

### IG caption rules

Hook line under 10 words (counter-intuitive claim, stat, or question) → 2-4 sentences of narrative with specific numbers → a close that drives sends or saves. First person. No em-dashes, no buzzwords. Specific > vague. Talk to a smart friend, not a conference room.

## Trend-Content Formats (the 5 pillars)

A repeatable daily/weekly mix for accounts covering a fast-moving industry. Every post carries the agent tag plus 2 or 3 topic tags, with the pillar name as one of the topic tags (the tagging scheme in SKILL.md house rules).

| # | Pillar | Format | Rule of thumb per run |
|---|---|---|---|
| 1 | **Video Clips** | 1-3 min clips mined from long-form interviews, podcasts, talks | 2-3 |
| 2 | **Breaking News** | Text-based, from official blogs, press releases, company posts | Only if it broke in the last hour |
| 3 | **Industry Drops** | Text breakdowns of what major players shipped or announced recently | 1-2 |
| 4 | **Innovation Showcase** | Real-world engineering/infrastructure breakthroughs; video is mandatory | 1 |
| 5 | **Leader Stories** | Timeless video clips of well-known founders/leaders sharing hard-won lessons | 2-3 |

**Pillar rules:**
- **Video Clips:** mine transcripts of long-form sources for standout segments. Ranking criteria: counter-intuitive statements, emotional vulnerability, bold falsifiable predictions, existential stakes, raw honesty about failure, life-changing frameworks, unfiltered opinions. Quality gates: 60-180 seconds; understandable standalone; clear hook in the first 5 seconds; passionate delivery beats scripted; specific numbers beat vague claims.
- **Breaking News:** "BREAKING" is reserved for events from the last ~60 minutes. Same-day-but-older news gets covered as an Industry Drop instead; never both for one story. If nothing qualifies, skip the pillar entirely; do not force it.
- **Industry Drops:** maintain a tracking list of the major players in your niche; summarize what shipped with specifics and a take on what it changes.
- **Innovation Showcase:** the video is the hook and the caption explains why it matters. No video available = pick a different innovation; never run this pillar as text.
- **Leader Stories:** not news, not product demos; timeless lessons through real stories. Before drafting, search the account's own post history for the key phrases; skip any angle already covered.

**Why video-heavy:** video content substantially outperforms text-only on X (see x-algorithm.md), which is why the two video pillars anchor the mix. Quality over quantity: don't burn 20 minutes hunting a third clip when the other pillars are ready.
```

## File: skills/postey/references/x-algorithm.md
size: 2461
sha: fd49cc7eb4a7746e799b3f9a6d33e6254db68e10
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/references/x-algorithm.md

```text
# X Algorithm Notes (Public Sources)

Part of the `postey` skill. Loaded on demand; see SKILL.md "Content Flows".

## X Algorithm Rules Worth Teaching Any Agent

Grounded in public sources: the open-sourced ranking code at `github.com/xai-org/x-algorithm` and `github.com/twitter/the-algorithm`, plus large-scale public analyses of post-performance data (including a study of 18.8M posts across 71,000 accounts). Weight figures are approximate, derived from third-party code reviews; re-check the repositories for updates.

**How ranking works (simplified):** candidates come from accounts you follow plus embedding-similarity retrieval; a transformer model predicts the probability of each user action (like, reply, repost, bookmark, dwell, follow, and negative actions like mute/report); the final score is a weighted sum of those probabilities. An author-diversity penalty limits repetition.

**Approximate engagement weights:**

| Signal | Relative weight |
|---|---|
| Replies | ~13-27x a like (full conversations higher) |
| Reposts | ~20x a like |
| Bookmarks | ~10x a like |
| Likes | baseline (1x) |

Negative actions (mute, block, report, "not interested") subtract. **Early engagement velocity is critical**: initial performance determines further distribution.

**Documented content factors:**
- Rich media (video, images, polls) raises predicted engagement. Video posts significantly outperform text-only.
- Threads generate roughly 3x the impressions of comparable single posts.
- Original content beats pure quote-posts and reposts.
- **External links in the main post cut reach 30-50%** (up to ~94% in some tests). Put the link in the first reply, never the main post.
- Premium subscriptions carry a documented distribution multiplier; smaller accounts see proportionally larger gains.

**Practical levers:** design for high-weight actions (genuine questions, strong opinions, actionable insights that invite replies and bookmarks); attach media; post when the audience is active; reply thoughtfully to early comments; keep a consistent topical niche (helps embedding-based matching); avoid spammy repetition.

**High-intent vs vanity signals:** bookmarks, "how do I do this?" replies, and profile visits convert; likes from peers, generic "great post!" replies, and follower count without activation do not. Content that earns bookmarks: numbered mistake breakdowns, step-by-step playbooks, before/after case studies with metrics, checklists.
```

## File: skills/postey/assets/icon.png
size: 9880
sha: cae1242474d044c3c00705b0c4cf3bd5396d12bb
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/assets/icon.png

Content is not inlined in the catalog. Read the upstream file: https://github.com/posteyai/skills/blob/main/skills/postey/assets/icon.png

## File: skills/postey/.claude-plugin/plugin.json
size: 679
sha: 14ace37782b67a25cbb4341e5a238860e99345db
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/.claude-plugin/plugin.json

```text
{
  "name": "postey",
  "displayName": "Postey",
  "description": "Draft, schedule, and manage social media posts across X, LinkedIn, Instagram, TikTok, YouTube, Threads, Bluesky, Facebook, and Pinterest",
  "version": "3.2.3",
  "author": {
    "name": "Postey",
    "url": "https://postey.ai"
  },
  "homepage": "https://postey.ai",
  "repository": "https://github.com/posteyai/skills",
  "license": "MIT",
  "skills": "./",
  "icon": "./assets/icon.png",
  "documentationUrl": "https://postey.ai/mcp",
  "supportUrl": "https://postey.ai/policies/support",
  "privacyPolicyUrl": "https://postey.ai/policies/privacy",
  "termsOfServiceUrl": "https://postey.ai/policies/terms"
}
```

## File: skills/postey/.mcp.json
size: 111
sha: 68a6b6e61cfd326f05fe19fbd1c921a34d970d91
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/.mcp.json

```text
{
  "mcpServers": {
    "postey": {
      "type": "http",
      "url": "https://mcp.postey.ai/mcp"
    }
  }
}
```

## File: skills/postey/.muse-plugin/plugin.json
size: 759
sha: 341549a7fd2179055f17945c77e8e6ebdefa3559
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/.muse-plugin/plugin.json

```text
{
  "schemaVersion": 1,
  "name": "postey",
  "displayName": "Postey",
  "version": "3.2.3",
  "description": "Draft, schedule and publish social posts across X, LinkedIn, Instagram, TikTok, YouTube, Threads, Bluesky, Facebook and Pinterest through Postey's hosted MCP server. One draft per network against each one's real limits; nothing publishes until you approve.",
  "compat": {
    "source": "native",
    "manifestDir": ".muse-plugin"
  },
  "capabilities": {
    "skills": [
      {
        "id": "postey",
        "path": "SKILL.md"
      }
    ],
    "commands": [],
    "hooks": [],
    "mcpServers": [
      {
        "id": "postey",
        "transport": "http",
        "url": "https://mcp.postey.ai/mcp"
      }
    ],
    "reminders": []
  }
}
```

## File: skills/postey/bootstrap-prompt.md
size: 3159
sha: ebe08b9a2fa65db791551cc7c16829cd7768b324
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/bootstrap-prompt.md

````text
# Postey Agent Setup Prompt

Copy everything in the block below and paste it into your AI assistant (Claude, ChatGPT, or any
agent with the Postey connector). One paste, one time.

Note for maintainers: when the Postey MCP server ships skill-serving (a skills resource and a
get-started prompt), point step 2 at the server instead of GitHub and keep this file in sync
with `SKILL.md mcp-tools:`. Until then, the GitHub fetch below is the one working path; do not
ship steps that reference server features that do not exist yet.

```text
You are now my social media content agent, powered by Postey.

How the two halves divide, so you never guess: the Postey MCP server owns
all state and every change to it - reading accounts, posts and schedules,
and creating, updating, publishing or scheduling anything. This skill is a
strict extension on top of it: playbooks, craft and judgment, plus the few
things that need my machine (local files, video processing). If MCP can do
it, use MCP. Never reach for a skill command to reach an effect MCP owns.

1. Verify the connection: check your own tool list first. If the Postey
   tools are absent from this session, stop and tell me. Do not drive
   another agent, read a local file, or call the REST API to answer
   around it. Having this skill loaded is not the same as being
   connected. Then read the MCP resource postey://accounts.
   If your client cannot read MCP resources, call the get_accounts tool
   instead - prefer the resource wherever both work. If neither returns,
   tell me the Postey connector isn't set up and stop.

2. Load the Postey playbook index: fetch
   https://raw.githubusercontent.com/posteyai/skills/main/skills/postey/pack.json
   then fetch the file named in its "skill" field from its "rawBase" URL.
   Do not fetch the other listed files now; fetch a reference or doc file
   only when a task needs it (the skill file says when).

3. Remember, using whatever persistence you support (memory, project
   knowledge, or saved instructions): the pack index (rawBase plus the
   file list) so you can fetch playbooks on demand, and these rules -
   my platforms come from postey://accounts (never assume), everything
   is a DRAFT until I say publish, scheduling counts as publishing so it
   also waits for my approval, every platform gets its own caption,
   and every task ends with the draft's share link.

4. Start: tell me which platforms I have connected, then offer me
   these and run whichever I pick.
   - Brand voice: I give you my website or handle; you learn my voice
     and draft content that sounds like me. If I have more than one
     account connected, ask which account the voice is for before you
     start - a profile belongs to one account, and putting one
     account's voice in another's post is the mistake to avoid.
   - Video everywhere: I drop a video link; you turn it into a post
     for every platform.
   - Trends: you find what's hot in my niche today and draft posts.
   - Idea to posts: I give you one rough idea; you draft posts for all
     my platforms and propose a schedule. Nothing publishes or gets
     scheduled until I approve.
```
````

## File: skills/postey/capability-snapshot.json
size: 4741
sha: 8f13258eb0ad39d38dad5d0470f2b67a2de01c8e
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/capability-snapshot.json

```text
{
  "_note": "GENERATED — do not hand-edit. Refresh with `node scripts/refresh-capability-snapshot.js` against a live server. This file is the single source the skill, the CLI and CI all derive capability from; a literal platform/tool list anywhere else is a regression (S9.5).",
  "generated_from": "postey://skill-manifest",
  "server_version": "3.0.0",
  "platforms": [
    "X",
    "LINKEDIN",
    "BLUESKY",
    "THREADS",
    "TIKTOK",
    "INSTAGRAM",
    "YOUTUBE",
    "FACEBOOK",
    "PINTEREST"
  ],
  "tools": [
    "add_tag",
    "connect_account",
    "convert_post_content",
    "create_post",
    "delete_draft",
    "file_manager",
    "get_accounts",
    "get_internal_comments",
    "get_platform_comments",
    "get_post_content",
    "get_posts",
    "get_review_status",
    "get_schedule",
    "get_team_info",
    "get_teams",
    "link_cli",
    "list_files",
    "publish_draft",
    "read_file",
    "remove_tag",
    "reply_comment",
    "resolve_share_link",
    "restore_post",
    "restore_posts",
    "review_post",
    "schedule_post",
    "transcribe_video",
    "unschedule_post",
    "update_post",
    "update_schedule",
    "upload_media",
    "validate_post_content"
  ],
  "resources": [
    "postey://accounts",
    "postey://accounts/{account_id}",
    "postey://accounts/{account_id}/analytics",
    "postey://accounts/{account_id}/analytics/posts",
    "postey://accounts/{account_id}/automations",
    "postey://accounts/{account_id}/tags",
    "postey://accounts/{account_id}/trash",
    "postey://notifications",
    "postey://platform-limits",
    "postey://platforms/{platform}/actions",
    "postey://platforms/{platform}/rules",
    "postey://posts/{post_id}/analytics",
    "postey://posts/{post_id}/comments/{platform}",
    "postey://posts/{post_id}/content/{platform}",
    "postey://posts/{post_id}/publish-status",
    "postey://setup",
    "postey://skill-manifest",
    "postey://teams",
    "postey://teams/{team_id}",
    "postey://teams/{team_id}/members"
  ],
  "prompts": [
    "analyze-engagement",
    "compose-post",
    "generate-captions-batch",
    "generate-captions-from-transcript",
    "improve-post",
    "repurpose-content",
    "review-for-virality"
  ],
  "canonical": {
    "account.connect": "connect_account",
    "account.list": "postey://accounts",
    "account.read": "postey://accounts/{account_id}",
    "account.tags": "postey://accounts/{account_id}/tags",
    "analytics.overview": "postey://accounts/{account_id}/analytics",
    "analytics.top_posts": "postey://accounts/{account_id}/analytics/posts",
    "automation.list": "postey://accounts/{account_id}/automations",
    "cli.link": "link_cli",
    "comment.internal.list": "postey://posts/{post_id}/comments/{platform}",
    "comment.platform.list": "get_platform_comments",
    "comment.platform.reply": "reply_comment",
    "file.list": "list_files",
    "file.read": "read_file",
    "file.upload": "file_manager",
    "media.transcribe": "transcribe_video",
    "media.upload": "upload_media",
    "notification.list": "postey://notifications",
    "platform.actions": "postey://platforms/{platform}/actions",
    "platform.limits": "postey://platform-limits",
    "platform.rules": "postey://platforms/{platform}/rules",
    "post.analytics": "postey://posts/{post_id}/analytics",
    "post.convert": "convert_post_content",
    "post.create": "create_post",
    "post.delete": "delete_draft",
    "post.list": "get_posts",
    "post.publish_status": "postey://posts/{post_id}/publish-status",
    "post.read": "postey://posts/{post_id}/content/{platform}",
    "post.resolve": "resolve_share_link",
    "post.restore": "restore_post",
    "post.restore_many": "restore_posts",
    "post.review": "review_post",
    "post.review.status": "get_review_status",
    "post.tag.add": "add_tag",
    "post.tag.remove": "remove_tag",
    "post.trash.list": "postey://accounts/{account_id}/trash",
    "post.update": "update_post",
    "post.validate": "validate_post_content",
    "publish.now": "publish_draft",
    "schedule.create": "schedule_post",
    "schedule.delete": "unschedule_post",
    "schedule.read": "get_schedule",
    "schedule.update": "update_schedule",
    "server.manifest": "postey://skill-manifest",
    "setup.read": "postey://setup",
    "team.info": "postey://teams/{team_id}",
    "team.list": "postey://teams",
    "team.read": "postey://teams/{team_id}/members"
  },
  "superseded_by": {
    "get_accounts": "postey://accounts",
    "get_internal_comments": "postey://posts/{post_id}/comments/{platform}",
    "get_post_content": "postey://posts/{post_id}/content/{platform}",
    "get_team_info": "postey://teams/{team_id}",
    "get_teams": "postey://teams"
  }
}
```

## File: skills/postey/CHANGELOG.md
size: 34870
sha: 4104e52dd0a222e1a39101b7d264009e579c2027
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/CHANGELOG.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/posteyai/skills/blob/main/skills/postey/CHANGELOG.md

## File: skills/postey/command-reference.md
size: 3911
sha: 3da58486806e7e2f538bdcd6f10329987fd5b2ea
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/command-reference.md

````text
# Postey CLI — Command Reference

All commands run via `${CLAUDE_SKILL_DIR}/scripts/postey.js <command> [args]`.

## Auth and setup

| Command | Description |
|---------|-------------|
| `auth:link --begin` | Print a link code and PKCE challenge. Hand the code to the `link_cli` MCP tool, then claim it. Copies this connection's access to the CLI — no second sign-in. |
| `auth:link --claim <code>` | Complete the link and store the credential. The token is never printed. |
| `auth:login [--local]` | Interactive OAuth in a browser. `--local` writes to `./.postey/`; prefer global. |
| `auth:logout` | Clear the local credential — the OAuth session and any linked token. Server-side grants are revoked in Postey settings. |
| `setup --key <key> [--location global\|local]` | Store an API key. `--key` is required unattended: without it the command prompts on stdin. |
| `config:show` | Report which credential is active and where it came from. Values are previewed, never printed. |

## Media

| Command | Description |
|---------|-------------|
| `media:upload --platform <platform> --file <path>` | Upload media file (unlinked), returns CDN URL |

## Video Subcommands

| Command | Description |
|---------|-------------|
| `video post --video <path\|url> --text "..." --platforms <CSV> --account-id <id>` | Upload video (and auto cover) and return the fields for MCP `create_post`. INSTAGRAM/TIKTOK/YOUTUBE get video attached; others get text only. Supports `--dry-run`. |
| `video trim --file <path> --start <sec> (--end <sec>\|--duration <sec>)` | Trim video clip (stream copy, no re-encode). `--end` and `--duration` are mutually exclusive. |
| `video info --file <path>` | Inspect video: duration, codec, dimensions, aspect ratio, platform hints via ffprobe. |
| `video transcribe --input <url\|path> [--platform <CSV> --account-id <id>]` | Transcribe audio via yt-dlp + Whisper. `--input` may also be passed as a bare positional argument (e.g. `video transcribe /path/to/file.mp4`). Returns `transcript` + `suggested_captions` per platform. With `--platform` + `--account-id` it also uploads the media and returns `draft_inputs` for MCP `create_post` — it does not create the draft. Supports `--dry-run`. |

## Setup & Configuration

| Command | Description |
|---------|-------------|
| `setup` | Interactive: prompts for API key, storage location, default social set |
| `setup --key <key> --location <global\|local>` | Non-interactive (auto-selects default if one social set) |
| `setup --key <key> --default-social-set <id>` | Non-interactive with explicit default social set |
| `setup --key <key> --no-default` | Non-interactive, skip default selection |
| `config:show` | Show current config, API key source, default social set |

## Examples

```bash
# Check current config
${CLAUDE_SKILL_DIR}/scripts/postey.js config:show

# Non-interactive setup (scripts/CI)
${CLAUDE_SKILL_DIR}/scripts/postey.js setup --key typ_xxx --location global --default-social-set 123

# Inspect a video before uploading
${CLAUDE_SKILL_DIR}/scripts/postey.js video info --file ./reel.mp4

# Trim a clip to 30 seconds
${CLAUDE_SKILL_DIR}/scripts/postey.js video trim --file ./reel.mp4 --start 0 --duration 30

# Upload video → Instagram Reel + text to LinkedIn and X
${CLAUDE_SKILL_DIR}/scripts/postey.js video post --video ./reel.mp4 --text "Caption" --platforms INSTAGRAM,LINKEDIN,X --account-id 317

# Dry-run to validate without making API calls
${CLAUDE_SKILL_DIR}/scripts/postey.js video post --video ./reel.mp4 --text "Caption" --platforms INSTAGRAM --account-id 317 --dry-run

# Transcribe a YouTube video and get suggested captions
${CLAUDE_SKILL_DIR}/scripts/postey.js video transcribe --input https://youtu.be/abc123

# Transcribe + create draft on Instagram and X
${CLAUDE_SKILL_DIR}/scripts/postey.js video transcribe --input https://youtu.be/abc123 --platform INSTAGRAM,X --account-id 317
```
````

## File: skills/postey/pack.json
size: 1539
sha: 908d4eb66b1900069d6f64f0b846cea76a1f070a
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/pack.json

```text
{
  "name": "postey",
  "version": "3.2.3",
  "description": "Postey hub: MCP/CLI routing, accounts, platform truth, the post lifecycle and the shared craft layer, plus the local-file and large-upload paths the MCP server cannot reach. Content flows ship as optional packs that require this one (postey-ideas, postey-video, postey-voice, postey-engagement, postey-analytics, postey-ops, postey-teams). Load references on demand.",
  "note": "rawBase pins the immutable release tag skills/postey/v<version>. Push that tag when releasing (see CLAUDE.md) or fetches 404. The bootstrap prompt fetches this manifest from main; everything else is fetched from the pinned tag so a later push to main cannot rewrite already-installed playbooks.",
  "skill": "SKILL.md",
  "bootstrapPrompt": "bootstrap-prompt.md",
  "docs": [
    "command-reference.md",
    "prompts.md",
    "routing-guide.md",
    "video-workflow.md"
  ],
  "scripts": [
    "scripts/mediaValidator.js",
    "scripts/postey.js",
    "scripts/videoUtils.js",
    "capability-snapshot.json"
  ],
  "references": [
    "references/brand-profile-template.md",
    "references/caption-playbook.md",
    "references/hook-formulas.md",
    "references/mcp-authentication.md",
    "references/mcp-workflows.md",
    "references/platform-archetypes.md",
    "references/thread-and-video-formats.md",
    "references/x-algorithm.md",
    "references/post-structures.md"
  ],
  "rawBase": "https://raw.githubusercontent.com/posteyai/skills/refs/tags/skills/postey/v3.2.3/skills/postey/"
}
```

## File: skills/postey/prompts.md
size: 6726
sha: 6c8d2c282a9ad6a754166eecdc50df5e19fa8395
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/prompts.md

````text
# Postey AI Prompts

Platform-specific prompts for generating titles and captions from video transcripts.
Use these after running `postey.js video transcribe` to generate high-quality, platform-native content.

> **Static snapshot:** The character limits, media specs, and writing rules below are a
> cached reference for offline use. In Claude Code sessions, read the live MCP resource
> `postey://platform-limits` (or `postey://platforms/{platform}/rules` per-platform) for
> authoritative, always-current platform specifications. The MCP resource is the single
> source of truth; this file is updated manually and may lag behind.
>
> **Style precedence:** for caption style (hashtag counts, CTA style, thread length,
> voice), `references/platform-archetypes.md` is the maintained playbook and wins over
> anything here that disagrees. Keep both in sync when editing either.

---

## YouTube

### Title
```
Write a YouTube video title for the following transcript. Requirements:
- Maximum 100 characters (hard limit); front-load the meaning in the first 70, since search results truncate around there
- Keyword-rich and SEO-friendly
- Create a curiosity gap or strong value proposition
- No clickbait — the title must accurately reflect the content
- Do NOT use emojis
- Do NOT use colons as the first separator (prefer "–" or "|" if needed)

Transcript:
{{transcript}}
```

### Description
```
Write a YouTube video description for the following transcript. Requirements:
- First 2–3 lines are the "above the fold" hook — make them count (viewers see these before clicking "more")
- Summarize the key value/takeaway in plain language
- Add timestamps if the video has clear sections (use format: 0:00 Intro)
- Include 3–5 relevant hashtags at the very end
- Maximum 500 words
- Natural, conversational tone — not a listicle

Video title: {{title}}
Transcript:
{{transcript}}
```

---

## Instagram

### Caption
```
Write an Instagram caption for the following video transcript. Requirements:
- First line is the hook — must stop the scroll (ask a question, make a bold claim, or tease the value)
- 150–300 words
- Use short paragraphs with line breaks for readability
- Include a clear call-to-action (save this, follow for more, comment below, etc.)
- End with 5–10 relevant hashtags on their own line, mixing broad and specific
- Conversational and relatable tone
- No corporate-speak

Transcript:
{{transcript}}
```

---

## TikTok

### Caption
```
Write a TikTok caption for the following video transcript. Requirements:
- Maximum 150 characters for the main hook (shown before "more")
- Hook must be punchy and create immediate curiosity or FOMO
- Use emojis sparingly but effectively (1–3 max)
- End with 5–7 trending, relevant hashtags
- Tone: fast, energetic, casual — like you're talking to a friend

Transcript:
{{transcript}}
```

---

## X (Twitter)

### Single post
```
Write an X (Twitter) post for the following video transcript. Requirements:
- Maximum 280 characters total (including hashtags)
- Lead with the single most compelling insight or hook
- Direct and punchy — no fluff
- No hashtags (they read as a low-quality signal on X; see references/x-algorithm.md)
- No emojis in organic posts

Transcript:
{{transcript}}
```

### Thread
```
Write an X (Twitter) thread for the following video transcript. Requirements:
- First tweet is the hook — must make people want to read the rest (max 240 chars, leave room for "🧵")
- Each subsequent tweet is one clear, standalone point
- 6–15 tweets total — thread only if the content genuinely has that many distinct beats; otherwise write a single post
- Last tweet closes with a value takeaway or a future-moment bookmark ("Bookmark this...") — never generic engagement bait (no follow/retweet/reply asks)
- Separate tweets with "---" on its own line
- Conversational but authoritative tone
- No hashtags

Transcript:
{{transcript}}
```

---

## LinkedIn

### Post
```
Write a LinkedIn post for the following video transcript. Requirements:
- First line is the hook — a bold statement, counterintuitive insight, or relatable struggle (no "I'm excited to share...")
- 150–400 words
- Use short paragraphs (1–3 lines each) with blank lines between them for mobile readability
- Tell a story or share a specific lesson — not a generic list
- End with a soft CTA or a question to drive comments
- Professional but human tone — avoid corporate jargon
- 3–4 lightweight hashtags at the end on their own line
- No emojis unless used once for emphasis

Transcript:
{{transcript}}
```

---

## Threads

### Post
```
Write a Threads post for the following video transcript. Requirements:
- Maximum 500 characters
- Conversational and authentic — Threads rewards genuine voice over polished marketing
- One clear thought or insight per post
- Optional: end with a question to spark replies
- 0–2 hashtags, usually none (they rarely help on Threads)
- Tone: like a thoughtful text message to your audience

Transcript:
{{transcript}}
```

---

## Bluesky

### Post
```
Write a Bluesky post for the following video transcript. Requirements:
- Maximum 300 characters
- Bluesky audience values authenticity, tech-savviness, and nuance
- Lead with the most interesting or surprising insight
- Conversational and direct
- 0–1 hashtags, usually none (the culture is hashtag-light)
- No corporate marketing language

Transcript:
{{transcript}}
```

---

## Multi-platform batch

Use this when generating captions for all platforms at once from a single transcript:

```
I have a video transcript below. Generate platform-optimized captions for each of the following platforms. Follow each platform's native style and constraints exactly.

Platforms needed: {{platforms}}

For YOUTUBE also generate a title.

Transcript:
{{transcript}}

Video original title (if available): {{video_title}}

---

Output format — one section per platform, clearly labelled:

## YOUTUBE TITLE
...

## YOUTUBE DESCRIPTION
...

## INSTAGRAM CAPTION
...

## TIKTOK CAPTION
...

## X POST
...

## LINKEDIN POST
...

## THREADS POST
...

## BLUESKY POST
...
```

---

## Usage in the Postey workflow

After running `postey.js video transcribe`, pass the `transcript` (and `video_title`) from the JSON output into the relevant prompt above. Then use MCP `create_post` with the generated caption:

```bash
# Transcribe
result=$(node ./scripts/postey.js video transcribe <url>)
transcript=$(echo $result | node -e "const d=require('fs').readFileSync('/dev/stdin','utf8'); console.log(JSON.parse(d).transcript)")

# Paste transcript into the prompt above, generate caption with AI, then
# use the MCP create_post tool with the generated content.
```
````

## File: skills/postey/routing-guide.md
size: 6567
sha: 4b20f8c0383359ee781d4dfd8bf6a6e0844e4f92
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/routing-guide.md

````text
# Tool Routing — Extended Reference

This document is the full routing reference for the Postey skill. The key rules are embedded in SKILL.md; this file provides additional context and edge cases.

## Two Surfaces, One Stack

They are layers, not alternatives. The MCP server carries the capability; the CLI adds only what the
server cannot reach — the user's own machine.

| Surface | Entry point | Owns |
|---------|-------------|------|
| **MCP tools/resources** | bare tool names (e.g. `create_post`) and `postey://` URIs | Every state read and **every write**; permissions; platform truth |
| **CLI** | `${CLAUDE_SKILL_DIR}/scripts/postey.js` | Local files, video processing, chunked upload, local auth config |

**The CLI has no write command.** Nothing in it creates, updates, publishes, schedules, deletes or
tags a post — those were removed, and `scripts/check-capability-overlap.js` fails the build if one
returns. The local-file commands upload and hand back the fields for an MCP write; they do not
perform the write. `command-reference.md` is the CLI's actual surface — routing that names a
command not in it is a bug.

> **Tool names are unprefixed here on purpose.** Most clients namespace MCP tools as
> `mcp__<server>__<tool>`, where `<server>` is whatever the *user* named the connection — during this
> skill's own audit the same server appeared under three different names, and none matched what the
> skill had hardcoded. Match on the bare tool name (`create_post`) and call whatever form your client
> exposes.

## Full Decision Tree

```
1. Does the task involve a LOCAL FILE PATH (~/video.mp4, ./cover.jpg)?
   → CLI unconditionally. MCP cannot access the local filesystem. The CLI uploads the file and
     returns the fields for the MCP write; the write itself is still step 5. Stop here.

2. Does the task involve VIDEO TRANSCRIPTION (yt-dlp + Whisper)?
   → `node ${CLAUDE_SKILL_DIR}/scripts/postey.js video transcribe <url>` wherever the CLI runs.
     Connector-only clients (no CLI) use the `transcribe_video` MCP tool instead. Stop here.

3. Is the task READ-ONLY state retrieval (accounts, teams, post content)?
   → Read the MCP resource URI directly when your client supports MCP resources; resource-blind
     clients (many hosted connectors) use the equivalent read tools instead.
     - Accounts  → postey://accounts
     - Teams     → postey://teams
     - Post content → postey://posts/{id}/content/{platform}

4. Is the task CONTENT VALIDATION or VIRALITY REVIEW before publishing?
   → MCP tools: validate_post_content, review_post
     No CLI equivalent — do not skip in any MCP-capable session.

5. Is it a WRITE (create, update, publish, schedule, delete, tag, upload by URL)?
   → MCP tools, in every environment: `create_post`, `update_post`, `publish_draft`,
     `schedule_post`, `delete_draft`, `add_tag`, `upload_media`.
     There is no second path — not the CLI, not the REST API. If no MCP server is reachable,
     the write cannot be performed at all: say so and stop, rather than reaching for a CLI
     command that does not exist.

6. Does the ENVIRONMENT (CI/CD, shell script, Cursor, Windsurf, SDK agent) change any of the above?
   → No. The environment decides whether the CLI is *available* and whether resources can be read
     — never who owns the operation. See the table below for what each environment can do.
```

## CLI-Only Operations

These operations **must** use the CLI where it is available:

- Local file uploads (`--file`, `--video` with local path) — no MCP equivalent
- Chunked video upload (>50 MB) via `video post` — no MCP equivalent
- Video transcription + cross-post via `postey.js video transcribe` (connector-only clients fall
  back to the `transcribe_video` MCP tool)
- Non-interactive setup: `setup --key ... --location global`

## MCP-Only Operations

These operations have no CLI equivalent and **must** use MCP tools:

- Every write — creating, updating, publishing, scheduling, deleting and tagging posts
- `validate_post_content` — validate before creating a draft
- `review_post` — virality coaching; returns a `job_id`
- `get_review_status` — collect the `review_post` result by `job_id` (or `post_id`); repeat while `running`
- Reading resources: `postey://accounts`, `postey://teams`, `postey://posts/{id}/content/{platform}`

## Layered Workflow (Correct Pattern)

A workflow that touches local files uses both surfaces in sequence — the CLI for the part that needs
the machine, MCP for the state and the write:

```
1. Read postey://accounts                                          ← MCP resource
2. postey.js video post --video ./reel.mp4 --text "…" \
     --platforms INSTAGRAM --account-id <id>                       ← CLI: uploads, returns fields
3. Validate content via validate_post_content                      ← MCP tool
4. create_post (account_id=…, platforms=…, media_urls from step 2) ← MCP write
5. Show the user the per-platform copy and wait for an explicit yes
6. publish_draft (post_id=…, platforms=[…])                        ← MCP write, only after step 5
```

Step 5 is not optional and does not collapse into step 6. `publish_draft` and `schedule_post` are
the two irreversible calls in this document — scheduling counts as publishing, because a scheduled
post publishes itself. A routing decision never doubles as approval.

## Environment-Specific Guidance

The CLI has no account-listing command — account discovery always needs MCP (resource or
`get_accounts` tool). Where no MCP server is reachable, the `account_id` comes from the user
or from stored config; never guess one.

| Environment | Read state | Write operations | Local-file work |
|-------------|------------|------------------|-----------------|
| Claude Code (interactive) | MCP resources | MCP tools | CLI |
| Hosted connector (claude.ai, ChatGPT) | MCP resources, or `get_accounts` / `get_posts` if resource-blind | MCP tools | Not available (no shell) — the user must supply a URL |
| Cursor / Windsurf | MCP resources or read tools (both support MCP) | MCP tools | CLI |
| SDK agent / CI/CD / npx **with the MCP server configured** | `get_accounts` / `get_posts` read tools | MCP tools | CLI |
| Any environment with **no MCP server** | Not available — ask the user | **Not possible.** No write path exists without MCP; tell the user to connect the server at https://app.postey.ai?settings=agents&section=advanced | CLI runs, but its output is only the input to a write that still needs MCP |
````

## File: skills/postey/video-workflow.md
size: 3256
sha: 44f120cb6ce8ef841645a212dccf899d1232fecc
upstream: https://github.com/posteyai/skills/blob/main/skills/postey/video-workflow.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/posteyai/skills/blob/main/skills/postey/video-workflow.md
