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 crea

Preview of the first 4,000 characters. Read full instructions →

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 bef

Preview of the first 4,000 characters. Read full instructions →

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 

Preview of the first 4,000 characters. Read full instructions →

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