---
name: build-collection-ads-and-product-sets
description: >-
  Builds two things that pair together: product sets (filtered catalog subsets by category, price
  band, margin, or performance tier) used for targeting and segmentation, and Collection ads, a
  hero image or video plus a product grid that opens into an Instant Experience, Meta's fast
  mobile storefront format. Covers when Collection beats a single-image or carousel ad, how to
  validate a product set actually returns a sane, non-empty, non-total item count, and pairing a
  curated hero with dynamic Advantage+ catalog fill for the grid underneath. Builds the creative
  (mads_create_creative), ad set (mads_create_adset), and ad (mads_create_ad), always created
  PAUSED. Reach for it once the catalog is live and either a purpose-built segment or a
  storefront-style mobile browsing ad is the goal. It ends at live product sets and a Collection
  ad, it does not build the catalog itself (set-up-product-catalog) or standard catalog
  retargeting/prospecting ad sets (launch-advantage-plus-catalog-ads).
---
# Build Collection Ads and Product Sets

## Purpose
Product sets are the segmentation primitive that every catalog-commerce skill eventually needs, a filtered slice of the catalog by category, price, margin, or performance instead of
"everything." Collection is the flagship format built on top of them: a hero image or video
paired with a product grid that opens into an Instant Experience, giving mobile users a fast,
native-feeling storefront to browse without leaving the app. This skill builds both, together, and
pairs them with dynamic catalog fill where that beats a fully hand-picked grid.

## When to run
- A targeting or reporting need calls for a filtered slice of the catalog, best sellers, a price
  band, a margin tier, a single category, rather than the default "all products" set.
- The goal is a mobile-first storefront browsing ad rather than a single-image, carousel, or plain
  catalog ad.
- Pairing a curated hero moment (launch, seasonal push, best-sellers) with dynamic product fill
  underneath it.

## When NOT to run
- No catalog exists yet → `set-up-product-catalog`.
- The goal is standard retargeting/prospecting catalog ads without the grid/Instant Experience →
  `launch-advantage-plus-catalog-ads`.
- The product data underlying a set is wrong (prices, disapprovals, missing fields) →
  `maintain-catalog-feed-hygiene` first, or the set inherits the bad data.

## Prerequisites
- A live, populated catalog, `mads_list_catalogs`.
- A reasonably clean feed for the SKUs going into the set (`maintain-catalog-feed-hygiene` run
  recently is ideal, not mandatory).
- A hero asset (image or video) meeting Collection placement specs, HUMAN STEP, creative
  production/upload.
- Agreement on filter logic for the set(s) needed, category, price band, a margin tag (often
  sourced from `sheets_get_values` if finance tracks margin outside the catalog), or a performance
  tier from `mads_run_insights` / `mads_get_insights`.

## Procedure
1. **Define the filter logic with the user.** Category equals X, price between A and B, a margin
   or priority custom label, or a performance tier ranked by ROAS/units sold over a stated window.
2. **Build or update the product set.** Configure the rule in Commerce Manager (HUMAN STEP where
   rule-based sets aren't exposed through a `mads_*` call), or drive it through custom-label
   fields on `mads_upsert_catalog_products` when VigilDog owns the tagging. Preview the resulting
   item count and a sample of items with the user before relying on it.
3. **Validate the set size.** Confirm the count is sane, not zero, and not accidentally the whole
   catalog, which would make the set meaningless. Re-check via `mads_list_catalogs` / a sampled
   pull.
4. **Decide the ad format fit.** Collection vs. single-image/carousel/plain catalog ad, per
   Decision rules, don't default to Collection just because it's available.
5. **Assemble the Collection creative.** `mads_create_creative` with the hero image/video plus
   the product set wired in for grid fill, configured as an Instant Experience. Preview →
   plain-English diff → explicit user approval → commit.
6. **Build the ad set.** `mads_create_adset`, targeting broad or retargeting per the same patterns
   as `launch-advantage-plus-catalog-ads`, scoped to the product set from steps 2-3.
7. **Create the ad, always PAUSED.** `mads_create_ad` linking creative and ad set with
   status=PAUSED.
8. **HUMAN STEP: preview the Instant Experience end to end.** Mobile preview link, hero renders,
   grid populates from the correct set, tap-through into the storefront actually works.
9. **Get explicit go-live approval, then activate.** Only after user approval, flip status via
   `mads_update_adset`.
10. **Monitor and feed learnings back.** `mads_run_insights` / `mads_get_insights`
    for grid engagement and outbound clicks versus plain catalog-ad benchmarks; refine the set's
    filter logic (step 1) as performance data accrues.

## Decision rules
- **Collection beats single-image/carousel when:** the set has enough breadth to justify browsing
  (roughly 10+ relevant SKUs), mobile is the majority placement, and the goal is storefront-style
  discovery rather than pushing one hero product.
- **Single-image/carousel still wins when:** it's a one-product launch, placements skew
  non-mobile, or the catalog/set is too thin for a grid to feel populated.
- **Performance-tier sets need enough history to trust.** Thin spend/conversion data produces a
  noisy tier, use category or price sets instead until volume accrues.
- **Pairing rule:** Collection + full Advantage+ catalog fill for prospecting/retargeting breadth;
  Collection + a hand-picked curated set for merchandising moments (new arrivals, a sale).
- **Always create PAUSED,** no exceptions.
- **Done means:** the product set returns a validated, non-zero, non-total item count; the
  Collection creative is assembled and previewed end to end on mobile; ad set and ad exist PAUSED;
  go-live approval is logged before activation.

## Common failure modes
- **Filter too narrow.** The grid renders near-empty, or the ad set can't find enough eligible
  inventory to deliver.
- **Filter too broad, accidentally the whole catalog.** Defeats the purpose of building a set at
  all; indistinguishable from the default set.
- **Hero asset spec mismatch** (wrong aspect ratio, oversized file) gets the creative rejected or
  crops badly at placement.
- **Skipping the mobile Instant Experience preview** and shipping a broken tap-through live.
- **Performance-tier set built on too little data,** chasing noise instead of real winners.
- **Forgetting PAUSED at creation,** letting spend start before anyone reviewed the assembled ad.

## Related skills
- Run after: `set-up-product-catalog` (catalog base), `maintain-catalog-feed-hygiene` (clean
  inputs before building a set on top of them).
- Run alongside: `launch-advantage-plus-catalog-ads` (shares audience/targeting patterns; the
  non-Collection catalog-ad format).