Realize Plugin

View saved version →

---
name: accounts
description: Discover Realize accounts and capture the account_id required by every other Realize MCP tool. Must run before any campaign or report query.
allowed-tools: ["Read", "AskUserQuestion"]
---

# Accounts

Every other Realize MCP tool requires an `account_id`. This skill resolves one.

## When to use

- The user mentions a new account name, numeric ID, or advertiser.
- No `account_id` is cached for the current session.
- The user's question is ambiguous about which account they mean.
- The user wants to switch accounts.

## Workflow

1. **Call `search_accounts`** with the user's input. `query` is **optional** and routed server-side by shape: a pure-digits string is an exact `id` lookup, free text is a fuzzy name lookup, and an **omitted or empty `query` lists all accounts** the authenticated user has access to. To fuzzy-search a number rather than look it up exactly, append `*` (`"123*"`).
   ```
   # the user named an account:
   mcp__realize-mcp__search_accounts(query="<user input>", page_size=10, page=1)

   # "list all my accounts" — omit query entirely, do NOT pass "*" or "all":
   mcp__realize-mcp__search_accounts(page_size=10, page=1)
   ```
2. **Inspect the response.** The returned `account_id` is an **opaque string** supplied by the server (examples from upstream docs: `advertiser_12345_prod`, `mktg_corp_001`), not the numeric ID the user might have typed. Do not fabricate, re-case, or otherwise transform it — pass it through verbatim.

   Each result also carries `currency`, `country`, `time_zone_name` (use these for budget amounts and `activity_schedule.time_zone`) and the account **`type`**. **Carry `type` forward — it decides which report tool the `reports` skill can use:** `PARTNER` and `NETWORK` support the metamodel dynamic report; **`GROUP` accounts and admin networks do not** (the dynamic tools return 403 by design) and must use `get_campaign_breakdown_report`. Note the type when you resolve the account, so reporting routes correctly the first time instead of recovering from a 403.
3. **Disambiguate if multiple results.** Use `AskUserQuestion` to let the user pick. Show account name + `account_id` string in each option.
4. **Paginate if needed.** If the user's match isn't in the first page, call again with `page=2`, keeping `page_size` constant. Hard cap: `page_size=10`.
5. **Persist the choice** (optional). If the user wants this as their default, write it to `.claude/realize.local.md` (gitignored):
   ```yaml
   ---
   default_account_id: advertiser_12345_prod
   default_account_name: Example Advertiser
   ---
   ```

## Example

**User:** "Pull my Q1 numbers for Example Advertiser."

**You:**
1. `search_accounts(query="Example Advertiser")` → one result, `account_id=advertiser_12345_prod`.
2. Cache it, hand off to `reports` skill for the actual data pull.

**User:** "Show me the acme account."

**You:**
1. `search_accounts(query="acme")` → three matches.
2. `AskUserQuestion`: "Which Acme account?" with each `account_id` as an option.
3. Proceed with the user's pick.

## Gotchas

- **Numeric IDs from the user are not `account_id`s.** Users often say "account 12345" meaning the numeric ID; the MCP expects the opaque string returned by `search_accounts`. The server explicitly rejects numeric-only IDs passed as `account_id` to downstream tools, so always route through `search_accounts` first.
- **Hard page_size cap of 10.** Unlike report tools (cap 100), account search declares `maximum: 10` in its schema, so `page_size=50` is **rejected with a validation error** rather than clamped — ask for 10 or fewer and page.
- **Omit `query`** to list all accounts when the user asks for an inventory, rather than guessing a search term. Upstream documents the empty/omitted query as the list-all form and documents `*` only as a suffix for fuzzy-matching a number (`"123*"`); it says nothing about a bare `*`. Don't rely on one.
- **Don't cache stale account_ids across sessions** without re-validati

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: campaigns
description: List and inspect Realize campaigns and their creatives/items. Use after an account_id is resolved.
allowed-tools: ["Read", "AskUserQuestion"]
---

# Campaigns

Inspection of campaigns and their items (creatives) for a given account using the campaign query tools currently exposed by the MCP.

## Prerequisites

- `account_id` resolved via the `accounts` skill. If missing, hand off there first.

## Related skills

- For **writes** — create or update a campaign or native item — hand off to the [`manage-campaigns`](../manage-campaigns/SKILL.md) skill. This skill stays read-only.

## Tools this skill wraps

| Tool | Required params | Paginated? |
|---|---|---|
| `mcp__realize-mcp__list_campaigns` | `account_id` | **Yes** — `page` / `page_size`, **max 10 per page** |
| `mcp__realize-mcp__get_campaign` | `account_id`, `campaign_id` | — |
| `mcp__realize-mcp__list_items` | `account_id`, `campaign_id` | **No** — full list in one call |
| `mcp__realize-mcp__get_item` | `account_id`, `campaign_id`, `item_id` | — |

`list_campaigns` **is paginated and caps at 10 rows per page** — page until a short page before claiming you have every campaign. `list_items` is not paginated: if a campaign has hundreds of items they all come back in one call, so filter or summarize in post-processing. None of these tools accept filter parameters.

**The owning-account rule.** `get_campaign` and `list_items` need the campaign's **owning** account, which is the `advertiser_id` on the campaign row from `list_campaigns` — not necessarily the account you listed from. A NETWORK or parent account can *list* its children's campaigns but rejects campaign- and item-level calls on them (404 and 403 respectively). Always carry `advertiser_id` forward from the listing rather than reusing the account you searched with.

## Typical flows

**"List my active campaigns."**
1. `list_campaigns(account_id=...)` — then **keep paging until a page returns fewer than `page_size` rows.** The cap is 10 per page, so a single call covers only the smallest accounts; answering from it gives a wrong count and a wrong combined spend, presented as the whole account.
2. Inspect the `status` field on each campaign and filter in memory to rows with an active/running status (the exact enum comes from the API response — e.g., `RUNNING`). Then summarize: count, combined spend, date range — and state how many campaigns you actually read.

**"What's the deal with campaign 98765?"**
1. `get_campaign(account_id=..., campaign_id=98765)` for configuration and status.
2. `list_items(account_id=..., campaign_id=98765)` for the creative list.
3. Summarize: objective, budget, targeting, creative count, any items flagged paused/rejected.

**"Show me the creatives for my top-spending campaign."**
1. Combine with the `reports` skill: run a campaign-grain dynamic report sorted by spend DESC (`get_dynamic_report_settings` → `get_dynamic_report_data`), pick the top campaign. On a **GROUP or admin-network** account the dynamic tools 403 — use `get_campaign_breakdown_report` (`sort_field="spent"`, `sort_direction="DESC"`) instead; the `reports` skill owns that routing rule.
2. `list_items(account_id=<the top campaign's `advertiser_id`>, campaign_id=<top>)` and list creatives with IDs, names, status. **Use the campaign's `advertiser_id`, not the account you reported on** — on a NETWORK / parent / GROUP account, passing the reporting account here returns 403.

## Interpretation guidelines

- **Always cite the account in your summary.** Make it obvious which account the numbers are from.
- **Don't list raw JSON back at the user.** Pull the 3–5 fields that answer their question (status, spend, budget, objective) and surface those in prose.
- **If the account is large**, ask what the user actually needs before paging through it. You will not know the size from the first call — it caps at 10 — so judge from the second page onward, or from the user's own description of the account. Most q

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: diagnose-tracking
description: Diagnose whether the Taboola Pixel on an advertiser's site is installed correctly, actually firing, and feeding conversions into Realize — and route the fix. Covers both the base pixel ("pixel shows inactive") and specific conversion events and their rules ("make_purchase isn't tracking"). Activates on "my pixel isn't firing", "conversions aren't tracking", "is my pixel installed correctly", "purchases are double-counted", "check the pixel on this page". Works from the user's page URL plus evidence the user captures (a HAR recording, a window._tfa dump), cross-checks conversion rules and reports via the MCP, and hands rule fixes to manage-campaigns. Not for installing the pixel (web-fallback has the platform steps), campaign performance questions (optimize-campaign), or app-install campaigns landing on an app store — no web pixel runs there (S2S/MMP territory).
allowed-tools: ["Read", "Grep", "Glob", "AskUserQuestion"]
---

# Diagnose Tracking

Evidence-driven diagnosis of the Taboola Pixel on an advertiser's own site: is it installed, does it fire,
does it send the right data, and do its conversions reach Realize. The skill names a single most likely
root cause, states which side of the fence it lives on (the user's site vs. Taboola), and routes the fix —
site-side fixes as copy-paste instructions, rule fixes through `manage-campaigns`' write gate, Taboola-side
gaps through the support escalation path.

## The four layers — split before diagnosing

Every pixel problem is one of four, and the fixes don't overlap. Confirm which layer before naming a cause:

| Layer | Meaning | Typical fix owner |
|---|---|---|
| **Not implemented** | The code isn't on the page | User's site team |
| **Implemented but blocked** | Code present; a consent tool, ad-blocker, or the site's CSP stops it | User's site/consent config |
| **Fires but wrong data** | Events go out with missing/malformed fields (`revenue` with a `$`, no `orderid`) | User's site team |
| **Fires fine — downstream gap** | Client side healthy; the issue is rule config, attribution, or Taboola-side | Rule fixes: this plugin (gated write). Taboola-side: escalation |

These labels are internal scaffolding — per `os/guardrails.md`, don't narrate "layer 2" at the user;
describe the actual finding ("the code is on the page, but your consent banner blocks it until visitors
opt in").

## When to use — and when not

**Use for:** "pixel not firing", "conversions not tracking", "pixel shows inactive", "is it installed
right", "double-counted purchases", "revenue is blank on my conversions", "check the pixel on this URL",
pre-launch pixel verification.

**Route elsewhere:**
- *How to install* the pixel (Shopify / WordPress / GTM steps) → `web-fallback` has the public steps; the
  Realize UI is where install work happens. This skill verifies installs; it doesn't walk through creating them.
- *Rule work with no diagnostic question* ("create a conversion rule", "change my attribution window") →
  `manage-campaigns` directly.
- *Campaign performance* ("CPA spiked", "not spending") → `optimize-campaign`. It hands back here when its
  tracking pre-check finds the pixel itself broken.

## What this skill can and cannot see — say it, don't blur it

**Can:** the page's served code (fetched live), whatever runtime evidence the user captures (HAR,
`window._tfa` dump, Pixel Helper screenshot), the account's conversion rules (`get_conversion_rules`), and
conversion/spend numbers from the report tools.

**Cannot:** whether an event that left the browser actually landed inside Taboola's processing, matched a
rule server-side, or was dropped in ingestion. No MCP tool exposes that today. When the client side is
verified healthy and Realize still shows nothing (with rules live and campaigns spending), the honest
conclusion is *"healthy on your side — this needs Taboola's eyes"* plus the escalation path below. Never
fabricate a server-side fact to close the gap.

## 

Preview of the first 4,000 characters. Read full instructions →

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

View saved version →

---
name: discovery
description: Look up Realize targeting metadata, audiences, publishers, conversion rules, time zones, and CTA types. Use when the user asks "what X is available" or needs an opaque ID before going to the Realize UI. Read-only — no campaign or item state is changed.
allowed-tools: ["Read", "Grep", "AskUserQuestion"]
---

# Discovery

Resolve opaque IDs and enumerate the catalogs that Realize's targeting / audience / publisher / conversion settings draw from. This skill wraps the nine read-only "look it up" tools the MCP exposes, so the user does not have to guess country codes, audience IDs, publisher IDs, segment IDs, conversion-rule IDs, CTA enum values, or IANA time zone names.

## When to use

Trigger on any of:

- "What countries / regions / DMAs / cities / postal codes can I target?"
- "What operating systems / browsers does Realize support?"
- "What audiences / lookalike audiences / contextual segments are available on account X?"
- "List publishers on account X" / "Find publishers matching <name>"
- "What conversion rules are configured on account X?"
- "What time zones does Realize support?"
- "What CTA button types are available for native items?"
- Any campaign-creation walkthrough where the user needs to paste an opaque ID rather than a display name.

For pulling **performance numbers**, route to the `reports` skill instead. For campaign/item lookup, route to the `campaigns` skill.

## Prerequisites

- `account_id` resolved via the `accounts` skill is required for every tool below **except** `search_geos`, `search_techno`, `list_time_zones`, and `list_cta_types` (those are global catalogs).

## Tools this skill wraps

| Tool | Required params | Optional params | Returns |
|---|---|---|---|
| `mcp__realize-mcp__search_geos` | `dimension` ∈ {`countries`, `regions`, `dma`, `cities`, `postal_codes`} | `country_code` (ISO-2 — **required** when `dimension` ≠ `countries`) | `{dimension, values: [{code, name}, ...]}` |
| `mcp__realize-mcp__search_techno` | `dimension` ∈ {`operating_system_versions`, `browsers`} | `os_family` (**required** when `dimension=operating_system_versions`) | `{dimension, values: [...]}` |
| `mcp__realize-mcp__search_audiences` | `account_id` | `country_codes` (comma-separated ISO-2), `country_targeting_type` ∈ {`ALL`, `INCLUDE`, `EXCLUDE`} | Audience list with `audience_id`, `name`, ... |
| `mcp__realize-mcp__search_lookalike_audiences` | `account_id` | `country_code` (ISO-2) | Lookalike rules with `rule_id`, ... |
| `mcp__realize-mcp__search_contextual_segments` | `account_id` | `country_codes`, `country_targeting_type` | Segments with `segment_id`, ... |
| `mcp__realize-mcp__search_publishers` | `account_id`, `query` (use `"*"` for all) | `publisher_ids` (array of int), `page` (default 1), `page_size` (max **50**, default 10) | Paginated publisher list `{id, name, account_id, country, is_active}` |
| `mcp__realize-mcp__get_conversion_rules` | `account_id` | `rule_id` (numeric id **as a string**, narrows to one rule), `page` (default 1), `page_size` (default 25, max **50**), `status` (`ACTIVE`/`DISABLED`/`ARCHIVED`), `search_text` (substring of `display_name`) | `{account_id, values: [...]}` — each rule in full, with `condition` and `effects`. **Paginated**, ordered by rule id; the response states the true `total`. `page`/`page_size` are ignored when `rule_id` is set. |
| `mcp__realize-mcp__list_time_zones` | — | — | Array of IANA time zone names (e.g., `America/New_York`) |
| `mcp__realize-mcp__list_cta_types` | — | — | Array of valid `cta_type` enum values |

## Examples

- *"What DMAs are available in the US?"* → `search_geos(dimension="dma", country_code="US")`.
- *"List regions in Brazil."* → `search_geos(dimension="regions", country_code="BR")`.
- *"All Windows OS versions I can target?"* → `search_techno(dimension="operating_system_versions", os_family="Windows")`.
- *"Audiences on account advertiser_12345_prod for US/CA, include-mode."* → `search_audiences(account_id="a

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: manage-campaigns
description: Create and update Realize campaigns, native + display items, and account-level conversion rules via the Realize MCP write tools. Activates on any write-intent request — create, edit, pause/resume, launch, budget changes, bid changes, targeting edits, creative swaps, conversion-rule creation, attribution-window changes, retiring a conversion rule. Enforces a tiered preview-then-confirm pattern with a mandatory account-identity header on every confirmation so the user always sees which account is being mutated. Falls back to a UI reference for actions the MCP does not currently expose (delete, duplicate, bulk operations, pixel installation, codeless-conversion setup, pixel test-fire). Grounded in the realize-toolkit's setup guidance and Taboola's official setup guide for the input-validation heuristics (Marketing Objective enum, Bid Strategy × budget minimums, learning-phase defaults).
allowed-tools: ["Read", "Grep", "AskUserQuestion"]
---

# Manage Campaigns

Writes for Realize campaigns and native + display items via MCP. Every destructive call is gated behind a preview and an explicit user confirmation; the preview always identifies the target account by name and opaque `account_id`. This skill is the only place in the plugin that calls the MCP write tools.

**Depth:** the full field-by-field MCP write-surface reference (every scalar on `create_campaign`, every field on `create_native_item` / `create_display_item`, per-strategy bid-lever gates, common payload patterns, failure modes) lives in `references/mcp-write-surface.md`. Read it when a payload needs detailed field coverage or when debugging a write rejection.

## When to use

Trigger on any of: *create, make, set up, launch, edit, update, change, pause, resume, duplicate, clone, delete, remove, bump the budget, raise the bid, lower CPC, swap the creative, add an ad, add a creative, target X, exclude Y*.

If the user is *asking* about a campaign rather than changing it, route to the `campaigns` skill (reads only). If the user is *diagnosing* performance, route to `optimize-campaign` — that skill hands write prescriptions back here.

## Prerequisites

- `account_id` resolved via the `accounts` skill. If missing, hand off there first.
- For **updates**, the relevant `get_campaign` / `get_item` read MUST precede the write — both to render a diff preview and (for `update_campaign` targeting blocks) to merge client-side so the full-replace semantics do not wipe dimensions the user didn't mention.

## Tools this skill wraps

| Tool | Required params | Idempotent? | Notes |
|---|---|---|---|
| `mcp__realize-mcp__create_campaign` | `account_id`, `name`, `marketing_objective`, `branding_text`, `spending_limit_model`, `bid_strategy` | No | Atomic. Ships PAUSED unless `is_active=true`. 15 optional targeting blocks (full-replace within block). |
| `mcp__realize-mcp__update_campaign` | `account_id`, `campaign_id` | Yes | **Scalars partial-merge**; **targeting blocks full-replace within a section**. At least one updatable field required. |
| `mcp__realize-mcp__create_native_item` | `account_id`, `campaign_id`, `url`, `title`, `description`, `thumbnail_url` | No | Optional `branding_text`, `cta`. New items typically PENDING_APPROVAL → RUNNING. |
| `mcp__realize-mcp__update_native_item` | `account_id`, `campaign_id`, `item_id` | Yes | At least one updatable field required. |
| `mcp__realize-mcp__create_display_item` | `account_id`, `campaign_id`, `url`, `creative_name`, plus either `ad_tag` (3P JS) or `asset_url` + `dimensions` (1P-hosted) | No | Locks campaign as Display on first call when `pricing_model=CPC`. 3P tags must match the validator allowlist (no `<!DOCTYPE>` / `<html>` wrapper). |
| `mcp__realize-mcp__update_display_item` | `account_id`, `campaign_id`, `item_id` | Yes | At least one updatable field required. Arrays like `verification_pixel` are full-replace. |
| `mcp__realize-mcp__create_conversion_rule` | `account_id`, `display_name`,

Preview of the first 4,000 characters. Read full instructions →

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

View saved version →

---
name: optimize-campaign
description: Diagnose a Realize campaign that's underperforming or had a discrete performance event, and prescribe fixes. Walks 5 mandatory pre-checks then routes to RCA (when something broke on a specific date) or general optimization (ongoing review). Activates on questions like "why is this campaign underperforming?", "CPA spiked yesterday", "what should I pause?", "how do I improve CPA?", "campaign isn't spending", "lead quality is bad", "performance has plateaued".
allowed-tools: ["Read", "AskUserQuestion"]
---

# Optimize Campaign

Data-driven diagnosis and recommendation loop for a Realize campaign. Pulls performance data via the MCP, applies mandatory pre-checks, then routes to one of two diagnostic paths and prescribes concrete next actions.

## Internal vs user-facing terminology — never leak the framework names

The framework labels in this file (*"pre-checks P1–P5"*, *"RCA — 6-signal framework"*, *"Signal 1 / Signal 2 / Signal 6"*, *"residual signal"*, *"creative restructure shock"*) are **internal scaffolding** for the model. **Never surface them in user-facing output.** Per `os/guardrails.md`, do the work and describe the actual finding in plain English.

| Internal label (this file uses) | What to say to the user |
|---|---|
| *"mandatory pre-checks"* / *"running P1–P5"* | Just do the checks silently. If a check matters to the answer, describe the finding ("the campaign has no conversion goal attached"). |
| *"RCA — root cause analysis"* (without expansion) | Either say *"root cause analysis"* in full, or just present the analysis. Don't label the process. |
| *"Signal 1 (config change) → Signal 2 (supply concentration) chain"* | Describe the actual sequence: *"The Feb 13 block redirected spend to Yahoo Homepage, which then served lower-engagement slots — that's what shows up as the CTR drop."* |
| *"silent failure mode"* / *"silent diagnostic-quality killer"* | Describe what's wrong factually: *"The campaign doesn't have a conversion goal attached, so the optimizer doesn't know what to bid toward."* No "silent" anything. |
| *"residual signal — never the default"* | Don't surface the framework hierarchy. Just present the conclusion. |

The framework helps you think; the user needs the conclusion, not the framework.

**Depth:** The substantive depth (dimensional drill-down rules, supply-side eligibility, creative-fatigue tiers, bid-lever matrix, symptom-class branches, common-mistake table, output discipline) lives in `references/optimization-flow.md`. Read it when a branch fires that needs operational specifics.

## When to use

Trigger on any of these — across the two paths below:

**RCA (something broke on a specific date)**
- "CPA spiked yesterday" / "conversions dropped this week" / "it broke on date X"
- "Why isn't my campaign spending today / since [date]?"
- "What happened to the campaign after I made [change]?"

**General optimization (no specific event)**
- "Why is this campaign underperforming?" / "How do I improve CPA?"
- "What should I pause / cut / scale up?"
- "Performance has plateaued — what's next?"
- "Lead quality is bad" / "Which sites should I block?"

If the user asks to *create* a new campaign — or to apply any of the prescriptions below (pause an item, bump a budget, change a bid, edit targeting) — route to the `manage-campaigns` skill, which calls the MCP write tools behind a preview-then-confirm gate.

## Prerequisites

- `account_id` resolved via the `accounts` skill.
- A specific `campaign_id` in scope, or the user asking "across my whole account". For single-campaign questions, identify the campaign first via the `campaigns` skill if needed.

## Pre-checks (mandatory — never skip)

Before any analysis, run all five. Skipping leads to wrong conclusions.

| # | Pre-check | Action | Why |
|---|---|---|---|
| **P1** | **Tracking health** | Pull a campaign-grain report over the date window with clicks + conversions. On a PARTNER / NETWORK account that is `get_d

Preview of the first 4,000 characters. Read full instructions →

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

View saved version →

---
name: realize-guardrails
description: Apply the shared Realize account-resolution, user-facing output, privacy, and preview-then-confirm safety rules before answering Realize questions or performing writes.
allowed-tools: ["Read"]
---

# Realize guardrails

Read and follow `../../os/guardrails.md` before handling a Realize request. This is the canonical guardrails file; do not duplicate its contents here.

View saved version →

---
name: reports
description: Pull Realize performance reports (CSV) and interpret them. Covers the metamodel-driven dynamic report (any dimension × metric combination — e.g. campaign, ad, site, day/week, country, platform, browser, OS), the classic campaign-breakdown report that still serves GROUP and admin-network accounts, and the campaign-history change log, with the mandatory settings-first workflow, filter/sort rules, and pagination.
allowed-tools: ["Read", "AskUserQuestion"]
---

# Reports

Wraps the Realize MCP reporting tools. Reports return **CSV**, not JSON — interpret the output in prose rather than dumping it back at the user.

Performance questions are normally answered by the **dynamic report**, a two-tool pair: first fetch the metamodel (the menu of every dimension, metric, and filterable field), then build and run the query.

Two of the fixed-grain tools that predated it — `get_top_campaign_content_report` and `get_campaign_site_day_breakdown_report` — are **retired from the live tool surface**; do not call them. **`get_campaign_breakdown_report` was not retired.** It still ships, and it is the *only* report that serves **GROUP and admin-network accounts**, which the dynamic report cannot (403). Campaign *change history* (an audit log, not performance data) keeps its own tool.

## Prerequisites

- `account_id` resolved via the `accounts` skill.
- The **dynamic report** works on **PARTNER** (advertiser) and **NETWORK** accounts. On a **GROUP or admin-network** account both dynamic tools return **403 by design** — that is not an auth problem, so do not retry or re-authenticate. **Switch to `get_campaign_breakdown_report`**, which serves every account type. Never tell the user to "pick a different account" when their account type simply needs the other tool.

## Tools this skill wraps

| Tool | Role |
|---|---|
| `mcp__realize-mcp__get_dynamic_report_settings` | **Required first step.** Returns the metamodel: every dimension, metric, and filterable field with its allowed operators, as fully-qualified names. |
| `mcp__realize-mcp__get_dynamic_report_data` | Builds and executes the query — any combination of the metamodel's dimensions and metrics. |
| `mcp__realize-mcp__get_campaign_breakdown_report` | Classic campaign-grain performance report (one row per campaign). **Still live.** The required path for **GROUP / admin-network** accounts, and a valid shortcut when the question really is just "metrics per campaign". |
| `mcp__realize-mcp__get_campaign_history_report` | Campaign **change/audit log** — who changed what, when. NOT performance data; the dynamic report does not replace it and it does not answer performance questions. |

## Choosing the report tool

1. **`type` is `GROUP`?** → `get_campaign_breakdown_report`. The dynamic tools 403 on those. Route on `type` up front rather than discovering it from an error.
   - **Admin networks are the awkward case.** Upstream documents `PARTNER` and `NETWORK` as the reporting-capable types and says results *may also include* GROUP accounts and admin networks — without pinning down what `type` an admin network reports. So read `type` and trust it when it says `GROUP`, but don't assume `NETWORK` guarantees the dynamic report will work. If a dynamic call 403s on an account that looked fine, that is the admin-network case: switch to `get_campaign_breakdown_report` and carry on.
2. **Question is campaign-grain only** (spend/clicks/CTR per campaign, no further breakdown)? → either tool works. `get_campaign_breakdown_report` answers in one call and gives you a grand `Total`; the dynamic report needs the settings round-trip first.
3. **Anything else** — a dimension other than campaign, or two dimensions crossed (site, day/week, country, platform, OS, ad) → the **dynamic report**.

## The mandatory two-step workflow (dynamic report)

This applies to the dynamic report only — `get_campaign_breakdown_report` and `get_campaign_history_report` are single calls with no settings step

Preview of the first 4,000 characters. Read full instructions →

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

View saved version →

---
name: support
description: Package the current conversation into a single Markdown file the user can email to Taboola Support so Professional Services can debug what happened. Activates on /realize-plugin:support, and whenever the user wants to escalate to a human, report that the plugin gave a wrong or suspicious answer, or file a bug. Writes one local file after an explicit confirmation — never transmits anything.
allowed-tools: ["Read", "Edit(~/.realize-plugin/tmp/**)", "Bash(node \"${CLAUDE_PLUGIN_ROOT}/skills/support/scripts/build-bundle.js\" --preview)", "Bash(node \"${CLAUDE_PLUGIN_ROOT}/skills/support/scripts/build-bundle.js\" --write --complaint-file ~/.realize-plugin/tmp/complaint-*.txt)", "Bash(node \"${CLAUDE_PLUGIN_ROOT}/skills/support/scripts/build-bundle.js\" --write --title-file ~/.realize-plugin/tmp/title-*.txt)", "AskUserQuestion"]
---

# Support Bundle

Turns the current session into a support case file for Taboola Professional Services (PS).

Users run the plugin in their own terminal, so PS has no visibility into these conversations. When someone says "the plugin gave me the wrong number", PS currently has only that sentence. This skill hands them the actual transcript instead.

## When to use

- The user runs `/realize-plugin:support` — plugin components are namespaced, so a bare `/support` is not a valid invocation.
- The user says the plugin gave wrong, stale, or suspicious information and wants it looked at.
- The user asks to talk to a person, open a ticket, or escalate.
- The user hit an error they can't get past and wants help.

**Not** for answering product questions or diagnosing campaign performance — those belong to the normal skills. This skill only packages evidence.

## The one rule that matters

**The transcript is the deliverable.** Everything above it in the file is mechanically extracted from the transcript by the script — never written from your own recollection of the conversation.

This is deliberate. If the plugin misread the user, a summary written by the plugin carries that same misreading into the bug report. Only the raw exchange is independent of the bug. So: do not editorialize, do not explain away what happened, and do not "clean up" the user's complaint.

**Section 1 (Summary) is not an exception.** It exists because PS pastes it into the case Description, but every line in it is a count, a tool name, or a file path pulled from the log — never a narrative. It reports *which* Realize tools ran, *which* skills were invoked, and *which* knowledge files were read, so PS can tell "the plugin had the right guidance and still got it wrong" apart from "the plugin never read the guidance". Those are different bugs. Do not add a prose account of what went wrong to that section.

**You write nothing into this bundle.** The case subject is now the user's own complaint text, so there is no field left for your judgment.

## Workflow

### Step 1 — Preview (never skip)

```bash
node "${CLAUDE_PLUGIN_ROOT}/skills/support/scripts/build-bundle.js" --preview
```

Run it exactly in this form — path in double quotes, one line. The quotes keep a plugin path with a space in it (`C:/Users/John Smith/…`) in one piece. The pre-approval covers only this command and the Step 4 command, character for character; anything else, including extra flags, raises a permission prompt.

If the shell reports that `node` is not found, stop: the bundle needs Node.js 18 or later, which Claude Code's native and desktop installs don't include. Tell the user that plainly, and offer the fallback — they can email Support@taboola.com directly with a description of the problem and the account ID.

Writes nothing. Prints what would be captured: session ID, time window, turn counts, Realize actions attempted and how many failed, account/campaign IDs involved, local paths, and estimated file size.

### Step 2 — Show the user what's about to leave their machine

This file contains their real campaign data — budgets, spend, acc

Preview of the first 4,000 characters. Read full instructions →

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

View saved version →

---
name: web-fallback
description: Answer in-scope Realize questions the plugin's own knowledge base does not cover, by looking the topic up in Taboola's public advertiser help documentation. Activates only after a real miss — no knowledge file, no MCP tool, and no other skill answers the question as asked. Read-only. A fallback rather than a supplement — when the knowledge base has the answer, or when a web source contradicts it, the plugin's own guidance wins and no lookup happens.
allowed-tools: ["Read", "WebSearch", "WebFetch(domain:realize.com)", "WebFetch(domain:www.realize.com)"]
---

# Web Fallback

The knowledge base is finite; the questions aren't. There are 12 topic files, and an advertiser can ask hundreds of reasonable "how do I…" questions that fall just outside them. Before this skill existed, those questions got a thin answer from model priors or a shrug — neither of which is what the user came for, and the first is worse than the second.

This skill closes that gap with one narrow move: look the topic up in Taboola's public advertiser help documentation, and answer with a *"this is what I found online"* framing. It is the last tier of the sourcing ladder in `os/guardrails.md` → *Sourcing — prioritize the plugin's own sources*, and it never outranks anything above it.

## When to use

Trigger only when **all four** hold:

- The question is about advertising on Realize — a setup step, a platform feature, a policy, a how-to, a term the user hit in the UI.
- **No `knowledge/` topic file answers the question as asked.** Check `knowledge/manifest.json` first, every time.
- **No MCP tool answers it.** This isn't an account, campaign, item, catalog, or report question.
- **It isn't a refusal case.** Out-of-scope requests (forecasting, ROI projections, competitor comparisons, legal advice, creative copywriting, landing-page critique) and UI-only *actions* keep the answers they have today.

**Not** for adding polish to an answer the plugin can already give. That's the failure mode this skill is one bad judgment call away from: once web content starts topping up good answers, the plugin's own curated guidance stops being the thing users hear, and the freshness problem it exists to avoid arrives anyway.

## The miss test — per question, not per topic

The topic file existing is not coverage. What matters is whether it answers **the question that was asked**:

| Situation | Do |
|---|---|
| The knowledge base answers the question | Answer from it. **No lookup.** |
| The knowledge base covers the topic but is silent on the actual ask | **Miss — look it up.** |
| The knowledge base answers it; a lookup would only add detail | **Knowledge base wins. No lookup.** |
| Out of scope, or a UI-only action | Existing refusal / UI redirect, unchanged. **No lookup.** |

The worked example: `knowledge/tracking.md` explains pixel-vs-S2S selection, network-vs-account-level pixel, and validation. It says nothing about installing the pixel on a specific storefront platform. *"Which tracking method should I use?"* is covered. *"How do I install the pixel on Shopify?"* is a miss — same topic, different question.

**The how-vs-do split on UI-only domains.** A UI-only *action* ("install the pixel on my store for me", "upload this CRM audience") still gets the one-sentence acknowledgment plus the UI redirect — a lookup never unlocks work the plugin doesn't do. (Conversion-rule creation is **not** such an action — it's an MCP-backed gated write; don't cite it as a UI-only example.) But when the user asked *how* to do it themselves, the steps may come from a lookup, and the redirect to the Realize UI stays in the answer either way.

## Allowed source

- **Search `realize.com`.** Nothing else. There is no second domain, and Taboola's developer documentation is deliberately out of scope — it documents the same API the Realize MCP already wraps, and this plugin does not emit endpoint paths, payloads, or client code.
- **Read only `realize.com/help/

Preview of the first 4,000 characters. Read full instructions →