Simplified

View saved version →

---
name: campaign-review
description: Prepare Simplified social drafts for client, stakeholder, or team review and manage approval-ready revisions. Use when the user asks to package selected or all drafts for approval, create and present a social review link or review bundle, collect a campaign for client review, inspect draft status, revise selected drafts, or prepare approved content for a later publishing step.
---

# Campaign Review

Turn a group of social drafts into a clear approval package without publishing them.

## Guardrails

- A review bundle is not publishing authorization. Never schedule or queue posts from approval language alone.
- Create a shareable review bundle when the user explicitly asks to package or send drafts for review. Otherwise preview the proposed bundle first.
- For agencies or multi-client work, create one review bundle per client and
  campaign. Never combine drafts from different clients, workspaces, or teamspaces
  in the same bundle.
- Modify only drafts the user selected or changes they approved.
- Do not expose internal IDs as the primary presentation; use names, channels, dates, and short copy previews.
- Present returned review URLs as clickable links, never embedded content.
- Stop on `401` or when Simplified is not connected.

## Workflow

1. Establish the client, campaign or review scope, reviewer, desired deadline, and
   which drafts should be included. Infer scope from the active campaign only when
   unambiguous.
2. For a named client workspace or teamspace, hand off first to
   `$simplified-workspace`: call `api_getWorkspaceInfo`, resolve the exact numeric
   teamspace ID with `api_listTeamspaces` when needed, state the selected client
   context, and pass the same `space_id` on every downstream account, draft,
   update, and review-bundle call. Re-resolve context when switching clients.
3. If exact draft IDs are already known, reuse them only after verifying they belong
   to the selected client scope. Otherwise call `social_getSocialMediaAccounts`,
   select the relevant account IDs, then call `social_getSocialMediaDrafts` with
   those IDs as the required comma-separated `account_ids` string. If that
   multi-account lookup returns no rows when drafts are expected, use the read-only
   per-account fallback: query each selected account separately, merge the results,
   and deduplicate by exact draft ID. Never create replacement drafts, invent draft
   IDs, assume that every draft belongs in the bundle, or reuse IDs from another
   client scope.
   - If the user explicitly asks for **all drafts**, select every connected account
     in the resolved client scope. Retrieve every draft page for those accounts,
     using `per_page: 100` and incrementing `page` until the response is exhausted.
     Apply the per-account fallback when needed, merge the results, and deduplicate
     by exact draft ID. “All” means all drafts in the resolved client scope, never
     all drafts across other client teamspaces.
4. Present a review manifest with client/teamspace, draft, channel/account, copy
   preview, media status, planned timing, and issues requiring attention. If the
   user did not identify the drafts, let them choose from this manifest before
   creating the bundle.
5. Apply requested copy, media, account, or settings changes with
   `social_updateSocialMediaDraft`, following the connector's current tool schema
   and carrying the selected `space_id`.
6. When authorized, call `social_createSocialMediaReviewBundle` once with `title`,
   optional `description`, all selected draft IDs in `draft_ids`, and the same
   `space_id`. Use a client-identifying title such as
   `Client — Campaign — Review round`.
7. Verify which drafts were included and return the response's `linkToReview` URL
   plus a concise manifest. For an “all drafts” request, state the total discovered,
   included, excluded, and failed counts so the user can verify completeness. Keep
   a separate bundle/link record for each client.
8. The hosted connector currently does not expose a separate append-to-existing-bundle tool. If the user asks to append drafts, explain the limitation; do not silently recreate or replace the bundle.
9. If the user later approves publication, hand off to `$simplified-social`: show the final account/date/media matrix and obtain explicit publishing confirmation before `schedule` or `add_to_queue`.

## Review Checklist

- Copy: factual accuracy, brand voice, CTA, spelling, and platform length.
- Targeting: correct connected account and audience setting.
- Media: present, accessible, and valid for the selected post type.
- Timing: intended date, account timezone, campaign order, and no past dates.
- Platform requirements: all required `additional` fields are present.
- Campaign consistency: offer, link, naming, visual identity, and legal terms agree across drafts.
- Client isolation: every draft, account, and bundle belongs to the same resolved
  workspace/teamspace; no cross-client IDs or assets are present.

## Output

Report the client/teamspace, bundle name, included and excluded drafts, unresolved
issues, and the review URL. State clearly that the content remains in review and
has not been published or scheduled.

For an explicit “create a review bundle of all drafts and present it” request,
creating the bundle is authorized: do not stop at a hypothetical preview. Complete
the scoped draft collection, create the bundle once, and present its clickable
review link and manifest.

Referenced files: 3

View saved version →

---
name: content-repurposer
description: Transform one source asset into multiple channel-native social posts and a reusable content sequence. Use when the user asks to repurpose a blog post, video, transcript, webinar, newsletter, announcement, product page, testimonial, case study, podcast, or existing social post into content for LinkedIn, Instagram, Facebook, TikTok, YouTube, Threads, Bluesky, Pinterest, or Google Business.
---

# Content Repurposer

Extract the strongest ideas from supplied source material and reshape them for the intended channels without inventing facts.

## Guardrails

- Treat the source as authoritative. Preserve names, numbers, claims, qualifications, links, and offer terms.
- Clearly label any interpretation that is not directly supported by the source.
- Return copy in conversation unless the user asks to save drafts.
- Create remote content with `action: "draft"`; require explicit approval before scheduling or queueing.
- Stop on MCP authorization failure or when required accounts are not connected.
- Present returned URLs as links, never as embedded media.

## Workflow

1. Read the complete source material available to the user. If only a link is provided, retrieve it with an available browsing or connector tool before writing; do not guess its contents.
2. Build a source ledger: central thesis, useful facts, proof points, quotes that may be paraphrased, stories, objections, CTA, and prohibited or unsupported claims.
3. Identify reusable angles such as insight, checklist, contrarian point, customer proof, behind-the-scenes detail, FAQ, short tip, and offer.
4. Select an output sequence that matches the source depth. Prefer fewer distinct posts over padded variations.
5. Adapt each post to the channel's audience behavior, length, hook, CTA, and media format. Do not merely shorten the same caption.
6. Call `social_getSocialMediaAccounts` once when the user wants connected-channel drafts.
7. Show the proposed set with its source angle and intended channel. If asked to save it, call `social_createSocialMediaPost` with `action: "draft"` and the required settings from `../simplified-social/references/platform-settings.md`.
8. If new supporting visuals are explicitly requested, use `$generate-image` with `storage: "asset"` and pass each returned `asset_id` into social `media`.
   If the user supplies a local visual, follow `$simplified-social` through
   signed upload and `api_registerAsset`, then reuse the returned UUID.
9. Wait for explicit approval before any scheduling or queueing operation.

## Transformation Patterns

- Long-form article: insight post, checklist, myth-versus-fact, quote card concept, and discussion prompt.
- Webinar or transcript: key lesson, clip concept, speaker insight, FAQ, and follow-up CTA.
- Case study or testimonial: challenge, turning point, outcome, lesson, and proof-led offer. Preserve exact attribution requirements.
- Product announcement: problem, benefit, differentiator, demonstration, objection response, and launch CTA.
- Event or promotion: announce, explain value, social proof, reminder, last call, and recap.

## Output

State what was extracted from the source, then present each channel-ready post with its angle, copy, CTA, and media suggestion. Report whether the result is copy only, saved drafts, or awaiting publishing approval.

Referenced files: 3

View saved version →

---
name: creative-testing
description: Design, produce, and evaluate disciplined social creative tests for marketers. Use when the user asks for A/B tests, hook tests, creative variants, message experiments, format tests, offer or CTA tests, an experimentation roadmap, ways to improve a campaign systematically, or draft variants whose results can produce a reusable marketing learning.
---

# Creative Testing

Create tests that isolate a meaningful decision and produce learning the team can reuse—not a pile of unrelated variants.

## Guardrails

- Do not claim statistical significance from ordinary organic social comparisons, small samples, unequal delivery, or platform-reported totals without a valid experiment design.
- Hold audience, offer, placement, timing, and CTA constant when testing a creative variable unless one of those is the declared variable.
- Preserve factual claims and required disclaimers across variants. Never make a test “stronger” by inventing proof or urgency.
- Image or video generation spends credits. Confirm ambiguous generation and avoid generating variants that do not test a defined hypothesis.
- Create variants as drafts and require explicit approval before scheduling or queueing.
- Do not automatically declare a winner from the highest raw engagement count; match the decision metric to the objective.

## Workflow

1. Define the business decision: what choice will change if this test succeeds? Resolve objective, audience, offer, channel/placement, conversion path, current control, constraints, and available volume.
2. When a baseline exists, call `social_getSocialMediaAccounts`, then retrieve relevant aggregated, range, and post analytics. Distinguish observed patterns from hypotheses.
3. Write one falsifiable hypothesis: changing **X** for **Y audience/context** should improve **Z metric** because **reason**.
4. Select one primary variable: hook, promise framing, proof type, visual treatment, opening frame, format, CTA language, creator/brand voice, or offer framing. Use [references/experiment-design.md](references/experiment-design.md) to control confounds.
5. Define the control and two to four purposeful variants. Each variant must express a distinct strategic alternative, not superficial synonym changes.
6. Choose a primary decision metric and guardrails before production. Examples: qualified reach/video hold for attention, saves or substantive engagement for utility, clicks/leads/bookings for response, and negative feedback for audience cost.
7. Produce a test matrix with invariant elements, variable, hypothesis, assets, account/placement, run window, minimum practical evidence, and decision rule.
8. If new creative is authorized, use `$generate-image` or `$generate-video` with reusable asset storage. Keep composition, product, and brand constants unless visual treatment is the tested variable.
9. Create each execution with `social_createSocialMediaPost` and `action: "draft"`, using required platform settings. Never publish one variant early and call it a fair comparison.
10. After the run, use `$social-performance-analyst` to compare results. Record result, confidence/limitations, learning, next decision, and follow-up test. Retain a control until a challenger wins under a credible comparison.

## Experimentation Standard

- Prioritize high-leverage uncertainty. Test the promise or proof before button color, emoji, or trivial copy edits.
- Separate exploration from validation. Early tests can identify promising territories; later tests should isolate and confirm the driver.
- Build variants from different audience tensions or persuasion mechanisms, not random creativity.
- Evaluate platform delivery effects, audience overlap, spend, timing, and sample imbalance before attributing performance to creative.
- Stop tests that create brand, legal, reputational, or customer-experience risk regardless of short-term metrics.
- Turn each result into a reusable rule with scope: what worked, for whom, where, under what conditions, and what remains unknown.

## Output

Lead with the decision and hypothesis. Then show the controlled matrix, draft/asset status, measurement and stopping rules, validity risks, and the learning record the team should complete after results arrive.

Referenced files: 2

View saved version →

---
name: cross-platform-campaign
description: Turn a launch, promotion, event, announcement, or marketing brief into a coordinated campaign of channel-native social posts. Use when the user asks to launch or promote something across multiple platforms, create a campaign sequence, coordinate social messaging, generate campaign visuals, prepare drafts, or schedule a multi-channel rollout.
---

# Cross-Platform Campaign

Build one coherent campaign while respecting how each social channel works. Compose the `generate-image` and `simplified-social` capabilities when campaign visuals are needed.

## Guardrails

- Do not publish or schedule without explicit approval of the final campaign matrix.
- Create safe previews with `action: "draft"` when the user asks to prepare the campaign.
- Image generation spends credits. Proceed when the image request is explicit; confirm first when visual generation is ambiguous.
- Carry a generated image's permanent `asset_id` into social `media`; never rely on its expiring signed URL.
- Stop on authorization failure or when no target accounts are connected.
- Present all returned URLs as clickable links, never inline images.

## Workflow

1. Distill the brief into audience, objective, offer, proof, CTA, dates, channels, tone, constraints, and success metric. State sensible assumptions instead of requesting a long questionnaire.
2. Call `social_getSocialMediaAccounts` once and map requested channels to returned account IDs.
3. Define the campaign spine: one promise, supporting proof, CTA, and a sequence such as tease, launch, proof, reminder, and last call.
4. Create channel-native variants. Change hook, length, CTA, format, and platform settings; do not paste the same caption everywhere.
5. Plan media by post. If generation is requested, follow `$generate-image`, discover the current model schema, and use `storage: "asset"` for anything that will be attached to a post.
   For a user-supplied local file, follow `$simplified-social` through signed
   upload and `api_registerAsset`, wait for `api_getAsset`, and carry the UUID.
6. Show a campaign matrix containing phase, date, account, copy, media, objective, and CTA.
7. When drafts are authorized, call `social_createSocialMediaPost` with `action: "draft"` for each post. Pass generated asset UUIDs in `media` and use `../simplified-social/references/platform-settings.md` for `additional` fields.
8. Offer a stakeholder review package via `$campaign-review` when several drafts need approval.
9. Schedule or queue only after the user explicitly approves the final matrix. `add_to_queue` means publish as soon as possible.

## Quality Bar

- Keep the promise and visual identity consistent across the campaign.
- Make each post useful on its own while advancing the sequence.
- Match media to platform format requirements; never attach an image to a reel or short that requires video.
- Do not invent product claims, prices, deadlines, testimonials, or availability.
- Surface missing landing-page URLs, legal copy, offer terms, or media before publishing.

## Output

Lead with the campaign idea and rollout. Then show the channel matrix, asset plan, drafts created, and any items blocking approval or scheduling.

Referenced files: 3

View saved version →

---
name: evergreen-content-engine
description: Build a renewable, long-lived content system that repeatedly turns durable brand expertise, customer questions, proof, and offers into channel-native social content. Use when the user asks for an evergreen strategy, always-on content engine, recurring content series, 60- or 90-day program, content bank, sustainable posting system, content recycling plan, or a way to keep publishing without chasing daily trends.
---

# Evergreen Content Engine

Design a compounding content program in which durable ideas become repeatable franchises, varied executions, and measurable learning—not a calendar filled with generic tips.

## Guardrails

- Do not label time-sensitive offers, statistics, platform features, event dates, seasonal advice, or changing regulations as evergreen.
- Treat brand claims, customer proof, prices, outcomes, and quotations as source-dependent. Never manufacture authority or testimonials.
- Separate planning, remote draft creation, scheduling, and publishing authorization.
- Create remote posts only with `action: "draft"` unless the user explicitly approves a final schedule or queue action.
- Do not automate indefinite recycling. Every reusable asset needs a review date, fatigue signal, and retirement rule.
- Stop when Simplified is unauthorized or required accounts are not connected.

## Workflow

1. Define the business objective, audience segments, buying questions, offers, expertise, proof library, content capacity, channels, cadence, and measurement horizon. State assumptions rather than forcing a long intake.
2. Call `social_getSocialMediaAccounts` once when connected-channel planning or drafting is requested.
3. If the user wants an evidence-led engine, inspect recent aggregated, trend, and post analytics. Use `$social-performance-analyst` for a full diagnosis.
4. Build a durable source map: customer questions, misconceptions, decision criteria, demonstrations, processes, founder/operator insight, customer evidence, and objection handling. Distinguish owned expertise from borrowed opinion.
5. Define three to five content territories with a strategic job, audience problem, credible point of view, proof sources, conversion bridge, and exclusions.
6. Turn territories into recurring franchises such as teardown, checklist, FAQ, myth, before/after process, decision guide, customer lesson, or behind-the-scenes operating principle.
7. Create a content bank with atomic ideas. Score each for relevance, distinctiveness, evidence strength, reuse potential, production effort, and shelf life using [references/content-system.md](references/content-system.md).
8. Build a 60- or 90-day sequence that balances discovery, trust, consideration, proof, and conversion. Rewrite ideas for each channel instead of duplicating captions.
9. When drafts are requested, call `social_createSocialMediaPost` with `action: "draft"`, permanent asset IDs, and platform settings from `../simplified-social/references/platform-settings.md`.
10. Define the renewal loop: review results, retain winners, vary one meaningful element, refresh changed claims, pause fatigued concepts, and feed learning back into the bank.

## Marketing Standard

- Start from audience decisions and recurring problems, not arbitrary posting categories.
- Give each territory a defensible brand angle. “Educational content” is not a territory until it has a subject, viewpoint, and audience consequence.
- Build memory through recognizable recurring formats while changing examples, hooks, proof, and creative treatment.
- Maintain an intentional conversion bridge. Evergreen does not mean every post sells, but the program should make the next step obvious over time.
- Protect production sustainability. A viable engine respects access to experts, customer proof, design/video capacity, approval time, and channel cadence.
- Use performance as directional evidence; do not let one outlier post rewrite the entire strategy.

## Output

Lead with the evergreen thesis and audience value. Then provide territories, franchises, source requirements, content-bank priorities, cadence, a dated first cycle, refresh/retirement rules, success measures, and the exact authorized state: plan, drafts, or awaiting scheduling approval.

Referenced files: 2

View saved version →

---
name: generate-image
description: >-
  Generate AI images with Simplified — text-to-image, image editing, and
  reference-guided generation across Flux, Google (Gemini/Imagen), OpenAI GPT
  Image, Ideogram, Stable Diffusion, Qwen and Seedream. Use when the user asks to
  create, generate, make, draw, or design an image, photo, picture, graphic,
  logo, poster, banner, icon, or illustration from a description.
---

# Generate AI Image

Generate an image from a text prompt using Simplified, across many leading AI
providers, and return a viewable image URL (plus an asset id you can reuse).

## What it can do

- **Text-to-image** (`capability: "prompt"`) — make an image from a description.
- **Image editing / image-to-image** (`capability: "reference_image"`) — transform
  or edit using one reference image.
- **Multi-reference composition** (`capability: "multiple_images"`) — guide with
  several reference images (supported on some models).

Good for: product shots, hero/banner images, social graphics, illustrations,
3D-style renders, icons/logo concepts, photoreal scenes, and **text rendered inside
the image** (posters, quote cards, ad headlines).

## How to use it

1. **Discover** — call `api_getModelFields(type: "image")` to get the current list of
   models, capabilities, and credit costs. Filter out models that cannot satisfy the
   requested capability; don't choose on model name alone.
2. **Choose the model** — use [Model selection](#model-selection). For the selected
   model, call `api_getModelFields(type: "image", model_id, capability)` and use its
   exact `parameters` schema. This is the source of truth; don't guess model ids,
   capabilities, field names, or costs.
3. **Choose storage** — `transient` for a one-off, `asset` to reuse the image (e.g.
   post it via the `simplified-social` skill).
4. **Explain the choice when it matters** — before a costly or ambiguous request,
   name the selected model, why it fits, and the discovered credit cost. If the user
   explicitly chose a model, honor it when it supports the requested capability.
5. **Generate** — call `api_generateImage` with `parameters` matching the discovered
   schema. This spends credits.
6. **Present the result** — show the returned URL as a link, never embedded (see
   [Presenting the result](#presenting-the-result)).

For an ordinary prompt-only request, use the quality-first default below after
confirming it is still available. Always inspect live fields for reference-image,
multi-image, exact-size, quality, or resolution requests.

## The request

### The tools

- **`api_getModelFields`** — discover available models and the per-(model, capability)
  field schema. Read-only, spends **no credits**. Call it first.
- **`api_generateImage`** — **consumes paid AI credits**.

### Fields

Top-level fields for `api_generateImage`:

- `model` — a model id from `api_getModelFields` (e.g. `google.gemini-3.1-flash-image-preview`).
- `capability` — `prompt` | `reference_image` | `multiple_images`.
- `storage` — see [Storage](#storage) (default `transient`).
- `parameters` — a **required nested object**; never flatten its fields to the top
  level, and put the prompt text in `parameters.prompt` (not in `capability`).

The **exact keys inside `parameters` vary by model** — get them from
`api_getModelFields(type: "image", model_id, capability)`, don't assume. They differ
in real ways: most models take `aspect_ratio`, but OpenAI GPT Image uses `size` +
`quality` + `count`, Gemini adds `image_size`, Flux 2 uses `resolution`, and the
reference-image field is variously named `input_image`, `image_prompt`,
`reference_images`, `source_image`, or `style_reference_images`.

### Resolving Simplified asset references

Treat a Simplified `asset_id` as the canonical reference, but follow the live model
schema at the generation boundary. When a model field is a URL or URL list (for
example Gemini `reference_images`):

1. Call `api_getAsset` with the permanent asset UUID.
2. Require `status: 4` (`DONE`) and the expected `asset_type` before generating.
3. Pass the current `file_url` returned by `api_getAsset` into the model-specific
   reference field. If the URL is signed, preserve its complete query string and use
   it before expiry.
4. Do not trust a cached URL copied from a brand-kit record when an `asset_id` is
   available. Brand records can contain stale or malformed derived URLs; resolve the
   ID immediately before generation instead.

In short: **IDs at rest, URLs at the model boundary, IDs downstream.** Do not pass a
client-local path to the hosted connector.

### Storage

| `storage` | Behavior |
|---|---|
| `transient` | **Default.** Temporary URL, not saved, expires. Best for one-off images. |
| `asset` | Persistent — no expiry, returns an `asset_id`. Use when you want to **reuse** the image, e.g. attach it to a post via the `simplified-social` skill (pass the `asset_id` in `media`). |
| `default` | Saved to your AiImageArt gallery. |

### Examples

**Text-to-image (default, transient):**
```json
{ "model": "google.gemini-3.1-flash-image-preview", "capability": "prompt", "storage": "transient",
  "parameters": { "prompt": "A white ceramic coffee cup on a clean white background", "aspect_ratio": "1:1" } }
```

**Keep it to reuse / post to social (asset):**
```json
{ "model": "google.gemini-3.1-flash-image-preview", "capability": "prompt", "storage": "asset",
  "parameters": { "prompt": "product hero shot of sneakers", "aspect_ratio": "4:5" } }
```

**Edit / reference-guided** — the reference field name is model-specific; take it from
`api_getModelFields` (here `input_image` for a Flux Kontext model, not a guessed name):
```json
{ "model": "flux.flux-kontext-pro", "capability": "reference_image", "storage": "asset",
  "parameters": { "prompt": "put this logo on a t-shirt", "input_image": "<asset_uuid_or_https_url>" } }
```

## Model selection

Choose for the requested outcome, not provider popularity. These routes are maintained
defaults, but model availability, capabilities, parameters, and credits can change;
`api_getModelFields(type: "image")` remains authoritative.

| User need | Preferred model | Why / tradeoff |
|---|---|---|
| Normal social image, product shot, illustration, character continuity, or general edit | `google.gemini-3.1-flash-image-preview` | **Quality-first default.** Strong all-around prompt following and reference fidelity. Do not interpret “Flash” as the cheapest option. |
| Complex professional design, dense typography/layout, menu, invitation, high-fidelity product mockup, factual visualization, or explicit 4K | `google.gemini-3-pro-image-preview` | Premium quality and instruction handling; slower and typically costs more. Use only when the request benefits from it. |
| Budget-sensitive generation or explicit GPT Image request | `openai.imgen-2` | The catalog's `credits_per_image` is a **baseline**, not the final charge. Cost varies with `size`, `quality`, and `count`. Use the live API field `quality: "auto"` (the operational “effort auto” setting) unless the user requests a different quality. It uses `size` rather than `aspect_ratio`. |
| Short headline or typography-first poster/banner | `ideogram.ideogram-v3-turbo` | Specialized text rendering. Prefer Gemini Pro when the design also requires a dense or complex professional layout. |
| Targeted edit with a single source image | `google.gemini-3.1-flash-image-preview`; `flux.flux-kontext-pro` when explicitly requested or better suited by live metadata | Default to Gemini for fidelity. Flux Kontext is a specialized alternative; inspect its `input_image` contract first. |
| Many reference images or exact reference limits | Best compatible model returned live | Filter by `multiple_images` and the discovered reference limit. Never assume every model accepts the same number or field name. |
| User names Flux, Seedream, Qwen, Stable Diffusion, or another available model | The requested model, if compatible | Respect an explicit preference. Otherwise do not automatically route to an unvalidated specialist merely because it is available or cheaper. |

### Routing rules

1. Infer the hard constraints: capability, reference count, aspect ratio/size,
   resolution, text/layout complexity, budget, and any explicit provider choice.
2. Filter the live catalog by those constraints.
3. Use Gemini 3.1 Flash when no stronger constraint applies. Upgrade to Gemini 3 Pro
   only for the professional-design cases above. Consider GPT Image 2 when minimizing
   credits is explicit or as the first fallback, but state that its live catalog rate
   is only a baseline and the final charge varies with `size`, `quality`, and `count`.
   Default to `size: "auto"`, `quality: "auto"`, and `count: 1` unless the request
   requires different values.
4. For a typography-first graphic, choose Ideogram Turbo; for dense layout or 4K,
   choose Gemini Pro instead.
5. Never silently change models after an error. Report the failure and proposed
   fallback with its live credit cost, then regenerate only when the user's existing
   intent clearly authorizes the additional spend.

When a request is ambiguous and the choice materially changes cost or output, offer
the most relevant two choices, leading with the recommended model. Do not dump the
entire catalog on the user.

## Response

The response shape depends on `storage`:

- **`transient` (default)** — `result` is a list of **URL strings**:
  ```json
  { "status": "SUCCESS", "detail": { "result": ["https://replicate.delivery/…/out-0.webp"], "transient": true } }
  ```
  Read `detail.result[0]` (a URL string). No `asset_id` — the URL is temporary.

- **`asset`** — `result` is a list of **objects** with a reusable id:
  ```json
  { "status": "SUCCESS", "detail": { "result": [{ "asset_id": "<uuid>", "url": "https://…/image.webp?Expires=…" }], "transient": false, "storage": "asset" } }
  ```
  Read `detail.result[0].url` (the image; **signed URL — expires**) and
  `detail.result[0].asset_id` (permanent — hand off to `simplified-social`'s `media`).

Output format varies by model and provider. Inspect the returned asset or response
metadata instead of assuming WebP; for example, Gemini may return JPEG.

## Presenting the result

**Never embed the returned image URL with Markdown image syntax** (`![](url)`), and
never do anything that makes the client fetch/render the image inline. Always present
the result as a **plain URL or a Markdown link** the user can click:

- ✅ `Here's your image: https://…/out-0.webp`
- ✅ `[View generated image](https://…/out-0.webp)`
- ❌ `![generated image](https://…/out-0.webp)`

Reasons: these URLs are signed and **expire**, inline rendering fails or shows a
broken image, and clients like Codex otherwise try to display the asset instead of
handing the user a usable link — poor UX. When `storage:"asset"`, also surface the
permanent `asset_id` (as text) so it can be reused with `simplified-social`.

## Gotchas

- **Discover before generating.** Call `api_getModelFields` to confirm the model id
  and `parameters` schema — it eliminates 400 errors on invalid/missing keys and
  prevents routing from stale model or credit assumptions.
- **Resolve asset-backed references before generating.** Use `api_getAsset`, require
  `status: 4`, and pass its current `file_url` when the live model field expects a
  URL. Keep the source `asset_id` for future runs.
- **Generation spends credits.** If the request is ambiguous, restate what you'll
  generate and confirm once. If it's explicit, proceed.
- **Do not overstate GPT Image 2 pricing.** Treat `credits_per_image` as baseline
  metadata. Final usage varies with `size`, `quality`, and `count`. The live API calls
  the effort control `quality`; use `quality: "auto"` for the usual “effort auto”
  behavior and never describe the baseline as the guaranteed charge.
- `429` = AI credits exhausted; tell the user plainly and don't retry.
- On error, report it; don't silently retry.

## Example prompts to try

- "A minimalist product photo of a white ceramic coffee cup on a clean white background, soft studio lighting"
- "A vibrant 3D render of a friendly robot mascot, pastel colors, studio lighting, 1:1"
- "A cinematic 16:9 landscape of snowy mountains at golden hour"
- "A flat vector app icon of a paper plane, rounded corners, blue gradient"
- "A bold quote card that says 'Ship it' in modern type" (use `ideogram.ideogram-v3-turbo` for crisp text)

Referenced files: 4

View saved version →

---
name: generate-video
description: Generate AI videos with Simplified from text, reference images, first and last frames, multiple images, or source video. Use when the user asks to create an AI video, product teaser, social clip, campaign motion asset, image-to-video animation, first/last-frame transition, or reusable generated video asset, or asks which Simplified video model supports a particular format, duration, resolution, or capability.
---

# Generate Video

Create a production-appropriate video by discovering the live model contract, generating with valid parameters, and returning a reusable result.

## Guardrails

- Video generation spends credits. Proceed when generation is explicit; confirm before spending when the user is exploring options or has not approved generation.
- Call `api_getModelFields` before generation. Never rely on a memorized model list, price, duration, aspect ratio, or parameter schema.
- Use only parameters returned for the selected model and capability.
- File-typed parameters take permanent Simplified asset UUIDs, not local paths, signed URLs, or arbitrary remote URLs.
- Use `storage: "asset"` when the video will be posted, reused, or retained. Use `transient` only for an explicitly temporary result.
- Do not treat the submission `task_id` as render completion. Follow the variation status contract in [references/models-and-polling.md](references/models-and-polling.md).
- Show returned URLs as clickable links; never embed them.

## Workflow

1. Define the job: audience, objective, placement, aspect ratio, duration, visual subject, action, camera language, pacing, brand constraints, references, audio needs, and required delivery format. Infer common social dimensions only when the requested placement makes them unambiguous.
2. Call `api_getModelFields` with `type: "video"` and no model ID to discover current choices. Shortlist by supported capability, quality, speed, estimated time, and credit cost—not model fame alone.
3. Call `api_getModelFields` again with the selected `model_id` and capability to retrieve exact required fields, enums, defaults, and file-field expectations.
4. For image-to-video, multiple-image, or first/last-frame work, ensure every reference is a permanent asset UUID. Use the Simplified signed-upload asset workflow for user-supplied local files.
5. Write a motion prompt that describes subject, action over time, environment, camera behavior, composition, lighting, pacing, and exclusions. Avoid stacking contradictory movements or scene changes into a short clip.
6. Show the chosen model, capability, duration, format, credit information when available, storage mode, and prompt before generation when cost or creative direction remains ambiguous.
7. Call `api_generateVideo` with the exact nested `parameters` contract and the chosen storage mode.
8. If the call returns before terminal completion, preserve both returned IDs and call `api_getVideoVariation` until `job_status` is `DONE` or `FAILED`. Use a reasonable interval; do not busy-loop.
9. On success, report the reusable asset UUID, rendered video link, thumbnail link when available, model, format, and any material limitations. On failure, surface the provider error and suggest one targeted correction.

## Creative Standard

- Design one clear visual beat per short clip. A six-second asset needs a readable action, not a miniature screenplay.
- Match the first frame and opening motion to the social hook; assume many viewers begin muted unless generated audio is central to the concept.
- Preserve product geometry, logos, packaging, people, and claims when references are supplied. Flag visible inconsistencies instead of presenting them as final.
- For paid or conversion creative, leave intentional visual space for on-screen copy and CTA overlays.
- Treat AI-generated people, testimonials, product behavior, and locations as synthetic; never imply documentary proof.

## Output

Lead with the creative choice and generation status. Then provide the permanent asset ID, result links, intended placement, model/capability, and next useful action such as drafting a post or producing a controlled variant.

Referenced files: 2

View saved version →

---
name: local-business-marketing
description: Plan and create locally relevant social and Google Business content for location-based and service-area businesses. Use when the user asks for local marketing, neighborhood content, Google Business posts, store or restaurant promotion, appointment or booking campaigns, local events, service-area awareness, foot-traffic content, location launches, or a practical social plan for a small local business.
---

# Local Business Marketing

Turn local relevance, operational truth, community proof, and timely offers into content that drives calls, bookings, directions, visits, and qualified inquiries.

## Guardrails

- Verify business name, locations or service area, hours, availability, prices, offer terms, event dates, phone/booking destination, and required disclaimers before publishing them.
- Never fabricate reviews, customer identities, local partnerships, awards, scarcity, neighborhood knowledge, or “near me” relevance.
- Treat regulated services, health claims, financial claims, age restrictions, and before/after results conservatively; surface required approvals.
- Do not publish the same generic promotional caption to every location or platform.
- Create drafts first. Obtain explicit approval of location, offer terms, CTA destination, date, account, and media before scheduling or queueing.
- Stop on authorization failure or when the requested local account is not connected.

## Workflow

1. Establish location model: storefront, multi-location, mobile/service-area, appointment-led, event-led, or locally delivered ecommerce. Capture geography, audience, demand windows, offer, proof, conversion action, and operational constraints.
2. Call `social_getSocialMediaAccounts` once and map returned accounts to locations and channels. Do not infer that similarly named accounts represent the same branch.
3. Audit useful local inputs: FAQs, service availability, customer proof with permission, team expertise, products/menu, events, partnerships, landmarks, seasonality, weather sensitivity, inventory, and booking capacity.
4. Build a balanced plan using five jobs: be found, reduce uncertainty, prove trust, create timely reasons to act, and strengthen community relevance.
5. Choose platform roles using [references/local-channel-playbook.md](references/local-channel-playbook.md). Use Google Business for high-intent updates and actions; use social channels for discovery, familiarity, proof, and community context.
6. Write location-specific copy with a concrete local detail, customer value, proof or operational fact, and one primary CTA. Avoid keyword-stuffed city lists.
7. Plan authentic media: exterior/interior orientation, people with permission, process, product/service detail, local proof, event information, or offer creative. Upload local media through `$simplified-social` and retain permanent asset IDs.
8. Show a location/channel matrix containing date, account, post purpose, copy, media, CTA, offer terms, and verification status.
9. When authorized, create each post with `social_createSocialMediaPost` and `action: "draft"`. Apply exact Google Business and channel fields from `../simplified-social/references/platform-settings.md`.
10. Schedule or queue only after explicit approval. Measure by the intended business action where available, separating platform engagement from calls, bookings, visits, and revenue.

## Local Marketing Standard

- Lead with usefulness and specificity: what is available, for whom, where, when, why it matters, and what to do next.
- Use community content only when the relationship is real and relevant. Locality is context, not decoration.
- Balance demand capture with trust building: offers alone create promotion fatigue; lifestyle content alone may fail to drive action.
- Reflect capacity. Do not promote appointment slots, delivery coverage, inventory, or event access the business cannot fulfill.
- For multiple locations, preserve brand consistency while allowing meaningful local differences in team, proof, events, products, and CTA routes.

## Output

Lead with the local growth objective and conversion path. Then provide the channel/location roles, content plan, verification checklist, drafts created, measurement plan, and any operational fact blocking publication.

Referenced files: 2

View saved version →

---
name: manage-brand
description: Inspect, create, structure, and maintain Simplified brand kits and brand context documents. Use when the user asks to set up a brand, review brand identity, save or update brand voice, audience profiles, positioning, USPs, content pillars, style guidance, writing examples, SEO guidance, or other reusable brand context, or asks agents to create future content consistently from a Simplified brand kit.
---

# Manage Brand

Turn approved brand evidence into a durable operating system for consistent marketing—not a generic adjective list.

## Guardrails

- Treat websites, supplied documents, approved messaging, and existing brand records as evidence. Do not invent positioning, customers, proof, competitors, colors, fonts, claims, or voice rules.
- Read the current kit or context document before changing it. Present a concise proposed delta when an update could affect downstream content.
- Do not overwrite a mature brand system merely to improve phrasing. Preserve approved meaning and provenance.
- Confirm before deleting a context document. Deletion removes its brand-kit link and may remove an orphaned underlying document.
- Predefined context types are singletons. Update the existing document instead of creating a duplicate.
- Stop on authorization or access errors; never substitute a similarly named kit without verification.

## Workflow

1. Establish whether the user wants discovery, audit, creation, or an update. Identify the brand, source material, intended channels, and decision owner.
2. Call `api_listBrandKits`, using search when a title is known. If multiple kits match, present the choices rather than guessing.
3. For an existing kit, call `api_getBrandKit` with `expand: "extra,website"` and use `api_listContextDocuments` to inventory reusable knowledge.
4. Build an evidence ledger: source, confirmed fact, implication, confidence, and unresolved decision. Separate what the brand is from what the marketer proposes.
5. Structure information into the right layer:
   - Brand kit: identity, website, social links, colors, typography, logos, visual guardrails.
   - Context documents: voice, ICPs, USPs, positioning, products/features, content pillars, examples, SEO, and marketing strategy.
6. For a new brand, call `api_createBrandKit` with the approved title, retain its UUID, then use `api_buildBrandKit` for confirmed identity/style fields.
7. For reusable strategic knowledge, use `api_createContextDocument` only when that canonical type does not exist. Otherwise retrieve it with `api_getContextDocumentByType` and update it with `api_updateContextDocument`.
8. Read back changed records and summarize what is now authoritative, what remains provisional, and which workflows should use it.

## Brand asset handoff

- Treat logo and reference-image `asset_id` values as the durable identity. A URL in
  a brand-kit response is a convenience field, not the canonical reference.
- When handing a brand asset to image generation, resolve its UUID with
  `api_getAsset`, require `status: 4`, and pass the returned current `file_url` only
  when the live model schema expects a URL.
- Preserve the complete query string on signed URLs. Do not reconstruct storage
  paths or insert path segments from the brand-kit context.
- Generated output returns a new permanent `asset_id`; carry that ID into social
  drafts and publishing workflows rather than its preview URL.

Read [references/brand-system.md](references/brand-system.md) before creating or restructuring a brand kit.

## Marketing Standard

- Define voice as observable choices: sentence shape, vocabulary, energy, point of view, humor boundaries, evidence style, CTA style, and explicit do/don't examples.
- Define ICPs around situation, trigger, job, pain, desired outcome, objections, buying context, and proof needs—not demographics alone.
- Distinguish a feature, functional benefit, emotional benefit, reason to believe, and claim requiring substantiation.
- Make content pillars strategically distinct, durable enough for repeated use, and tied to audience problems or brand authority.
- Record uncertainty. A useful provisional field is better than fabricated certainty.

## Output

Lead with the brand-system verdict. Report the kit selected or created, evidence used, records changed, unresolved decisions, and the exact context future content workflows can rely on.

Referenced files: 2

View saved version →

---
name: manage-projects
description: Organize marketing work in Simplified projects and project items. Use when the user asks to create or inspect a marketing project, campaign workspace, content production board, launch checklist, editorial pipeline, or deliverable list; add, retrieve, prioritize, reorder, assign, export, or remove project items; or turn an approved content plan into trackable work.
---

# Manage Projects

Translate a marketing plan into accountable, sequenced work without confusing project organization with publishing authorization.

## Guardrails

- Inspect before mutating. Reuse an existing project when it clearly matches the user's initiative.
- Use the same `resourcetype` for every operation on a project. Prefer `Project` for ordinary marketing work and `AdCreativeProject` only for specialized ad-creative projects.
- Do not invent project, item, partner, or agent IDs. Resolve them from tool results or user-provided values.
- Creating a project or item does not authorize assigning an agent, exporting content, publishing content, or deleting records.
- Confirm the target and consequences before soft-deleting a project/item, assigning an execution agent, or exporting to a partner integration.
- Dates must be realistic and internally ordered. Surface impossible dependencies or missing owners rather than silently compressing the plan.

## Workflow

1. Define the initiative: outcome, scope, deadline, deliverables, channels, approval points, owners, dependencies, and definition of done.
2. Call `api_listProjects` with the chosen `resourcetype` and search term. Reuse a unique match or show choices when several projects could apply.
3. If creation is requested, call `api_createProject` with a clear title, concise outcome-based description, and only supported structured data. Preserve the returned project ID.
4. Call `api_listProjectItems` before adding work to understand existing deliverables and avoid duplicates.
5. Convert the plan into outcome-oriented items. Each item should have one deliverable, owner or owner-needed flag, status, priority, start/due date, dependencies in the description or data, and a measurable definition of done.
6. Call `api_createProjectItem` for authorized items. Use `data.assets` for known permanent asset UUIDs; never store signed URLs as durable references.
7. Use `api_reorderProjectItem` only when the user requests or approves a new sequence. Use `api_assignAgentToItem` only with a resolved agent ID and explicit execution scope.
8. Use `api_exportProjectItems` only after confirming the partner integration and exact item IDs. Report export initiation separately from export completion.

Read [references/project-operations.md](references/project-operations.md) for field and lifecycle rules.

## Marketing Operations Standard

- Organize work around deliverables and approvals, not vague activity such as “work on social.”
- Separate strategy, copy, creative, channel adaptation, compliance, review, scheduling, and reporting when different owners or gates apply.
- Put the decision deadline before the publish deadline. Include contingency time for legal, customer, or executive review where relevant.
- Use priorities to express business consequence and sequencing, not urgency theater.
- Do not create a bloated project for a one-step request; perform the direct task unless the user wants tracking.

## Output

Lead with project status and the critical path. Then report created or changed items, owners, dates, dependencies, approval gates, IDs needed for follow-up, and any action awaiting confirmation.

Referenced files: 2

View saved version →

---
name: simplified-social
description: >-
  Manage your entire social media from Codex with Simplified — post, schedule,
  queue, draft, and analyze across Facebook, Instagram, TikTok, YouTube,
  LinkedIn, Pinterest, Threads, Bluesky, X/Twitter, Google Business, Mastodon,
  Reddit, and Telegram. Triggers: social media, post to, schedule post, publish
  on, social accounts, analytics, reach, impressions, engagement, followers
  growth, content calendar, auto-comments, link in first comment, attach local
  media, upload an image or video for a social post.
---

# Simplified Social Media

Schedule, queue, and draft social media posts, add timed auto-comments, and
retrieve analytics across 13 platforms using Simplified.com.

## Connector

All tools (`social_getSocialMediaAccounts`, `social_createSocialMediaPost`,
`api_createAsset`, etc.) are provided by the **Simplified hosted MCP connector**
(`https://apikit.simplified.com/mcp`). They are not built-in tools.

The connector is **OAuth-secured** — Codex walks the OAuth flow; there is no API key to set.

## IMPORTANT: Before Any Operation

If any tool call returns a **401 / Unauthorized**, the Simplified connector is not authorized:

1. **Stop immediately** — do not retry the failed call.
2. **Inform the user** that they need to connect Simplified (authorize the connector) before social tools will work.
3. **Do not proceed** with the original request until the connector is authorized.

## Setup

1. Sign up at [simplified.com](https://simplified.com).
2. Connect your social media accounts in the Simplified dashboard.
3. Enable the Simplified connector in Codex and complete the OAuth authorization.

## Core Workflow

Always follow this sequence: **Discover → Select → Compose → Confirm → Publish**

### Step 1: Discover Accounts

Call `social_getSocialMediaAccounts` to list connected accounts. Optionally filter by network.

```
social_getSocialMediaAccounts({ network: "instagram" })
```

Returns `{ accounts: [...] }` where each account has `id` (integer), `name`, and `type` (see type values below).

If `social_getSocialMediaAccounts` returns an empty list, stop and inform the user with this message:

> **No social media accounts connected yet.**
>
> You're one step away from managing your entire social media presence without leaving your editor. Connect your accounts in the [Simplified dashboard](https://app.simplified.com) and you'll be able to:
>
> - 📅 Schedule and publish posts to Facebook, Instagram, TikTok, YouTube, LinkedIn, Pinterest, Threads, Bluesky, X/Twitter, Google Business, Mastodon, Reddit, and Telegram — with a single command
> - 📊 Pull analytics, track reach, engagement and follower growth across all platforms
> - 🤖 Let your AI agent run full social media campaigns autonomously
>
> Takes 2 minutes to connect. No code required.

### Step 2: Select Target Accounts

Pick one or more `account_ids` from the results. You can post to multiple accounts in a single call.

### Step 3: Compose the Post

Build the post payload:
- `message` (required) — the post text, max 5000 chars at the connector boundary
  (tighter per-platform limits apply)
- `account_ids` (required for publishing actions) — array of target account IDs
- `action` (required) — `schedule`, `add_to_queue`, or `draft`
- `date` — required for `schedule`, format: `YYYY-MM-DD HH:MM`
- `media` — array (max 10) of **Simplified asset UUIDs** or public media URLs
- `comments` — ordered auto-comments, each with `message` and a nonnegative
  `delay` in seconds after the post publishes; comments cannot include media
- `additional` — platform-specific settings (see below)

**Attaching a generated image:** `media` accepts Simplified **asset UUIDs**, resolved server-side to fresh permanent URLs at publish time — exactly what the **generate-image** skill returns with `storage:"asset"`. Pass that `asset_id` straight into `media`.

**Attaching a local file:** never pass a client-local path to the hosted server.
Read [references/assets.md](references/assets.md), then follow the UI-equivalent
flow: `api_signAssetUpload` → direct client PUT to signed storage →
`api_registerAsset`. Poll `api_getAsset` until `status=4`, then pass that exact UUID
into `media`. Never expose the signed upload URL or attach Simplified auth to the
storage PUT.

### Step 4: Confirm, then Publish

Publishing is outward-facing. For `schedule` / `add_to_queue`, **show the composed post to the user and get explicit confirmation first** (drafting first with `action:"draft"` is a good way to preview). Then call `social_createSocialMediaPost`.

If the post includes auto-comments, the confirmation must show each comment's text
and post-relative delay. For “link in first comment after X minutes,” convert
nonnegative minutes to an integer number of seconds with `delay = X * 60`.
`delay` is measured in seconds after the post publishes, not after the previous
comment. Comments execute in array order. Do not move the comment text into the
main post.

**Show returned URLs as links, never embed them.** Any URL these tools return
(review-bundle links, published-post URLs, media URLs) must be presented as a plain
URL or Markdown link — **never** Markdown image syntax (`![](url)`) and never
inline-rendered. The user clicks the link; the agent does not render it.

## Choosing the Right Analytics Tool

| User asks about... | Tool to call |
|---|---|
| Trends over time, charts, metric growth/decline | `social_getSocialMediaAnalyticsRange` |
| Specific posts, best/worst performing content | `social_getSocialMediaAnalyticsPosts` |
| Account overview, KPIs, period summary | `social_getSocialMediaAnalyticsAggregated` |
| Demographics, follower origins, age/gender breakdown | `social_getSocialMediaAnalyticsAudience` |
| "Show me analytics" with no further context | `social_getSocialMediaAnalyticsAggregated` + `social_getSocialMediaAnalyticsRange` with key metrics |

## Tool Reference

### `social_getSocialMediaAccounts`

| Parameter | Type   | Required | Description                          |
|-----------|--------|----------|--------------------------------------|
| `network` | string | No       | Filter by platform (see networks)    |

**Networks (filter parameter):** `facebook`, `instagram`, `linkedin`, `tiktok`,
`tiktokBusiness`, `youtube`, `pinterest`, `threads`, `google`, `bluesky`,
`mastodon`, `reddit`, `telegram`

Returns `{ accounts: [...] }`. Each account object:

| Field  | Type    | Description |
|--------|---------|-------------|
| `id`   | integer | Account ID — use for all analytics calls and for `account_ids` in `social_createSocialMediaPost` |
| `name` | string  | Account display name |
| `type` | string  | Account type — see values below |

**`type` values and their meaning:**

| `type` value | Platform | Notes |
|---|---|---|
| `Facebook page` | Facebook | — |
| `Instagram business` / `Instagram profile` | Instagram | — |
| `Youtube account` | YouTube | — |
| `TikTok profile` | TikTok Personal | use `tiktok` metrics set |
| `TikTok profile (business)` | TikTok Business | use `tiktokBusiness` metrics set |
| `LinkedIn company` | LinkedIn | use LinkedIn Company metrics set |
| `LinkedIn profile` | LinkedIn | use LinkedIn Personal metrics set |
| `Pinterest board` | Pinterest | — |
| `Threads account` | Threads | — |
| `Bluesky account` | Bluesky | — |
| `Google Profile` | Google Business | — |
| `Reddit account` | Reddit | `additional.reddit.post.targets` is required |

### `social_createSocialMediaPost`

| Parameter     | Type     | Required | Description                              |
|---------------|----------|----------|------------------------------------------|
| `message`     | string   | Yes      | Post text (connector max 5000 chars; tighter platform limits apply) |
| `account_ids` | int[]    | For publish | Target account IDs from `social_getSocialMediaAccounts`; omit/empty for an accountless `draft` |
| `action`      | string   | Yes      | `schedule`, `add_to_queue`, or `draft`   |
| `date`        | string   | For `schedule` | Schedule datetime: `YYYY-MM-DD HH:MM` (not in the past) |
| `media`       | string[] | No       | Asset UUIDs or public media URLs (max 10) |
| `tags`        | int[]    | No       | Tag IDs |
| `comments`    | object[] | No       | Ordered auto-comments: `{message, delay}`; `delay` is seconds after publish and must be ≥ 0 |
| `additional`  | object   | Per platform | Platform-specific settings |

### `social_getSocialMediaDrafts`

Lists unpublished drafts for selected accounts. `account_ids` is required and must
be a comma-separated string of numeric IDs returned by
`social_getSocialMediaAccounts`, for example `"123,456"`. If a multi-account lookup
returns no rows when drafts are expected, retry once per account ID, merge the
results, and deduplicate by exact draft ID. This per-account fallback is read-only
and must not create replacement drafts. Optional filters are `page`, `per_page`,
`search`, `tz`, `order_by`, and `order` (`asc` or `desc`). Omit ordering by default;
if the connector rejects an optional filter, retry without that filter rather than
treating the drafts as absent.

### `social_updateSocialMediaDraft`

Updates one draft. `draft_id` is required. Optional fields are `message`, `media`,
`tags`, `date`, `time`, and `timezone`. Only pass fields the user asked to change.

### `social_createSocialMediaReviewBundle`

Creates a shareable stakeholder-review package. `title` is required; `description`
and `draft_ids` are optional. Prefer one call containing all selected draft IDs.
Draft IDs must come from `social_getSocialMediaDrafts`; never fabricate them. The
response includes `linkToReview`, which must be shown as a link and never embedded.

The hosted connector currently does not expose a separate tool for appending drafts
to an existing bundle. Do not recreate an existing bundle unless the user explicitly
asks for a replacement.

### `social_getSocialMediaAnalyticsRange`

Retrieves time-series data for selected metrics within a date range.

| Parameter    | Type     | Required | Description                                                  |
|--------------|----------|----------|--------------------------------------------------------------|
| `account_id` | integer  | Yes      | Social media account ID (from `social_getSocialMediaAccounts`) |
| `metrics`    | string[] | Yes      | List of metrics to retrieve (see `references/analytics.md`)  |
| `date_from`  | string   | Yes      | Start date: `YYYY-MM-DD`                                     |
| `date_to`    | string   | Yes      | End date: `YYYY-MM-DD` (never in the future)                 |
| `tz`         | string   | No       | Timezone, e.g. `UTC`, `Europe/Warsaw` (default: `UTC`)       |

Returns `data` (per-day series), `baseLine` (period totals with `prevValue`), and `additional` (windowed extras). See `references/analytics.md` for the full metric list, default metrics per network, and response examples.

### `social_getSocialMediaAnalyticsPosts`

Retrieves analytics for individual posts within a date range.

| Parameter    | Type    | Required | Description                                             |
|--------------|---------|----------|---------------------------------------------------------|
| `account_id` | integer | Yes      | Social media account ID                                 |
| `date_from`  | string  | Yes      | Start date: `YYYY-MM-DD`                                |
| `date_to`    | string  | Yes      | End date: `YYYY-MM-DD`                                  |
| `page`       | integer | No       | Page number (default: 1, minimum: 1)                    |
| `per_page`   | integer | No       | Posts per page (default: 10, max: 100)                  |

Returns paginated posts with per-post metrics. **Pagination:** use `per_page: 100`, start at `page: 1`, increment until `current_page >= pages_count` or `posts` is empty.

### `social_getSocialMediaAnalyticsAggregated`

Retrieves aggregated analytics (totals and averages) for an account within a date range.

| Parameter    | Type    | Required | Description             |
|--------------|---------|----------|-------------------------|
| `account_id` | integer | Yes      | Social media account ID |
| `date_from`  | string  | Yes      | Start date: `YYYY-MM-DD` |
| `date_to`    | string  | Yes      | End date: `YYYY-MM-DD`  |

Returns `data` plus `baseLine` with four KPIs: `impressions_aggregated`, `engagement_aggregated`, `followers_aggregated`, `publishing_aggregated` (each with `value` and `prevValue`).

### `social_getSocialMediaAnalyticsAudience`

Retrieves audience demographics and follower data for an account.

| Parameter    | Type    | Required | Description                          |
|--------------|---------|----------|--------------------------------------|
| `account_id` | integer | Yes      | Social media account ID              |
| `date_from`  | string  | Yes      | Start date: `YYYY-MM-DD`             |
| `date_to`    | string  | Yes      | End date: `YYYY-MM-DD`              |
| `tz`         | string  | No       | Timezone, e.g. `UTC`, `Europe/Warsaw` |

Returns `audience_page_fans_gender_age`, `audience_page_fans_country`, `audience_page_fans_city`. Not all fields are available for every network.

## Action Types

| Action         | When to Use                                          | `date` Required? |
|----------------|------------------------------------------------------|-------------------|
| `schedule`     | Post at a specific date/time                         | Yes               |
| `add_to_queue` | Publish as soon as possible (optimal-time queue)     | No                |
| `draft`        | Save for later editing in the Simplified dashboard   | No                |

**Default:** When the user doesn't specify timing (or says "post now"), use `add_to_queue` — it publishes ASAP; there is no separate immediate-publish action. When they give a date/time, use `schedule`. When they say "save" or "draft", use `draft`.

## Platform Settings Quick Reference

All platform settings go inside the `additional` object, grouped by platform name. **Bold** = required. For full details see [references/platform-settings.md](references/platform-settings.md).

| Platform       | Required additionals              | Optional additionals               |
|----------------|-----------------------------------|------------------------------------|
| Facebook       | **`postType`**                    | —                                  |
| Instagram      | **`postType`**, **`channel`**     | `postReel` (reel only)             |
| TikTok         | **`postType`**, **`channel`**, **`post`** | `postPhoto` (photo only)  |
| TikTok Biz     | **`postType`**, **`post`**        | `postPhoto` (photo only)           |
| YouTube        | **`postType`**, **`post`**        | —                                  |
| LinkedIn       | **`audience`**                    | —                                  |
| Pinterest      | **`post`**                        | —                                  |
| Threads        | **`channel`**                     | —                                  |
| Google         | **`post`**                        | —                                  |
| Bluesky        | —                                 | —                                  |
| Mastodon       | —                                 | —                                  |
| Reddit         | **`post.targets`**                | target flair, NSFW flag, link URL  |
| Telegram       | —                                 | —                                  |

Key enum values:

| Platform   | Field              | Values                              |
|------------|--------------------|-------------------------------------|
| Facebook   | `postType.value`   | `post`\*, `reel`, `story`           |
| Instagram  | `postType.value`   | `post`\*, `reel`, `story`           |
| Instagram  | `channel.value`    | `direct`\*, `reminder`              |
| TikTok     | `postType.value`   | `video`\*, `photo`                  |
| TikTok     | `channel.value`    | `direct`\*, `reminder`              |
| TikTok     | `post.privacyStatus` | `PUBLIC_TO_EVERYONE`\*, `MUTUAL_FOLLOW_FRIENDS`, `FOLLOWER_OF_CREATOR`, `SELF_ONLY` |
| YouTube    | `postType.value`   | `video`\*, `short`                  |
| YouTube    | `post.privacyStatus` | `""`, `public`, `private`, `unlisted` |
| LinkedIn   | `audience.value`   | `PUBLIC`\*, `CONNECTIONS`, `LOGGED_IN` |
| Threads    | `channel.value`    | `direct`\*, `reminder`              |
| Google     | `post.topicType`   | `STANDARD`\*, `EVENT`, `OFFER`      |
| Reddit     | `post.targets[].type` | `self`, `link`                    |

\* = default

## Example Workflows

### Simple Queue Post

```
1. social_getSocialMediaAccounts({ network: "instagram" })
2. social_createSocialMediaPost({
     message: "Check out our new feature! 🚀",
     account_ids: [123],
     action: "add_to_queue",
     media: ["https://cdn.example.com/image.jpg"],
     additional: {
       instagram: { postType: { value: "post" }, channel: { value: "direct" } }
     }
   })
```

### Scheduled YouTube Short

```
1. social_getSocialMediaAccounts({ network: "youtube" })
2. social_createSocialMediaPost({
     message: "Quick tip: how to use our API",
     account_ids: [456],
     action: "schedule",
     date: "2026-06-10 14:00",
     media: ["https://cdn.example.com/video.mp4"],
     additional: {
       youtube: { postType: { value: "short" },
         post: { title: "API Quick Tip", privacyStatus: "public", selfDeclaredMadeForKids: "no" } }
     }
   })
```

### Post a freshly generated image

```
1. (generate-image skill) → asset_id "a1b2c3…"
2. social_getSocialMediaAccounts({ network: "instagram" })
3. social_createSocialMediaPost({
     message: "Meet the new drop 👟",
     account_ids: [123],
     action: "draft",
     media: ["a1b2c3…"],                       // asset UUID from generate-image
     additional: { instagram: { postType: { value: "post" }, channel: { value: "direct" } } }
   })
```

### Reddit draft

```
1. social_getSocialMediaAccounts({ network: "reddit" })
2. social_createSocialMediaPost({
     message: "What we learned from shipping our new workflow",
     account_ids: [789],
     action: "draft",
     additional: {
       reddit: {
         post: {
           targets: [{
             subreddit: "devtestsmp",
             title: "What we learned from shipping our new workflow",
             type: "self",
             flairId: null,
             flairText: null,
             nsfw: false,
             url: null
           }]
         }
       }
     }
   })
```

### Link in the first comment after 5 minutes

```
1. Preview and confirm both the main post and:
   first comment: "Read the full guide: https://example.com/guide"
   delay: 5 minutes after the post publishes
2. social_createSocialMediaPost({
     message: "We published a practical guide to better campaign reviews.",
     account_ids: [123],
     action: "schedule",
     date: "2026-06-10 14:00",
     comments: [{
       message: "Read the full guide: https://example.com/guide",
       delay: 300
     }]
   })
```

### Analytics: Account Overview

```
1. social_getSocialMediaAccounts({ network: "facebook" })
2. social_getSocialMediaAnalyticsAggregated({ account_id: 789, date_from: "2026-05-01", date_to: "2026-05-31" })
```

## Gotchas

- **Analytics `account_id` is an integer** — use the numeric `id` from `social_getSocialMediaAccounts`.
- **Analytics date format** is `YYYY-MM-DD` (no time component, unlike post scheduling); never set `date_to` in the future.
- **Unknown metrics are silently ignored** by `social_getSocialMediaAnalyticsRange` — check `references/analytics.md` for per-network availability.
- **Audience data availability varies** — `social_getSocialMediaAnalyticsAudience` may return partial or empty data depending on the network.
- **Post `date` format** must be `YYYY-MM-DD HH:MM` (24-hour, no seconds, no timezone — uses account timezone).
- **Media** must be a Simplified asset UUID (from `generate-image` with `storage:"asset"`) or a publicly accessible URL — localhost does not work.
- **Local media** uses `api_signAssetUpload` → direct storage PUT →
  `api_registerAsset`; never send a local path to the hosted connector.
- **`date` is required** when `action` is `schedule` — omit it for `add_to_queue` and `draft`.
- **Platform character limits** — see `references/platform-settings.md`.
- **Auto-comments** — `comments[].delay` is measured in seconds after the post
  publishes. For X minutes use `X * 60`; the delay is not relative to the previous
  comment, and comments do not support media.
- **Reddit targets are required** — include at least one entry in
  `additional.reddit.post.targets`; omit the `r/` prefix from `subreddit`.
- **Instagram always requires `channel`** — include `channel: { value: "direct" }` for every Instagram post.
- **TikTok `postType`** values are `video` and `photo` (not `image`); **channel** values are `direct` and `reminder` (not `business`).
- **LinkedIn audience** value is `LOGGED_IN` (not `LOGGED_IN_MEMBERS`).
- **Google `topicType`** only has `STANDARD`, `EVENT`, `OFFER` (no `PRODUCT`).
- **Instagram story** — message must be empty (`""`), max 1 photo.
- **Reels and Shorts require video** — Instagram reel, Facebook reel, YouTube short all require a video file in `media`; images are not allowed.
- **YouTube always requires `post.title`** — include `additional.youtube.post` with a `title` for every YouTube video or short.

Referenced files: 7

View saved version →

---
name: social-content-planner
description: Build goal-led weekly or monthly social content calendars for marketers, social media managers, and small businesses. Use when the user asks for a content plan, posting calendar, campaign calendar, content pillars, posting cadence, ideas to fill calendar gaps, or a set of social drafts organized across dates and channels.
---

# Social Content Planner

Turn business goals into a practical, channel-aware content calendar. Use the Simplified hosted MCP connector for account discovery, analytics, drafts, tags, and scheduling.

## Guardrails

- Treat planning, drafting, and publishing as separate levels of authorization.
- Return a plan in conversation when the user asks only for a plan. Do not create remote drafts unless requested.
- Use `action: "draft"` when the user asks to create or save the planned content.
- Before any `schedule` or `add_to_queue` call, show the final posts, accounts, dates, media, and platform settings and obtain explicit confirmation.
- Stop on `401` or an empty account list and explain how to connect Simplified.
- Present returned URLs as links, never as embedded images.

## Workflow

1. Establish the planning frame: business goal, audience, offer or topic, date range, channels, cadence, key dates, and desired call to action. Ask only for information that materially changes the plan; otherwise state reasonable assumptions.
2. Call `social_getSocialMediaAccounts` once without a network filter when connected channels matter. Use only returned account IDs.
3. If the user wants a performance-informed plan, retrieve the relevant account analytics before ideating. Use `$social-performance-analyst` for a full analysis.
4. Create three to five useful content pillars. Balance education, proof, promotion, engagement, and brand or community content rather than repeating one message.
5. Assign each post a date, channel, pillar, objective, format, hook, core message, CTA, and asset requirement. Adapt the idea to each channel instead of copying identical text everywhere.
6. Present the calendar in chronological order and flag missing source material or media.
7. If remote drafts were requested, create each with `social_createSocialMediaPost` and `action: "draft"`. Include required platform-specific `additional` fields from `../simplified-social/references/platform-settings.md`.
8. If scheduling was requested, create or show drafts first, then wait for explicit approval before scheduling.

## Planning Heuristics

- Tie every post to one primary objective: awareness, engagement, consideration, conversion, retention, or trust.
- Use realistic cadence for the available channels and source material; do not fill a calendar with low-value repetition.
- Build sequences around launches and events: setup, reveal, proof, reminder, last call, and follow-up.
- For small businesses, prioritize offers, local relevance, customer proof, FAQs, behind-the-scenes content, events, and Google Business updates where appropriate.
- Reuse a campaign idea across channels, but rewrite the hook, length, CTA, hashtags, and format for each audience context.

## Output

Summarize the strategy first, then show the calendar. End with counts by channel and pillar, unresolved inputs, and the exact next authorized action: plan only, drafts created, or awaiting scheduling approval.

Referenced files: 3

View saved version →

---
name: social-performance-analyst
description: Analyze connected social accounts and translate metrics into decisions for marketers and small businesses. Use when the user asks how social performed, requests a weekly or monthly report, wants winners and losers, needs KPI or audience analysis, asks what content worked, wants account comparisons, or needs evidence-based recommendations for the next content plan.
---

# Social Performance Analyst

Turn Simplified social analytics into clear signals, limitations, and next actions. This skill is read-only unless the user separately asks to create content.

## Workflow

1. Resolve the reporting period. Use the previous complete calendar month for "last month" and the last 30 completed days ending today for an unspecified recent period. Never send a future `date_to`.
2. Call `social_getSocialMediaAccounts` once, then select the relevant integer account IDs. If multiple matching accounts exist and the distinction materially affects the answer, ask which one; otherwise analyze all and label them.
3. Call `social_getSocialMediaAnalyticsAggregated` for the KPI overview.
4. Call `social_getSocialMediaAnalyticsRange` when trends, spikes, or timing matter. Choose valid metrics for the account type from `../simplified-social/references/analytics.md`.
5. Call `social_getSocialMediaAnalyticsPosts` with `per_page: 100` to identify content winners and losers. Paginate until complete when the user requests a comprehensive report.
6. Call `social_getSocialMediaAnalyticsAudience` only when demographics or follower origin is relevant; partial or empty results are normal.
7. Compare `value` with `prevValue`. Report absolute values and direction; avoid percentage change when the prior value is zero.
8. Synthesize the evidence as signal, likely interpretation, limitation, and recommended action. Do not claim causation from correlation.

## Analysis Standard

- Separate reach or impressions, engagement, audience growth, and publishing volume.
- Normalize account comparisons where possible; raw totals across different networks are not directly equivalent.
- Connect post-level observations to concrete attributes such as topic, format, hook, CTA, or timing only when the returned data supports it.
- Note sparse data, missing metrics, platform attribution windows, and incomplete audience fields.
- Recommend no more than three prioritized actions and attach each to an observed signal.
- Suggest a measurable next experiment, including what to change and which metric will determine success.

## Failure Handling

- On `401`, stop and ask the user to authorize the Simplified connector.
- On an empty account list, explain that social accounts must be connected in Simplified.
- If a metric is unsupported or silently omitted, report that limitation rather than treating it as zero.

## Output

Lead with a concise performance verdict. Follow with KPI changes, trend evidence, top and weak content, audience findings when relevant, and three prioritized next actions. Include the exact reporting period and account names.

Referenced files: 3