GooseWorks Ads — create, edit & analyze

The GooseWorks ads skill. Two jobs:

1. Create / edit ad creative — a thin wrapper over the backend's single generation

workflow. You pick the brand + approved source ad(s) and submit ONE batch; the backend runs the whole pipeline (compose → generate → persist → judge), reserves and bills credits, and stores the renders. You do NOT generate images, call FAL, manage render rows, or upload files — those are gone. This is the exact same workflow the GooseWorks ads app uses, so the skill and the app can never drift.

1. Analyze ad performance — fetch ad-analytics recipes from goose-skills on demand

(these are unrelated to generation; see "Analyze / intelligence" below).

Prerequisite — the GooseWorks MCP server is REQUIRED

Everything goes through the mcpgooseworks* tools. If they are not available, stop and tell the user to run gooseworks install --claude --mcp (and restart Claude Code). There is no HTTP/file fallback — the REST ad endpoints are session-cookie-only and reject your token.

Start from the brand context — don't re-ask what it already answers

If the gooseworks router handed you brand context, USE IT. If you were invoked directly, call brandgetcontext first (falling back to getbrandkit for the selected brand). It already answers most of what the flows below would otherwise ask the user:

• Which product to feature → products[]. Offer the real catalog entries; never guess a

product name and never ask the user to list their products.

• The vibe / tone of the copy → the brand's voice. Use it; don't ask "what tone?".
• Who the ad is for → the brand's audience. Don't ask "who's the target?".
• The angle, offer framing, and what to claim → positioning, value props, proof points.
• Logo, colors, fonts → owned by the backend research pass. Never re-derive them.
• Whether the facts are trustworthy yet → research status. If it isn't complete, say so in

one line and continue; the batch queues and runs when research finishes.

Ask only for what the context genuinely doesn't answer: the specific campaign intent (season, promo, which of several angles), the source ad, and anything the user must consent to.

Identity & credits

• One agent-scoped token authenticates the gooseworks MCP tools. Never print it. The tools

resolve your org automatically — you do NOT resolve an "Ads agent" or pass target for the generation tools.

• Credits are handled entirely by the backend. submitremixbatch reserves the estimated

cost up front (it errors with insufficientcredits if the wallet is short — relay the message and stop) and bills only the images that actually complete. Call estimateremix_batch first to tell the user the cost; gooseworks credits shows balance.

Live MCP contract — inspect it before asking

The currently registered MCP tool schemas are the source of truth for inputs, supported choices, and defaults. Do not copy an exhaustive input list from this skill or rely on remembered fields.

Before each tool call:

1. Inspect the live schema for the tool you are about to use.
2. Fill required inputs already known from the Brand Kit, selected source, or conversation.
3. Ask the user only for required inputs that cannot be inferred and for choices that materially

change the result. Do not turn every optional field into a questionnaire.

1. Omit unspecified optional settings so the backend applies its current app defaults.
2. If the live schema conflicts with this workflow, follow the live schema and report the drift

with logclievent.

The generation tools (the new, single-workflow surface)

• submitremixbatch — the one call that makes ads. Inspect its live schema and supply

the required brand/source inputs plus any choices the user explicitly made. Returns the batch with a links block (brandurl + per-creative appurl). If the brand's research isn't finished yet the batch comes back status: "queued" — it auto-runs the moment research completes; tell the user it'll appear shortly, don't error.

• estimateremixbatch — cost preview. Reserves nothing. Use it to quote the cost first and

check whether every selected source resolved before submitting.

• getremixbatch — poll status. Returns each creative with its renders and

completed/failed/pending counts, plus links. A creative is done when its pending is 0 — NOT when currentrenderurl is set (during a regenerate that field still points at the prior image). Each render carries ageseconds (since queued) and elapsedseconds (time generating): use them to tell a slow-but-healthy render from a stuck one. A render only failed when its status is "failed" — never assume a stall and re-submit, that double-bills.

• listbrandcreatives — the brand's gallery feed (newest

first) + brand_url. Alternative poll target; also use to show everything made for a brand.

• surprisemetemplates — the "Surprise me" recommender. Picks

remixable Community creations (SAME logic as the web /create "Surprise me" button), shuffled so picks stay fresh. It does not use the retired curated third-party catalog. Returns the picked templates (id, slug, title, image, ratio) AND a ready-to-open create_url (the /create page with cli=true and the picks pre-selected). This is how you recommend templates — do NOT hand-pick from the raw catalog yourself (see "Picking templates" below).

• regenerate_creative — edit or re-roll one existing creative through the same pipeline.

Inspect the live schema to select the supported mode and required source inputs. Returns a single-item batch; poll it with getremixbatch.

• setcreativefeedback — record the user's reaction to a generated image. Use it whenever

the user reacts; inspect the schema for the current rating and reason choices.

Plan mode — review the plan BEFORE generating (optional)

For users who want to approve each ad's plan before spending credits (the app's "Plan it" flow):

• Use the approval option exposed by submitremixbatch — it composes each creative's plan and PAUSES.

No credits are reserved and no image renders until you approve.

• listadapprovals — poll this. While a creative is

composing, wait; once awaiting_approval, show its plan (composed prompt + refs + quality) to the user.

• reviseadplan — recompose from a chat steer, still

free. Poll listadapprovals until it's awaiting_approval again.

• approveadplan — approve one creative or the whole batch using the live schema.

This is the step that reserves credits and renders. Then poll getremixbatch and hand back links as usual.

Only offer plan mode when the user asks to review/approve first — the default path generates immediately.

Reading the brand & picking inputs (still MCP, read-only)

• getbrandkit — read the canonical brand context and available products/assets.
• listadbrands / getadbrand — find and fetch the active brand.
• listuserad_templates — list the org's own uploads and

imported ads. Prefer relationship: "self" when the user wants to reuse their own ads; relationship: "competitor" is research/inspiration, never proof that the user owns the ad.

• searchadtemplates — search remixable Community generations. The

retired curated third-party catalog is not returned.

• getstaticad_template — resolve a source already owned by

the org, including an own upload or a snapshotted Community creative. It does not resolve the retired curated third-party catalog.

• remixcommunityad — turn a selected Community creative into a private remix source before

submitting it. A Community ad id is an ad_project id, not a template id. Call this FIRST to snapshot it into a private template, then use the returned template id in items.

• createuserad_template — upload a source image as a private template. Answer any

ownership/rights input only from the user's explicit confirmation. Never claim rights for a competitor ad or an image found online.

• getadproject / appendprojectmessage — inspect a creative / leave a note on its thread.

Keep the brand kit in sync — reconcile, then update (ASK first)

The brand kit is the source of truth every generation reads. During ANY task, when the user tells you something about the brand or asks to change something brand-level — a different tagline, audience, voice, a product's name/price/description, "our logo is X", "we don't sell Y anymore", a new product photo — treat it as a possible kit update, don't just use it for this one ad and forget it:

1. Check it against the kit. Call getbrandkit for the active brand and see whether what the user said

matches, is missing from, or contradicts the kit.

1. If it's already in the kit and matches — nothing to do; proceed.
2. If it's new or different — ASK before writing. Confirm in one line: *"Want me to update

the brand kit so this sticks for future ads?"* Only persist on a yes (or when the user clearly asked you to change the brand). Don't silently mutate the kit, and don't nag on trivia.

1. Persist with the write tools (partial — only the fields you pass are touched; each edit is

recorded as a user override that later re-research won't clobber): - updatebrandkit — structured brand fields. - upsertbrandproduct / deletebrandproduct — products. - addbrandproductimage / removebrandreferenceimage — product and reference photos. Inspect each live schema and send only the fields needed for the confirmed change.

1. Confirm what changed and continue the task. (Logo, colors, and fonts are owned by the

backend research pass — prefer updateadbrand / the research flow for those, not free text.)

This is the parity gap the app closes in-product: a brand fact the user gives mid-task should be able to flow back into the kit — with their ok — instead of being lost.

Picking source ads — use approved sources, not the retired catalog

When the user wants to make ads but has NOT named a specific template (id/slug/Community ad/upload), do NOT silently browse the raw catalog and hand-pick for them. Instead run this short ask flow — it mirrors the web app and keeps the human in the loop:

1. Ask what kind of ads they want — the angle/offer/theme/season. **The brand context already

gives you the vibe (voice), the audience, and the product catalog — do NOT ask for those.** Offer the real products[] to pick from rather than asking "which product?", and derive the tone from the brand's voice. This shapes both the source choice and your steering prompt. Keep it to one quick question about campaign intent.

1. Ask how to pick a source: their own ads, Community, upload, or "Surprise me".

- Their own ads → use listuseradtemplates to load the active brand's own sources and let them choose from the results. - Community → searchadtemplates, let them choose, then call remixcommunityad before submitting. - Upload → upload through the workspace and call createuseradtemplate. If its live schema requires an ownership or permission answer, only supply it after explicit confirmation. - Surprise me (they want you/the app to pick) → call surprisemetemplates for the active brand and hand the user the returned createurl. It opens /create in CLI mode with the picks pre-selected, a preview modal, and the copyable remix prompt at the bottom (in place of the Generate input). They can swap picks and copy that prompt. If they'd rather you "just make them" without reviewing in the app, you MAY submit the surpriseme_templates picks directly (skip to submit). - Browse in the app → hand the user this URL, with the active brand's slug filled in: https://make.gooseworks.ai/create?brand=<brand-slug>&cli=true In CLI mode the app shows the copyable remix prompt at the bottom (dismissable / switchable back to the UI composer). They browse the available own/Community sources and copy the prompt.

1. Close the loop. When the user pastes back the copyable remix prompt from the app

(it names the brand + the templates they chose), THAT is your cue to generate: resolve the named source(s), inspect submitremixbatch, and collect only its unresolved required inputs.

If the user already named an owned source (id/slug), a Community ad, or an upload, skip the source choice. Competitor ads may inform the angle or structure, but describe them as inspiration, never claim ownership, and never attest rights for the user.

Workflow — make ads from a template

1. Resolve the brand. Use listadbrands by name/site, then call getbrandkit for the

selected brand. If the kit's researchStatus isn't complete, you can still submit (the batch queues and runs when research finishes) — just tell the user. Use the kit to pick productname (a real entry from products[], not a guess) and, if the user supplied product photos, referenceimage_urls.

1. Pick the source ad(s) via the ask flow above. Once you have concrete ids:

call getstaticadtemplate for each. For a Community ad, remixcommunityad first; for an uploaded image, createuseradtemplate first.

1. (Optional) Craft the steering prompt. The prompt is OPTIONAL — this is where the skill

adds value: turn the user's intent (from step 1) into a concise steering note (e.g. tone, season, emphasis). Don't over-specify; the backend pipeline + brand kit handle palette, fonts, product swap.

1. Quote the cost. Inspect and call estimateremixbatch, then tell the user.
2. Submit ONE batch. Inspect the current submitremixbatch schema, fill known required

inputs, ask only for unresolved user decisions, and omit unspecified optional settings. Keep the returned batch_id and links.

1. Poll until done. Call getremixbatch for the returned batch (or use

listbrandcreatives) every ~20-30s until every creative's pending is 0. Most images finish in a few minutes; text-heavy templates and quality: high take longer. Read each render's elapsed_seconds rather than guessing — a render that's still running is healthy; do NOT re-submit thinking it stalled (that double-bills).

1. Hand back the links from the batch's links block — brand_url (gallery) and each

creative's app_url — copied verbatim. Never end on just "done" or a file path.

Workflow — edit an existing ad

User wants to tweak a creative they already made → use regeneratecreative. Infer whether they want another take, a targeted edit, or an exact instructed change from their request. Then inspect the live schema, ask only for any required source or instruction that is still missing, submit, poll with getremix_batch, and hand back the links.

Brand research

Prefer the backend's result: call getbrandkit for the selected brand. If researchStatus is complete, REUSE it — never re-research.

The split — backend owns visuals, you own the qualitative depth:

• Backend LIGHT pass (automatic). createadbrand with a website_url kicks off the same

backend research the web app uses, in mode: "light": it resolves the authoritative logo, colors, and fonts (Brandfetch + context.dev) plus a baseline kit, then flips research_status to complete — usually under a minute. You can't reproduce those visual signals locally, so never re-derive logo/colors/fonts. (Web onboarding via /api/ads/onboard runs the full thing; nothing to do but read it.)

• Your DEEP pass (local, agentic). You add the qualitative depth the light pass leaves thin —

positioning, audience segments, voice, brandType, value props, proof points, products — grounded on the actual site.

CLI brand-research flow:

1. Inspect and call createadbrand with the known brand identity and website, then keep its id

and slug. The brand comes back with research_status: "pending" (light pass in flight).

1. Wait for the backend light pass: poll getbrandkit for that brand until researchStatus

is complete (usually <60s). Now the kit has authoritative logo/colors/fonts + a baseline. At this point generation is already unblocked — but do the deep pass to make it good.

1. Deep research locally: gooseworks fetch brand-research and follow its phases. **Ground

every fact on the fetched site** — if the site can't be read, say so and ask the user; never guess a category from the brand name alone.

1. Write the pack with write_file under agent-config/brands/<slug>/:

- the brand-research/*.md docs + brand-assets/manifest.json (human-readable pack), AND - brand-research/kit-patch.json — the STRUCTURED fields the web UI renders. Field-for-field contract; only what you put here reaches the kit. Shape: { positioning?: string, audience?: string, voice?: string, brandType?: string, tagline?: string, valueProps?: string[], proofPoints?: string[], products?: [{ name, description?, link?, pricing?, imageUrls?: string[] }] } (brandType ∈ product | saas | service | agency | restaurant | fashion | beauty | fitness | finance | education | health). Only URLs already in our storage for product images. - Do NOT set logo / colors / fonts here — the backend light pass already owns those.

1. Persist it: call finalizebrandresearch for the brand. It merges kit-patch.json into the kit

NON-CLOBBERINGLY (it will NOT overwrite the backend's visuals or any user edit), then re-confirms research_status: complete.

1. Verify: call getbrandkit again and confirm the qualitative fields you wrote are present

before generating.

If the brand has NO website, the backend light pass can't run (nothing to fetch) — do the whole thing locally (steps 3–6) and finalize; an un-finalized brand has no kit for generation and leaves no artifact to debug a wrong run (this is how a bad local classification, e.g. mislabelling a SaaS as a "drink company", used to vanish without a trace).

Analyze / intelligence (fetched recipes — NOT generation)

These are analysis recipes you fetch from goose-skills with gooseworks fetch <slug> and follow; they do NOT touch the generation tools or credits-for-images. Pick the closest match; if unsure, gooseworks search "<what the user wants>" first:

• Campaign performance diagnosis ("why is my Meta/Google campaign underperforming",

creative fatigue, learning phase, pacing, auction overlap) → gooseworks fetch meta-ads-analyzer (or ad-campaign-analyzer for cross-platform).

• Lead/CAC quality ("are these ads driving qualified leads", true CAC vs vanity CPA,

Scale/Keep/Investigate/Cut) → gooseworks fetch ad-lead-quality-analyzer.

• Competitor ad intelligence ("what ads are competitors running") →

gooseworks fetch competitor-ad-intelligence (Meta Ad Library: meta-ad-scraper; Google: google-ad-scraper).

• Creative ideation (ad angles, winning hooks) → gooseworks fetch ad-angle-miner /

gooseworks fetch trending-ad-hook-spotter.

• Policy / landing-page checks → gooseworks fetch meta-ad-policy-checker /

gooseworks fetch ad-to-landing-page-auditor.

Save their scripts to /tmp/gooseworks-scripts/<slug>/ and follow their instructions. These run through the gooseworks CLI (gooseworks fetch / gooseworks call), like the GTM skills.

Rules

• MCP required — if mcpgooseworks* is unavailable, stop and tell the user to run

gooseworks install --claude --mcp.

• One backend workflow — generation is submitremixbatch / regenerate_creative ONLY.

Do NOT call FAL, the media proxy, submitrender, updaterender_status, or upload render files yourself; do NOT gooseworks fetch a local remix recipe to generate. The backend owns it.

• Always end a successful run with the links from the batch's links block (brand_url +

each creative's app_url), copied verbatim. Never end on just "done" or a file path.

• Quote cost before generating when it's non-trivial (use estimateremixbatch), and

relay insufficient_credits plainly if the submit is rejected — don't retry blindly.

• Use approved source paths. If the user didn't name a source, run the ask flow (own ads,

Community, upload, Surprise me, or browse in the app). "Surprise me" goes through surprisemetemplates; browsing uses /create?brand=<slug>&cli=true. Never use the retired curated third-party catalog. Generate when they paste the app's copyable remix prompt back (or submit the surprise picks directly if they'd rather not review).

• Treat competitor ads as inspiration — never attest rights, imply ownership, or promise to

copy a competitor's distinctive expression.

• Reconcile brand facts into the kit — when the user states or changes something brand-level

mid-task, check it against getbrandkit and, with their ok, persist it via updatebrandkit / upsertbrandproduct / addbrandproduct_image so it sticks for future ads. Ask first; never silently mutate the kit.

• Record feedback — when the user reacts to a generated image, inspect and call

setcreativefeedback so the quality loop learns.

• Plan mode is opt-in — only use the live approval option, then listadapprovals and

approveadplan, when the user wants to review before spending credits; otherwise generate immediately.

• Don't busy-loop — poll getremixbatch on a sensible interval (~20-30s); a queued

batch is waiting on research and will start on its own.

• Report problems so we can fix them — when a batch fails/is rejected and you can't resolve it,

a required brand input/asset is missing, or a recipe/instruction is ambiguous or contradictory, call the logclievent MCP tool (eventtype: error/blocker/missinginput/confusion, with the real error + step in details) so the team gets visibility. Still tell the user too.