AdStellar

View saved version →

---
name: analyze-ad-performance
description: Pull and summarize synced Meta ads performance from AdStellar grouped by campaign, ad set, ad, or creative component over a date range. Use when the user asks how their ads, campaigns, or spend are performing, or wants ROAS, CPA, CTR, or budget breakdowns.
---

Use this skill when the user asks about the results of their Meta ads and their AdStellar account is connected.

## Steps

1. Call `list_ad_accounts` first. Note each account's currency and `last_synced_at`; if data is more than a day old, say so in the summary. If the team has several ad accounts and the user did not specify one, ask which one or report per account.
2. Call `query_performance` with:
   - `breakdown`: `campaign` (default), `ad_set`, or `ad` for entity levels, or one of the creative-component breakdowns listed in the tool's schema when the user asks about hooks, formats, or other creative elements.
   - A date range: `preset` (for example `last_7d` or `last_30d`; the tool schema lists the valid presets) or explicit `startDate` and `endDate` in YYYY-MM-DD.
   - `adAccount`, `campaignId`, or `adSetId` filters when the user names them, and `limit` when they want a top-N list.
3. Summarize what the numbers say: total spend, results, cost per result, ROAS, and the top and bottom performers by the metric the user cares about. Use the account's currency. Present rows in a compact table when there are more than three.
4. When comparing periods, run `query_performance` twice with the two ranges and compare like for like.

## Do not

- Do not spell the ad-set breakdown as adset or adgroup; the value is `ad_set`.
- Do not compute metrics that are not derivable from the returned rows, and do not mix currencies across accounts without saying so.
- Do not treat `purchases` or `results` as revenue; ROAS comes from the tool when Meta reports it.
- Do not pause, edit, or launch anything from this skill. When the user wants to act on the numbers, hand off to the optimize-campaigns skill, which previews and confirms every change.

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

View saved version →

---
name: automate-optimization
description: Create and manage standing AdStellar automation rules (for example pause campaigns whose 7-day CPA exceeds a threshold) and work the approval queue they produce. Use when the user says "whenever", "automatically", "every day", "set up a rule", or wants to review, approve, or reject suggested actions.
---

Use this skill for recurring optimization logic. A rule evaluates synced Meta data on a schedule and either queues suggested actions for approval ("suggest_only") or executes them itself ("auto_run"). Automations are enabled per team; if a tool says they are not enabled, tell the user to contact AdStellar and stop.

## Authoring a rule

1. Call `get_automation_rule_schema` once. It returns the exact rule shape, the valid metrics, operators, windows, scopes and action kinds, a valid example, and authoring guidance. Follow it exactly.
2. Translate the user's request into a rule: a name, "ad_account_ids" from `list_ad_accounts`, a scope (campaign, ad set within ABO or CBO, or ad), a condition tree of metric predicates (for example spend at least 50 and CPA above 40 over the last 7 days), an action (pause, resume, archive, scale budget with a percentage, or notify only), a schedule interval in minutes with the user's timezone, and an execution mode. Default to "suggest_only" unless the user explicitly asks for autonomous execution.
3. Scaling actions require a hard budget ceiling ("max_budget_cap"). Ask the user for it; never pick one yourself.
4. Optionally dry-run with `preview_automation_rule` passing the `rule` to show how many entities it evaluates and which would match right now.
5. Call `create_automation_rule` with the `rule`. The first call validates it, dry-runs it, and returns a preview and a `confirmationToken`. Show the user the rule in plain language, the current matches, and whether it will act on its own. After a yes, call again with the identical `rule` plus the token.

## Managing rules and the queue

- `list_automation_rules` shows every rule with its status. `set_automation_rule_active` with `isActive` false pauses a rule immediately; turning one on returns a `confirmationToken` first because an active rule can act on live ads.
- `list_pending_automation_actions` shows suggested actions awaiting a decision with the entity, proposed action and rule. Present them as a short table.
- `approve_automation_action` applies one suggestion to Meta and is two-step with a `confirmationToken`. `reject_automation_action` declines it with a `reason` from the schema's rejection reasons; the reason teaches the rule (for example protecting a winner from future pauses).

## Do not

- Do not create "auto_run" rules unless the user explicitly asked for autonomous execution and understands the rule will change live ads without asking.
- Do not invent metric names, windows, or action kinds; use only values returned by `get_automation_rule_schema`.
- Do not approve queued actions in bulk without listing each one and getting approval that covers the list.

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

View saved version →

---
name: generate-ad-creatives
description: Generate AI image or video ad creatives in an AdStellar team, confirm before spending credits, and poll until the assets are ready. Use when the user asks to create, make, or generate ad images, video ads, UGC videos, or talking-actor videos.
---

Use this skill when the user wants new ad creatives (images or videos) produced in their AdStellar account. Generation spends AI credits from the team's balance, so the user must confirm before any generation call.

## Before generating

1. Establish the product or brand kit with `list_products` and `get_brand_kit`. Ask which product if it is ambiguous. If the team has neither yet, offer to create them from the user's website with `create_brand_kit_from_url` and `create_product_from_url` before generating. For image references, find asset ids with `search_assets`.
2. Call `get_credit_balance` so you can tell the user what they have available.
3. Work out the exact request:
   - Images: `aspectRatios` (one or more of `1:1`, `4:5`, `9:16`, `16:9`), `variationCount`, `instructions` (required unless `referenceAssetIds` are given), optional `renderMode` (`express` or `studio`). One image is generated per aspect ratio per variation, and each image costs a fixed number of credits. There is no model choice for images.
   - Video: `approach` (`exact` for a talking actor reading `scriptText`, `realistic` for cinematic UGC from a `scenePrompt`), `aspectRatio` (default `9:16`), `durationSeconds` (default 15), `variationCount`. Optionally call `list_models` with `capability: "video"` and pass a returned id as `model`; omit it to let AdStellar choose.
4. State the plan in one short message: what will be generated, how many outputs, and that it will spend AI credits from the balance you just reported. Do not quote an exact credit figure unless a tool returned one. Wait for the user to confirm before generating.

## Generating

- Images: call `generate_image`. It returns a `batchId` and `creditsConsumed`.
- Video with `approach: "exact"`: call `list_avatars` so the user can pick an `actorId`. Call `list_voices`; if it returns voices let the user pick a `voiceId`, and if it returns none, omit `voiceId` and the actor's default voice is used. Then call `generate_video`.
- Video with `approach: "realistic"`: call `generate_video` with `scenePrompt`, plus `productId` or `productImageUrl` when featuring a product.
- `generate_video` returns a `projectId` and does not report credits; tell the user the charge appears in their balance.
- Poll `get_generation_status` with the `batchId` or `projectId` every 10 to 20 seconds until every generation is `completed` or `failed`. Image batches usually finish within a minute; video can take several minutes. Tell the user roughly how long to expect.

## Presenting results

- Show each completed generation's asset or video URL as returned by `get_generation_status`. For images, report the `creditsConsumed` value from `generate_image`.
- If a generation failed, report the tool's error message as given and offer to retry with adjusted instructions. Do not retry automatically; a retry spends credits again.

## Do not

- Do not call `generate_image` or `generate_video` without explicit confirmation of the request.
- Do not pass a `model` to `generate_image` (it has none) or invent a video model id; only use ids returned by `list_models`.
- Do not describe an asset before `get_generation_status` reports it complete, and do not invent dimensions or file sizes the tool did not return.

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

View saved version →

---
name: launch-campaign
description: Build a complete Meta campaign with AdStellar's AI Campaign Builder, review the preview, and publish it, spending credits and ad budget only after explicit confirmation. Use when the user asks to launch, publish, set up, or create a campaign, or to turn approved creatives and copy into live ads.
---

Use this skill when the user wants a campaign built and launched. Building is free and reversible. Launching spends AI credits and, once active, ad budget, so it is gated by a preview-then-confirm step and publishes paused by default.

**The most important rule: know what is being advertised before you build.** The builder writes every headline and primary text from the `destinationUrl` you pass. If that URL points at the wrong product, every ad in the campaign sells the wrong thing. The product and its landing page come from the user or from the team's products in AdStellar, never from what happens to be connected to the ad account.

## Gather inputs

1. Ad account: call `list_ad_accounts` and confirm which one if there are several.
2. Product and landing page. Call `list_products`. If the team has exactly one product, use its url field and say so. If it has several, or none, or the user's request does not make the product obvious, ask which product or landing page to advertise and wait for the answer. If the team has no product and the user gives a landing page URL, offer to add it with `create_product_from_url` first so the builder has a real product record to sell from. When the user asks for a campaign "based on my winning ads", identify the winner with `query_performance` or `list_campaigns`, then still confirm which product and landing page that winner was selling; the tools do not expose a past campaign's URL, so ask if it is not clear.
3. Call `get_launch_options` with the `adAccountId`. It returns connected pixels, Facebook Pages and advertisable apps plus the rules: every campaign needs a Page; Sales, and Leads with a website conversion location, need a pixel; website campaigns need a landing URL. If something required is missing, tell the user what to connect in AdStellar Integrations and stop. The apps in this response exist only for `OUTCOME_APP_PROMOTION` campaigns. They describe what the Meta business has registered, not what the user sells, and a business often has several unrelated apps and Pages. Never derive the product, offer, or `destinationUrl` from them.
4. Establish `objective` (`OUTCOME_SALES`, `OUTCOME_LEADS`, `OUTCOME_TRAFFIC`, `OUTCOME_AWARENESS`, `OUTCOME_ENGAGEMENT`, `OUTCOME_APP_PROMOTION`), `dailyBudget` in the account currency, and `destinationUrl` from step 2. Ask for anything the user did not provide rather than inventing it.
5. Before calling `build_campaign`, state in one line what you are about to build: the product, the landing page, the objective and the daily budget. If the user did not explicitly name the product or URL earlier in the conversation, wait for them to confirm this line.
6. Optional inputs: `pixelId` and `pageId` (auto-selected when the account has exactly one), `conversionEvent` such as Purchase or Lead, `campaignName`, `creativeAssetIds` from `search_assets` or `get_generation_status`, `approvedCopy` from `generate_ad_copy`, `geos`, `languages`, and free-text `instructions` for audience or angle.

## Build

1. Call `build_campaign`. It returns a `jobId` and the resolved pixel, Page and destination. The builder assembles audiences, ad sets, ads, copy and creatives as a paused draft.
2. Poll `get_campaign_build` with the `jobId` every 10 to 15 seconds. The "phase" moves from "preparing" to "preview_ready", or to "failed" with an error you should relay verbatim. Builds usually take one to three minutes.
3. When the phase is "preview_ready", present the preview: campaign name, objective, budget, ad sets and audiences, ads and creatives. Ask whether to launch, and whether to publish paused (default) or start delivering immediately.

## Launch

1. Call `launch_campaign` with the `jobId` and `status` (`paused` or `active`) without a token. It returns the preview, the credit cost and a `confirmationToken`.
2. State plainly: how many credits it costs, that ads will be published to Meta, and whether they start spending immediately. Wait for an explicit yes.
3. Call `launch_campaign` again with the same `jobId` and `status` plus the `confirmationToken`. Then poll `get_campaign_build` until the phase is "live" and report the result. Ad budget only spends once the campaign is active on Meta.

## Do not

- Do not call `launch_campaign` with a `confirmationToken` before the user approved that exact launch, including the paused-versus-active choice; the token is bound to it.
- Do not promise results, delivery, or approval by Meta's review.
- Do not invent pixel, Page, or asset ids. Use only values returned by `get_launch_options`, `search_assets`, or `get_generation_status`.
- Do not take the product, offer, or `destinationUrl` from `get_launch_options`. Its apps and Pages are Meta account plumbing, not the thing being advertised. A URL you did not get from the user or from `list_products` is a guess, and a guessed URL produces a campaign for the wrong product.
- Do not build when the product is ambiguous. Asking one question costs seconds; a campaign for the wrong product costs the user's trust.
- Do not use `create_launch_draft` for a launch; it only saves a shell draft for the dashboard. Use `build_campaign`.

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

View saved version →

---
name: optimize-campaigns
description: Pause, resume, archive, or re-budget live Meta campaigns, ad sets, and ads in AdStellar with a preview-then-confirm flow. Use when the user wants to turn ads on or off, cut or scale budgets, stop a losing creative, or act on performance results.
---

Use this skill when the user wants to change something that is live on Meta. Every change goes through a two-step confirmation: the first tool call returns a preview and a `confirmationToken`; nothing changes until you call again with that token after the user explicitly agrees.

## Resolve the target first

- Campaigns: call `lookup_campaign` with a name fragment to get the Meta campaign id. Never guess an id.
- Ad sets and ads: call `query_performance` with `breakdown` `ad_set` or `ad` so you have the entity id from synced data. Targets that are not in the team's synced data cannot be changed.
- If several results match, list them and ask which one.

## Tools

- `pause_campaign`, `resume_campaign`, `archive_campaign` take `campaignId` and an optional `campaignName` for the preview.
- `update_campaign_budget` takes `campaignId` and `dailyBudget` in the ad account's currency. On a CBO or Advantage+ campaign it sets the shared budget; on an ABO campaign it sets every ad set to that amount, so use `update_ad_set_budget` to change one ad set.
- `pause_ad_set`, `resume_ad_set`, `update_ad_set_budget` take `adSetId`; `pause_ad` and `resume_ad` take `adId`.

## Flow

1. Call the tool without `confirmationToken`. It returns a preview: the target, its ad account, whether the change is reversible, and the new budget when relevant.
2. Show the user exactly what will happen in one or two lines and ask for a yes. For budget changes state the new amount and currency; for archive say it cannot be undone from AdStellar.
3. On a yes, call the same tool with identical arguments plus `confirmationToken`. Report the tool's message. Tokens expire after 10 minutes and are bound to the exact target and amount, so a change of mind means starting again.
4. For several changes (for example pausing three ad sets), run the preview for each, get one approval covering the list, then execute each with its own token.

## Do not

- Do not call a mutation tool with `confirmationToken` before the user has approved that specific change.
- Do not archive when the user says pause; prefer `pause_campaign` and offer archive only when asked.
- Do not change budgets by more than the user asked for, and do not infer a budget from performance data without stating the number and getting approval.
- Do not create standing rules from this skill; use the automate-optimization skill for "whenever X, do Y" requests.

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

View saved version →

---
name: write-ad-copy
description: Write on-brand Meta ad copy (primary text, headlines, descriptions, CTAs) for an AdStellar team using its brand kit and products. Use when the user asks for ad copy, headlines, hooks, CTAs, or copy variants for Facebook or Instagram ads.
---

Use this skill when the user wants ad copy for Meta (Facebook or Instagram) ads and their AdStellar account is connected.

## Inputs to establish

1. Which product or brand kit the copy is for. Call `list_products` and `get_brand_kit`; if the team has several products and the user did not name one, ask which one before generating.
2. The goal of the ad (for example trial signups, purchases, lead capture) and the tone. If the user gives neither, use the brand kit's tone of voice and ask for the goal in one short question.
3. How many variants they want (`count`, default 5, maximum 10) and the `length` (`short`, `medium`, or `long`).

## Steps

1. Call `generate_ad_copy` once with `productId` or `brandKitId`, `count`, `tone`, `length`, `adGoal`, and any `customInstructions` the user gave. This tool is free and does not use AI credits.
2. Each variant comes back with `headline`, `primaryText` (the long-form Meta primary text), an optional `description` (short link description), and `cta`. Present the variants as a numbered list with those fields on separate lines. Keep the copy exactly as returned; do not silently rewrite it.
3. Offer one round of refinement (different tone, shorter, a specific angle) and re-run the tool with updated `customInstructions` instead of editing the copy yourself.

## Do not

- Do not invent brand facts, prices, offers, or claims that are not in the brand kit, the product record, or the user's message.
- Do not promise results or compliance with Meta's advertising policies; suggest the user review claims before launch.
- Do not call `generate_image` or `generate_video` from this skill unless the user explicitly asks for creatives; use the generate-ad-creatives skill for that.

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