⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v3.2.3

postey

posteyai@posteyai⭐ 6 stars· last commit 5d ago· 0 open issues

>

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐ 6 on GitHubGitHub ↗

New / niche

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

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

License

MIT

// HOW IT'S BUILT

// FILES

26 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/postey/SKILL.md26 KBf5b53cfb85c0upstream ↗
    ---
    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)
    
  • skills/postey/README.md2.5 KB3136490fff27upstream ↗
    # 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: [email protected] · https://postey.ai/policies/support
    
    ## License
    
    MIT
    
  • skills/postey/scripts/mediaValidator.js7.9 KB43928c12b535upstream ↗
    '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 };
    
  • skills/postey/scripts/postey.js76 KB53bad335ee02upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/postey/scripts/videoUtils.js5.0 KBac8c20472a7bupstream ↗
    "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,
    };
    
  • skills/postey/references/brand-profile-template.md3.3 KB08544c166d95upstream ↗
    # 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.
    
  • skills/postey/references/caption-playbook.md4.5 KB60ef91f24a97upstream ↗
    # 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
    
  • skills/postey/references/hook-formulas.md2.3 KBa340dcc5b966upstream ↗
    # 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.
    
  • skills/postey/references/mcp-authentication.md8.1 KB425f295f1ab4upstream ↗
    # 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.
    
  • skills/postey/references/mcp-workflows.md10 KBbc75a058524fupstream ↗
    # 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.
    
  • skills/postey/references/platform-archetypes.md6.6 KB6b0968ecea4dupstream ↗
    # 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.
    
  • skills/postey/references/post-structures.md11 KBceeb4e49e05bupstream ↗
    # 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).
    
  • skills/postey/references/thread-and-video-formats.md8.7 KB688e6caf1fabupstream ↗
    # 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.
    
  • skills/postey/references/x-algorithm.md2.4 KBfd49cc7eb4a7upstream ↗
    # 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.
    
  • skills/postey/assets/icon.png9.6 KBcae1242474d0upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/postey/.claude-plugin/plugin.json679 B14ace37782b6upstream ↗
    {
      "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"
    }
    
  • skills/postey/.mcp.json111 B68a6b6e61cfdupstream ↗
    {
      "mcpServers": {
        "postey": {
          "type": "http",
          "url": "https://mcp.postey.ai/mcp"
        }
      }
    }
    
  • skills/postey/.muse-plugin/plugin.json759 B341549a7fd21upstream ↗
    {
      "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": []
      }
    }
    
  • skills/postey/bootstrap-prompt.md3.1 KBebe08b9a2fa6upstream ↗
    # 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.
    ```
    
  • skills/postey/capability-snapshot.json4.6 KB8f13258eb0adupstream ↗
    {
      "_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"
      }
    }
    
  • skills/postey/CHANGELOG.md34 KB4104e52dd0a2upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/postey/command-reference.md3.8 KB3da58486806eupstream ↗
    # 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
    ```
    
  • skills/postey/pack.json1.5 KB908d4eb66b19upstream ↗
    {
      "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/"
    }
    
  • skills/postey/prompts.md6.6 KB6c8d2c282a9aupstream ↗
    # 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.
    ```
    
  • skills/postey/routing-guide.md6.4 KB4b20f8c03833upstream ↗
    # 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 |
    
  • skills/postey/video-workflow.md3.2 KB44f120cb6ce8upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/posteyai-skills-skills-postey.md

// REPO STATS

6 stars
0 open issues
Last commit: 5d ago