Update to JoomPulse

{
  "description": "Analyzes one Mercado Livre product and its competitors. Use this skill when a user wants to size up a single product or the products that compete with it — by a Mercado Livre link, a JoomPulse link, a photo, or a row of data. It returns a product card for the subject plus a ranked table of comparable products, each with price, estimated monthly sales and revenue, logistics, and catalog / buy-box status. Triggers include: \"analyze this product\", \"how much does this sell\", \"find similar products\", \"find competing products\", and the pt-BR equivalents \"analisar este produto\", \"quanto vende esse produto\", \"produtos parecidos\", \"produtos concorrentes\", \"análise por foto\", \"análise por link\". For \"what new products should I add to my store\" across a whole catalog, use the assortment gap-analysis skill instead — this skill analyzes a single product the seller already has in hand.",
  "included_files": [],
  "name": "ml-product-analysis",
  "skill_md_contents": "---\nname: ml-product-analysis\ndescription: >\n  Analyzes one Mercado Livre product and its competitors. Use this skill when a\n  user wants to size up a single product or the products that compete with it —\n  by a Mercado Livre link, a JoomPulse link, a photo, or a row of data. It\n  returns a product card for the subject plus a ranked table of comparable\n  products, each with price, estimated monthly sales and revenue, logistics, and\n  catalog / buy-box status. Triggers include: \"analyze this product\", \"how much\n  does this sell\", \"find similar products\", \"find competing products\", and the\n  pt-BR equivalents \"analisar este produto\", \"quanto vende esse produto\",\n  \"produtos parecidos\", \"produtos concorrentes\", \"análise por foto\", \"análise por\n  link\". For \"what new products should I add to my store\" across a whole catalog,\n  use the assortment gap-analysis skill instead — this skill analyzes a single\n  product the seller already has in hand.\n---\n\n# Mercado Livre Single-Product Analysis\n\nThis skill analyzes **one** Mercado Livre (Brasil) product and the products that\ncompete with it. Given a single product — by a Mercado Livre link, a JoomPulse\nlink, a photo, or a row of data — it identifies the product, finds comparable\nlistings, and returns a product card for the subject plus a ranked table of\nanalogs. For each product it shows price, estimated monthly sales and revenue,\nlogistics, and catalog / buy-box status.\n\nThis is different from whole-catalog assortment analysis. If the user wants to\nknow which new products to add to their store, hand off to the gap-analysis\nskill. This skill works on a single product the seller already has in hand.\n\n## Prerequisites\n\n- JoomPulse MCP access is configured for the current agent environment.\n- The user provides one product as a Mercado Livre link, a JoomPulse link, a\n  product photo, or a row of data (a `.csv` / `.xlsx` file, a pasted table, or\n  typed fields).\n- The available JoomPulse tools can look up product market data and search for\n  comparable listings.\n\nIf JoomPulse MCP access is unavailable, stop and explain that the skill requires\nJoomPulse MCP setup before it can analyze a product or find competitors.\n\n## Scope\n\n- **Mercado Livre (Brasil) only.** Other marketplaces are out of scope.\n- **Sales and revenue are JoomPulse estimates** derived from historical listing\n  data — not real transactions. Disclose this in every output.\n- **Prices are Mercado Livre prices only.** Do not surface sourcing prices,\n  margins, or profit figures.\n- **Read-only.** The skill does not sign in as the seller or modify any listing.\n- **Language:** detect the seller's language and respond in it. Default to\n  pt-BR.\n- **Keep the workflow invisible.** The seller wants the answer, not a play-by-\n  play. Do the analysis quietly and present only the result. If one approach to\n  finding the product or its competitors does not work, switch to another\n  silently; only if every approach fails do you say one short, friendly sentence.\n\n## Input Router\n\nResolve the input to a single normalized subject product, then find analogs. The\nfirst matching rule wins:\n\n1. **A photo** → Photo route.\n2. **A `.csv` / `.xlsx` file, a pasted table, or typed fields** → Tabular route.\n3. **A Mercado Livre link** → MLB route.\n4. **A JoomPulse product link** → JoomPulse route.\n5. **A JoomPulse store link** → this is a whole store, not one product. Ask for a\n   specific product link or a product title; whole-store analysis belongs to the\n   gap-analysis skill.\n6. **Any other link** (a different marketplace, a generic web page) → do not\n   scrape it. Explain that only Mercado Livre and JoomPulse links can be resolved\n   directly, and ask the seller to paste the product name or upload a photo →\n   Keyword route.\n7. **Plain text** (a product name or keywords) → Keyword route.\n\nEvery route converges on one normalized subject product plus a set of candidate\nanalogs.\n\n### MLB route\n\n1. Extract the product identifier from the link, noting whether it is a catalog\n   product or an individual listing.\n2. Look up the canonical title, category, and attributes for that identifier\n   when available. If the lookup is unavailable for that listing, continue with\n   the JoomPulse market data instead.\n3. Fetch JoomPulse market data for the subject. For a catalog product, several\n   competing listings may come back; pick the representative one (the strongest\n   seller / buy-box winner) for the card and read competition from the number of\n   buy-box sellers and total sellers.\n4. Build the subject from that data, then find analogs.\n\n### JoomPulse route\n\nLook up the product directly in JoomPulse by its identifier, optionally enriching\nthe title and attributes from the canonical product lookup, then find analogs.\n\n### Photo route\n\nImage-based matching is primary; visual inspection is the fallback. Accept common\nimage formats, including phone formats such as HEIC/HEIF. Always tell the seller\nthe results are **visually similar — not a guaranteed exact match.**\n\n1. Use the available JoomPulse image-based product search to find similar\n   listings from the photo. Alongside the matches, this search can return a quick\n   opportunity summary — an overall verdict on whether the product is worth\n   selling, the number of matching listings, and aggregate market stats. For a\n   fast answer you can present that summary directly (still labeled as a visual\n   match); otherwise carry the matched listings into the analog pipeline below.\n2. If image search is unavailable or returns nothing, inspect the photo yourself:\n   note the product type, brand and model if legible, color, material, and key\n   attributes. Turn that into search keywords and run the Keyword route. Label\n   the subject card as the best visual match, not an exact match.\n\n### Tabular route\n\nNormalize the rows into product records (handle pt-BR column headers and\n`R$ 1.234,56`-style prices). For each row: if it carries a Mercado Livre\nidentifier, use the MLB route; otherwise its title drives the Keyword route. One\nrow yields one subject. For several rows, analyze each — cap at a small number\nand say so when you do.\n\n### Keyword route\n\nBuild a clean search query from the title or photo description, plus a broadened\nfallback query.\n\n## Finding Analogs\n\nBoth the keyword and photo paths feed the same analog pipeline:\n\n1. **Search for candidates.** Use JoomPulse semantic product search to find\n   listings similar to the subject, keeping the closest matches. Query in pt-BR\n   first and English second. If recall is too low, retry once with the broadened\n   query. For the photo route, the image-search results play this role.\n2. **Augment when recall is thin.** Optionally widen the candidate set using\n   category and keyword search, or constrain to the subject's predicted category.\n3. **Merge and drop the subject.** Deduplicate the candidate identifiers and\n   remove the subject itself.\n4. **Validate and fetch market data.** Look up the candidates in JoomPulse to\n   confirm they are active listings and to fetch price, sales, revenue,\n   logistics, and catalog / buy-box fields.\n5. **Rank.** Score each candidate by a blend of similarity to the subject,\n   demand (estimated revenue), and how crowded the listing is, then sort by that\n   score. Drop candidates with no sales. Present a single ranked list — do not\n   split analogs into thematic sub-tables.\n\n## Output\n\nRespond in the seller's language. The visible reply contains only the result, in\nthis order, with no commentary about how it was produced:\n\n1. An optional one-line framing sentence.\n2. The subject product card.\n3. The ranked analogs table.\n4. The disclaimer.\n5. The download offer.\n\nUse plain markdown so it renders cleanly in any client.\n\n**Subject card** — product name and image, category and brand, current price and\nhistoric minimum price, estimated monthly sales and revenue, logistics (Mercado\nEnvios Full / free shipping / international), catalog / buy-box status (whether it\nis in the catalog, the number of buy-box sellers and the buy-box price, and the\ntotal number of sellers), and links to the product on Mercado Livre and on\nJoomPulse. On the photo route, label the card as the best visual match, not an\nexact match.\n\n**Analogs table** — one row per comparable product, with the product name, brand,\nprice (current and historic minimum), estimated monthly sales and revenue,\nlogistics, catalog / buy-box status, number of sellers, review rating, and a\nlinks column holding the Mercado Livre and JoomPulse links. Keep both links for\nevery product. You may translate the column headers and card labels into the\nseller's language.\n\n**Disclaimer (every report):**\n\n> ⚠️ Sales and revenue are JoomPulse **estimates** based on historical listing\n> data — they are **not** actual transactions. / Vendas e receita são\n> **estimativas** do JoomPulse com base no histórico de anúncios — **não são\n> transações reais**.\n\n**Download** — offer a downloadable spreadsheet (`.xlsx` plus `.csv`) of the\nsubject and analogs, with separate Mercado Livre and JoomPulse link columns so\nthe seller can see the source of every product's data.\n\n## Notes & Guardrails\n\nThe seller should never see a system or stack error — only a friendly next step.\n\n- **Subject not tracked in JoomPulse / no sales:** JoomPulse tracks products that\n  have sales, so a product may not be tracked. Say so, show whatever canonical\n  product facts are available, and still surface analogs by category or keywords.\n- **Valid product, no market data:** show the canonical product facts and note\n  that there is no JoomPulse estimate; draw analogs from the predicted category.\n- **Photo:** image search first; if it is unavailable or empty, switch silently\n  to visual inspection plus keywords. Always label results as similar, not exact;\n  if the match is ambiguous, show the top candidates and ask the seller to\n  confirm.\n- **Search returns nothing:** an empty result for a niche or non-pt-BR query is\n  normal — retry once with an English or broadened query, then move on. If search\n  is temporarily unavailable, say so briefly and rely on the other data.\n- **Market data temporarily unavailable:** retry once quietly; if it is still\n  down, say market data is temporarily unavailable. Never paste internal error\n  text, HTTP codes, or field names to the seller.\n- **Never silently limit coverage** — if you analyze only some rows or some\n  candidates, say so.\n- **Prefer precision over recall.** A shorter list of confident analogs is better\n  than a long list of weak ones.\n"
}