Ravenpost

View saved version →

---
name: manage-scheduled-posts
description: Find, edit, reschedule, cancel or delete posts already in Ravenpost, and check how a published post actually landed on each account. Use when the user asks what is scheduled, wants to change or move a post ("move Friday's post to Monday", "fix the typo in the draft", "cancel the TikTok one"), asks whether a post went out, or asks why one failed. Covers the trap that editing a post resets it to a draft, and what deleting does and does not remove.
---

# Manage posts that already exist

Everything here acts on a post that is already in Ravenpost. Composing a new one
is the `publish-a-social-post` skill. Full argument list:
[`../publish-a-social-post/references/tools.md`](../publish-a-social-post/references/tools.md).

**Settle the workspace first** — `list_workspaces`, and ask if there is more than
one. Post ids belong to a workspace like everything else.

## Finding the post

`list_posts` takes an optional `status`: `DRAFT`, `SCHEDULED`, `PUBLISHING`,
`PUBLISHED`, `FAILED`. "What's scheduled?" is `status: "SCHEDULED"`, which
comes back soonest first; "did anything fail?" is `FAILED`. It returns 50 posts
a page, newest first otherwise — `total` says how many match, and `page` reads
further back, so say "the 50 most recent" rather than "all of them" when
`totalPages` is more than one.

`get_post` returns one post with **every destination's own status, permalink and
error**. That per-target list is the answer to "did it go out?" — a post can be
published to X and failed on Instagram at the same time, and the rollup alone
would hide it.

## Changing one

| The user wants | Use | Watch out for |
|---|---|---|
| Different words, media, accounts or format | `update_post` | **It resets the post to a draft.** |
| The same post at a different time | `schedule_post` | Content untouched; absolute ISO 8601 with offset |
| It out now | `publish_post` | Not reversible — needs an explicit instruction |
| It gone | `delete_post` | Only removes Ravenpost's copy |

**The reset is the one that bites.** `update_post` returns the post to `DRAFT`,
so a scheduled post that is edited **stops going out** unless the same call also
carries `action` (`schedule` + `scheduledAt`, `queue`, or `now`). Fixing a typo
in Friday's post and leaving it there is how a post silently misses its slot.
When the user says "fix the typo", the whole job is: update, re-schedule to the
same time, and say both happened.

A published or publishing post can no longer be edited. Offer to delete it and
compose a new one instead — and see the next section before promising that.

## What deleting actually does

`delete_post` removes the Ravenpost copy and cancels a pending publish. **It does
not take down a post that is already live**, and on Instagram, Threads, TikTok and
YouTube nothing can: their APIs expose no delete endpoint Ravenpost holds the
scope for. Say which copies stay up rather than letting "deleted" be heard as
"gone from the internet". A post the user actually wants removed from Instagram
has to be removed in Instagram.

Deleting is permanent and takes the post's targets and queued jobs with it, so
confirm before calling it — a draft is cheap to keep, and there is no undo.

## Watching a publish land

Publishing is queued, not synchronous: `publish_post` and `create_post` with
`action: "now"` return as soon as the job is accepted. The per-account outcome
arrives seconds to minutes later.

So report it honestly — "queued for 3 accounts" — then call `get_post` to see
each target settle. A target that fails carries the platform's own reason in
`error`; pass it on verbatim rather than paraphrasing it into something vaguer.
Common ones are worth recognising:

- **a token that expired** — LinkedIn connections need reconnecting roughly
  every 60 days, and the account shows as needing attention on the Accounts page.
  Nothing you can do from here; tell the user where to fix it.
- **a missing Pinterest board** — the post was created without one. Add it with
  `update_post` (`board`), then re-publish.
- **TikTok rejecting an image** — PNG is refused; JPEG or WebP only, and the
  refusal arrives minutes after the upload succeeded.

View saved version →

---
name: measure-and-time-posts
description: Read a Ravenpost workspace's social analytics — follower counts per connected account, a 30-day follower series, and engagement on recent posts — and answer "when should I post?" without inventing a measured hour. Use when the user asks how a post or an account is doing, how many followers they have, which post did best, or when they should publish ("how did last week do?", "what's the best time to post on Instagram?"). Covers the difference between a metric that is zero and one that was never collected, which is the mistake this data invites.
---

# Measure posts, and time the next one honestly

One tool does the measuring, and it is read-only:

- `get_analytics` — followers per connected account with a 30-day daily series,
  plus engagement on recent posts.

**Settle the workspace first** (`list_workspaces`); analytics are per workspace,
and an agency's clients are measured separately for a reason. Full argument list:
[`../publish-a-social-post/references/tools.md`](../publish-a-social-post/references/tools.md).

## Absent is not zero

This is the rule that decides whether your answer is true.

- An account's `followers` is **`null`** when that platform reports none — not
  when the account has none. Which platforms report nothing today is named in
  `get_analytics`'s own description; trust that over memory, because it moves
  as permissions are granted. Say "Instagram reports followers; LinkedIn
  doesn't expose them", never "LinkedIn: 0".
- A post metric that is **missing** was not collected. Do not add it into a total
  as a zero, and do not present a sum as complete when part of it is unknown.
- `collectedAt` says when the numbers were last read from the platforms. If the
  user is surprised by a stale number, that is the explanation.
- A post's `source` is `ravenpost` for one published from here and `platform`
  for one that was already on the account and imported so its engagement counts.
  Both are real posts; only the first went out through Ravenpost.

## When to post

Ravenpost does not compute a "best time to post", and nothing it returns is
one. When the user asks:

- **If the workspace runs a posting queue** (`list_queue_slots`), its slots are
  the times this workspace has chosen to post. `create_post` with
  `action: "queue"` takes the next free one, with no arithmetic.
- **Otherwise ask for a time**, or offer one plainly as a suggestion — never as
  a finding.
- You may point at which recent posts earned the most engagement in
  `get_analytics`, but say how many posts that rests on. A handful of posts is
  an anecdote, not a measurement, and it does not make an hour "the best".

When you do schedule, pass `scheduledAt` as an absolute ISO 8601 datetime **with
the offset**, worked out in the workspace's timezone (`list_workspaces` gives
it), and show the user the local time you computed — a timezone mistake should
be visible before the post is scheduled, not after it goes out.

## Never

- Never invent a benchmark ("good engagement for this size is ~3%"). Report what
  was measured.
- Never present an hour as a measured best time to post. Nothing here measures
  one.

View saved version →

---
name: prepare-post-media
description: Get images and video into Ravenpost's media library and into the right shape for each network — upload from a URL, a local path or a direct presigned upload, reformat to feed, square, landscape, story or reel canvases, and cut one image into several platform sizes at once. Use when a post needs a picture or video, when the user hands over a file or link to post, when an image is the wrong aspect ratio for Instagram or TikTok, or when they ask what sizes a platform wants.
---

# Prepare media for a post

Media lives in a per-workspace library and is referenced by id: upload once,
reuse the id in as many posts as you like. **Settle the workspace first**
(`list_workspaces`) — a media id from one workspace is refused in another, and
a storage key is refused outright.

Full argument list:
[`../publish-a-social-post/references/tools.md`](../publish-a-social-post/references/tools.md).
Per-platform media rules:
[`../publish-a-social-post/references/platforms.md`](../publish-a-social-post/references/platforms.md).

## You cannot make the picture

These tools **ingest** files; nothing here generates an image or a video. If a
post needs media and the user has not provided any, ask for it. Do not describe
an image you intend to produce, and do not fetch a stock photo from the open web
on the user's behalf — that is someone else's licence, and they did not ask for it.

## Getting a file in

| Situation | Tool | Notes |
|---|---|---|
| The file is already online | `upload_media` with `url` | The usual case, and the cheapest |
| A large file, or anything in production | `create_media_upload` → HTTP `PUT` the bytes → `attach_media` | Bytes go straight to storage, never through this conversation |
| A small image you already hold as bytes | `upload_media` with `base64` | Images only; avoid for video |
| A local path | `upload_media` with `path` | A development server only — it reads its own disk. The hosted server does not offer the argument at all |
| It is already in the library | `list_media` | Reuse the id instead of uploading twice |

The presigned route is three calls on purpose: `create_media_upload` returns an
`uploadUrl` and a `storageKey`, you PUT the raw bytes to that URL with the
matching `Content-Type`, then `attach_media` records it with the **same**
`workspaceId` you presigned in.

## Shaping it

Images are reformatted on the way in; pass `format`:

- `feed_square` (1:1), `feed_portrait` (4:5 — the largest an Instagram feed shows),
  `landscape` (1.91:1), `story` (9:16, also what a reel or a TikTok photo wants),
  `original` (untouched).
- `fit`: `cover` crops to fill (default), `contain` pads so nothing is cut off.
- `crop`: `smart` finds the subject (default), `centre` is predictable — better
  for posters, screenshots and flat graphics composed around their middle.

`image_formats` returns the live list with target dimensions.

**One image, several networks:** `create_variants` cuts one library image into
any of `feed_portrait`, `feed_square`, `landscape` and `story` in one call and
returns the new ids. Variants inherit the source's alt text and folder, the
source is left alone, and two formats with the same dimensions produce one file.
This is the right move when a post goes to an Instagram feed and a TikTok at
once — pass each destination the id that fits it.

## Video is stored as-is

Video is never re-encoded: `format`, `fit` and `crop` are ignored, and the file
is recorded exactly as uploaded (mp4, mov or webm). Cut it before uploading.
Three consequences worth saying out loud before the post fails:

- **Instagram video must be posted as `REEL` or `STORY`.** An `IMAGE` or
  `CAROUSEL` post carrying a video is rejected at publish time.
- **Bluesky takes no video at all**, and **YouTube takes nothing but video**
  (one per post, no images).
- **TikTok refuses PNG images** — JPEG or WebP — and it refuses them
  *asynchronously*, minutes after the upload appeared to work. Convert before
  uploading rather than debugging it afterwards.

## Alt text

Alt text belongs to the asset, not the post: written once, it rides along to X,
Bluesky, Threads and Mastodon on every post that uses the file. Set it in the
Ravenpost media library.

View saved version →

---
name: publish-a-social-post
description: Compose, preview and publish a social media post with Ravenpost — Instagram, TikTok, X (Twitter), LinkedIn, Threads, Bluesky, YouTube, Pinterest and Telegram. Use whenever the user wants to post, tweet, share, cross-post, schedule, queue or draft something to their connected social accounts ("post this on Instagram and X", "schedule a tweet for Tuesday 9am", "put this in the queue", "draft a launch post"). Covers choosing the workspace and accounts, the per-platform limits and required fields a post can fail on, previewing before anything is written, and the confirmation a publish needs.
---

# Publish a social post

Ravenpost is compose-once, fan-out: **one post carries one caption and one set
of media, and goes to any number of connected accounts across nine networks.**
Each account is a separate destination with its own publish status, permalink
and error.

Full argument list for every tool: [`references/tools.md`](references/tools.md).
Caption budgets and per-platform rules: [`references/platforms.md`](references/platforms.md).

## Before writing anything

**1. Settle the workspace.** Call `list_workspaces`. With exactly one, pass
nothing and forget about it. **With more than one, ask the user which** and pass
`workspaceId` on every later call. Do not guess and do not pick the first: a
workspace is a client, and the accounts differ per workspace. The server enforces
this — a workspace-scoped call with several available fails with an error naming
them, which is your cue to ask, not to retry.

**2. Find the destinations.** `list_accounts` returns each account's `id`,
`platform`, `username` and `status`. Targets are **account ids**, never platform
names. If the user said "Instagram" and two Instagram accounts are connected,
ask which; if they said "everywhere", list what you are about to select and let
them confirm.

## The workflow

**3. Collect what the destinations require.** Only some of this applies:

- **Pinterest** — call `list_boards` for that account and pass `board`. A pin
  belongs to a board, Pinterest has no default, and without one the post is
  created and then fails at publish time.
- **Instagram reel audio** — `list_audio` (omit the query for what is trending),
  then pass the track as `audio`. Only reels, and only Instagram accounts
  connected through Facebook; the tool says so if the account cannot.
- **Instagram collaborators** — `collaborators` (up to three usernames) reach
  only an Instagram account whose `connection` in `list_accounts` is
  `FACEBOOK_LOGIN`, and never a story. On any other account they are dropped,
  the post publishes without them, and nothing reports it afterwards — so check
  before promising co-authors, and pass them to `preview_post`, which warns.
- **TikTok** — the `tiktok` argument carries the creator's posting options.
  Omit it and the post publishes **privately** (`SELF_ONLY`), which is the safe
  default, not a bug. Say so rather than letting the user assume it went public.
- **Media** — Instagram, TikTok, YouTube and Pinterest refuse a post with none.
  Use the `prepare-post-media` skill; pass the returned ids as `mediaIds`.

**4. Preview. Always, when you composed any part of the post.** `preview_post`
takes exactly `create_post`'s arguments, **writes nothing**, and returns the post
as each destination will render it plus a `warnings` list. Fix the warnings before
you write. A caption 40 characters over X's budget is a rejected post, and the
preview is the only place that is visible before the fact.

Skip the preview only when the user dictated the post verbatim and asked for it
to go out immediately.

**5. Show the user what will happen, then write it.** Name the accounts, the
caption, and the time. `create_post` needs `caption`, `accountIds` and `action`:

| `action` | What happens | When |
|---|---|---|
| `draft` | Saved, nothing scheduled | The user is still working on it |
| `schedule` | Goes out at `scheduledAt` | A time was given — absolute ISO 8601 **with offset** (`2026-07-05T09:00:00+03:00`) |
| `queue` | Goes out at the workspace's next free queue slot | "queue it", "next slot", "whenever you normally post" — see `list_queue_slots` |
| `now` | Publishes immediately | **Only** when the user explicitly asked to publish now |

**Publishing is the one step that cannot be undone.** People see a post within
seconds, and a post on Instagram, Threads, TikTok or YouTube cannot be taken
down through Ravenpost at all — deleting in Ravenpost removes our copy and leaves
theirs live. So
`action: "now"` and `publish_post` need an explicit instruction from the user in
this turn. Scheduling does not: it sits on the calendar where it can be read and
cancelled.

**6. Report what happened.** `create_post` returns the post id and its status.
Publishing is handed to a queue, so the per-account outcome arrives after the
call — `get_post` shows each target's status, permalink and error. Say "queued
for 3 accounts, I can check in a moment", not "published to 3 accounts".

## Decisions this skill makes for you

**One caption per post.** The MCP surface has no per-platform caption override.
If the user wants different wording per network — a short X post and a long
LinkedIn one — **create one post per group of accounts**, not one post and an
apology. Say that is what you are doing.

**Hashtags** go in `hashtags`; they are appended to the caption and count
against the budget like any other characters.

**Threads** (`thread`) are follow-up posts published in order after the caption,
which carries the media. Supported on X, Bluesky, Threads, Telegram; a platform
with no thread model just publishes the caption. Limits come from the strictest
selected platform, and an over-long thread is rejected rather than trimmed.

**Markdown belongs in Telegram-only posts.** Telegram renders a markdown subset
as real formatting; every other network publishes the caption verbatim, so
`**bold**` reaches Instagram as four asterisks.

## Refuse, or stop and ask

- Never invent media. The model cannot generate images or video here; the media
  tools ingest what the user provides. If a post needs a picture and there is
  none, ask for one.
- Never publish, delete, or change an existing post's schedule on your own
  initiative — only on a clear instruction.
- Never post to an account the user did not name or approve, and never fan out
  to "all accounts" without listing them first.
- If a tool errors, read it: this server's errors name the fix (which workspaces
  exist, which boards exist, why TikTok refused). Pass that on instead of
  retrying the same call.

## Worked example

> "Schedule this for Tuesday 9am on Instagram and X: *Ravenpost 1.0 is out.*"

1. `list_workspaces` → one workspace, nothing to ask.
2. `list_accounts` → `acc_ig` (@ravenpost), `acc_x` (@ravenpost).
3. `preview_post` with `caption`, `accountIds: [acc_ig, acc_x]` → warning:
   *Instagram requires media*. Ask the user for an image, upload it, preview
   again — clean, 31/280 characters.
4. Confirm: "Instagram @ravenpost and X @ravenpost, Tuesday 16 Sep 09:00
   (+03:00)."
5. `create_post` with `action: "schedule"` and
   `scheduledAt: "2026-09-16T09:00:00+03:00"`.
6. Report the post id and that both destinations are scheduled.

Referenced files: 2 — file references are metadata, not package contents.