meta-ad-manager

Meta Ad Manager

What this is for. Someone says "I want to run ads on Meta", or comes back a week later and says "where are we?", or a scheduled check wakes up. This skill works out where things stand from the brand's ad docs, picks the next step, hands it to the skill that does that step, and writes down what happened and why. It never makes the user repeat themselves.

It does not do the stage work itself. Intake, strategy, making creatives, launching, checking and fixing each belong to their own skill. This skill decides which one runs, sets the tone, and keeps the docs true.

The docs contract is law. How to read and write the files and the rules for numbers are in contract/RULES.md. The file shapes are in contract/templates/, and contract/validate.py checks a folder. Read RULES.md before your first write.

Where this skill's files are

Every path in this skill (contract/…, references/…) is relative to this skill's own folder, not to your working directory:

Installed by	This skill's folder
GooseWorks (the in-app coworker)	`agent-config/skills/meta-ad-manager/` in the workspace
The GooseWorks CLI (`--with meta-ad-manager`)	the agent's skills folder, for example `~/.claude/skills/meta-ad-manager/` in Claude Code

The stage skills below are installed with this one and sit beside it, in the same parent folder. ads/ itself is never inside a skill folder.

Choose one mode

Use the first mode that is available, and read its adapter before Step 1:

GooseWorks when the GooseWorks tools are callable (the in-app coworker, or any agent with the GooseWorks MCP). Read references/gooseworks-adapter.md.
Direct Meta when there is no GooseWorks, but a Meta access token and ad account are available. Read references/direct-meta-adapter.md.
Planning only when neither is available. Read references/planning-only.md. Intake, strategy and the creative brief still work; nothing is read from or written to Meta.

"The adapter" in the workflow below means the file for the mode you chose. A campaign stays in the mode it started in; say so if the user's access changes mid-campaign.

Stage skills

Skill	Stage it runs	Notes
`ad-management-intake`	intake: business facts, familiarity, the campaign brief; creates the `ads/` files	every mode
`ads-north-star-strategy`	strategy: goal, audience, budget split, creative count, test frame	every mode
campaign planning + creative generation	create and review	GooseWorks generates; other modes write a creative brief
`launch-meta-ad-campaign`	launch: readiness, paused build, readback, confirmation	GooseWorks or direct Meta
a quick check (daily report)	quick check on live campaigns	where the adapter has one
`meta-ads-analyzer`	deep check on complete days	when installed
fix-and-adjust actions (pause, revert, budget change, replace creative)	acting on an approved recommendation	the adapter lists what it supports
`answer-ads-questions`	factual questions about the ads	every mode

The first four and the answers skill are installed with this one. When a listed skill is not installed, the workflow's Fallback column says what to do. Outside GooseWorks, "campaign planning + creative generation" means the adapter's written creative brief, and the check and fix rows are what the adapter lists.

Inputs

The message — the user's words, or the automation's prompt for a scheduled run.
The surface — chat, a messaging channel, a scheduled run, or an outside agent host. It changes only Step 0 and whether you may ask questions.
The brand's ads/ folder — the adapter says where it is. It may not exist yet.
The docs contract — contract/RULES.md and contract/templates/.

Workflow

Step 0 — Surface gate

The harness needs a conversation to ask questions and get approvals.

Web chat, a messaging channel, or an outside agent host: go on. Web chat is a full surface; never send its user elsewhere to continue.
A surface with no conversation (a button or form that started the request, with no chat behind it): tell the user in one sentence to continue in chat or connect a messaging channel, and stop. Write nothing.
Scheduled run: go on, but you may not ask questions (see Step 6).

Follow-ups after launch arrive in the report. If the user asks how they will hear about results and has no messaging channel, say how the report reaches them and offer to connect a channel. Do not block on it.

Step 1 — Read the index

Read ads/README.md. Always first, always the whole file.

It does not exist → this brand has never started the harness. Route to intake (Step 4) and write nothing yourself: ad-management-intake creates ads/brand.md, the index and the campaign folder, after it has stated its assumptions to the user (its Step 5 comes before its Step 6). Only on the fallback path (intake not installed) do you write them yourself, as below. The folder must always be valid under the contract, and that needs ads/brand.md, which needs the business type and the user's familiarity. Once you have those two (research usually gives the business type; familiarity is one question) and you have stated your assumptions, write ads/brand.md, ads/README.md and the new campaign folder (Step 2) together, in one turn. Both files need the brand's id and its coworker agent id in the frontmatter; the adapter says where they come from (outside GooseWorks, write local for both). Never write a placeholder or none for either.
It exists → read the Campaigns table. Each row is a campaign slug, its stage, the last and next action. Do not open any campaign folder yet.

Step 2 — Pick the campaign

Situation	Do
No campaigns, or the user clearly wants something new ("now ads for our new serum")	Start a new campaign (below)
One campaign that is not `ended`	That one
Several, and the message names a product, offer or campaign that matches one slug or its last/next action	That one. Say which in the reply, in the user's words ("Picking up the gift bundles campaign.")
Several, and nothing in the message decides it	Ask one question listing the open campaigns in plain words, with each one's next action. Never guess
Scheduled run	Every campaign at `live` or `paused`, one at a time (Step 6)

Starting a new campaign. Pick a short kebab-case slug from the product or offer (holiday-gift-bundles) and route to intake. When ad-management-intake is installed it creates the folder and the index row with that slug; do not write them twice. On the fallback path, create ads/campaigns/<slug>/ with all three files, following the templates:

state.md — campaign: <slug>, stage: intake, goose_campaign_id: none, meta_push_ids: [], meta_campaign_id: none, updated_at: <today>, updated_by: meta-ad-manager; Open recommendations, Pre-approved rules and Last check each None.
strategy.md — campaign: <slug>, product_ids (catalog ids if known, else []), version: 1, updated_at: <today>, based_on: intake <today>, and every section heading with "Not decided yet — the strategy stage sets this." under it (the same stub intake writes).
decisions.md — one entry ### <today> — Campaign opened: Recommended gives the reason (the user's request, quoted briefly), Evidence user request, Decided <user> asked for it, Outcome opened.

Add the row to the index in the same turn. For a brand with no ads/ yet, this happens together with ads/brand.md (Step 1).

Step 3 — Read only what this campaign needs

Read ads/campaigns/<slug>/state.md. Then only what the next step needs:

ads/brand.md frontmatter only (familiarity, business_type) on any turn that talks to the user, for tone (RULES.md §3 allows this). The body only when the next step needs a business fact: intake, strategy, a deep check, or a question the docs might already answer.
strategy.md — for create, review, launch and deep check.
decisions.md — when an open recommendation is being decided, for a quick or deep check (to follow up the last recommendation), and when the user asks "why did we…".

Never read other campaigns "for context".

Step 4 — Route

Find the row for the campaign's stage and the user's intent. Hand off to the skill in Runs. If that skill is not installed, do what the Fallback column says.

Stage, or intent	Runs	Fallback while it is missing
`intake`, or `ads/brand.md` missing	`ad-management-intake`	Ask the goal-first questions from `launch-meta-ad-campaign` Stage 1 that the docs do not already answer, plus the familiarity question ("How much have you used Meta Ads before: never, a little, or a lot?"). At most four questions per turn, familiarity and the goal first; the rest wait for later turns unless the user asks to answer everything at once. State what you are assuming instead of asking. Write business facts to `ads/brand.md` and campaign facts (goal, audience, budget, destination) to the campaign brief (the adapter says where it lives). Never create a brief file under `ads/`
Meta is not connected and the next step needs it	the connection repair flow	—
`strategy`	`ads-north-star-strategy`	Use `launch-meta-ad-campaign`'s test-design stage and write the result into `strategy.md`
`create`, `review`	campaign planning and creative generation, as `ads-north-star-strategy` hands it off: about three times the creatives the plan needs, so the user can choose. Nothing that spends credits runs without the user's yes (a cost quote, or the approval step the generation flow provides); an approved plan is not approval to spend credits	—
`launch`	`launch-meta-ad-campaign`	—
`live` or `paused` + a daily scheduled run, or "send me the report"	quick check (the daily report)	—
`live` or `paused` + "dig in", "what's working", or a weekly scheduled run	`meta-ads-analyzer` as a deep check	—
An open recommendation in `state.md` is approved or declined	the fix-and-adjust action it names	Pause or revert, or propose the budget change or creative swap. A proposal changes nothing in Meta until the user approves it on the page the tool returns: say so and give them that link
Any stage + a question in chat ("how are the ads doing?", "how much have we spent?")	`answer-ads-questions`	Answer from the read tools only, with each number's data window and sync time (RULES.md §5). Never from the docs
`live` or `paused` + an open recommendation still awaiting + "what's next?"	Put that recommendation to the user as the one next step, with its evidence; act only on a yes	—
The user asks to pause ads or a campaign	the pause action (their request is the approval); stage `live → paused` when the whole campaign stops	—
The user asks to turn paused ads back on	Say it will start spending again, and how much per day, and get an explicit yes. Then the launch skill's confirmation flow; stage `paused → live` after Meta confirms	—
The user asks to stop a campaign for good	Confirm once, pause everything still running, then stage `→ ended`	—
`ended`	Nothing. Say it ended and when, and offer a new campaign	—

Stage skills never get a new question the docs already answer. Pass them what you read.

Planning without Meta is allowed. A missing Meta connection blocks launch, checks and fixes, not intake, strategy or creative.

Step 5 — Hand-back and write-back

When a stage skill returns, decide whether the campaign moves stage.

Allowed moves: intake → strategy → create → review → launch → live, live ↔ paused, and any stage → ended. Do not skip a stage, with one exception: a user who already has approved creatives and asks to publish them may go from intake straight to launch once ads/brand.md exists; the launch skill's test design is then written to strategy.md, and the decisions entry says why the stages were skipped. review → launch needs the user's approval of the creatives. launch → live needs Meta to confirm the ads exist (the launch skill's readback), not a successful write.

On every stage change, in the same turn, write all three:

state.md — set stage, updated_at (today), updated_by: meta-ad-manager. Keep ids the stage skill wrote.
ads/README.md — that campaign's row: Stage (must equal state.md), Last action (what just happened, one clause), Next action (what happens next and who owns it), Updated (today). Update updated_at in the frontmatter.
decisions.md — append one entry at the end:
```
### 2026-09-24 — Stage: strategy → create
- Recommended: Move to creatives: the strategy is set (3 ads from 9, $30/day for 14 days) and the user agreed to it.
- Evidence: user request
- Decided: Maya approved the strategy
- Outcome: moved to create
```
The Recommended line is the reason. Evidence is a pointer (report:<id>, push:<id>, finding:<id>, or the form the adapter names) or user request. Never make up a pointer: use one only when a tool or report gave you that id.

A decision without a stage change (an open recommendation approved or declined, a pause of one ad) still writes: append a decisions.md entry with what was decided (or fill the matching - Outcome: pending line), remove the R<n> line from state.md Open recommendations, set updated_at and updated_by, and update the index row's Last action, Next action and Updated. If strategy.md still says the decided item is awaiting approval, update that line (and its updated_at) so the docs never state something that is no longer true.

Whole-file writes: read the file, change it, write it all back (RULES.md §4). If nothing was decided and no stage changed (a question answered, a check with nothing new), write nothing except what the stage skill itself owns.

Then tell the user, in their tone (below), what happened and what happens next. One next step, not a menu.

Step 6 — Scheduled runs

Only on a host that runs scheduled checks (the adapter says whether yours does). No one is there to answer, so:

Never ask a question. Anything that needs a decision becomes an open recommendation in state.md (- R<n> (<date>): <what> — evidence <pointer> — awaiting) and a line in the report.
Go through each live or paused campaign on its own: read its state.md and decisions.md, run the check the schedule names, and write back before starting the next one.
Open every check by saying whether the last recommendation was acted on, from decisions.md.
Any write to state.md (a new R<n>, Last check) also sets updated_at and updated_by, and the index row's Last action and Updated.
A weekly deep check with nothing above the evidence threshold stays silent in the report except for one line saying so.

How to talk to the user

Read familiarity from ads/brand.md. Until intake has recorded it, treat the user as a novice. Never guess "expert".

Familiarity	Before each recommendation	Then
`novice`	One plain sentence explaining the idea, with no ad jargon	The recommendation, in business words
`intermediate`	A short clause of explanation only for terms beyond the basics	The recommendation and the key evidence
`expert`	Nothing	The recommendation and the evidence, with Meta's own terms allowed

The same recommendation, two ways:

Novice: "Meta needs a few days of results before it can tell which ad works, a bit like a new salesperson learning the pitch. So I'd leave all three ads running until Friday before we change anything. OK to wait?"
Expert: "Hold changes until Friday: two ad sets are still in learning (18 and 23 of ~50 weekly conversions), and a budget edit now resets it. Approve the hold?"

For every level: use the vocabulary rules in launch-meta-ad-campaign ("How to talk to the user"). Talk about the business, not Meta's objects. Surface a raw id only when the user asks.

Decision Rules

Never ask what the docs answer. Before asking the user for a fact, look for it in the index, the campaign's state.md and strategy.md, and the body of ads/brand.md (reading them for this is allowed at any stage). Business type, unit economics, familiarity, connected accounts, claims rules, the budget, the goal and the audience are all recorded there once known. If it is written down, use it and say so ("Going with the $45 target cost per subscriber you gave me").
One question at a time for routing. Stage skills may ask more; this skill asks at most one.
Numbers from tools are observations. Never write a Meta number into the docs as a fact or call it "current" (RULES.md §5).
Numbers in a reply come from one of three places: a tool read this turn (with its window and sync time), the user, or a dated Observed: line in the docs quoted as the evidence behind a recommendation already made ("the 22 Sep report, covering 16–21 Sep, had the gift ad at $71 per order"). A saved snapshot is never an answer to "how is it doing"; read the tools for that. Always say the snapshot's date. Before acting on an approved recommendation, re-read the tools; if the picture has changed, say so and ask again.
Evidence pointers stay in the docs. In a reply, name the evidence in words ("the 22 Sep report"), not by id, whatever the familiarity level.
The docs record decisions, not Meta's state. Spend, delivery and rejections are read from tools when needed.
Budget changes always need the user's approval, every time. Pause is the only action that can be pre-approved (in state.md Pre-approved rules).
Credits are spend too. Anything that uses credits (generating creatives, research runs) gets a cost quote and the user's yes first, every time.
At most four questions in a turn, across every stage. Ask the ones where a wrong guess changes money, claims or legal exposure; state the rest as assumptions.
Never activate spend from here. Launch keeps objects paused until the user confirms in the launch skill's own flow.

Output

A reply to the user (or a report line on a scheduled run): where the campaign stands, what just happened, and one next step.
The ads/ docs updated per Step 5, and valid under the contract: from the directory that holds ads/, python3 <this skill's folder>/contract/validate.py ads.

Quality Checks

ads/README.md was read first, and only the campaign in play was opened.
Index Stage equals state.md stage for every row you touched.
Every stage change has its decisions.md entry, appended at the end; nothing earlier changed.
No question asked whose answer is in the docs.
The wording matches familiarity; novice when unknown.
No number read from a tool is in the docs without an Observed tag. Every number in the reply came from a read this turn, the user, or a dated Observed line quoted as a recommendation's evidence with its window.
A scheduled run asked nothing and left every open decision in state.md.

Failure Modes

Symptom	Cause	Fix
The user is asked for their budget or business type again	The docs were not read before asking	Read the index, `state.md`, `strategy.md` and `brand.md` first; quote what is there
Index says `strategy`, `state.md` says `create`	One of the two writes in a transition was skipped	Write both in the same turn; the validator flags the mismatch
A campaign "resumes" at the wrong product	Two campaigns, and the message was guessed	If the message does not name one, ask the one routing question
Files written but nothing appears on the next run	Written somewhere other than where the adapter keeps `ads/`	Use the adapter's paths exactly
`contract/RULES.md` "does not exist"	Opened relative to the working directory	Paths are relative to this skill's folder (see "Where this skill's files are")
The routed skill is not installed	A stage skill is missing on this host	Use the Fallback column; do not improvise a new flow
The user is told "your ads are live" after a write	A write is not delivery	Only move to `live` after the launch skill's readback
A scheduled run asks a question nobody sees	The scheduled rules were skipped	Turn it into an open recommendation in `state.md`