PostZen

View saved version →

---
name: analytics
description: Build a social media analytics report from PostZen — post performance, follower growth, daily metrics, and best times to post across connected accounts. Use when the user asks how their posts or accounts are performing.
---

# PostZen analytics report

Produce a readable performance summary for the user's connected social accounts. The user's request follows: "$ARGUMENTS"

## Workflow

1. **Scope it.** Call `listAccounts` to see connected accounts. If the user didn't specify platforms or a time range, default to all accounts over the last 7 days and say so in the report.
2. **Pull the data** (parallel calls where independent):
   - `getAnalytics` — per-post engagement metrics for the period.
   - `getDailyMetrics` — day-by-day account-level metrics (impressions, engagement).
   - `getFollowerStats` — follower counts and growth.
   - `listPosts` — recently published posts, to tie metrics back to actual content.
   - `syncExternalPosts` stores imported records and is a write. Use it only when the user explicitly asks to synchronize external posts; ordinary analytics summaries use stored data.
3. **Synthesize, don't dump.** Lead with the headline (best-performing post, follower trend direction, notable spikes or drops). Then a short per-platform breakdown. Quote actual numbers with their period. Call out anything actionable — e.g. a content type that consistently outperforms, or a platform going stale.
4. **Close with timing guidance** if relevant: `getBestTimeToPost` gives data-driven posting-time suggestions per account; mention the top slots.

## Notes

- Some platforms gate analytics behind extra permission scopes; if a tool returns an authorization/scope error for one account, note it in the report ("analytics not enabled for this account — reconnect it in the PostZen dashboard to grant analytics access") and continue with the rest rather than failing the whole report.
- The analytics retrieval tools are read-only. Empty or unavailable history is not zero; report gaps without inventing metrics. Do not silently synchronize or modify account settings.

View saved version →

---
name: connect
description: Connect a new social media account to PostZen (X, Instagram, TikTok, LinkedIn, Facebook, YouTube, Threads, Pinterest, Bluesky, Telegram) or review/disconnect existing connections.
---

# Connect a social account to PostZen

Walk the user through linking a social account so posts can target it. The user's request follows: "$ARGUMENTS"

## Workflow

1. **Show current state.** Call `listAccounts` and summarize what's already connected (platform + username) so the user doesn't double-connect.
2. **Start the connection.** Call `createConnectUrl` for the requested platform. Give the user the returned auth URL as a clickable link and tell them to open it in their browser, sign in to the platform, and approve access. Do not try to complete the OAuth flow for them.
3. **Finish and verify.** The browser callback completes authorization. After the user says they have approved, call `listAccounts` again. Never request or exchange authorization codes in chat. Check the resulting account's `status` — not just that it appears. Potential pitfall:
   - A `connected` status proves auth, not publishing. If the user is connecting because publishing failed, suggest a quick test post (a draft, or a real post they confirm) to exercise the publish path. Sometimes users will forget to approve all permissions requested by the platform's OAuth flow.
4. **Platform-specific follow-ups:**
   - **Pinterest**: after connecting, a default board should be selected — use `listPinterestBoardsForSelection` and `selectPinterestBoard` (or `createPinterestBoard` for a new one). The board-selection window is time-limited, so do this right after connecting.
   - **Bluesky**: uses an app password rather than OAuth — direct the user to the connect URL, where they'll paste an app password generated in their Bluesky settings. Never ask the user to paste the app password into this chat.

## Disconnecting

`disconnectAccount` removes a connection. Confirm with the user first — scheduled posts targeting that account will no longer be able to publish.

## Cautions

- Never ask for or handle the user's social media passwords, app passwords, or tokens directly; the browser-based connect flow is the only path.
- If a connection repeatedly fails, point the user to the PostZen dashboard (https://app.postzen.dev) where the same flow exists with more error detail.

View saved version →

---
name: post
description: Create, schedule, or queue a social media post with PostZen. Use when the user wants to post, schedule, cross-post, or draft content for X (Twitter), Instagram, TikTok, LinkedIn, Facebook, YouTube, Threads, Pinterest, Bluesky, or Telegram.
---

# Post with PostZen

Publish or schedule the user's content using the PostZen MCP tools. The user's request follows: "$ARGUMENTS"

## Workflow

1. **Drafts without targets.** If the user only requests a draft and names no target accounts, call `createPost` with `isDraft: true`, title and content; no account selection is required.
2. **Resolve accounts for targeted posts.** Call `listAccounts` to get connected accounts. Each account has an `_id` (the `accountId` you must reference), a `platform`, and a `username`. If the user named platforms, match them; if ambiguous (multiple accounts on one platform), ask which. If a requested platform has no connected account, tell the user and offer to connect it (see the connect skill / `createConnectUrl`).
2. **Adapt the content per platform.** Don't blast identical text everywhere unless asked:
   - **X**: 280 chars for standard accounts — trim or thread-style tighten. Hashtags sparingly.
   - **LinkedIn**: longer-form is fine; professional tone; line breaks improve readability.
   - **Instagram / TikTok / YouTube / Pinterest**: media is required — a text-only post cannot publish there. If the user gave no media, either drop the platform (confirm first) or save as draft.
   - **Pinterest**: pins need a board; the account's default board is used unless the user picks one (`getPinterestBoards` / `listPinterestBoardsForSelection`).
   - **Bluesky**: 300 chars.
   - Platform value strings: `x` (alias `twitter`), `instagram`, `tiktok`, `linkedin`, `facebook`, `youtube`, `threads`, `pinterest`, `bluesky`, `telegram`.
3. **Handle media.** For local files, call `createMediaPresign`, upload the file with an HTTP `PUT` to the returned `uploadUrl`, then reference the returned `publicUrl` in the post's `mediaItems`. Already-hosted public URLs can be referenced directly.
4. **Choose the timing — exactly one of:**
   - `publishNow: true` — publishes immediately.
   - `scheduledFor` — ISO-8601 UTC, at least 60 seconds in the future. If the user gave a local time, convert to UTC and confirm the conversion.
   - `isDraft: true` — saves without publishing.
   - Queue: if the user says "add to queue" or gives no time preference for a scheduled post, pass `queuedFromProfile` (the profile id) on `createPost` instead of `scheduledFor` — PostZen claims the next free slot atomically and returns it. Never fetch `getNextQueueSlot` and pass its time as `scheduledFor` (the slot isn't reserved, so it can race); use it only to tell the user when their post would go out. `getBestTimeToPost` suggests data-driven times for non-queue scheduling.
5. **Confirm before publishing.** Show the final per-platform content and timing and get an explicit yes before calling `createPost` with `publishNow` or a near-term `scheduledFor`. Drafts don't need confirmation.
6. **Create the post** with `createPost`: `content`, `platforms: [{ platform, accountId }, ...]`, optional `mediaItems`, and the timing field. Report back the returned post `_id`, actual per-platform statuses, and scheduled time. Never equate pending or failed statuses with successful publishing. Pass a user-supplied request id as `x-request-id`. Reuse it for an explicitly requested replay of the same creation, and report the original ID from `existingPost` on replay.

## Cautions

- Publishing is a real, outward-facing action. Never call `createPost` with `publishNow: true` without the user's explicit confirmation in this conversation.
- Never invent `accountId` values — always take them from `listAccounts`.
- If a `createPost` call fails, report the actual error; don't retry blindly (retries can double-post if the first attempt landed).

View saved version →

---
name: queue
description: Set up and manage PostZen posting queues — recurring time slots that posts fill automatically. Use when the user wants to create, review, or reorganize their posting schedule, see upcoming slots, or post at their best-performing times.
---

# Manage PostZen queues

Help the user build and maintain a posting queue. The user's request follows: "$ARGUMENTS"

A queue is a set of recurring weekly time slots (e.g. Mon/Wed/Fri at 9:00) tied to a profile and timezone. Posts added "to the queue" are scheduled into the next open slot automatically.

## Workflow

1. **Show current state.** Call `listQueueSlots` and summarize the existing schedule as a compact weekly view (day + time + timezone). If empty, say so and move to setup.
2. **Setting up or changing slots:**
   - First resolve the profile with `listProfiles` and read its queue with `listQueueSlots`. `createQueue` creates an entire queue, not a single slot. To add or move slots on an existing queue, use `updateQueue` with its queue ID and the complete slot list, preserving all slots the user did not ask to change. Do not duplicate an existing day/time. Create a queue only when a new queue is requested or none exists. Confirm the timezone — use the user's profile timezone unless they specify one, and echo it back ("9:00 AM America/Edmonton").
   - If the user asks for "good times" or doesn't specify, call `getBestTimeToPost` for their connected accounts and propose a concrete slot set built from the top suggestions (e.g. 3 slots/week to start). Create the slots only after they approve the proposal.
   - To remove one slot, use `updateQueue` with the remaining slots. `deleteQueue` deletes a whole queue; omitting queueId deletes every queue on the profile. Always supply the intended queueId and obtain confirmation before deleting a queue. Existing posts retain their scheduled times. Reshuffling existing posts requires an explicit update with reshuffleExisting=true; do not request it unless the user authorized rescheduling.
3. **Review what's coming.** `previewQueue` shows how queued posts map onto upcoming slots — use it after any slot change so the user sees the effect, and whenever they ask "what's going out this week?" (combine with `listPosts` filtered to scheduled/queued for the full picture).
4. **Filling the queue.** Queue a post by calling `createPost` with `queuedFromProfile` (plus `queueId` for a non-default queue) instead of `scheduledFor` — PostZen assigns the next free slot atomically and returns it as the post's `scheduledFor`. Queuing several posts in sequence lands them in consecutive slots automatically. Never fetch `getNextQueueSlot` and pass its time back as `scheduledFor`: the slot isn't reserved by that call, so a concurrent create can take it and the post ends up scheduled outside the queue. `getNextQueueSlot` is for *telling the user* when their next slot is, nothing more.

## Notes

- Slots are per-profile. If the user has multiple profiles, confirm which one before creating or deleting anything.
- Keep proposals modest: a new queue with 3–5 slots a week is easier to sustain than a dense one; the user can always add more.
- All times shown to the user should include the timezone; silent UTC is how posts end up publishing at 3 AM.