Update to commercetools

{
  "description": "Exports a selected set of commercetools products (by product selection, category, product type, SKU, product key, store assortment or query predicate) for commercetools AI Hub across vendors (OpenAI Commerce feed, OpenAI Ads feed, Google Merchant Center and Microsoft Merchant Center, including supplemental feeds). Downloads once, then works offline. Maps product data to each vendor spec, checks every vendor's required fields, writes a working file per vendor for the business team to complete, and converts the completed file into the vendor upload format (.jsonl.gz, .tsv, .txt) with upload guidance, including OpenAI manual upload. Use when exporting products for ChatGPT shopping or AI Hub, checking feed readiness or missing required fields, building a supplemental feed, or converting an edited feed file for upload. Not for building or deploying the Connect feed connector itself (see commercetools-connect) and not for loading a catalog into commercetools (see commercetools-catalog-migration).",
  "included_files": [
    {
      "relative_path": "references/mapping-and-files.md",
      "size_in_bytes": 13020
    },
    {
      "relative_path": "references/selecting-products.md",
      "size_in_bytes": 12360
    },
    {
      "relative_path": "references/vendors.md",
      "size_in_bytes": 10490
    },
    {
      "relative_path": "scripts/aihub_feeds.py",
      "size_in_bytes": 167590
    },
    {
      "relative_path": "scripts/docs-search.mjs",
      "size_in_bytes": 26525
    }
  ],
  "name": "commercetools-aihub",
  "skill_md_contents": "---\nname: commercetools-aihub\ndescription: \"Exports a selected set of commercetools products (by product selection, category, product type, SKU, product key, store assortment or query predicate) for commercetools AI Hub across vendors (OpenAI Commerce feed, OpenAI Ads feed, Google Merchant Center and Microsoft Merchant Center, including supplemental feeds). Downloads once, then works offline. Maps product data to each vendor spec, checks every vendor's required fields, writes a working file per vendor for the business team to complete, and converts the completed file into the vendor upload format (.jsonl.gz, .tsv, .txt) with upload guidance, including OpenAI manual upload. Use when exporting products for ChatGPT shopping or AI Hub, checking feed readiness or missing required fields, building a supplemental feed, or converting an edited feed file for upload. Not for building or deploying the Connect feed connector itself (see commercetools-connect) and not for loading a catalog into commercetools (see commercetools-catalog-migration).\"\nwhen_to_use:\n  - \"Exporting a product selection, category, product type or SKU list from commercetools for the OpenAI Commerce feed, OpenAI Ads feed, Google or Microsoft\"\n  - \"Checking which products are missing fields the OpenAI, Google or Microsoft product feed specs require\"\n  - \"Building a Google Merchant Center or Microsoft Merchant Center supplemental feed from commercetools data\"\n  - \"Turning a feed file the business team completed in a spreadsheet into the vendor upload format\"\n  - \"Mapping commercetools attributes (brand, GTIN, color, size) and categories to feed fields\"\n  - \"Automating recurring feed delivery from a Connect application — see commercetools-connect\"\nmetadata:\n  contentType: SKILL\n  area:\n    - Integrations\n  docsSearch:\n    products:\n      - AI Hub\n      - Composable Commerce\n---\n\n# commercetools AI Hub product feeds\n\nAI Hub feeds go to several vendors: OpenAI Commerce feed (ChatGPT shopping), OpenAI Ads feed,\nGoogle Merchant Center and Microsoft Merchant Center. \"AI Hub\" names the whole export, not one vendor.\n\nExports what commercetools has for a product selection, per vendor, as a **semi-finished\nworking file**: every row, every vendor field, blanks where commercetools has no value, and a\nnote per row listing the required fields it is missing. The business team completes the file\noffline; the completed file comes back and is converted, unchanged, into the vendor upload\nformat. The merchant decides what and when to upload; the skill supplies facts and guidance.\n\n```\naihub_feeds.py fetch     commercetools          ─► <run>/raw/                 products, categories, Store, manifest\naihub_feeds.py build     raw + mapping + specs  ─► <run>/working/<vendor>-working.csv, report/, NEXT-STEPS.md\n   (business team completes the working files offline)\naihub_feeds.py finalize  completed file         ─► <out>/<vendor upload file> + finalize report\n```\n\n`scripts/aihub_feeds.py` (Python 3.9+, standard library only) is the whole toolchain; run\n`aihub_feeds.py <command> --help` for options. The network is used for the download and to\nread the vendors' current specs; the specs are cached per run, so rebuilding and finalizing\nwork offline.\n\nRun it with `python3 scripts/aihub_feeds.py` (`py -3` on Windows, where `python3` is often\nmissing or a Microsoft Store stub). When no Python 3.9+ is found, tell the user to install it\nfrom python.org and stop; do not rewrite the script in another language.\n\nVendor specs are **not hardcoded**: `build` and `finalize` read each vendor's published spec\nat runtime (fields, required/conditional/optional, allowed values, length limits, Microsoft's\nsupplemental fields) and merge it with the code that maps commercetools data to fields. New\nspec fields become empty columns, removed ones are dropped, and the report lists both. See\n[references/vendors.md](references/vendors.md#specs-are-read-at-runtime).\n\n## Data integrity: commercetools is the only source of product data\n\nFeeds are checked against the storefront, and a guessed value hides a real gap. So:\n\n- Do not write, rewrite, shorten, translate, summarise or infer product content: titles,\n  descriptions, brands, GTINs, MPNs, categories, colors, sizes, conditions, availability,\n  prices or images. Not in `mapping.json`, not in the working files, not in the completed file.\n- `mapping.json` changes only *where* a value is read from (attribute names, category and\n  Store fields, id strategy) and *how* an existing value is spelled for a vendor\n  (`valueMaps`, units, separators). It holds no values of its own.\n- Feed eligibility flags are merchant settings, not product data, and the only defaults:\n  discovery on (`is_eligible_search=true`), checkout off (`is_eligible_checkout=false`) and,\n  for the OpenAI Ads feed only, `is_ads_eligible=true`. A product attribute overrides them;\n  change a default only when the user asks. Google and Microsoft have no checkout flag; their\n  products are listed for discovery by default.\n- Storefront URL, seller name and policy URLs (privacy, terms, refund) come from the Store\n  passed with `--store`, the Store whose product selections define the assortment.\n- Values the business team adds in the working file are theirs. Convert the completed file\n  as it is: `finalize` changes the format, never the content. If a value looks wrong,\n  report it; do not correct it.\n\n## Before you start\n\n1. <!-- ct:docs-search:begin -->\n   **Docs search (required, run first)** — The first time you use this skill in a session you must run this before answering. It gathers the latest verified documentation as your primary grounding, filtered to the products this skill covers. Use this script for documentation search while working with this skill; the Knowledge MCP covers everything else. Always confirm details against retrieved documentation rather than the skill text alone:\n\n   ```bash\n   node \"<this skill's directory>/scripts/docs-search.mjs\" \\\n     --query \"<extract key terms: AI Hub, product feed, Product Projections, price selection, Product Selections>\" \\\n     --app-name \"<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>\" \\\n     --model \"<current-model>\" \\\n     --commercetools-project-key \"<if known>\" \\\n     --commercetools-region \"<if known>\" \\\n     --limit 10\n   ```\n\n   Pass the commercetools project key and region (as in `api.{region}.commercetools.com`) only if already in your context; otherwise omit both. Never search files or ask the user for them.\n   <!-- ct:docs-search:end -->\n\n2. **Vendor specs change often**, which is why they are read at runtime. When the user asks\n   whether a spec changed, or a vendor flags a field the report marked valid, rebuild the run\n   with `--specs live` and report its *Changes since the previous spec* section. If a spec\n   page could not be read, the report says which fallback was used and links the page.\n\n## Workflow\n\n1. **Agree the selection and market.** Collect, asking only for what is missing:\n   - credentials: a dotenv file with the `CTP_*` variables. Pass it with `--env-file` and\n     never print or copy secret values;\n   - Store, currency, country, distribution channel, locale. `aihub_feeds.py fetch --list-stores`\n     prints the project's currencies, countries, languages and channels and every Store with\n     its languages, countries, channel keys, product selections and storefront fields;\n   - filters: any combination of product selections, categories, product types, SKUs,\n     product keys, attribute conditions (`--attribute color=blue`), query predicates\n     (`--where`) and search filters (`--search-filter`, e.g. inventory or price ranges).\n     `--list-categories` and `--list-attribute` map the user's wording to keys. When wording\n     could mean different data (stock as inventory or as an attribute), show both counts and\n     ask;\n   - vendors: the user names them; if the request does not say, ask, for example \"Which\n     vendors should I build feeds for: OpenAI Commerce feed, OpenAI Ads feed, Google\n     Merchant Center, Microsoft Merchant Center?\" Never assume all of them, and do not label\n     one vendor \"AI Hub\". `build` requires `--vendors` (`openai`, `openai-ads`, `google`,\n     `microsoft`);\n\n   Flags, scopes and filter recipes: [references/selecting-products.md](references/selecting-products.md).\n\n2. **Resolve, then download.** Run `aihub_feeds.py fetch --dry-run` first. It writes nothing, shows\n   what each name resolved to, counts matching products, samples whether they are in the\n   Store assortment, and checks the feed locale against the data. Show the user the plan and\n   any warnings, then run the download once they confirm. A name that matches several\n   categories stops with the candidates: ask which one is meant (a dry run over the union\n   shows whether the choice changes the result). Ignoring the Store assortment changes the\n   scope, so ask before using `--ignore-assortment`.\n\n3. **Build the working files.** `aihub_feeds.py build --run <run> --vendors <named vendors>` writes\n   one working file per requested vendor, `report/gap-report.md` (required fields per vendor first), `report/issues.csv`\n   and `NEXT-STEPS.md`. The first build writes `<run>/mapping.json`.\n\n4. **Review the gaps with the user.** For each vendor, report which required fields are\n   filled and which are missing, with example SKUs, and the `⚠?` fields whose spec condition\n   may apply (e.g. required for apparel) for the user to judge. Sort gaps into:\n   - **mapping gaps**, where the value exists in commercetools under another name or\n     spelling: point `attributes.*` (or `store.*`, `categoryFields`) at it, or add a\n     `valueMaps` entry. Confirm with the user, rebuild offline, show before/after counts.\n     See [references/mapping-and-files.md](references/mapping-and-files.md);\n   - **values commercetools does not have**: they stay blank in the working file, marked in\n     `_missing_required`. The team fills them in the file or in commercetools.\n\n5. **Hand over the working files.** Point to `working/` and `NEXT-STEPS.md`: how to edit the\n   files safely (import as text so GTINs and SKUs keep their form, keep the header row) and\n   what each helper column means.\n\n6. **Finalize a completed file.** When the user hands a completed file back, run\n   `aihub_feeds.py finalize --vendor <v> --input <file> --out <dir>` (Google and Microsoft:\n   `--kind supplemental|primary`, optional `--columns`). When the user wants an upload file\n   straight away, finalize the generated working file as it is. Report the finalize report as facts:\n   rows, required fields still missing or invalid, empty cells in supplemental columns,\n   columns a vendor does not accept. Then give the vendor's upload guidance from its reference.\n   Do not decide for the user whether to upload.\n\n## Facts to surface (information, not decisions)\n\n| Topic | Fact | Where |\n| :--- | :--- | :--- |\n| OpenAI Ads feed | A separate feed in the ad account (its own SFTP), not the merchant portal feed. Products need `is_ads_eligible=true`; `ads_metadata` keys come from the Ads setup and are never invented. | [vendors.md](references/vendors.md#openai-ads-feed) |\n| OpenAI uploads | Each upload is treated as the complete catalog; products missing from a later upload drop out after up to 14 days. | [vendors.md](references/vendors.md#full-snapshot-semantics) |\n| Supplemental ids | Supplemental rows apply only to products whose `id` matches the primary feed. A SKU-vs-key mismatch updates nothing and reports no error. | [mapping-and-files.md](references/mapping-and-files.md#item-and-group-ids) |\n| Supplemental cells | Every column overrides the primary value, and an empty cell can clear it. `--columns` limits the file to chosen attributes. | [vendors.md](references/vendors.md#choosing-columns) |\n| Microsoft supplemental | Accepts only the fields Microsoft lists for supplemental feeds (read at runtime; `id`, `title`, `description`, `size`, `color`, `custom_label_0–4`, `promotion_ID` when captured); other fields belong in the primary feed. | [vendors.md](references/vendors.md#supplemental-feed-limits) |\n| Market | Prices come from price selection (currency, country, channel); availability from inventory, blank without inventory entries. | [selecting-products.md](references/selecting-products.md#market-context) |\n\n## Reference index\n\n| Topic | Reference |\n| :--- | :--- |\n| Credentials, scopes, `--list-stores`, filters, store assortment, market context, dry run | [references/selecting-products.md](references/selecting-products.md) |\n| `mapping.json`, working files, finalize, reading the gap report | [references/mapping-and-files.md](references/mapping-and-files.md) |\n| Runtime vendor specs, per-vendor facts, file formats, upload steps (OpenAI manual upload, OpenAI Ads feed, Google and Microsoft supplemental feeds) | [references/vendors.md](references/vendors.md) |\n\n## Scope\n\nIn scope: read-only export of published (or `--staged`) product data, variant-level rows,\nprice selection, inventory-based availability, Store and seller data, required-field checks\nper vendor, working files for offline completion, conversion of completed files into vendor\nupload formats, upload guidance.\n\nOut of scope: uploading files, deciding whether to upload, recurring delivery (a Connect job,\nsee `commercetools-connect`), shipping and tax settings (configured per account in each\nmerchant center), and changing product data in commercetools.\n\n## Checklist\n\n- [ ] The vendors were named by the user (asked when missing, listing OpenAI Commerce feed,\n      OpenAI Ads feed, Google and Microsoft), and only those were built.\n- [ ] Flags stayed at their defaults (discovery on, checkout off, ads on only for the OpenAI Ads feed)\n      unless the user asked otherwise.\n- [ ] The selection, Store, currency, country and locale were confirmed with the user, and\n      the dry run resolved every product selection, category and product type.\n- [ ] The download used an API client with `view_products` and `view_categories` (plus\n      `view_product_selections` / `view_stores` when used), and no secret was printed.\n- [ ] Per vendor, the user knows which required fields are filled and which are missing,\n      with example SKUs. Mapping gaps were fixed in `mapping.json` with the user's agreement.\n- [ ] No product content was written or inferred; `mapping.json` only points at attributes\n      and fields; the completed file was converted without changing its values.\n- [ ] The report says which spec was used per vendor (live with fetch time, or the built-in\n      list when the fetch failed); new or removed spec fields were mentioned.\n- [ ] The user has the working files, `NEXT-STEPS.md`, the finalize report when a completed\n      file was converted, and the upload guidance for each vendor.\n"
}