From d617b0883cf6c36d0a5b0029fbfe6ab8fd6fc4e2 Mon Sep 17 00:00:00 2001 From: Elizaveta Orekhova Date: Wed, 19 Aug 2026 15:26:27 -0300 Subject: [PATCH] Make the focused skills marketplace-aware: add Shopee Brasil MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit JoomPulse now serves Shopee Brasil alongside Mercado Livre (Brasil). Until now every focused skill scoped itself to Mercado Livre, so a Shopee question either went unanswered or came back with the wrong marketplace's numbers. Thirteen skills now decide the marketplace first and then read that marketplace's own data. Each gained the same two blocks — a marketplace-decision step and a statement of how Shopee data differs — plus a Shopee output contract: 30-day sales windows instead of weekly, shop tiers (Official store / Preferred (Indicado) / Common) instead of medals, Shopee item links, and an em dash where Shopee has no equivalent (free shipping, fulfilment programme, listing tier). Four stay Mercado Livre only because the Shopee data does not exist, and now say so and offer the nearest alternative instead of answering wrongly: top-keywords-in-my-category (no search-demand data), my-product-vs-catalog (no catalogue or buy-box), top-brand-position-tracker (brand coverage too incomplete to rank) and top-sellers-in-category (no per-seller revenue within a category). Two traps found while verifying against live Shopee data and encoded in the skills: an unreviewed item reports a rating of zero rather than a blank, so the low-rating search now requires at least one review; and price and review history are recorded only when a value changes, so "a week ago" carries the last record forward and an absent record means no change, not missing data. Also updates the seller-copilot marketplace reference, which claimed every focused skill was Mercado Livre only, and the README skills section. Co-Authored-By: Claude Opus 4.8 --- README.md | 12 + skills/category-monitor/SKILL.md | 343 +++++++++++----- skills/category-opportunity-index/SKILL.md | 280 +++++++++---- .../SKILL.md | 217 +++++++--- skills/growing-leaf-category-tracker/SKILL.md | 189 +++++++-- .../high-demand-low-quality-finder/SKILL.md | 241 ++++++++--- skills/ml-product-analysis/SKILL.md | 353 +++++++++++----- skills/my-product-vs-catalog/SKILL.md | 14 +- .../new-growing-products-in-category/SKILL.md | 224 ++++++++--- .../popular-international-products/SKILL.md | 213 ++++++++-- skills/product-change-monitor/SKILL.md | 257 +++++++++--- skills/pulse-find-exact-same-product/SKILL.md | 243 ++++++++--- .../references/which-marketplace.md | 25 +- skills/seller-overview-tracker/SKILL.md | 275 ++++++++++--- skills/top-brand-position-tracker/SKILL.md | 13 +- skills/top-keywords-in-my-category/SKILL.md | 15 +- .../unbranded-products-in-category/SKILL.md | 202 ++++++++-- skills/uncontested-niche-finder/SKILL.md | 377 ++++++++++++------ 18 files changed, 2627 insertions(+), 866 deletions(-) diff --git a/README.md b/README.md index a211a7c..3656753 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,18 @@ Click **Add → Connect**, sign in with your JoomPulse account — you're ready ## Skills +JoomPulse covers two marketplaces — **Mercado Livre (Brasil)** and **Shopee Brasil** — and they +are separate datasets. Each skill decides the marketplace first, from what you say or from the +link or identifier you paste, and asks if it cannot tell. Data from the two is never mixed in one +table or one total. + +**Most skills below cover both marketplaces. Four are Mercado Livre only, because the Shopee data +does not exist:** `top-keywords-in-my-category` (Shopee has no search-demand data), +`my-product-vs-catalog` (Shopee has no catalogue or buy-box), `top-brand-position-tracker` +(Shopee brand coverage is too incomplete to rank) and `top-sellers-in-category` (no per-seller +revenue within a Shopee category yet). Those four say so and offer the nearest alternative rather +than answering with the wrong marketplace's numbers. + | Skill | What it does | Typical requests | Typical requests (pt-BR) | | --- | --- | --- | --- | | [`pulse-find-exact-same-product`](skills/pulse-find-exact-same-product/SKILL.md) | Finds product listings that appear to represent the same real-world product as a reference item. | "find the same product", "match this product", "find duplicate listings" | "encontrar o mesmo produto", "achar produto igual", "encontrar anúncios duplicados" | diff --git a/skills/category-monitor/SKILL.md b/skills/category-monitor/SKILL.md index 482d957..b5588e5 100644 --- a/skills/category-monitor/SKILL.md +++ b/skills/category-monitor/SKILL.md @@ -1,147 +1,290 @@ --- name: category-monitor description: > - Monitors one Mercado Livre (Brasil) category's aggregate health via JoomPulse — estimated - sales, number of products and catalog products, active sellers, the seller-medal - distribution, and the monopolization level. Each run builds today's snapshot table and - offers it for download; to see what changed, the user sends a table from a previous period - and the skill shows the metric-by-metric difference. The baseline is whatever table the user - supplies — no hidden session memory. Triggers: "monitor this category", "what changed in - this category", "track category sales and sellers", and the pt-BR "monitorar esta - categoria", "o que mudou na categoria", "comparar a categoria com o período anterior". Sales - and revenue are JoomPulse estimates, not real transactions. To track one named product over - time use the product-change-monitor skill; for a one-shot market-size or opportunity - snapshot use the category-opportunity-index skill. + Monitors one category's aggregate health on JoomPulse — Mercado Livre + (Brasil) or Shopee Brasil: estimated sales, product count, seller count, + the seller-tier mix and market concentration. Each run builds today's + snapshot table and offers it for download; send a table from a previous + period and the skill shows the metric-by-metric difference. The baseline is + whatever table the user supplies — no hidden session memory. Triggers: + "monitor this category", "what changed in this category", "track category + sales and sellers", "monitor a Shopee category"; pt-BR "monitorar esta + categoria", "o que mudou na categoria", "comparar a categoria com o período + anterior", "monitorar categoria na Shopee", "o que mudou na categoria da + Shopee". Ask which marketplace when unclear; never mix the two. Sales and + revenue are JoomPulse estimates, not real transactions. To track one named + product over time use the product-change-monitor skill; for a one-shot + opportunity snapshot use the category-opportunity-index skill. --- # Category Monitor -This skill tracks **one Mercado Livre (Brasil) category's aggregate health over time** — its estimated -sales, number of products and catalog products, number of active sellers, the distribution of sellers -across medal tiers, and how concentrated the market is (monopolization). - -Each run builds **today's snapshot table** for the category and offers it as a **downloadable table**. -To see what changed, the user **supplies the table from a previous period** (the one this skill -produced before); the skill compares the two and shows the difference per metric. **The baseline is -whatever table the user provides — there is no hidden session memory and nothing is stored -server-side.** The default view is the whole category; the user may instead point it at a single -listing or a catalog product (a catalog product rolls up its competing listings). - -To track one named product over time, use the product-change-monitor skill. For a one-shot -opportunity / market-size snapshot, use the category-opportunity-index skill. +This skill tracks **one category's aggregate health over time** on **Mercado +Livre (Brasil) or Shopee Brasil** — its estimated sales, how many products and +sellers it holds, how those sellers split across tiers, and how concentrated +the market is. + +Each run builds **today's snapshot table** for the category and offers it as a +**downloadable table**. To see what changed, the user **supplies the table from +a previous period** (the one this skill produced before); the skill compares the +two and shows the difference per metric. **The baseline is whatever table the +user provides — there is no hidden session memory and nothing is stored +server-side.** The default view is the whole category; on Mercado Livre the user +may instead point it at a single listing or a catalog product (a catalog product +rolls up its competing listings). **Shopee has no catalogue at all**, so that +input mode does not exist there. + +To track one named product over time, use the product-change-monitor skill. For +a one-shot opportunity / market-size snapshot, use the +category-opportunity-index skill. ## Prerequisites - JoomPulse MCP access is configured for the current agent environment. -- The user names a category (or, optionally, a single listing or catalog product). -- For a period comparison, the user supplies a previous table that this skill produced for the same - category (pasted or uploaded). Without it, the skill produces a standalone snapshot. -- The available JoomPulse tools can return a category's aggregate metrics and its seller-medal - distribution. - -If JoomPulse MCP access is unavailable, stop and explain that the skill requires JoomPulse MCP setup -before it can monitor a category. +- The user provides a marketplace — Mercado Livre (Brasil) or Shopee Brasil — + and names a category (on Mercado Livre, optionally a single listing or a + catalog product instead). +- For a period comparison, the user supplies a previous table that this skill + produced for the **same category on the same marketplace** (pasted or + uploaded). Without it, the skill produces a standalone snapshot. +- The available JoomPulse tools can resolve a category name to its identifier + and return that category's monthly aggregate metrics and its seller-tier + breakdown on **either** marketplace. + +If JoomPulse MCP access is unavailable, stop and explain that the skill requires +JoomPulse MCP setup before it can monitor a category. ## Scope -- **Mercado Livre (Brasil) only.** Other marketplaces are out of scope. -- **Sales and revenue are JoomPulse estimates** derived from historical listing data — not real - transactions. Disclose this in every output. -- **Read-only.** The skill never writes or modifies anything; it does not store the snapshot — the - user keeps the downloadable table and brings it back next period. -- **Language:** detect the seller's language and respond in it. Default to pt-BR. -- **The baseline is user-supplied.** Never claim a change without a previous table to compare against, - and never infer or fabricate one from memory. +- **Mercado Livre (Brasil) and Shopee Brasil**, one at a time. Other + marketplaces are out of scope. +- **Sales and revenue are JoomPulse estimates** — not real transactions. + Disclose this in every output. The estimates are built differently on each + marketplace: on Mercado Livre from historical listing data, on Shopee from the + marketplace's own rounded sold counters refined with review movement. Use the + matching disclaimer. +- **Read-only.** The skill never writes or modifies anything; it does not store + the snapshot — the user keeps the downloadable table and brings it back next + period. +- **Language:** detect the seller's language and respond in it. Default to + pt-BR. +- **The baseline is user-supplied.** Never claim a change without a previous + table to compare against, and never infer or fabricate one from memory. + +**Shopee data — what differs from Mercado Livre** + +- **Estimates come from Shopee's own rounded sold counters**, refined with review + movement. Treat small gaps between items as noise and never rank on a difference + of a few units. Price, rating and review count are real. +- **Coverage is not a census**: only items with at least one lifetime sale are + tracked, so any count is a lower bound and an absent item is not evidence it does + not sell. +- **History starts May 2026** — there is no long-run trend and no seasonal read. +- **Category analytics stop at three levels**; the item view reaches deeper. Say + which you used. +- **No seller medals** — Shopee has three mutually exclusive shop tiers: **Official + store**, **Preferred (Indicado)** and **Common**. There is no ladder; inventing + Shopee medals is fabrication. +- **No catalogue and no buy-box**, and an item belongs to one shop. +- **No fulfilment programme, no free-shipping flag and no listing tier** — show `—` + rather than guessing. +- **Concentration is measured differently** and thresholds do not transfer between + marketplaces. +- Item titles mix Portuguese, English and Chinese — search both languages. ## Workflow +### Step 0 — Decide the marketplace + +JoomPulse covers **two separate marketplaces**: Mercado Livre (Brasil) and Shopee +Brasil. They are independent datasets with different coverage, history and +mechanics. Decide which one the request belongs to **before reading any data**: + +- **The seller said so.** "Shopee" means Shopee; "Mercado Livre", "MeLi" or "ML" + means Mercado Livre. +- **An identifier gives it away.** An identifier beginning `MLB` is Mercado Livre; + a bare 10–11 digit number is a Shopee item or shop. A `mercadolivre.com.br` link + is Mercado Livre, a `shopee.com.br` link is Shopee. If an identifier is not found + on the marketplace you assumed, check the other one before telling the seller it + does not exist. +- **The request only makes sense on one of them** — buy-box, catalogue position, + seller medals, a fulfilment programme or search keywords are Mercado Livre only. +- **Otherwise ask** — one short question, mentioning that both are available. + **Never guess and never default.** + +**Never mix data from the two marketplaces in one query, one table or one total.** +They are separate pipelines with different grains and estimate methods; a combined +figure is simply wrong. If the seller wants both, run the analysis twice and report +the two side by side, comparing direction and orders of magnitude — never exact +numbers. + ### Step 1 — Resolve what to monitor -Ask for a category if none was given, then use JoomPulse to match the free text to a category -(disambiguate with the user when several plausible matches return). Optionally, the user can point the -skill at a single listing or a catalog product instead. +Ask for a category if none was given, then use JoomPulse to match the free text +to a category **on the chosen marketplace** (disambiguate with the user when +several plausible matches return, listing the candidates with their level). On +Mercado Livre the user may instead point the skill at a single listing or a +catalog product. On Shopee, **category analytics stop at three levels and there +is no catalogue** — if the seller names a deeper niche, answer at its level-3 +ancestor and say out loud which category the snapshot actually describes; a +catalog product is not an available input there. ### Step 2 — Collect today's aggregates -Use JoomPulse to collect, for the target: estimated sales, number of products, number of catalog -products, number of active sellers, the seller-medal distribution, and the monopolization level. +Use JoomPulse to collect, for the target: + +- **Mercado Livre:** estimated sales, number of products, number of catalog + products, number of active sellers, the seller-medal distribution, and the + monopolization level. +- **Shopee:** estimated sales, number of products, number of sellers, the split + across the three shop tiers (Official store / Preferred (Indicado) / Common), + and the concentration measure. **Omit the catalog-products metric entirely** — + Shopee has no catalogue, so drop that row rather than leaving it blank. There + are no medals and no ladder either: report the three-tier breakdown, never a + four-tier medal one. + +Two Shopee-specific cautions: + +- **The flag that marks a month as the latest is unreliable.** Resolve the most + recent available month explicitly instead of trusting it, and state in the + output which month the snapshot describes. +- **Concentration is a different measurement on the two marketplaces.** On + Mercado Livre it is the leading seller's share (monopolization); on Shopee it + is an index computed across all sellers. Label it with the term that belongs + to the marketplace you queried, and never compare the two marketplaces' + values. ### Step 3 — Present today's snapshot and offer it for download -Render the snapshot table for **today** (head it with the category name and the date). This table is -the deliverable — and **offer it as a downloadable file (`.csv` / `.xlsx`)** so the user can save it -and bring it back next period as the baseline. On a standalone snapshot there is **no change column -and no color-dot legend** — just metric and current value. +Render the snapshot table for **today**, headed with the marketplace, the +category name and the date — and, on Shopee, the month the aggregates cover. +This table is the deliverable — and **offer it as a downloadable file (`.csv` / +`.xlsx`)** so the user can save it and bring it back next period as the +baseline. On a standalone snapshot there is **no change column and no color-dot +legend** — just metric and current value. ### Step 4 — Offer comparison, and compare if a previous table is supplied -Invite the user to send a previous table for the same category to compare periods. **If they provide -one**, parse its metric values, align by metric to today's snapshot, and render a comparison table -with the difference per metric. A difference **requires both an old and a new value** for the same -metric — if a metric is missing or unreadable in the supplied table, show `—`, never a fabricated -trend. If no previous table is supplied, the snapshot stands on its own and the user is told to save -it for next time. +Invite the user to send a previous table for the same category **on the same +marketplace** to compare periods. **If they provide one**, parse its metric +values, align by metric to today's snapshot, and render a comparison table with +the difference per metric. A difference **requires both an old and a new value** +for the same metric — if a metric is missing or unreadable in the supplied +table, show `—`, never a fabricated trend. If no previous table is supplied, the +snapshot stands on its own and the user is told to save it for next time. + +On Shopee the comparison is also limited by the data itself: **history starts +May 2026** and partial months are excluded, so a prior period may simply not +exist yet. Say that plainly instead of inventing a baseline or comparing against +an incomplete month. ## Output -Respond in the seller's language (default pt-BR). +Respond in the seller's language (default pt-BR). Name the marketplace the +figures came from. -**Snapshot (always):** a markdown table `| Métrica | Valor atual |` for **Vendas (estimadas), -Produtos, Produtos de catálogo, Vendedores, Distribuição de medalhas, Monopolização**, plus a +**Snapshot (always):** a markdown table `| Métrica | Valor atual |`, plus a downloadable `.csv` / `.xlsx` of the same data. -**Comparison (only when a previous table is supplied):** a markdown table `| Métrica | Anterior | -Atual |`. Put the change (figure or percentage point) inside the **Atual** cell, prefixed with a -semantic color dot: +- **Mercado Livre** rows: **Vendas (estimadas), Produtos, Produtos de catálogo, + Vendedores, Distribuição de medalhas, Monopolização**. +- **Shopee** rows: **Vendas (estimadas), Produtos, Vendedores, Distribuição por + tipo de loja, Concentração** — there is **no Produtos de catálogo row**; omit + it rather than showing it empty. -- **Vendas ↑ = 🟢**; Vendas ↓ = 🔴. -- **Monopolização is inverted** (like cancellation rate): **down = 🟢** (easier to enter), **up = 🔴**. -- **Produtos / Vendedores** moving is neutral context — show the change without a strong good/bad dot. -- **Distribuição de medalhas** — show the tiers that moved (for example `platina 4 → 5`). +**Comparison (only when a previous table is supplied):** a markdown table `| +Métrica | Anterior | Atual |`. Put the change (figure or percentage point) +inside the **Atual** cell, prefixed with a semantic color dot: -Column headers are words (`Métrica | Anterior | Atual`), never a bare "Δ" symbol. Show the color-dot -legend (🟢/🔴) **only** in the comparison table, where the dots actually appear — never on a plain -snapshot. - -Close with a short **Principais insights** section: with a comparison, interpret what moved; on a -standalone snapshot, frame it as the starting picture with no trend claims. - -**Disclaimer (every report):** - -> ⚠️ Vendas, vendedores, produtos e monopolização são estimativas do JoomPulse com base no histórico -> de anúncios — não são transações reais. / Sales, sellers, products, and monopolization are JoomPulse -> estimates based on historical listing data — not actual transactions. +- **Vendas ↑ = 🟢**; Vendas ↓ = 🔴. +- **Monopolização (Mercado Livre) and Concentração (Shopee) are inverted** (like + cancellation rate): **down = 🟢** (easier to enter), **up = 🔴**. The + direction rule holds on both marketplaces even though the measurements differ. +- **Produtos / Vendedores** moving is neutral context — show the change without + a strong good/bad dot. +- **Distribuição de medalhas** (Mercado Livre) — show the tiers that moved (for + example `platina 4 → 5`). On Shopee the same line is the **shop-tier + breakdown**: show which of the three tiers moved (for example `Indicado 12 → + 15`), and never phrase it as a medal or a rung. + +Column headers are words (`Métrica | Anterior | Atual`), never a bare "Δ" +symbol. Show the color-dot legend (🟢/🔴) **only** in the comparison table, +where the dots actually appear — never on a plain snapshot. + +Close with a short **Principais insights** section: with a comparison, interpret +what moved; on a standalone snapshot, frame it as the starting picture with no +trend claims. + +**Disclaimer (every report) — use the variant for the marketplace you queried.** + +Mercado Livre: + +> ⚠️ Vendas, vendedores, produtos e monopolização são estimativas do JoomPulse +> com base no histórico de anúncios — não são transações reais. / Sales, +> sellers, products, and monopolization are JoomPulse estimates based on +> historical listing data — not actual transactions. + +Shopee: + +> ⚠️ Vendas são estimativas do JoomPulse a partir dos contadores arredondados da +> própria Shopee — não são transações reais. Só itens com pelo menos uma venda +> no histórico são rastreados, então as contagens são um piso, e a concentração +> é medida de forma diferente da do Mercado Livre. / Sales are JoomPulse +> estimates built from Shopee's own rounded sold counters — not actual +> transactions. Only items with at least one lifetime sale are tracked, so the +> counts are a lower bound, and concentration is measured differently than on +> Mercado Livre. ## Visualization -When the client can render inline visuals, present metric cards and a medal-distribution chart; -otherwise fall back to the markdown tables plus text cards. Never block on visuals. The snapshot table -(and the comparison table, when present) always render as markdown in the response text, and the -downloadable file mirrors what is shown. +When the client can render inline visuals, present metric cards and a +seller-tier chart; otherwise fall back to the markdown tables plus text cards. +Never block on visuals. The snapshot table (and the comparison table, when +present) always render as markdown in the response text, and the downloadable +file mirrors what is shown. When inline visuals are available: -- **Cards:** estimated sales, number of products, number of catalog products, and number of active - sellers — plus the monopolization level as a value or small bar. With a comparison, you may annotate - each card with its `anterior → atual` change. -- **A medal-distribution bar:** sellers (or listings) split across medal tiers, using the medal - palette — platina = purple, ouro = amber, prata = blue, sem medalha = white with a thin border - (white needs the border to stay visible on a light background). With a previous table, note the shift. -- **No synthesized trend line** from a single run (there is no server-side history). Only if the user - supplies several past-period tables may you plot a simple line across those periods. - -Presentation rules: column headers are words, never a bare "Δ" symbol; show the color-dot legend only -when those dots appear (the comparison table); render a chart only when the data supports it. +- **Cards:** estimated sales, number of products and number of active sellers, + plus the concentration figure as a value or small bar — labelled + Monopolização on Mercado Livre, Concentração on Shopee. On Mercado Livre add a + **number of catalog products** card; on Shopee there is **no such card** — + drop it. With a comparison, you may annotate each card with its `anterior → + atual` change. +- **A distribution bar:** on Mercado Livre, sellers (or listings) split across + medal tiers using the medal palette — platina = purple, ouro = amber, prata = + blue, sem medalha = white with a thin border (white needs the border to stay + visible on a light background). On Shopee, a **three-tier** bar — Official + store / Preferred (Indicado) / Common — with plain labels and a neutral + palette: no medal colours, no four-tier phrasing, and never a shop tier mapped + onto a medal. With a previous table, note the shift. +- **No synthesized trend line** from a single run (there is no server-side + history). Only if the user supplies several past-period tables may you plot a + simple line across those periods. + +Presentation rules: column headers are words, never a bare "Δ" symbol; show the +color-dot legend only when those dots appear (the comparison table); render a +chart only when the data supports it. ## Notes & Guardrails The seller should never see a system or stack error — only a friendly next step. -- **No previous table supplied:** render today's snapshot only (no change column, no legend) and - invite the user to save it for next time. -- **Supplied table is for a different category, malformed, or unreadable:** say so plainly and fall - back to the snapshot only; do not force a misaligned comparison. -- **Empty or failed data:** say the data is temporarily unavailable and to try again. Never paste - internal error text, HTTP codes, or field names to the seller. -- **Catalog product input:** when monitoring a catalog product, note the buy-box competition (how many - sellers compete) rather than implying a single listing. +- **No previous table supplied:** render today's snapshot only (no change + column, no legend) and invite the user to save it for next time. +- **Supplied table is for a different category, a different marketplace, + malformed, or unreadable:** say so plainly and fall back to the snapshot only; + do not force a misaligned comparison, and never align a Shopee table against + a Mercado Livre one. +- **No prior period available on Shopee:** history starts May 2026 and partial + months are excluded — say the comparison has no baseline yet instead of + producing one. +- **Category deeper than Shopee's third level:** answer at its level-3 ancestor + and state which category the numbers actually describe. +- **Empty or failed data:** say the data is temporarily unavailable and to try + again. Never paste internal error text, HTTP codes, or field names to the + seller. +- **Catalog product input (Mercado Livre only):** when monitoring a catalog + product, note the buy-box competition (how many sellers compete) rather than + implying a single listing. Shopee has neither a catalogue nor a buy-box, so + this mode does not apply there. diff --git a/skills/category-opportunity-index/SKILL.md b/skills/category-opportunity-index/SKILL.md index c41c15b..68ad07b 100644 --- a/skills/category-opportunity-index/SKILL.md +++ b/skills/category-opportunity-index/SKILL.md @@ -1,31 +1,33 @@ --- name: category-opportunity-index description: > - Reports the JoomPulse opportunity index (low, medium, or high) for one - Mercado Livre (Brasil) category, alongside that category's current monthly - market stats — estimated GMV, estimated sales, number of active sellers, - number of active listings, and average ticket — then writes a plain-language - read on how attractive the category is to enter. Use it when a seller wants a - one-shot market snapshot for a category they name. Triggers include: "is this - category worth entering", "show the opportunity index for this category", - "how big is this market", and the pt-BR equivalents "qual o índice de + Reports the JoomPulse opportunity level (low, medium, high) for one category on + Mercado Livre (Brasil) or Shopee Brasil, with that month's snapshot — estimated + revenue and sales, sellers, listings, average ticket — plus concentration and + month-over-month growth, and a plain-language verdict on entering it. Use for a + one-shot snapshot of a category the seller names. Triggers: "is this category + worth entering", "opportunity index for this category", "how big is this + market", "category opportunity on Shopee"; pt-BR "qual o índice de oportunidade", "vale a pena entrar nessa categoria", "tamanho de mercado da - categoria". Sales and revenue are JoomPulse estimates, not real transactions. - For ranking the sellers in a category, use the top-sellers-in-category skill; for - trending search terms, use the top-keywords-in-my-category skill; for comparing - category aggregates against a user-supplied previous snapshot, use the + categoria", "índice de oportunidade na Shopee", "vale a pena vender nessa + categoria da Shopee". Ask which marketplace when unclear; never mix the two. + Sales and revenue are JoomPulse estimates, not real transactions. To rank the + sellers in a category use the top-sellers skill; for trending search terms the + top-keywords skill; to compare against a user-supplied previous snapshot the category-monitor skill. --- # Category Opportunity Index -This skill answers a single question for **one** Mercado Livre (Brasil) -category: is it worth entering? Given a category named in free text, it reads -that category's **opportunity index** (low, medium, or high) and its current -monthly market indicators — estimated GMV, estimated sales, active sellers, -active listings, and average ticket — then writes a short pt-BR summary that -interprets the opportunity level together with how concentrated the market is -(monopolization) and which way it is growing. +This skill answers a single question for **one** category on **Mercado Livre +(Brasil) or Shopee Brasil**: is it worth entering? Given a marketplace and a +category named in free text, it reads that category's **opportunity index** (low, +medium, or high) and its current monthly market indicators — estimated revenue, +estimated sales, sellers, listings, and average ticket — then writes a short +pt-BR summary that interprets the opportunity level together with how +concentrated the market is and which way it is growing. On Mercado Livre the +summary can also draw on a year of history and a seasonality read; on Shopee +neither exists yet, and the report says so plainly instead of guessing. This is a point-in-time snapshot, not a tracker. To rank the sellers inside a category, use the top-sellers-in-category skill. For the trending search terms @@ -37,20 +39,25 @@ now?" for a category the user names. ## Prerequisites - JoomPulse MCP access is configured for the current agent environment. -- The user names the category to evaluate (free text is fine). -- The available JoomPulse tools can resolve a category name to a category and - return that category's current monthly market indicators plus its recent - monthly history. +- The user provides a marketplace — Mercado Livre (Brasil) or Shopee Brasil — and + names the category to evaluate (free text is fine). +- The available JoomPulse tools can resolve a category name to a category on + **either** marketplace and return that category's current monthly market + indicators, plus — on Mercado Livre — its recent monthly history. If JoomPulse MCP access is unavailable, stop and explain that the skill requires JoomPulse MCP setup before it can report a category's opportunity index. ## Scope -- **Mercado Livre (Brasil) only.** Other marketplaces are out of scope. -- **Sales and revenue are JoomPulse estimates** derived from historical listing - data — not real transactions. The seller, listing, and average-ticket counts - shown here are estimates too. Disclose this in every output. +- **Mercado Livre (Brasil) and Shopee Brasil**, one at a time. Other marketplaces + are out of scope. +- **Sales and revenue are JoomPulse estimates** — not real transactions. The + seller, listing, and average-ticket figures shown here are estimates too. + Disclose this in every output. The estimates are built differently on each + marketplace: on Mercado Livre from historical listing data, on Shopee from the + marketplace's own rounded sold counters refined with review movement. Use the + matching disclaimer. - **Read-only.** The skill never writes or modifies anything. - **Language:** detect the seller's language and respond in it. Default to pt-BR. @@ -60,64 +67,139 @@ JoomPulse MCP setup before it can report a category's opportunity index. from general knowledge, and never fabricate a number — show `—` when a value is missing. +**Shopee data — what differs from Mercado Livre** + +- **Estimates come from Shopee's own rounded sold counters**, refined with review + movement. Treat small gaps between items as noise and never rank on a difference + of a few units. Price, rating and review count are real. +- **Coverage is not a census**: only items with at least one lifetime sale are + tracked, so any count is a lower bound and an absent item is not evidence it does + not sell. +- **History starts May 2026** — there is no long-run trend and no seasonal read. +- **Category analytics stop at three levels**; the item view reaches deeper. Say + which you used. +- **No seller medals** — Shopee has three mutually exclusive shop tiers: **Official + store**, **Preferred (Indicado)** and **Common**. There is no ladder; inventing + Shopee medals is fabrication. +- **No catalogue and no buy-box**, and an item belongs to one shop. +- **No fulfilment programme, no free-shipping flag and no listing tier** — show `—` + rather than guessing. +- **Concentration is measured differently** and thresholds do not transfer between + marketplaces. +- Item titles mix Portuguese, English and Chinese — search both languages. + ## Workflow +### Step 0 — Decide the marketplace + +JoomPulse covers **two separate marketplaces**: Mercado Livre (Brasil) and Shopee +Brasil. They are independent datasets with different coverage, history and +mechanics. Decide which one the request belongs to **before reading any data**: + +- **The seller said so.** "Shopee" means Shopee; "Mercado Livre", "MeLi" or "ML" + means Mercado Livre. +- **An identifier gives it away.** An identifier beginning `MLB` is Mercado Livre; + a bare 10–11 digit number is a Shopee item or shop. A `mercadolivre.com.br` link + is Mercado Livre, a `shopee.com.br` link is Shopee. If an identifier is not found + on the marketplace you assumed, check the other one before telling the seller it + does not exist. +- **The request only makes sense on one of them** — buy-box, catalogue position, + seller medals, a fulfilment programme or search keywords are Mercado Livre only. +- **Otherwise ask** — one short question, mentioning that both are available. + **Never guess and never default.** + +**Never mix data from the two marketplaces in one query, one table or one total.** +They are separate pipelines with different grains and estimate methods; a combined +figure is simply wrong. If the seller wants both, run the analysis twice and report +the two side by side, comparing direction and orders of magnitude — never exact +numbers. + ### Step 1 — Resolve the category 1. If the user did not name a category, ask which one to evaluate (for example *"Para qual categoria você quer o Índice de Oportunidade?"*). -2. Use JoomPulse to match the free text to a category, retrieving candidate - categories with their name, depth level, and opportunity index for the - current month. +2. Use JoomPulse to match the free text to a category **on the marketplace chosen + in Step 0**, retrieving candidate categories with their name, depth level, and + opportunity index for the current month. 3. Pick the best match. If several plausible categories come back, list the top candidates (name and level) and ask the user to choose — do not silently - guess between unrelated categories. If nothing matches, say the category was - not found and ask for a broader or rephrased term. + guess between unrelated categories. If nothing matches, check the other + marketplace before saying the category was not found, then ask for a broader + or rephrased term. +4. On **Shopee**, category analytics stop at **three levels**. If the seller names + a deeper niche, evaluate the closest available level instead, say which level + you used, and do not promise a deeper drill-down. ### Step 2 — Get the current monthly indicators -For the chosen category, use JoomPulse to obtain its **latest month's** market -indicators: +First **settle which month you are reading.** On Mercado Livre the latest month is +flagged reliably. On Shopee that flag is not trustworthy, so resolve the most +recent month that actually has data and use that one — then name the month in the +report so the seller knows exactly which period the figures describe. + +For the chosen category, use JoomPulse to obtain that month's market indicators: - Opportunity index (low / medium / high). -- Estimated monthly GMV and estimated monthly sales. -- Number of active sellers and number of active listings. +- Estimated monthly revenue and estimated monthly sales. +- Number of sellers and number of listings. On **Shopee** these count only the + sellers and the items that **had sales in that month** — label them that way and + never present them as the category's whole population. - Average ticket. -- Context for the summary: the monopolization level (the top seller's share of - orders, expressed 0–100%), the month-over-month growth direction, and any - seasonality signal. +- Context for the summary: the concentration measure, the month-over-month revenue + growth direction, and — **on Mercado Livre only** — any seasonality signal. + +**Concentration is not the same measurement on the two marketplaces.** On Mercado +Livre it is the leading seller's share of orders, expressed 0–100%. On Shopee it is +an index computed across all the sellers in the category: give it its own label, +never describe it as one seller holding a share of the shelf, never apply the +Mercado Livre thresholds to it, and never compare or combine the two marketplaces' +values. All indicators are monthly values. Use the always-positive monthly totals for market size, never a month-over-month delta — never label a change figure as a total or as "revenue". -### Step 3 — Get ~12 months of history for the trend line +### Step 3 — Get ~12 months of history for the trend line (Mercado Livre only) + +On **Mercado Livre**, use JoomPulse to retrieve the category's recent monthly +history (estimated revenue and estimated sales per month) for roughly the last 12 +months. Order the months oldest to newest. If fewer than about six months of +history come back (a new or sparse category), treat history as unavailable and +skip the trend line — show the cards only. -Use JoomPulse to retrieve the category's recent monthly history (estimated GMV -and estimated sales per month) for roughly the last 12 months. Order the months -oldest to newest. If fewer than about six months of history come back (a new or -sparse category), treat history as unavailable and skip the trend line — show -the cards only. +On **Shopee**, skip this step entirely. History only begins in May 2026, so about +three months exist and the six-month rule above would fire on every single run. +Do not draw a trend and do not pass three points off as one: state plainly that a +long-run trend is not available for Shopee yet, and report the snapshot plus the +month-over-month change instead. ### Step 4 — Build the report (pt-BR) 1. Lead with the **opportunity index**, prominently: 🟢 alto / 🟡 médio / 🔴 - baixo (show `—` if it is missing), noting the category name and level. + baixo (show `—` if it is missing), noting the marketplace, the category name + and level, and the month the figures describe. 2. Show the monthly indicators table (see Output). 3. Write a 2–4 sentence **resumo** that interprets the opportunity index - together with monopolization and growth: + together with concentration and growth: - What the level means — high implies good room for new sellers; low implies little relative upside. - - **Monopolization** — high concentration (roughly above half) means the - market is dominated by a few sellers and is harder to break into; low means - demand is spread out and more accessible. + - **Concentration** — on Mercado Livre, high concentration (roughly above + half) means the market is dominated by a few sellers and is harder to break + into; low means demand is spread out and more accessible. On Shopee, report + the index under its own label and read it in relative terms only — no + share-of-the-shelf phrasing, no borrowed thresholds, no cross-marketplace + comparison. - **Growth** — rising means the category is expanding; falling means it is contracting. - - Optionally note seasonality if relevant. + - **Seasonality** — on Mercado Livre, optionally note it if relevant. On + Shopee there is no seasonality data at all: say the read is unavailable + there, and never state that a category is not seasonal. - End on a practical takeaway: worth entering / enter with caution / not very attractive right now. -4. Add the mandatory disclaimer, and optionally the JoomPulse category dashboard - link. +4. On **Shopee**, name the category level you actually used, and do not promise a + deeper drill-down than the three levels available. +5. Add the mandatory disclaimer for the marketplace you queried, and — on Mercado + Livre — optionally the JoomPulse category dashboard link. ## Output @@ -125,9 +207,11 @@ Respond in the seller's language, default pt-BR, with no commentary about how th report was produced. The indicators table always renders as markdown so it shows cleanly in any client. -**Opportunity badge** — a heading line, for example: +**Opportunity badge** — a heading line naming the marketplace, the category and +the month the figures cover, for example: -> **Índice de Oportunidade: ALTO** 🟢 (categoria: , nível L) +> **Índice de Oportunidade: ALTO** 🟢 (Mercado Livre · categoria: , nível +> L · mês de referência: …) **Monthly indicators table:** @@ -139,20 +223,39 @@ cleanly in any client. | Anúncios Ativos | … | | Ticket Médio | R$ … | +On **Shopee**, keep the same five rows but rename the two count rows so they say +what they actually cover — for example *Vendedores com vendas no mês* and +*Anúncios com vendas no mês*. Wherever concentration appears, give it its own +Shopee label as an index across all sellers, never "Monopolização" and never a +top-seller share. + Format money as `R$` with pt-BR conventions (comma decimal, dot thousands, for example `R$ 1,2 mi`, `8.400`, `R$ 49,90`) and round large values sensibly. Empty cells show `—`. **Resumo** — the 2–4 sentence interpretation described in the workflow. -**Disclaimer (every report):** +**Disclaimer (every report) — use the variant for the marketplace you queried.** + +Mercado Livre: > ⚠️ GMV, vendas, vendedores e anúncios são estimativas do JoomPulse com base no > histórico de anúncios — não são transações reais. / GMV, sales, sellers, and > listings are JoomPulse estimates based on historical listing data — not actual > transactions. -Optionally add the JoomPulse category dashboard link. +Shopee: + +> ⚠️ Receita, vendas, vendedores e anúncios são estimativas do JoomPulse a partir +> dos contadores arredondados da própria Shopee — não são transações reais, e +> diferenças pequenas são ruído. Só itens com pelo menos uma venda no histórico +> são rastreados, então as contagens são um piso. / Revenue, sales, sellers, and +> listings are JoomPulse estimates built from Shopee's own rounded sold counters — +> not actual transactions, and small gaps are noise. Only items with at least one +> lifetime sale are tracked, so the counts are a lower bound. + +Optionally add the JoomPulse category dashboard link — **Mercado Livre only**. +There is no JoomPulse category dashboard link for Shopee, so never invent one. ## Visualization @@ -166,19 +269,28 @@ table always renders as markdown in the response text, on every surface, and the When inline visuals are available, present in one panel: - **Opportunity badge** at the top: Alta 🟢 / Média 🟡 / Baixa 🔴 (show `—` if - missing). -- **Five metric cards:** estimated monthly GMV, estimated monthly sales, active - sellers, active listings, and average ticket — pt-BR formatted, money with - `R$`. These match the five rows of the monthly indicators table. -- **12-month trend line** of estimated monthly GMV (one point per month, x = mês, - y = GMV; optionally a second series for estimated sales). Render this chart - only when the data supports it — skip it entirely when there are fewer than - about six months of history, leaving just the cards. Optionally add a small - growth-% chip from the month-over-month change. -- **Monopolization bar:** a 0–100% horizontal bar; note that a **low** value is - the favorable end (demand spread across many sellers). -- **Seasonality chip:** a pill only, no bar — "Não sazonal" when the category is - not seasonal, or "Sazonal · pico {mês}" naming the peak month. + missing), with the marketplace and the reference month. +- **Five metric cards:** estimated monthly revenue, estimated monthly sales, + sellers, listings, and average ticket — pt-BR formatted, money with `R$`. These + match the five rows of the monthly indicators table; on Shopee the two count + cards carry the "com vendas no mês" wording. +- **12-month trend line** of estimated monthly revenue (one point per month, x = + mês, y = receita; optionally a second series for estimated sales) — **Mercado + Livre only**. Render this chart only when the data supports it — skip it + entirely when there are fewer than about six months of history, leaving just the + cards. Optionally add a small growth-% chip from the month-over-month change. On + **Shopee** there is no long-run trend to draw at all: show the growth chip on its + own and say a 12-month trend is not available yet. +- **Concentration:** on **Mercado Livre**, a 0–100% horizontal bar for the leading + seller's share of orders; note that a **low** value is the favorable end (demand + spread across many sellers). On **Shopee**, show the index as its own labelled + value — not on the Mercado Livre 0–100% scale, not with the Mercado Livre + thresholds, and never side by side with a Mercado Livre figure. +- **Seasonality chip** — **Mercado Livre only**: a pill, no bar — "Não sazonal" + when the category is not seasonal, or "Sazonal · pico {mês}" naming the peak + month. On **Shopee** omit the chip; if seasonality comes up, say the read is + unavailable there, and never print "Não sazonal" — the data cannot support that + claim. Presentation rules: use the medal palette consistently if medals appear anywhere (platina = purple, ouro = amber, prata = blue, sem medalha = white with a thin @@ -189,23 +301,37 @@ chart only when the underlying data supports it, and skip it otherwise. On a text-only surface, render the same information as markdown and text: the badge as a heading line, the five metrics as the indicators table or text cards, -the trend as one short line describing the ~12-month direction (only when there -are at least about six months of history), the monopolization as a text -percentage (for example `Monopolização: 38% (baixa — bom)`), and the seasonality -as a text chip line. +the trend as one short line describing the ~12-month direction (Mercado Livre +only, and only when there are at least about six months of history), the +concentration as a text value under its own marketplace's label (for example +`Monopolização: 38% (baixa — bom)` on Mercado Livre), and the seasonality as a +text chip line on Mercado Livre only. ## Notes & Guardrails The seller should never see a system or stack error — only a friendly next step. - **Ambiguous category:** list the candidate categories and ask the user to - choose. Do not guess between unrelated categories. + choose. Do not guess between unrelated categories. If nothing matches, check the + other marketplace before saying the category does not exist. - **No current data / empty result:** say you could not find current data for that category and suggest a broader or different term. Never fabricate numbers. + On Shopee, add that only items with at least one lifetime sale are tracked, so an + empty result is not proof the category is quiet. - **Opportunity index missing:** show `—` for the badge and base the summary on - monopolization and growth instead. + concentration and growth instead. - **Sparse history:** when fewer than about six months of history exist, omit the - trend line and report the snapshot only. + trend line and report the snapshot only. On Shopee there is no long-run history + yet at all — say so rather than presenting a few months as a trend. +- **Reference month on Shopee:** never trust a latest-month flag there. Resolve + the most recent month that has data and name that month in the report. +- **Category depth on Shopee:** analytics stop at three levels. Say which level + you used and do not promise a deeper drill-down. +- **Concentration across marketplaces:** the two figures are different + measurements. Never compare them, average them, or carry one marketplace's + wording or thresholds onto the other. +- **Seasonality on Shopee:** the read simply does not exist. Say it is + unavailable; never assert that a category is or is not seasonal. - **Market data temporarily unavailable:** retry once quietly; if it is still down, say market data is temporarily unavailable and to try again. Never paste internal error text, HTTP codes, or field names to the seller. diff --git a/skills/fast-growing-international-products/SKILL.md b/skills/fast-growing-international-products/SKILL.md index 23793c1..3d7710d 100644 --- a/skills/fast-growing-international-products/SKILL.md +++ b/skills/fast-growing-international-products/SKILL.md @@ -1,26 +1,28 @@ --- name: fast-growing-international-products description: > - Finds fast-growing international (imported) products ACROSS ALL Mercado Livre - (Brasil) categories, using JoomPulse, and returns them as one product table - that includes each item's category, with price, estimated weekly sales and - revenue, rating, time on air, shipping, listing type, seller medal, and a - JoomPulse link per item. Use it when a seller wants rising imported products - marketwide, not inside a single niche. Triggers include: "fast-growing - international products", "imported products that are taking off", "cross-border - winners across all categories", and the pt-BR equivalents "produtos - internacionais em alta", "produtos importados crescendo rápido", "produtos - internacionais que mais crescem em todas as categorias". Sales and revenue are - JoomPulse estimates, not real transactions. For the same search limited to one - category, use the single-category international skill. + Finds fast-growing international (imported) products ACROSS ALL categories on + JoomPulse — Mercado Livre (Brasil) or Shopee Brasil — as one product table + that includes each item's category, plus price, estimated sales and revenue, + rating, time on air and each marketplace's own logistics, tier and link + columns. Use when a seller wants rising imported products marketwide, not in + one niche. Triggers: "fast-growing international products", "imported products + that are taking off", "cross-border winners across all categories", + "international products on Shopee"; pt-BR "produtos internacionais em alta", + "produtos importados crescendo rápido", "produtos internacionais que mais + crescem em todas as categorias", "produtos importados na Shopee". Ask which + marketplace when unclear; never mix the two. Sales and revenue are JoomPulse + estimates, not real transactions; price, rating and reviews are real. For one + category only, use the single-category international skill. --- # Fast-Growing International Products This skill returns the **fast-growing international (imported) products across all -Mercado Livre (Brasil) categories** — a marketwide shortlist of cross-border -items with recent momentum, each shown with the category it sits in. It is the -all-categories sibling of the single-category international skill. +categories** on **Mercado Livre (Brasil) or Shopee Brasil** — a marketwide +shortlist of cross-border items with recent momentum, each shown with the +category it sits in. It is the all-categories sibling of the single-category +international skill. For imported products inside one specific category, use the single-category international skill. @@ -28,67 +30,165 @@ international skill. ## Prerequisites - JoomPulse MCP access is configured for the current agent environment. +- The user provides a marketplace — Mercado Livre (Brasil) or Shopee Brasil. - The available JoomPulse tools can return active international listings across - categories with their category, price, estimated sales and revenue, rating, - time on air, logistics, listing type and seller medal. + categories on **either** marketplace, each carrying its own category path, + price, estimated sales and revenue, rating and review count. +- Per marketplace, the tools can also report: on Mercado Livre, how long the + listing has been on air, its logistics flags, listing type and seller medal; on + Shopee, the shop tier, whether the item ships cross-border, the seller's + location, the item's creation date, and a growth direction flag comparing the + item's current monthly rate against its own lifetime average. If JoomPulse MCP access is unavailable, stop and explain that the skill requires JoomPulse MCP setup before it can find international products. ## Scope -- **Mercado Livre (Brasil) only.** Other marketplaces are out of scope. -- **Sales and revenue are JoomPulse estimates** derived from historical listing - data — not real transactions. Price, rating, and reviews are real history. - Disclose the estimate caveat in every output. +- **Mercado Livre (Brasil) and Shopee Brasil**, one at a time. Other + marketplaces are out of scope. +- **Sales and revenue are JoomPulse estimates** — not real transactions. Price, + rating, and reviews are real history. The estimates are built differently on + each marketplace: on Mercado Livre from historical listing data, on Shopee from + the marketplace's own rounded sold counters refined with review movement. Use + the matching disclaimer, and disclose the estimate caveat in every output. - **Read-only.** The skill never writes or modifies anything. - **Language:** detect the seller's language and respond in it. Default to pt-BR. - **Keep the workflow invisible.** Show `—` for any missing value; never fabricate. +**Shopee data — what differs from Mercado Livre** + +- **Estimates come from Shopee's own rounded sold counters**, refined with review + movement. Treat small gaps between items as noise and never rank on a difference + of a few units. Price, rating and review count are real. +- **Coverage is not a census**: only items with at least one lifetime sale are + tracked, so any count is a lower bound and an absent item is not evidence it does + not sell. +- **History starts May 2026** — there is no long-run trend and no seasonal read. +- **Category analytics stop at three levels**; the item view reaches deeper. Say + which you used. +- **No seller medals** — Shopee has three mutually exclusive shop tiers: **Official + store**, **Preferred (Indicado)** and **Common**. There is no ladder; inventing + Shopee medals is fabrication. +- **No catalogue and no buy-box**, and an item belongs to one shop. +- **No fulfilment programme, no free-shipping flag and no listing tier** — show `—` + rather than guessing. +- **Concentration is measured differently** and thresholds do not transfer between + marketplaces. +- Item titles mix Portuguese, English and Chinese — search both languages. + ## Workflow +### Step 0 — Decide the marketplace + +JoomPulse covers **two separate marketplaces**: Mercado Livre (Brasil) and Shopee +Brasil. They are independent datasets with different coverage, history and +mechanics. Decide which one the request belongs to **before reading any data**: + +- **The seller said so.** "Shopee" means Shopee; "Mercado Livre", "MeLi" or "ML" + means Mercado Livre. +- **An identifier gives it away.** An identifier beginning `MLB` is Mercado Livre; + a bare 10–11 digit number is a Shopee item or shop. A `mercadolivre.com.br` link + is Mercado Livre, a `shopee.com.br` link is Shopee. If an identifier is not found + on the marketplace you assumed, check the other one before telling the seller it + does not exist. +- **The request only makes sense on one of them** — buy-box, catalogue position, + seller medals, a fulfilment programme or search keywords are Mercado Livre only. +- **Otherwise ask** — one short question, mentioning that both are available. + **Never guess and never default.** + +**Never mix data from the two marketplaces in one query, one table or one total.** +They are separate pipelines with different grains and estimate methods; a combined +figure is simply wrong. If the seller wants both, run the analysis twice and report +the two side by side, comparing direction and orders of magnitude — never exact +numbers. + ### Step 1 — Optional narrowing -This skill is marketwide by default. The seller may optionally narrow it to a +This skill is marketwide by default, on both marketplaces: a scan with no +category filter works, and every item carries its own category path, so the +Category column is fillable either way. The seller may optionally narrow it to a broad area; if they do and the term is ambiguous, disambiguate before continuing. ### Step 2 — Find fast-growing international products marketwide Use JoomPulse to get active **international (imported)** listings across -categories. There is no single "fast growth" flag, so it must be defined from a -real momentum proxy — **revenue alone is not growth**, and ranking by it surfaces -old, high-ticket slow movers rather than rising items. - -**Default fast-growth rule (always apply and disclose):** an item is "fast-growing" -only when it is **recently listed (low time on air)** *and* has **strong estimated -weekly sales (and/or estimated weekly revenue)** — that is, it gained real traction -in a short time. Rank the shortlist by that momentum (estimated weekly sales/revenue -relative to how recently it was listed), not by revenue on its own. **State this -rule in the output.** +categories on the chosen marketplace. There is no single "fast growth" flag, so +it must be defined from a real momentum proxy — **revenue alone is not growth**, +and ranking by it surfaces old, high-ticket slow movers rather than rising items. + +**What "international" means, per marketplace.** On Mercado Livre it is the +imported/cross-border listing signal. On Shopee it means the item **ships +cross-border**; a probe showed such items can also carry a specific foreign +country as the seller location, so the two signals are **not** equivalent — pick +one, say which one you used, and do not present them as the same thing. + +**Fast-growth rule on Mercado Livre (always apply and disclose):** an item is +"fast-growing" only when it is **recently listed (low time on air)** *and* has +**strong estimated weekly sales (and/or estimated weekly revenue)** — that is, it +gained real traction in a short time. Rank the shortlist by that momentum +(estimated weekly sales/revenue relative to how recently it was listed), not by +revenue on its own. **State this rule in the output.** + +**Fast-growth rule on Shopee (different — do not reuse the Mercado Livre rule):** +each item carries a growth direction flag comparing its current monthly rate +against its own lifetime average, so define fast-growing as **direction is +growing AND recent estimated sales above zero**. **Drop the "recently listed" +gate entirely** — Shopee's strongest cross-border items are often years old, and +the gate empties the list. **Never sort descending without first excluding the +zero-sales rows**, or the top of the list fills with items that sell nothing. +State the rule you applied. Keep a clearly stated **top-N** (for example top 30) and say it is a top-N. -**Fallback (not "growth"):** if recency data is unavailable, you may instead show -the **top international items by estimated weekly revenue** — but label it plainly -as a *top-by-revenue fallback*, never call it "fast-growing" or "growth", and say -the momentum rule could not be applied. +**Fallback (not "growth"):** if the momentum signal is unavailable, you may +instead show the **top international items by estimated revenue** — weekly on +Mercado Livre, over the last 30 days on Shopee, since Shopee has **no marketwide +weekly ranking**. Label it plainly as a *top-by-revenue fallback*, never call it +"fast-growing" or "growth", and say the momentum rule could not be applied. ## Output -Respond in the seller's language (default pt-BR). The product list always renders -as a markdown table, and **includes a Category column** (the cross-category -differentiator): +Respond in the seller's language (default pt-BR). Lead with a short line naming +the **marketplace** you queried. The product list always renders as a markdown +table, and **includes a Category column** (the cross-category differentiator). + +**Product table (Mercado Livre):** | MLB | Nome | Vendedor | Categoria | Preço | Vendas (semana) | Receita (semana) | Classificação | Avaliações | Tempo no ar | Frete grátis | Mercado Envios Full | Tipo de anúncio | Medalha | |---|---|---|---|--:|--:|--:|--:|--:|--:|:--:|:--:|---|---| - The **MLB** identifier links to the item's JoomPulse page. -- State the fast-growth rule — recently listed **and** strong estimated weekly - sales/revenue, ranked by that momentum — and the top-N cap you applied, in one - short line. If you used the top-by-revenue fallback instead, say so and do not - call it growth. -**Disclaimer (every report):** +**Product table (Shopee)** — same shape, with the marketplace's own columns: + +| Item | Nome | Loja | Categoria | Preço | Vendas (30 dias) | Receita (30 dias) | Classificação | Avaliações | Tempo no ar | Nível da loja | +|---|---|---|---|--:|--:|--:|--:|--:|--:|---| + +- The item identifier links to the item **on Shopee** — there is **no JoomPulse + dashboard link for Shopee rows**, so never invent one. +- **Nível da loja** is Official store / Preferred (Indicado) / Common. Never map + a shop tier onto a seller medal. +- **Tempo no ar** comes from the item's creation date. Shopee history starts May + 2026, so an item can predate any measurable sales — a long time on air does not + mean it has been selling all that time. +- Free shipping, the fulfilment programme and the listing type have **no Shopee + equivalent**: either drop these columns or show `—` in them. + +Sales and revenue are **not the same window** on the two marketplaces: Mercado +Livre reports weekly figures, Shopee reports 30-day figures only — label the +Shopee columns as 30 days and never present a 30-day figure under a weekly +heading. + +State the fast-growth rule you actually applied — on Mercado Livre, recently +listed **and** strong estimated weekly sales/revenue, ranked by that momentum; on +Shopee, a growing direction with non-zero recent sales and **no recency gate** — +plus which cross-border signal you used and the top-N cap, in one short line. If +you used the top-by-revenue fallback instead, say so and do not call it growth. + +**Disclaimer (every report) — use the variant for the marketplace you queried.** + +Mercado Livre: > ⚠️ Sales and revenue are JoomPulse **estimates** based on historical listing > data — they are **not** actual transactions. Price, rating, and reviews are @@ -96,6 +196,18 @@ differentiator): > com base no histórico de anúncios — **não são transações reais**. Preço, > classificação e avaliações são histórico real do Mercado Livre. +Shopee: + +> ⚠️ Sales and revenue are JoomPulse **estimates** built from Shopee's own +> rounded sold counters — they are **not** actual transactions, and small gaps +> between items are noise. Only items with at least one lifetime sale are +> tracked, so this list is a lower bound. Price, rating, and reviews are real +> Shopee history. / Vendas e receita são **estimativas** do JoomPulse a partir +> dos contadores arredondados da própria Shopee — **não são transações reais**, e +> diferenças pequenas entre itens são ruído. Só itens com pelo menos uma venda no +> histórico são rastreados, então esta lista é um piso. Preço, classificação e +> avaliações são histórico real da Shopee. + ## Visualization When the client can render inline visuals, present metric cards and a chart; @@ -107,13 +219,16 @@ When inline visuals are available: - **Three cards:** number of products in the shortlist (top-N), number of distinct categories represented, and average ticket. -- **A horizontal bar** of the top products by estimated weekly revenue, plus an - optional small companion bar of which categories contribute the most - fast-growing international products. Render charts only when there are enough - items (skip under about four). +- **A horizontal bar** of the top products by estimated revenue — weekly on + Mercado Livre, over the last 30 days on Shopee; label the axis with the window + you used. Add an optional small companion bar of which categories contribute + the most fast-growing international products. Render charts only when there are + enough items (skip under about four). Presentation rules: render a chart only when the data supports it; any change -column uses a word header, never a bare "Δ". +column uses a word header, never a bare "Δ". If you show Mercado Livre seller +medals as colored chips, use the standard palette. On Shopee there are no medals +— write the shop tier as plain text and never colour it as a rung on a ladder. ## Notes & Guardrails @@ -122,6 +237,10 @@ The seller should never see a system or stack error — only a friendly next ste - **High-ticket, low-rotation skew:** marketwide imported items can skew toward expensive, slow-moving SKUs; surface that honestly rather than implying broad momentum that is not there. +- **On Shopee the skew is worse, and you must warn about it:** only items with at + least one lifetime sale are tracked and very expensive items are excluded from + coverage, which compounds the high-ticket, low-rotation bias. Say so plainly + instead of presenting the shortlist as a broad read on the market. - **Market data temporarily unavailable:** retry once quietly; if it is still down, say market data is temporarily unavailable and to try again. Never paste internal error text, HTTP codes, or field names to the seller. diff --git a/skills/growing-leaf-category-tracker/SKILL.md b/skills/growing-leaf-category-tracker/SKILL.md index 12e104a..1e0cb56 100644 --- a/skills/growing-leaf-category-tracker/SKILL.md +++ b/skills/growing-leaf-category-tracker/SKILL.md @@ -1,27 +1,34 @@ --- name: growing-leaf-category-tracker description: > - Finds the fastest-growing deep sub-categories (leaf categories, deeper than the - third level) under a chosen Mercado Livre (Brasil) category, ranked by - month-over-month revenue growth, using JoomPulse market data. Use it when a - seller picks a category and wants the niches inside it that are growing fastest - right now. Triggers include: "fast-growing subcategories", "which niches are - growing in this category", "deep growing categories", and the pt-BR equivalents - "subcategorias em crescimento", "nichos que mais crescem nesta categoria", - "categorias profundas em alta". Sales and revenue are JoomPulse estimates, not - real transactions. For one category's opportunity index, use the - category-opportunity-index skill; for comparing category aggregates against a - user-supplied previous snapshot, use the category-monitor skill; for new products - inside a category, use the new-growing-products-in-category skill. + Finds the fastest-growing sub-categories under a chosen category on JoomPulse — + Mercado Livre (Brasil) or Shopee Brasil — ranked by month-over-month revenue + growth. On Mercado Livre it reaches the deep leaf niches below the third level; + on Shopee, category analytics stop at the third level, so it ranks there and says + plainly that deeper niches are folded into their level-3 ancestor. Use when a + seller picks a category and wants the niches inside it growing fastest now. + Triggers: "fast-growing subcategories", "which niches are growing in this + category", "growing categories on Shopee"; pt-BR "subcategorias em crescimento", + "nichos que mais crescem nesta categoria", "categorias em alta na Shopee". Ask + which marketplace when unclear; never mix the two. Sales and revenue are + JoomPulse estimates, not real transactions. For one category's opportunity index + use the category-opportunity-index skill; for new products inside a category, the + new-growing-products-in-category skill. --- # Growing Leaf Category Tracker -This skill takes one Mercado Livre (Brasil) category and surfaces the **deep -sub-categories inside it that are growing fastest** — the leaf niches (below the -third level of the category tree) with the strongest month-over-month growth in -estimated revenue. It helps a seller who already knows a broad area decide which -specific niche to move into next. +This skill takes one category on **Mercado Livre (Brasil) or Shopee Brasil** and +surfaces the **sub-categories inside it that are growing fastest** — the niches +with the strongest month-over-month growth in estimated revenue. It helps a seller +who already knows a broad area decide which specific niche to move into next. + +**How deep it can go differs by marketplace.** On Mercado Livre the answer is the +deep leaf niches below the third level of the category tree. On Shopee, category +analytics exist only down to the third level, so the ranking runs at the deepest +level available — the third — and anything deeper is folded into its level-3 +ancestor and cannot be separated. Say so in the output; never pass level-3 rows +off as deep leaves. This is a niche-discovery snapshot, not a tracker over time. For a single category's opportunity index and market size, use the category-opportunity-index @@ -32,65 +39,155 @@ category, use the new-growing-products-in-category skill. ## Prerequisites - JoomPulse MCP access is configured for the current agent environment. -- The user names a parent category (free text is fine). -- The available JoomPulse tools can resolve a category, walk its sub-categories, - and return each one's current monthly market stats (estimated revenue and - sales, number of active sellers, number of products) and its growth direction. +- The user provides a marketplace — Mercado Livre (Brasil) or Shopee Brasil — and + names a parent category (free text is fine). +- The available JoomPulse tools can resolve a category on **either** marketplace, + walk its sub-categories, and return each one's current monthly market stats + (estimated revenue and sales, number of active sellers, number of products) and + the month-over-month movement in estimated revenue. If JoomPulse MCP access is unavailable, stop and explain that the skill requires JoomPulse MCP setup before it can find growing niches. ## Scope -- **Mercado Livre (Brasil) only.** Other marketplaces are out of scope. -- **Sales and revenue are JoomPulse estimates** derived from historical listing - data — not real transactions. Disclose this in every output. +- **Mercado Livre (Brasil) and Shopee Brasil**, one at a time. Other marketplaces + are out of scope. +- **Depth differs by marketplace:** deep leaf niches below the third level on + Mercado Livre; the third level only on Shopee, where deeper niches are folded + into their level-3 ancestor. +- **Sales and revenue are JoomPulse estimates** — not real transactions. Disclose + this in every output. The estimates are built differently on each marketplace: + on Mercado Livre from historical listing data, on Shopee from the marketplace's + own rounded sold counters refined with review movement. Use the matching + disclaimer. - **Read-only.** The skill never writes or modifies anything. - **Language:** detect the seller's language and respond in it. Default to pt-BR. - **Keep the workflow invisible.** Surface the answer, not the steps. Never fill gaps from general knowledge; show `—` for any missing value. +**Shopee data — what differs from Mercado Livre** + +- **Estimates come from Shopee's own rounded sold counters**, refined with review + movement. Treat small gaps between items as noise and never rank on a difference + of a few units. Price, rating and review count are real. +- **Coverage is not a census**: only items with at least one lifetime sale are + tracked, so any count is a lower bound and an absent item is not evidence it does + not sell. +- **History starts May 2026** — there is no long-run trend and no seasonal read. +- **Category analytics stop at three levels**; the item view reaches deeper. Say + which you used. +- **No seller medals** — Shopee has three mutually exclusive shop tiers: **Official + store**, **Preferred (Indicado)** and **Common**. There is no ladder; inventing + Shopee medals is fabrication. +- **No catalogue and no buy-box**, and an item belongs to one shop. +- **No fulfilment programme, no free-shipping flag and no listing tier** — show `—` + rather than guessing. +- **Concentration is measured differently** and thresholds do not transfer between + marketplaces. +- Item titles mix Portuguese, English and Chinese — search both languages. + ## Workflow +### Step 0 — Decide the marketplace + +JoomPulse covers **two separate marketplaces**: Mercado Livre (Brasil) and Shopee +Brasil. They are independent datasets with different coverage, history and +mechanics. Decide which one the request belongs to **before reading any data**: + +- **The seller said so.** "Shopee" means Shopee; "Mercado Livre", "MeLi" or "ML" + means Mercado Livre. +- **An identifier gives it away.** An identifier beginning `MLB` is Mercado Livre; + a bare 10–11 digit number is a Shopee item or shop. A `mercadolivre.com.br` link + is Mercado Livre, a `shopee.com.br` link is Shopee. If an identifier is not found + on the marketplace you assumed, check the other one before telling the seller it + does not exist. +- **The request only makes sense on one of them** — buy-box, catalogue position, + seller medals, a fulfilment programme or search keywords are Mercado Livre only. +- **Otherwise ask** — one short question, mentioning that both are available. + **Never guess and never default.** + +**Never mix data from the two marketplaces in one query, one table or one total.** +They are separate pipelines with different grains and estimate methods; a combined +figure is simply wrong. If the seller wants both, run the analysis twice and report +the two side by side, comparing direction and orders of magnitude — never exact +numbers. + ### Step 1 — Resolve the parent category Ask the seller for a category if none was given, then use JoomPulse to match the -free text to a category. If several plausible matches come back, list the top -candidates (name and depth level) and let the seller choose. +free text to a category **on the chosen marketplace**. If several plausible +matches come back, list the top candidates (name and depth level) and let the +seller choose. -### Step 2 — Collect the deep sub-categories +### Step 2 — Collect the sub-categories at the deepest level available Use JoomPulse to list the descendant categories below the chosen one, keeping the -**deep ones — leaf niches deeper than the third level**. For each, get the -current monthly estimated revenue and sales, the number of active sellers, the -number of products, and the month-over-month revenue growth. +deepest level the marketplace actually supports: + +- **Mercado Livre:** the **deep ones — leaf niches deeper than the third level**. +- **Shopee:** the **third level**, which is as deep as category analytics go. + Anything deeper comes back empty, so do not chase it. If the seller specifically + wants deep niches on Shopee, name the limitation — deeper niches are folded into + their level-3 ancestor and cannot be separated — and point them at the item-level + view instead, where items carry their own deeper category path; that is a + different skill's territory, so hand it over rather than faking depth here. + +For each kept category, get the current monthly estimated revenue and sales, the +number of active sellers, the number of products, and the month-over-month revenue +growth. All five reported columns exist on both marketplaces. + +On Shopee, **work out the most recent month explicitly** instead of trusting a +latest-month indicator — that indicator is unreliable there — and state which month +the figures describe. ### Step 3 — Keep the fast-growing ones -From those deep sub-categories, **keep only the ones that are growing fast** -(strong month-over-month revenue growth), then order the kept niches by growth, -fastest first. Use the always-positive monthly totals for size (revenue, sales, +From those sub-categories, **keep only the ones that are growing fast** (strong +month-over-month revenue growth), then order the kept niches by growth, fastest +first. Use the always-positive monthly totals for size (revenue, sales, products); growth is the filter that selects the niches — never present a change figure as a total or as a table column. +Month-over-month revenue growth works on both marketplaces, and the growth ranking +survives on each. On Shopee only about three months of history exist, so compare +the most recent month with the one before it and read nothing longer-run into it. + ## Output Respond in the seller's language (default pt-BR), with no commentary about how the -result was produced. The ranking always renders as a markdown table: +result was produced. Lead with a short line naming the **marketplace**, the parent +category, the **level the ranking is at**, and the month the figures describe. On +Shopee that line also says plainly that niches deeper than the third level are +folded into their level-3 ancestor and cannot be separated here. + +The ranking always renders as a markdown table: | Categoria | Qtd. vendedores | Receita (mês est.) | Vendas (mês est.) | Produtos | |---|--:|--:|--:|--:| -- Exactly these five columns — fast growth is the filter that selects the niches, - not a displayed column. -- Each category links to its JoomPulse category dashboard page. +- Exactly these five columns on both marketplaces — fast growth is the filter that + selects the niches, not a displayed column. +- On Mercado Livre each category links to its JoomPulse category dashboard page. + **There is no JoomPulse category dashboard link for Shopee rows** — leave the + name as plain text and never invent a link. + +**Disclaimer (every report) — use the variant for the marketplace you queried.** -**Disclaimer (every report):** +Mercado Livre: > ⚠️ Receita e vendas são estimativas do JoomPulse com base no histórico de > anúncios — não são transações reais. / Revenue and sales are JoomPulse > estimates based on historical listing data — not actual transactions. +Shopee: + +> ⚠️ Receita e vendas são estimativas do JoomPulse a partir dos contadores +> arredondados da própria Shopee — não são transações reais, e diferenças +> pequenas entre categorias são ruído. / Revenue and sales are JoomPulse +> estimates built from Shopee's own rounded sold counters — not actual +> transactions, and small gaps between categories are noise. + ## Visualization When the client can render inline visuals, present metric cards and a chart; @@ -111,15 +208,23 @@ When inline visuals are available: Presentation rules: any change or difference column uses a word as its header ("Variação" / "Crescimento"), never a bare "Δ" symbol; render a chart only when -the underlying data supports it. +the underlying data supports it. On Shopee, label the visuals with the level the +ranking is at (the third) so nobody reads them as deep leaf niches. ## Notes & Guardrails The seller should never see a system or stack error — only a friendly next step. -- **Flat parent category:** if the chosen category has no sub-categories deeper - than the third level, say so plainly and offer to look at a broader parent - category instead of returning an empty table. +- **Flat parent category:** if the chosen category has nothing below it at the + level this skill ranks — deeper than the third level on Mercado Livre, the third + level on Shopee — say so plainly and offer to look at a broader parent category + instead of returning an empty table. +- **Deeper niches on Shopee:** never fabricate a level below the third and never + present a level-3 row as a deep leaf. Say the platform folds deeper niches into + their level-3 ancestor and offer the item-level route instead. +- **Not enough history:** with only about three months of Shopee history, there + will often be too little to judge growth. Say that honestly rather than lowering + the bar on what counts as fast growth. - **Negative or odd growth:** some niches may be shrinking; surface that honestly rather than hiding it, and never invent a positive trend. - **Market data temporarily unavailable:** retry once quietly; if it is still diff --git a/skills/high-demand-low-quality-finder/SKILL.md b/skills/high-demand-low-quality-finder/SKILL.md index b9e45d2..bab382b 100644 --- a/skills/high-demand-low-quality-finder/SKILL.md +++ b/skills/high-demand-low-quality-finder/SKILL.md @@ -1,27 +1,32 @@ --- name: high-demand-low-quality-finder description: > - Finds Mercado Livre (Brasil) products in one category that have high demand but a low rating - — listings that sell well yet score at or below a rating threshold the user chooses, an - opening to enter with a better offer. Use it when a seller wants weak-rated but well-selling - products to beat. The skill asks for a category and a rating threshold, then returns the - matching active listings ranked by demand, using JoomPulse market data. Triggers: "high - demand low rating products", "low quality opportunities", "products I can beat", and the pt- - BR "produtos com muita demanda e nota baixa", "oportunidades de baixa qualidade", "produtos - mal avaliados que vendem". Sales and revenue are JoomPulse estimates, not real transactions; - price, rating, and reviews are real history. For brand-new listings use the new-growing- - products-in-category skill; for niches without strong incumbents use the uncontested-niche- - finder skill; for one product and its competitors use the ml-product-analysis skill. + Finds products in one category on JoomPulse — Mercado Livre (Brasil) or Shopee + Brasil — that have high demand but a low rating: listings that sell well yet + score at or below a rating threshold the user chooses, an opening to enter with + a better offer. Use it when a seller wants well-selling products to beat. Asks + for a marketplace, a category and a rating threshold, then returns the matching + listings ranked by demand. Triggers: "high demand low rating products", "low + quality opportunities", "products I can beat", "badly rated products on + Shopee"; pt-BR "produtos com muita demanda e nota baixa", + "oportunidades de baixa qualidade", "produtos mal avaliados que vendem", + "produtos mal avaliados na Shopee". Ask which marketplace when unclear; never + mix the two. Sales and revenue are JoomPulse estimates, not real transactions; + price, rating and reviews are real. For brand-new listings use the + new-growing-products-in-category skill; for one product and its competitors, + the ml-product-analysis skill. --- # High-Demand, Low-Quality Finder -This skill surfaces products in one Mercado Livre (Brasil) category that **sell -well but are poorly rated** — listings with strong demand whose rating sits at or -below a threshold the seller chooses. These are the products a seller has the best -chance of beating: the demand is already proven, and a better offer can win on -quality. The result is a ranked product table, ordered by estimated demand, with a -JoomPulse link per product. +This skill surfaces products in one category that **sell well but are poorly +rated** — listings with strong demand whose rating sits at or below a threshold +the seller chooses — on **Mercado Livre (Brasil) or Shopee Brasil**, using +JoomPulse market data. These are the products a seller has the best chance of +beating: the demand is already proven, and a better offer can win on quality. +The result is a ranked product table, ordered by estimated demand. On Mercado +Livre each row links to its JoomPulse page; on Shopee each row links to the item +on Shopee. This is different from finding fresh entrants or empty niches. To find brand-new listings that are already selling in a category, use the new-and-growing-products @@ -33,56 +38,123 @@ category are weak on quality, so I can enter with a better offer?" ## Prerequisites - JoomPulse MCP access is configured for the current agent environment. -- The user provides the **category** (a name or a category identifier) **and** a - **rating threshold** (for example `4.0`). Both are required. -- The available JoomPulse tools can resolve a category and list the active - listings in it with their demand, rating, price, and logistics. +- The user provides a **marketplace** — Mercado Livre (Brasil) or Shopee Brasil — + plus the **category** (a name or a category identifier) **and** a **rating + threshold** (for example `4.0`). All three are required. +- The available JoomPulse tools can resolve a category and list the items in it + on **either** marketplace, and can report, per item, the demand, rating, review + count, price, and the date the item was created. If JoomPulse MCP access is unavailable, stop and explain that the skill requires JoomPulse MCP setup before it can find opportunities. ## Scope -- **Mercado Livre (Brasil) only.** Other marketplaces are out of scope. -- **Sales and revenue are JoomPulse estimates** derived from historical listing - data — not real transactions. Disclose this in every output. By contrast, - **price, rating, and review count are real history** from Mercado Livre — say - so, it is a strength of the report. +- **Mercado Livre (Brasil) and Shopee Brasil**, one at a time. Other marketplaces + are out of scope. +- **Sales and revenue are JoomPulse estimates** — not real transactions. Disclose + this in every output. By contrast, **price, rating, and review count are real + history** from the marketplace — say so, it is a strength of the report. The + estimates are built differently on each marketplace: on Mercado Livre from + historical listing data, on Shopee from the marketplace's own rounded sold + counters refined with review movement. Use the matching disclaimer. - **Read-only.** The skill does not sign in as the seller or modify any listing. - **Language:** detect the seller's language and respond in it. Default to pt-BR. - **Keep the workflow invisible.** The seller wants the answer, not a play-by- play. If one approach does not return data, switch to another quietly; only if every approach fails do you say one short, friendly sentence. +**Shopee data — what differs from Mercado Livre** + +- **Estimates come from Shopee's own rounded sold counters**, refined with review + movement. Treat small gaps between items as noise and never rank on a difference + of a few units. Price, rating and review count are real. +- **Coverage is not a census**: only items with at least one lifetime sale are + tracked, so any count is a lower bound and an absent item is not evidence it does + not sell. +- **History starts May 2026** — there is no long-run trend and no seasonal read. +- **Category analytics stop at three levels**; the item view reaches deeper. Say + which you used. +- **No seller medals** — Shopee has three mutually exclusive shop tiers: **Official + store**, **Preferred (Indicado)** and **Common**. There is no ladder; inventing + Shopee medals is fabrication. +- **No catalogue and no buy-box**, and an item belongs to one shop. +- **No fulfilment programme, no free-shipping flag and no listing tier** — show `—` + rather than guessing. +- **Concentration is measured differently** and thresholds do not transfer between + marketplaces. +- Item titles mix Portuguese, English and Chinese — search both languages. + ## Workflow +### Step 0 — Decide the marketplace + +JoomPulse covers **two separate marketplaces**: Mercado Livre (Brasil) and Shopee +Brasil. They are independent datasets with different coverage, history and +mechanics. Decide which one the request belongs to **before reading any data**: + +- **The seller said so.** "Shopee" means Shopee; "Mercado Livre", "MeLi" or "ML" + means Mercado Livre. +- **An identifier gives it away.** An identifier beginning `MLB` is Mercado Livre; + a bare 10–11 digit number is a Shopee item or shop. A `mercadolivre.com.br` link + is Mercado Livre, a `shopee.com.br` link is Shopee. If an identifier is not found + on the marketplace you assumed, check the other one before telling the seller it + does not exist. +- **The request only makes sense on one of them** — buy-box, catalogue position, + seller medals, a fulfilment programme or search keywords are Mercado Livre only. +- **Otherwise ask** — one short question, mentioning that both are available. + **Never guess and never default.** + +**Never mix data from the two marketplaces in one query, one table or one total.** +They are separate pipelines with different grains and estimate methods; a combined +figure is simply wrong. If the seller wants both, run the analysis twice and report +the two side by side, comparing direction and orders of magnitude — never exact +numbers. + ### Step 1 — Collect the inputs 1. Ask the user for both the **category** and the **rating threshold**. Both are - required before you proceed. -2. Resolve the user's category text to a category identifier. If they gave a name, - look it up in JoomPulse and confirm the match if it is ambiguous; if they gave - an identifier, use it directly. + required, on top of the marketplace from Step 0, before you proceed. +2. Resolve the user's category text to a category identifier, matching the current + category list **for the chosen marketplace**. If they gave a name, look it up in + JoomPulse and confirm the match if it is ambiguous; if they gave an identifier, + use it directly. On Shopee, category analytics stop at three levels — if the + seller names a deeper niche, work it through the item view instead and say which + you used. 3. The rating threshold becomes the upper bound: keep only products whose rating is **at or below** the chosen value. -### Step 2 — Pull the category's listings +### Step 2 — Pull the category's items -Use JoomPulse to obtain the active listings in the chosen category whose rating is -at or below the threshold. For each listing, gather the data needed for the table: -estimated weekly sales and revenue, estimated monthly demand, rating, review -count, price, time on air, free shipping, Mercado Envios Full, listing type, and -seller medal. +Use JoomPulse to obtain the items in the chosen category, with the fields each row +needs. Pull a generous set so the filters have room to work. + +- **Mercado Livre:** the **active listings** whose rating is at or below the + threshold, with name, seller, price, estimated weekly sales and revenue, + estimated monthly demand, rating, review count, time on air, free shipping, + Mercado Envios Full, listing type, and seller medal. +- **Shopee:** name, shop, shop tier (Official store / Preferred (Indicado) / + Common), price, **estimated sales and revenue over the last 30 days**, rating, + review count, the date the item was created, and the date it was last seen. + Time on air is computed from the creation date. There is no listing-status + filter on Shopee — how recently an item was last seen is what tells you whether + it is still live, so check it and never present a stale row as a live + opportunity. ### Step 3 — Filter and rank +- **On Shopee, require at least one review before applying the rating threshold.** + An item nobody has reviewed reports a rating of **zero**, not a blank, so a plain + "rating at or below the threshold" filter sweeps every unreviewed item into the + shortlist and labels proven-nothing items as low-quality. The review floor is + what makes the result mean "poorly rated" instead of "never rated". - Defensively drop any row whose rating is above the threshold, and ignore rows with no rating at all unless the user asks to include them. -- **Rank by estimated monthly demand**, highest first, so the high-demand, - low-quality products surface at the top (use estimated weekly revenue as a - tiebreaker). This monthly-demand figure is the ranking metric, so it must - appear as its own column in the table — never rank on a number the table does - not show. +- **Rank by estimated demand**, highest first, so the high-demand, low-quality + products surface at the top: estimated monthly demand on Mercado Livre (weekly + revenue as a tiebreaker), estimated 30-day sales on Shopee (30-day revenue as a + tiebreaker). The ranking figure must appear as its own column in the table — + never rank on a number the table does not show. - Keep roughly the top 20–30 rows for the table. ## Output @@ -91,10 +163,13 @@ Respond in the seller's language. Present the result with no commentary about ho it was produced. The product table always renders as markdown so it displays cleanly in any client. -**Product table** — one row per listing, with these columns (pt-BR labels by -default): +Lead with a short intro line naming the **marketplace**, the category and the +rating threshold actually applied. + +**Product table (Mercado Livre)** — one row per listing, with these columns (pt-BR +labels by default): -- product / listing identifier +- product / listing identifier, linked to its JoomPulse page - Nome (name) - Categoria (category) - Vendedor (seller) @@ -110,13 +185,38 @@ default): - Mercado Envios Full - Tipo de anúncio (listing type) - Medalha do vendedor (seller medal) -- A JoomPulse link for the product -Below the table, state the inputs used (the category and the rating threshold) and -that rows are ranked by **estimated monthly demand** (the "Demanda estimada (mês)" -column). When a cell has no value, show `—`; never guess or fabricate. +**Product table (Shopee)** — same shape, with the marketplace's own columns: + +- item identifier, linked to the item on Shopee — **there is no JoomPulse + dashboard link for Shopee rows**, so never invent one +- Nome (name) +- Categoria (category) +- Loja (shop) +- Preço (price) +- Vendas estimadas (30 dias) — estimated 30-day sales (**this is the ranking + metric** on Shopee) +- Receita estimada (30 dias) — estimated 30-day revenue +- Classificação (rating) +- Avaliações (review count) — at least one, by construction +- Tempo do anúncio no ar (time on air) — computed from the item's creation date +- Nível da loja (shop tier) — Official store / Preferred (Indicado) / Common +- Free shipping, Mercado Envios Full and listing type have **no Shopee + equivalent**: either drop these columns or show `—` in them. Never map a shop + tier onto a seller medal. + +The demand columns are **not** the same window on the two marketplaces: Mercado +Livre reports weekly and monthly figures, Shopee reports 30-day figures only — +label the Shopee columns as 30 days and never present a 30-day figure under a +weekly heading. + +Below the table, state the inputs used (the marketplace, the category and the +rating threshold) and which column the rows are ranked by. When a cell has no +value, show `—`; never guess or fabricate. -**Disclaimer (every report):** +**Disclaimer (every report) — use the variant for the marketplace you queried.** + +Mercado Livre: > ⚠️ Sales and revenue are JoomPulse **estimates** based on historical listing > data — they are **not** actual transactions. Price, rating, and reviews are @@ -124,6 +224,18 @@ column). When a cell has no value, show `—`; never guess or fabricate. > com base no histórico de anúncios — **não são transações reais**. Preço, > classificação e número de avaliações são histórico real do Mercado Livre. +Shopee: + +> ⚠️ Sales and revenue are JoomPulse **estimates** built from Shopee's own +> rounded sold counters — they are **not** actual transactions, and small gaps +> between items are noise. Only items with at least one lifetime sale are +> tracked, so this list is a lower bound. Price, rating, and reviews are real +> Shopee history. / Vendas e receita são **estimativas** do JoomPulse a partir +> dos contadores arredondados da própria Shopee — **não são transações reais**, e +> diferenças pequenas entre itens são ruído. Só itens com pelo menos uma venda no +> histórico são rastreados, então esta lista é um piso. Preço, classificação e +> avaliações são histórico real da Shopee. + ## Visualization When the client can render inline visuals, present metric cards and a chart on top @@ -134,23 +246,27 @@ table as markdown, with no chart. **Metric cards (three):** - **Oportunidades encontradas** — the count of products kept (rows in the table). -- **Demanda total** — the estimated monthly demand summed across the kept rows. +- **Demanda total** — the estimated demand summed across the kept rows, over the + window the marketplace reports (monthly on Mercado Livre, 30 days on Shopee). - **Nota média** — the average rating across the kept rows. It will be low by construction; label it as the low-quality signal. **Demand × rating chart:** one point per product — demand on the horizontal axis, -rating on the vertical axis, and bubble size by estimated weekly revenue. -Highlight the sweet spot (high demand, low rating — the bottom-right) by drawing -those points in **coral**, with all other points muted/grey: these are exactly the -products worth beating. **Skip the chart when there are fewer than five points** — -show the table only; no graph for the sake of a graph. +rating on the vertical axis, and bubble size by estimated revenue over the same +window as the demand axis (weekly revenue on Mercado Livre, 30-day revenue on +Shopee). Highlight the sweet spot (high demand, low rating — the bottom-right) by +drawing those points in **coral**, with all other points muted/grey: these are +exactly the products worth beating. **Skip the chart when there are fewer than +five points** — show the table only; no graph for the sake of a graph. Presentation rules: - Round numbers and format them in **pt-BR** (for example `R$ 1.234`, `1.234 vendas/mês`, rating `3,8`). -- Use the medal palette for any seller-medal styling: platina = purple, - ouro = amber, prata = blue, sem medalha = white with a thin border. +- The medal palette is **Mercado Livre only**: platina = purple, ouro = amber, + prata = blue, sem medalha = white with a thin border. On Shopee there are no + medals — write the shop tier as plain text and never colour it as if it were a + rung on a ladder. - Keep the ⚠️ estimate disclaimer on every output that shows estimated sales or revenue. @@ -170,10 +286,15 @@ The seller should never see a system or stack error — only a friendly next ste in this category — suggest **lowering** the threshold to focus on the truly weak-rated products, or trying a different category. Always frame it as adjusting the threshold in the sensible direction for the - value they gave. + value they gave. On Shopee, add that the list is a lower bound — only items with + at least one lifetime sale are tracked, and unreviewed items are excluded on + purpose — so an empty result is not proof the niche is all well-rated. - **Category not found or ambiguous:** ask the user to confirm the exact category - or to provide its category identifier. + or to provide its category identifier. If nothing matches, check the other + marketplace before saying the category does not exist. - **Market data temporarily unavailable:** retry once quietly; if it is still down, say market data is temporarily unavailable and offer to retry. Never paste internal error text, HTTP codes, or field names to the seller. -- **Empty cells:** show `—`; never guess or fabricate a value. +- **Empty cells:** show `—`; never guess or fabricate. On Shopee, free shipping, + the fulfilment programme and the listing tier are always `—` — that is an absent + attribute, not a missing value, and never a "Não". diff --git a/skills/ml-product-analysis/SKILL.md b/skills/ml-product-analysis/SKILL.md index b66c33c..7861b89 100644 --- a/skills/ml-product-analysis/SKILL.md +++ b/skills/ml-product-analysis/SKILL.md @@ -1,28 +1,31 @@ --- name: ml-product-analysis 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. + Analyzes one product and its competitors on JoomPulse — Mercado Livre (Brasil) + or Shopee Brasil. From a marketplace link, a JoomPulse link, a photo, or a row + of data, it returns a card for the subject product plus a ranked table of + comparable items, each with price, estimated monthly sales and revenue, rating + and reviews; on Mercado Livre also logistics and catalog / buy-box status, + which do not exist on Shopee. Triggers: "analyze this product", "how much does + this sell", "find similar products", "find competing products"; pt-BR + "analisar este produto", "quanto vende esse produto", "produtos parecidos", + "produtos concorrentes", "análise por foto", "analisar este produto da + Shopee", "quanto vende esse produto na Shopee", "concorrentes na Shopee". Ask + which marketplace when unclear; never mix the two. Sales and revenue are + JoomPulse estimates, not real transactions; price, rating and reviews are real. + For which products to add across a whole catalog, use the gap-analysis skill. --- -# Mercado Livre Single-Product Analysis +# Single-Product Analysis -This skill analyzes **one** Mercado Livre (Brasil) product and the products that -compete with it. Given a single product — by a Mercado Livre link, a JoomPulse -link, a photo, or a row of data — it identifies the product, finds comparable -listings, and returns a product card for the subject plus a ranked table of -analogs. For each product it shows price, estimated monthly sales and revenue, -logistics, and catalog / buy-box status. +This skill analyzes **one** product and the products that compete with it, on +**Mercado Livre (Brasil) or Shopee Brasil**, using JoomPulse market data. Given a +single product — by a marketplace link, a JoomPulse link, a photo, or a row of +data — it identifies the product, finds comparable listings, and returns a +product card for the subject plus a ranked table of analogs. For each one it +shows price, estimated monthly sales and revenue, rating and reviews; on Mercado +Livre also logistics and catalog / buy-box status. Shopee has no catalogue and no +buy-box, so that part of the analysis is omitted there, not left blank. This is different from whole-catalog assortment analysis. If the user wants to know which new products to add to their store, hand off to the gap-analysis @@ -31,21 +34,28 @@ skill. This skill works on a single product the seller already has in hand. ## Prerequisites - JoomPulse MCP access is configured for the current agent environment. -- The user provides one product as a Mercado Livre link, a JoomPulse link, a - product photo, or a row of data (a `.csv` / `.xlsx` file, a pasted table, or - typed fields). -- The available JoomPulse tools can look up product market data and search for - comparable listings. +- The user provides a marketplace — Mercado Livre (Brasil) or Shopee Brasil — and + one product on it: a marketplace link, a JoomPulse link, a product photo, or a + row of data (a `.csv` / `.xlsx` file, a pasted table, or typed fields). +- The available JoomPulse tools can look up product market data on **either** + marketplace and find comparable listings. The ways of finding comparables + differ: on Mercado Livre by image, by meaning, by category and by keyword; on + Shopee only by category and by title text. If JoomPulse MCP access is unavailable, stop and explain that the skill requires JoomPulse MCP setup before it can analyze a product or find competitors. ## Scope -- **Mercado Livre (Brasil) only.** Other marketplaces are out of scope. -- **Sales and revenue are JoomPulse estimates** derived from historical listing - data — not real transactions. Disclose this in every output. -- **Prices are Mercado Livre prices only.** Do not surface sourcing prices, +- **Mercado Livre (Brasil) and Shopee Brasil**, one at a time. Other marketplaces + are out of scope. +- **Sales and revenue are JoomPulse estimates** — not real transactions. Disclose + this in every output. By contrast, **price, rating, and review count are real + history** from the marketplace — say so. The estimates are built differently on + each marketplace: on Mercado Livre from historical listing data, on Shopee from + the marketplace's own rounded sold counters refined with review movement. Use + the matching disclaimer. +- **Prices are marketplace prices only.** Do not surface sourcing prices, margins, or profit figures. - **Read-only.** The skill does not sign in as the seller or modify any listing. - **Language:** detect the seller's language and respond in it. Default to @@ -55,7 +65,54 @@ JoomPulse MCP setup before it can analyze a product or find competitors. finding the product or its competitors does not work, switch to another silently; only if every approach fails do you say one short, friendly sentence. -## Input Router +**Shopee data — what differs from Mercado Livre** + +- **Estimates come from Shopee's own rounded sold counters**, refined with review + movement. Treat small gaps between items as noise and never rank on a difference + of a few units. Price, rating and review count are real. +- **Coverage is not a census**: only items with at least one lifetime sale are + tracked, so any count is a lower bound and an absent item is not evidence it does + not sell. +- **History starts May 2026** — there is no long-run trend and no seasonal read. +- **Category analytics stop at three levels**; the item view reaches deeper. Say + which you used. +- **No seller medals** — Shopee has three mutually exclusive shop tiers: **Official + store**, **Preferred (Indicado)** and **Common**. There is no ladder; inventing + Shopee medals is fabrication. +- **No catalogue and no buy-box**, and an item belongs to one shop. +- **No fulfilment programme, no free-shipping flag and no listing tier** — show `—` + rather than guessing. +- **Concentration is measured differently** and thresholds do not transfer between + marketplaces. +- Item titles mix Portuguese, English and Chinese — search both languages. + +## Workflow + +### Step 0 — Decide the marketplace + +JoomPulse covers **two separate marketplaces**: Mercado Livre (Brasil) and Shopee +Brasil. They are independent datasets with different coverage, history and +mechanics. Decide which one the request belongs to **before reading any data**: + +- **The seller said so.** "Shopee" means Shopee; "Mercado Livre", "MeLi" or "ML" + means Mercado Livre. +- **An identifier gives it away.** An identifier beginning `MLB` is Mercado Livre; + a bare 10–11 digit number is a Shopee item or shop. A `mercadolivre.com.br` link + is Mercado Livre, a `shopee.com.br` link is Shopee. If an identifier is not found + on the marketplace you assumed, check the other one before telling the seller it + does not exist. +- **The request only makes sense on one of them** — buy-box, catalogue position, + seller medals, a fulfilment programme or search keywords are Mercado Livre only. +- **Otherwise ask** — one short question, mentioning that both are available. + **Never guess and never default.** + +**Never mix data from the two marketplaces in one query, one table or one total.** +They are separate pipelines with different grains and estimate methods; a combined +figure is simply wrong. If the seller wants both, run the analysis twice and report +the two side by side, comparing direction and orders of magnitude — never exact +numbers. + +### Step 1 — Route the input to one subject product Resolve the input to a single normalized subject product, then find analogs. The first matching rule wins: @@ -63,20 +120,22 @@ first matching rule wins: 1. **A photo** → Photo route. 2. **A `.csv` / `.xlsx` file, a pasted table, or typed fields** → Tabular route. 3. **A Mercado Livre link** → MLB route. -4. **A JoomPulse product link** → JoomPulse route. -5. **A JoomPulse store link** → this is a whole store, not one product. Ask for a +4. **A Shopee item link** → Shopee route. +5. **A JoomPulse product link** → JoomPulse route. These exist for Mercado Livre + only; Shopee items have no JoomPulse product page. +6. **A JoomPulse store link** → this is a whole store, not one product. Ask for a specific product link or a product title; whole-store analysis belongs to the gap-analysis skill. -6. **Any other link** (a different marketplace, a generic web page) → do not - scrape it. Explain that only Mercado Livre and JoomPulse links can be resolved - directly, and ask the seller to paste the product name or upload a photo → - Keyword route. -7. **Plain text** (a product name or keywords) → Keyword route. +7. **Any other link** (a different marketplace, a generic web page) → do not + scrape it. Explain that only Mercado Livre, Shopee and JoomPulse links can be + resolved directly, and ask the seller to paste the product name or upload a + photo → Keyword route. +8. **Plain text** (a product name or keywords) → Keyword route. Every route converges on one normalized subject product plus a set of candidate analogs. -### MLB route +#### MLB route 1. Extract the product identifier from the link, noting whether it is a catalog product or an individual listing. @@ -86,70 +145,107 @@ analogs. 3. Fetch JoomPulse market data for the subject. For a catalog product, several competing listings may come back; pick the representative one (the strongest seller / buy-box winner) for the card and read competition from the number of - buy-box sellers and total sellers. + buy-box sellers and total sellers. This step is **Mercado Livre only** — it has + no counterpart on Shopee. 4. Build the subject from that data, then find analogs. -### JoomPulse route +#### Shopee route + +1. A Shopee product link carries **two bare numeric identifiers** — the shop and + the item — with no `MLB`-style prefix and no catalogue-versus-listing + distinction, because an item belongs to a single shop. Read both out of the + link. +2. Fetch the item's Shopee market data: title, category path, brand, current + price and the lowest price seen **since May 2026**, estimated sales and revenue + over the last 30 days, the item's lifetime monthly average and the direction + flag comparing the two, rating, review count, favourites, whether it ships + cross-border, how many photos it has, and the shop with its tier. +3. Check how recently the item was last seen before presenting it as live. +4. Build the subject from that data, then find analogs. **Skip catalogue and + buy-box work entirely** — Shopee has neither, so catalogue status, a buy-box + winner, a buy-box price and a seller count are meaningless there. Omit those + lines instead of leaving them empty. + +#### JoomPulse route Look up the product directly in JoomPulse by its identifier, optionally enriching the title and attributes from the canonical product lookup, then find analogs. - -### Photo route - -Image-based matching is primary; visual inspection is the fallback. Accept common -image formats, including phone formats such as HEIC/HEIF. Always tell the seller -the results are **visually similar — not a guaranteed exact match.** - -1. Use the available JoomPulse image-based product search to find similar - listings from the photo. Alongside the matches, this search can return a quick - opportunity summary — an overall verdict on whether the product is worth - selling, the number of matching listings, and aggregate market stats. For a - fast answer you can present that summary directly (still labeled as a visual - match); otherwise carry the matched listings into the analog pipeline below. -2. If image search is unavailable or returns nothing, inspect the photo yourself: - note the product type, brand and model if legible, color, material, and key - attributes. Turn that into search keywords and run the Keyword route. Label - the subject card as the best visual match, not an exact match. - -### Tabular route +This route is Mercado Livre only. + +#### Photo route + +On **Mercado Livre**, image-based matching is primary and visual inspection is the +fallback. On **Shopee there is no image search at all**, so the photo route there +is always the fallback: read the picture yourself and search by what you see. +Accept common image formats, including phone formats such as HEIC/HEIF. Always +tell the seller the results are **visually similar — not a guaranteed exact +match.** + +1. On Mercado Livre, use the available JoomPulse image-based product search to + find similar listings from the photo. Alongside the matches, this search can + return a quick opportunity summary — an overall verdict on whether the product + is worth selling, the number of matching listings, and aggregate market stats. + For a fast answer you can present that summary directly (still labeled as a + visual match); otherwise carry the matched listings into the analog pipeline + below. +2. If image search is unavailable or returns nothing — and **always on Shopee** — + inspect the photo yourself: note the product type, brand and model if legible, + color, material, and key attributes. Turn that into search terms and run the + Keyword route. Label the subject card as the best visual match, not an exact + match. + +#### Tabular route Normalize the rows into product records (handle pt-BR column headers and -`R$ 1.234,56`-style prices). For each row: if it carries a Mercado Livre -identifier, use the MLB route; otherwise its title drives the Keyword route. One -row yields one subject. For several rows, analyze each — cap at a small number -and say so when you do. +`R$ 1.234,56`-style prices). For each row: an `MLB`-style identifier takes the MLB +route, a bare numeric shop-and-item pair takes the Shopee route, and otherwise its +title drives the Keyword route. One row yields one subject. For several rows, +analyze each — cap at a small number and say so when you do. All rows in one run +must belong to the same marketplace. -### Keyword route +#### Keyword route Build a clean search query from the title or photo description, plus a broadened -fallback query. +fallback query. On Shopee, titles mix Portuguese, English and Chinese, so prepare +**short tokens in both languages** instead of one long phrase. -## Finding Analogs +### Step 2 — Find analogs Both the keyword and photo paths feed the same analog pipeline: -1. **Search for candidates.** Use JoomPulse semantic product search to find - listings similar to the subject, keeping the closest matches. Query in pt-BR - first and English second. If recall is too low, retry once with the broadened - query. For the photo route, the image-search results play this role. +1. **Search for candidates.** + - **Mercado Livre:** use JoomPulse search by meaning to find listings similar + to the subject, keeping the closest matches. Query in pt-BR first and + English second. If recall is too low, retry once with the broadened query. + For the photo route, the image-search results play this role. + - **Shopee:** there is **no image search and no search by meaning**. + Comparables come from the subject's own category plus a title search — and + because titles mix Portuguese, English and Chinese, search **short tokens in + both languages** rather than one long phrase, then merge the hits. 2. **Augment when recall is thin.** Optionally widen the candidate set using - category and keyword search, or constrain to the subject's predicted category. + category and keyword search, or constrain to the subject's category. On Shopee, + category analytics stop at three levels — if the subject sits deeper, work the + comparables through the item view and say which you used. 3. **Merge and drop the subject.** Deduplicate the candidate identifiers and remove the subject itself. -4. **Validate and fetch market data.** Look up the candidates in JoomPulse to - confirm they are active listings and to fetch price, sales, revenue, - logistics, and catalog / buy-box fields. +4. **Validate and fetch market data.** Look up the candidates to confirm they are + live and to fetch the fields each row needs — on Mercado Livre price, sales, + revenue, logistics and catalog / buy-box fields; on Shopee price, 30-day sales + and revenue, the lifetime monthly average and direction, rating, reviews, + favourites, cross-border shipping, photo count and shop tier, with **no + catalogue or buy-box fields at all**. 5. **Rank.** Score each candidate by a blend of similarity to the subject, demand (estimated revenue), and how crowded the listing is, then sort by that score. Drop candidates with no sales. Present a single ranked list — do not - split analogs into thematic sub-tables. + split analogs into thematic sub-tables. On Shopee, never rank on a difference + of a few units: the sold counters are rounded, so small gaps are noise. ## Output Respond in the seller's language. The visible reply contains only the result, in this order, with no commentary about how it was produced: -1. An optional one-line framing sentence. +1. An optional one-line framing sentence, naming the **marketplace**. 2. The subject product card. 3. The ranked analogs table. 4. The disclaimer. @@ -157,48 +253,99 @@ this order, with no commentary about how it was produced: Use plain markdown so it renders cleanly in any client. -**Subject card** — product name and image, category and brand, current price and -historic minimum price, estimated monthly sales and revenue, logistics (Mercado -Envios Full / free shipping / international), catalog / buy-box status (whether it -is in the catalog, the number of buy-box sellers and the buy-box price, and the -total number of sellers), and links to the product on Mercado Livre and on -JoomPulse. On the photo route, label the card as the best visual match, not an -exact match. - -**Analogs table** — one row per comparable product, with the product name, brand, -price (current and historic minimum), estimated monthly sales and revenue, -logistics, catalog / buy-box status, number of sellers, review rating, and a -links column holding the Mercado Livre and JoomPulse links. Keep both links for -every product. You may translate the column headers and card labels into the -seller's language. - -**Disclaimer (every report):** +**Subject card (Mercado Livre)** — product name and image, category and brand, +current price and historic minimum price, estimated monthly sales and revenue, +logistics (Mercado Envios Full / free shipping / international), catalog / +buy-box status (whether it is in the catalog, the number of buy-box sellers and +the buy-box price, and the total number of sellers), and links to the product on +Mercado Livre and on JoomPulse. On the photo route, label the card as the best +visual match, not an exact match. + +**Subject card (Shopee)** — same shape with the marketplace's own fields: item +title and image, category path and brand, current price and the lowest price +**since May 2026** (label it that way — it is not an all-time low), estimated +sales and revenue over the last 30 days, the item's lifetime monthly average with +the direction flag comparing the two, rating, review count, favourites, whether +it ships cross-border, photo count, the shop and its tier (Official store / +Preferred (Indicado) / Common), and links to the item and the shop on Shopee — +**there is no JoomPulse product page for Shopee items**, so never invent one. +**Omit catalogue status, buy-box sellers, the buy-box price and the seller +count** — they do not exist on Shopee, so leave the lines out rather than showing +them empty. Free shipping, the fulfilment programme and the listing tier have no +Shopee equivalent either: omit them or show `—`, never a "Não". + +**Analogs table (Mercado Livre)** — one row per comparable product, with the +product name, brand, price (current and historic minimum), estimated monthly +sales and revenue, logistics, catalog / buy-box status, number of sellers, review +rating, and a links column holding the Mercado Livre and JoomPulse links. Keep +both links for every product. + +**Analogs table (Shopee)** — one row per comparable item, with the item name, +brand, price (current and the lowest since May 2026), estimated sales and revenue +over the last 30 days, the lifetime monthly average and the direction flag, +rating, reviews, favourites, cross-border shipping, photo count, shop tier, and a +links column holding the item and shop links on Shopee. **No catalogue, buy-box +or seller-count columns** — drop them, do not leave them blank. + +You may translate the column headers and card labels into the seller's language. +Note that the sales windows are **not** the same on the two marketplaces: Mercado +Livre reports weekly and monthly figures, Shopee reports 30-day figures only — +label the Shopee columns as 30 days and never present a 30-day figure under a +weekly or monthly heading. Empty field → `—`; never guess or fabricate. + +**Disclaimer (every report) — use the variant for the marketplace you queried.** + +Mercado Livre: > ⚠️ Sales and revenue are JoomPulse **estimates** based on historical listing -> data — they are **not** actual transactions. / Vendas e receita são -> **estimativas** do JoomPulse com base no histórico de anúncios — **não são -> transações reais**. +> data — they are **not** actual transactions. Price, rating, and reviews are +> real Mercado Livre history. / Vendas e receita são **estimativas** do JoomPulse +> com base no histórico de anúncios — **não são transações reais**. Preço, +> classificação e avaliações são histórico real do Mercado Livre. + +Shopee: + +> ⚠️ Sales and revenue are JoomPulse **estimates** built from Shopee's own +> rounded sold counters — they are **not** actual transactions, and small gaps +> between items are noise. Only items with at least one lifetime sale are +> tracked, so this list is a lower bound. Price, rating, and reviews are real +> Shopee history. / Vendas e receita são **estimativas** do JoomPulse a partir +> dos contadores arredondados da própria Shopee — **não são transações reais**, e +> diferenças pequenas entre itens são ruído. Só itens com pelo menos uma venda no +> histórico são rastreados, então esta lista é um piso. Preço, classificação e +> avaliações são histórico real da Shopee. **Download** — offer a downloadable spreadsheet (`.xlsx` plus `.csv`) of the -subject and analogs, with separate Mercado Livre and JoomPulse link columns so -the seller can see the source of every product's data. +subject and analogs. On Mercado Livre give separate Mercado Livre and JoomPulse +link columns so the seller can see the source of every product's data; on Shopee +give the item and shop link columns instead, and use the Shopee column set. ## Notes & Guardrails The seller should never see a system or stack error — only a friendly next step. +- **Wrong marketplace assumed:** if an identifier or link is not found on the + marketplace you assumed, check the other one before telling the seller the + product does not exist. - **Subject not tracked in JoomPulse / no sales:** JoomPulse tracks products that have sales, so a product may not be tracked. Say so, show whatever canonical product facts are available, and still surface analogs by category or keywords. + On Shopee, coverage is a lower bound — only items with at least one lifetime + sale are tracked — so an absent item is not proof that it does not sell. - **Valid product, no market data:** show the canonical product facts and note - that there is no JoomPulse estimate; draw analogs from the predicted category. -- **Photo:** image search first; if it is unavailable or empty, switch silently - to visual inspection plus keywords. Always label results as similar, not exact; - if the match is ambiguous, show the top candidates and ask the seller to - confirm. + that there is no JoomPulse estimate; draw analogs from the item's category. +- **Photo:** on Mercado Livre, image search first, then visual inspection if it is + unavailable or empty; on Shopee there is no image search, so go straight to + visual inspection plus a title and category search. Always label results as + similar, not exact; if the match is ambiguous, show the top candidates and ask + the seller to confirm. - **Search returns nothing:** an empty result for a niche or non-pt-BR query is - normal — retry once with an English or broadened query, then move on. If search - is temporarily unavailable, say so briefly and rely on the other data. + normal — retry once with an English or broadened query, then move on. On Shopee, + also try short tokens in the other language before giving up. If search is + temporarily unavailable, say so briefly and rely on the other data. +- **No catalogue or buy-box on Shopee:** never present catalogue status, a buy-box + winner, a buy-box price or a seller count for a Shopee item, and never map a + shop tier onto a Mercado Livre seller medal — both are fabrication. - **Market data temporarily unavailable:** retry once quietly; if it is still down, say market data is temporarily unavailable. Never paste internal error text, HTTP codes, or field names to the seller. diff --git a/skills/my-product-vs-catalog/SKILL.md b/skills/my-product-vs-catalog/SKILL.md index 2a6032b..c4a8691 100644 --- a/skills/my-product-vs-catalog/SKILL.md +++ b/skills/my-product-vs-catalog/SKILL.md @@ -50,7 +50,11 @@ JoomPulse MCP setup before it can compare a listing against its catalog. ## Scope -- **Mercado Livre (Brasil) only.** Other marketplaces are out of scope. +- **Mercado Livre (Brasil) only.** JoomPulse also covers Shopee Brasil, but + **Shopee has no catalogue and no buy-box** — an item belongs to one shop, so + there is no set of rival offers on the same product to be measured against and + no buy-box to win. This analysis therefore exists only for Mercado Livre; never + apply its logic or its verdict wording to a Shopee item. - **It compares within one catalog product.** The comparison is the seller versus the other sellers of the same catalog product (the same buy-box), not a search for similar products. @@ -136,6 +140,14 @@ Respond in pt-BR, leading with the verdict: ## Edge Cases +- **The item is on Shopee, not Mercado Livre:** say plainly that Shopee has no + catalogue and no buy-box, so there is no rival-offer set on the same product to + compare against — the question cannot be answered there, and Mercado Livre logic + must not be borrowed. Offer the nearest real alternative: how the item compares + with others in its Shopee category on price, rating and reviews, labelled as a + public-market comparison rather than a buy-box verdict. If the marketplace is + unclear, ask first — an identifier beginning `MLB` is Mercado Livre, a bare + 10–11 digit number is Shopee. - **The input is a catalog product, not a single listing:** ask which listing is the seller's before comparing. - **The product is not part of a catalog:** there is no shared buy-box to compete in; diff --git a/skills/new-growing-products-in-category/SKILL.md b/skills/new-growing-products-in-category/SKILL.md index 16b0474..e2f1f44 100644 --- a/skills/new-growing-products-in-category/SKILL.md +++ b/skills/new-growing-products-in-category/SKILL.md @@ -1,28 +1,29 @@ --- name: new-growing-products-in-category description: > - Finds new, already-selling product listings inside one Mercado Livre (Brasil) - category on JoomPulse — recent listings (by default under about 30 days on air) - that are well rated (rating above 3) and have real traction (more than about 30 - estimated sales in the last month), all thresholds overridable — and returns - them as a product table with a JoomPulse link per listing. Use it when a seller - wants fresh, promising entrants in a niche. Triggers include: "new products in - category", "what's launching and already selling", "recent best-sellers in - my category", and the pt-BR equivalents "produtos novos na categoria", "novos - anúncios que já vendem", "lançamentos em alta na minha categoria". Mercado Livre - (Brasil) only; sales and revenue are JoomPulse estimates, not real transactions, - while price, rating, and review count are real history. For weak-rated but - well-selling products to beat, use the high-demand low-quality skill; for - tracking one product over time, use the product change-monitor skill. + Finds new, already-selling listings in one category on JoomPulse — Mercado + Livre (Brasil) or Shopee Brasil. Keeps listings that are recent (default: under + about 30 days on air), well rated (above 3) and have real traction (about 30+ + estimated monthly sales); all thresholds overridable. Returns a product table. + Use when a seller wants fresh, promising entrants in a niche. Triggers: "new + products in category", "what's launching and already selling", "recent + best-sellers in my category", "new products on Shopee"; pt-BR "produtos novos + na categoria", "novos anúncios que já vendem", "lançamentos em alta na minha + categoria", "produtos novos na Shopee", "novidades na Shopee que já vendem". + Ask which marketplace when unclear; never mix the two. Sales and revenue are + JoomPulse estimates, not real transactions; price, rating and reviews are real. + For well-selling but weak-rated products, use the high-demand low-quality + skill; for one product over time, the change-monitor skill. --- # New & Growing Products in a Category This skill surfaces **newly launched listings that are already selling well** -inside one Mercado Livre (Brasil) category, using JoomPulse market data. The -seller picks a category; the skill returns the recent, well-rated, -traction-having listings as a product table, each row linking to its JoomPulse -page so the seller can dig deeper. +inside one category, on **Mercado Livre (Brasil) or Shopee Brasil**, using +JoomPulse market data. The seller picks a marketplace and a category; the skill +returns the recent, well-rated, traction-having listings as a product table. On +Mercado Livre each row links to its JoomPulse page so the seller can dig deeper; +on Shopee each row links to the item on Shopee. This is a discovery snapshot, not a tracker and not a whole-catalog audit. For products that sell well but are poorly rated — gaps you can enter with a better @@ -33,68 +34,135 @@ fresh entrants in this niche are already getting traction right now?" ## Prerequisites - JoomPulse MCP access is configured for the current agent environment. -- The user provides a category, either by name or by its category identifier. -- The available JoomPulse tools can look up the active listings in a category and - resolve a category name to its identifier. +- The user provides a marketplace — Mercado Livre (Brasil) or Shopee Brasil — and + a category, either by name or by its category identifier. +- The available JoomPulse tools can look up the listings in a category and resolve + a category name to its identifier on **either** marketplace, and can report, + per listing, the price, rating, review count, estimated sales and revenue, and + the date the listing was created. If JoomPulse MCP access is unavailable, stop and explain that the skill requires JoomPulse MCP setup before it can find new growing products in a category. ## Scope -- **Mercado Livre (Brasil) only.** Other marketplaces are out of scope. -- **Sales and revenue are JoomPulse estimates** derived from historical listing - data — not real transactions. Disclose this in every output. By contrast, - **price, rating, and review count are real history** from Mercado Livre — say - so, it is a strength of the report. +- **Mercado Livre (Brasil) and Shopee Brasil**, one at a time. Other marketplaces + are out of scope. +- **Sales and revenue are JoomPulse estimates** — not real transactions. Disclose + this in every output. By contrast, **price, rating, and review count are real + history** from the marketplace — say so, it is a strength of the report. The + estimates are built differently on each marketplace: on Mercado Livre from + historical listing data, on Shopee from the marketplace's own rounded sold + counters refined with review movement. Use the matching disclaimer. - **Read-only.** The skill does not sign in as the seller or modify any listing. - **Language:** detect the seller's language and respond in it. Default to pt-BR. - **Keep the workflow invisible.** The seller wants the answer, not a play-by- play. If one approach does not return data, switch to another quietly; only if every approach fails do you say one short, friendly sentence. +**Shopee data — what differs from Mercado Livre** + +- **Estimates come from Shopee's own rounded sold counters**, refined with review + movement. Treat small gaps between items as noise and never rank on a difference + of a few units. Price, rating and review count are real. +- **Coverage is not a census**: only items with at least one lifetime sale are + tracked, so any count is a lower bound and an absent item is not evidence it does + not sell. +- **History starts May 2026** — there is no long-run trend and no seasonal read. +- **Category analytics stop at three levels**; the item view reaches deeper. Say + which you used. +- **No seller medals** — Shopee has three mutually exclusive shop tiers: **Official + store**, **Preferred (Indicado)** and **Common**. There is no ladder; inventing + Shopee medals is fabrication. +- **No catalogue and no buy-box**, and an item belongs to one shop. +- **No fulfilment programme, no free-shipping flag and no listing tier** — show `—` + rather than guessing. +- **Concentration is measured differently** and thresholds do not transfer between + marketplaces. +- Item titles mix Portuguese, English and Chinese — search both languages. + ## Workflow +### Step 0 — Decide the marketplace + +JoomPulse covers **two separate marketplaces**: Mercado Livre (Brasil) and Shopee +Brasil. They are independent datasets with different coverage, history and +mechanics. Decide which one the request belongs to **before reading any data**: + +- **The seller said so.** "Shopee" means Shopee; "Mercado Livre", "MeLi" or "ML" + means Mercado Livre. +- **An identifier gives it away.** An identifier beginning `MLB` is Mercado Livre; + a bare 10–11 digit number is a Shopee item or shop. A `mercadolivre.com.br` link + is Mercado Livre, a `shopee.com.br` link is Shopee. If an identifier is not found + on the marketplace you assumed, check the other one before telling the seller it + does not exist. +- **The request only makes sense on one of them** — buy-box, catalogue position, + seller medals, a fulfilment programme or search keywords are Mercado Livre only. +- **Otherwise ask** — one short question, mentioning that both are available. + **Never guess and never default.** + +**Never mix data from the two marketplaces in one query, one table or one total.** +They are separate pipelines with different grains and estimate methods; a combined +figure is simply wrong. If the seller wants both, run the analysis twice and report +the two side by side, comparing direction and orders of magnitude — never exact +numbers. + ### Step 1 — Capture the category and confirm the thresholds 1. Ask the user for the **category** — a name or a category identifier. -2. The skill keeps three filters, each with a **default the user may override**: +2. The skill keeps three filters, each with a **default the user may override**. + All three work on both marketplaces: - **recently listed** — under about 30 days on air; - **well rated** — rating above 3; - **real traction** — more than about 30 estimated sales in the last month. -3. Echo back what you captured (the category plus the three thresholds in use) so - the user can adjust before you run, then remember those inputs for the rest of - the run. +3. Echo back what you captured (the marketplace, the category and the three + thresholds in use) so the user can adjust before you run, then remember those + inputs for the rest of the run. 4. If the user gave a category **name**, resolve it to its identifier first with - JoomPulse, matching the current category list. If the name is ambiguous, list - the candidate categories with their level and ask which one. If the user - already gave an identifier, skip resolution. + JoomPulse, matching the current category list **for the chosen marketplace**. + If the name is ambiguous, list the candidate categories with their level and + ask which one. If the user already gave an identifier, skip resolution. On + Shopee, category analytics stop at three levels — if the seller names a deeper + niche, work it through the item view instead and say which you used. ### Step 2 — Find the new, already-selling listings -1. Use JoomPulse to retrieve the **active listings** in that category, with the - fields each row needs: name, seller, listing type, seller medal, free shipping - and Mercado Envios Full flags, price, estimated weekly sales and revenue, - estimated monthly sales, rating, review count, and how long the listing has - been on air. Pull a generous set of listings so the filters have room to work. -2. **Apply the three filters** to the retrieved listings: keep only those that +1. Use JoomPulse to retrieve the listings in that category, with the fields each + row needs. Pull a generous set so the filters have room to work. + - **Mercado Livre:** the **active listings**, with name, seller, listing type, + seller medal, free shipping and Mercado Envios Full flags, price, estimated + weekly sales and revenue, estimated monthly sales, rating, review count, and + how long the listing has been on air. + - **Shopee:** name, shop, shop tier (Official store / Preferred (Indicado) / + Common), price, **estimated sales and revenue over the last 30 days**, rating, + review count, the date the item was created, and the date it was last seen. + There is no listing-status filter on Shopee — how recently an item was last + seen is what tells you whether it is still live, so check it and never + present a stale row as a live opportunity. +2. **Work out how long each listing has been on air.** On Shopee this is computed + from the item's creation date. +3. **Apply the three filters** to the retrieved listings: keep only those that are recently listed (under the day-on-air threshold), well rated (above the rating threshold), and have real traction (above the monthly-sales threshold). -3. **Sort the survivors strongest-first** by estimated monthly sales, breaking - ties by estimated weekly revenue, so the most promising fresh entrants are on - top. + On Shopee, **also require at least one review** — rating is absent for items + nobody has reviewed, and without this guard unreviewed items slip through the + rating gate unchecked. +4. **Sort the survivors strongest-first** by estimated monthly sales, breaking + ties by estimated revenue over the same window, so the most promising fresh + entrants are on top. ## Output Respond in the seller's language. Present the result with no commentary about how it was produced. Use plain markdown so it renders cleanly in any client. -Lead with a short intro line naming the category and the three thresholds -actually applied, and state that the listings are **ranked by estimated monthly -sales** (ties broken by estimated weekly revenue). +Lead with a short intro line naming the **marketplace**, the category and the +three thresholds actually applied, and state that the listings are **ranked by +estimated monthly sales** (ties broken by estimated revenue over the same +window). -**Product table** — one row per surviving listing, ranked by estimated monthly -sales, in this order: +**Product table (Mercado Livre)** — one row per surviving listing, ranked by +estimated monthly sales, in this order: - Listing identifier (the Mercado Livre code), linked to its JoomPulse page - Name @@ -112,11 +180,37 @@ sales, in this order: - Listing type - Seller medal -Empty field → `—`; never guess or fabricate. Below the table, list the Mercado -Livre codes explicitly, each as a clickable JoomPulse link, so they are easy to -copy. You may translate the column headers into the seller's language. +**Product table (Shopee)** — same shape, with the marketplace's own columns: + +- Item identifier, linked to the item on Shopee — **there is no JoomPulse + dashboard link for Shopee rows**, so never invent one +- Name +- Shop +- Price +- Estimated sales (30 days) — the ranking metric and the figure behind the + traction filter +- Estimated revenue (30 days) +- Rating +- Reviews +- Time on air (days) — computed from the date the item was created +- Shop tier — Official store / Preferred (Indicado) / Common +- Free shipping, Mercado Envios Full and listing type have **no Shopee + equivalent**: either drop these columns or show `—` in them. Never map a shop + tier onto a seller medal. + +Note that the two sales columns are **not** the same window on the two +marketplaces: Mercado Livre reports weekly and monthly figures, Shopee reports +30-day figures only — label the Shopee columns as 30 days and never present a +30-day figure under a weekly heading. -**Disclaimer (every report):** +Empty field → `—`; never guess or fabricate. Below the table, list the item codes +explicitly so they are easy to copy — as clickable JoomPulse links on Mercado +Livre, as Shopee item links on Shopee. You may translate the column headers into +the seller's language. + +**Disclaimer (every report) — use the variant for the marketplace you queried.** + +Mercado Livre: > ⚠️ Sales and revenue are JoomPulse **estimates** based on historical listing > data — they are **not** actual transactions. Price, rating, and reviews are @@ -124,6 +218,18 @@ copy. You may translate the column headers into the seller's language. > com base no histórico de anúncios — **não são transações reais**. Preço, > classificação e avaliações são histórico real do Mercado Livre. +Shopee: + +> ⚠️ Sales and revenue are JoomPulse **estimates** built from Shopee's own +> rounded sold counters — they are **not** actual transactions, and small gaps +> between items are noise. Only items with at least one lifetime sale are +> tracked, so this list is a lower bound. Price, rating, and reviews are real +> Shopee history. / Vendas e receita são **estimativas** do JoomPulse a partir +> dos contadores arredondados da própria Shopee — **não são transações reais**, e +> diferenças pequenas entre itens são ruído. Só itens com pelo menos uma venda no +> histórico são rastreados, então esta lista é um piso. Preço, classificação e +> avaliações são histórico real da Shopee. + ## Visualization When the client can render inline visuals, present metric cards and, when the @@ -139,14 +245,17 @@ it is the main deliverable. - **Idade média (dias no ar)** — average time on air. - **Top-N bar (optional)** — the strongest new products by estimated monthly sales. Label each bar with a short product name (truncate long ones) plus its - Mercado Livre code. **Render this chart only when the data supports it** — skip - it when fewer than four listings survive; the cards and table are enough. + item code — the Mercado Livre code, or the Shopee item identifier. **Render + this chart only when the data supports it** — skip it when fewer than four + listings survive; the cards and table are enough. This is a discovery list, not a week-over-week tracker, so it has **no change or "Variação" column and no 🟢/🔴/🆕 legend** — those belong only to trackers that compare runs. Use a neutral color ramp for the bar (no semantic coloring). If you ever show seller medals as colored chips, use the standard palette: platina = -purple, ouro = amber, prata = blue, sem medalha = white with a thin border. +purple, ouro = amber, prata = blue, sem medalha = white with a thin border. On +Shopee there are no medals — write the shop tier as plain text and never colour +it as if it were a rung on a ladder. **Formatting (both surfaces):** round numbers and use pt-BR formatting — prices and revenue as `R$` with `.` thousands and `,` decimals (e.g. `R$ 1.234,50`); @@ -161,10 +270,15 @@ The seller should never see a system or stack error — only a friendly next ste - **No listings survive the filters:** say that no new listings currently match these thresholds in this category, and offer to relax them (for example, a larger day-on-air window or a lower monthly-sales floor). Keep it in pt-BR. + On Shopee, add that the list is a lower bound — only items with at least one + lifetime sale are tracked — so an empty result is not proof the niche is quiet. - **Category not found or ambiguous name:** list the candidate categories (name - and level) and ask the user to pick one. + and level) and ask the user to pick one. If nothing matches, check the other + marketplace before saying the category does not exist. - **Empty fields:** show `—` for any value that is missing; never assume "no" for - an unknown logistics flag and never fabricate a number. + an unknown logistics flag and never fabricate a number. On Shopee, free + shipping, the fulfilment programme and the listing tier are always `—` — that + is an absent attribute, not a missing value, and never a "Não". - **Market data temporarily unavailable:** retry once quietly; if it is still down, say market data is temporarily unavailable and to try again shortly. Never paste internal error text, HTTP codes, or field names to the seller. diff --git a/skills/popular-international-products/SKILL.md b/skills/popular-international-products/SKILL.md index e58c009..761887d 100644 --- a/skills/popular-international-products/SKILL.md +++ b/skills/popular-international-products/SKILL.md @@ -1,72 +1,160 @@ --- name: popular-international-products description: > - Finds fast-growing international (imported) products inside ONE chosen Mercado - Livre (Brasil) category, using JoomPulse, and returns them as a product table - with price, estimated weekly sales and revenue, rating, reviews, time on air, - shipping, listing type and seller medal, a JoomPulse link per item, and a - pointer to JoomPro for sourcing. Use it when a seller wants the trending - imported items in a specific category. Triggers include: "popular international - products in this category", "fast-growing imported products", and the pt-BR - equivalents "produtos internacionais em alta nessa categoria", "produtos - importados que mais crescem", "achados internacionais para importar". Sales and - revenue are JoomPulse estimates, not real transactions. For the same search - across all categories at once, use the all-categories international skill. + Finds fast-growing international (imported) products inside ONE chosen category + on JoomPulse — Mercado Livre (Brasil) or Shopee Brasil — and returns them as a + product table with price, estimated sales and revenue, rating, reviews, time on + air and the seller's standing. On Mercado Livre each row links to its JoomPulse + page and points to JoomPro for sourcing; on Shopee each row links to the item + and sourcing data is not available. Use when a seller wants the trending + imported items in one category. Triggers: "popular international products in + this category", "fast-growing imported products", "cross-border products on + Shopee"; pt-BR "produtos internacionais em alta nessa categoria", "produtos + importados que mais crescem", "produtos internacionais na Shopee", "produtos + que vêm de fora na Shopee". Ask which marketplace when unclear; never mix the + two. Sales and revenue are JoomPulse estimates, not real transactions. For the + same search across all categories, use the all-categories international skill. --- # Popular International Products -This skill looks inside **one** Mercado Livre (Brasil) category and returns the -**fast-growing international (imported) products** in it — items flagged as -cross-border, ranked by recent momentum. For each it shows price, estimated -weekly sales and revenue, rating, reviews, time on air, shipping, listing type -and seller medal, with a JoomPulse link per item and a pointer to JoomPro for -sourcing. +This skill looks inside **one** category on **Mercado Livre (Brasil) or Shopee +Brasil** and returns the **fast-growing international (imported) products** in it +— items that cross the border, ranked by recent momentum. For each it shows price, +estimated sales and revenue, rating, reviews, time on air and the seller's +standing. On Mercado Livre each row links to its JoomPulse page and carries a +pointer to JoomPro for sourcing; on Shopee each row links to the item on Shopee +and there is no sourcing data. -It covers a single category and gives a general JoomPro search link. To scan all -categories at once, use the all-categories international skill. +It covers a single category at a time. To scan all categories at once, use the +all-categories international skill. ## Prerequisites - JoomPulse MCP access is configured for the current agent environment. -- The user names a category (free text is fine). +- The user provides a marketplace — Mercado Livre (Brasil) or Shopee Brasil — and + names a category (free text is fine). - The available JoomPulse tools can return the active international listings in a - category with their price, estimated sales and revenue, rating, reviews, time - on air, logistics, listing type and seller medal. + category on **either** marketplace, with their price, estimated sales and + revenue, rating, reviews, time on air and the seller's standing — plus, on + Mercado Livre, logistics and listing type. If JoomPulse MCP access is unavailable, stop and explain that the skill requires JoomPulse MCP setup before it can find international products. ## Scope -- **Mercado Livre (Brasil) only.** Other marketplaces are out of scope. -- **Sales and revenue are JoomPulse estimates** derived from historical listing - data — not real transactions. By contrast, price, rating, and review count are - real history. Disclose the estimate caveat in every output. +- **Mercado Livre (Brasil) and Shopee Brasil**, one at a time. Other marketplaces + are out of scope. +- **Sales and revenue are JoomPulse estimates** — not real transactions. By + contrast, price, rating, and review count are real history. Disclose the + estimate caveat in every output. The estimates are built differently on each + marketplace: on Mercado Livre from historical listing data, on Shopee from the + marketplace's own rounded sold counters refined with review movement. Use the + matching disclaimer. - **Read-only.** The skill never writes or modifies anything. - **Language:** detect the seller's language and respond in it. Default to pt-BR. - **Keep the workflow invisible.** Surface the answer, not the steps. Show `—` for any missing value; never fabricate one. +**Shopee data — what differs from Mercado Livre** + +- **Estimates come from Shopee's own rounded sold counters**, refined with review + movement. Treat small gaps between items as noise and never rank on a difference + of a few units. Price, rating and review count are real. +- **Coverage is not a census**: only items with at least one lifetime sale are + tracked, so any count is a lower bound and an absent item is not evidence it does + not sell. +- **History starts May 2026** — there is no long-run trend and no seasonal read. +- **Category analytics stop at three levels**; the item view reaches deeper. Say + which you used. +- **No seller medals** — Shopee has three mutually exclusive shop tiers: **Official + store**, **Preferred (Indicado)** and **Common**. There is no ladder; inventing + Shopee medals is fabrication. +- **No catalogue and no buy-box**, and an item belongs to one shop. +- **No fulfilment programme, no free-shipping flag and no listing tier** — show `—` + rather than guessing. +- **Concentration is measured differently** and thresholds do not transfer between + marketplaces. +- Item titles mix Portuguese, English and Chinese — search both languages. + ## Workflow +### Step 0 — Decide the marketplace + +JoomPulse covers **two separate marketplaces**: Mercado Livre (Brasil) and Shopee +Brasil. They are independent datasets with different coverage, history and +mechanics. Decide which one the request belongs to **before reading any data**: + +- **The seller said so.** "Shopee" means Shopee; "Mercado Livre", "MeLi" or "ML" + means Mercado Livre. +- **An identifier gives it away.** An identifier beginning `MLB` is Mercado Livre; + a bare 10–11 digit number is a Shopee item or shop. A `mercadolivre.com.br` link + is Mercado Livre, a `shopee.com.br` link is Shopee. If an identifier is not found + on the marketplace you assumed, check the other one before telling the seller it + does not exist. +- **The request only makes sense on one of them** — buy-box, catalogue position, + seller medals, a fulfilment programme or search keywords are Mercado Livre only. +- **Otherwise ask** — one short question, mentioning that both are available. + **Never guess and never default.** + +**Never mix data from the two marketplaces in one query, one table or one total.** +They are separate pipelines with different grains and estimate methods; a combined +figure is simply wrong. If the seller wants both, run the analysis twice and report +the two side by side, comparing direction and orders of magnitude — never exact +numbers. + ### Step 1 — Resolve the category Ask for a category if none was given, then use JoomPulse to match the free text to -a category, disambiguating with the seller when several plausible matches return. +a category **on the chosen marketplace**, disambiguating with the seller when +several plausible matches return. On Shopee, category analytics stop at three +levels — if the seller names a deeper niche, work it through the item view instead +and say which you used. ### Step 2 — Find fast-growing international products Use JoomPulse to get the active **international (imported)** listings in the -category. There is no single "fast growth" flag, so use a clear momentum proxy -and **state the rule you used**: recently listed items (low time on air) with -strong estimated weekly sales or revenue. Do not label a list as fast-growing -when it is ranked by revenue alone. Keep the shortlist (about 10). +category, rank them by recent momentum and **state the rule you used**. + +**Which items count as international.** Shopee marks whether an item **ships +across the border**, and that is a shipping attribute, not the seller's country. A +separate seller-location label also exists, and the two are **not** the same thing +— an item held locally can belong to a foreign seller, and a domestic seller can +ship from abroad. This skill is about **cross-border shipping**, so use the +shipping signal, and say so in the intro line so the seller knows what +"international" means in the table. + +The momentum rule is different on each marketplace. + +**Mercado Livre.** There is no single "fast growth" flag, so use a clear momentum +proxy: recently listed items (low time on air) with strong estimated weekly sales +or revenue. Do not label a list as fast-growing when it is ranked by revenue +alone. + +**Shopee.** Each item carries a direction flag comparing its current monthly rate +against its own lifetime average. Keep the items whose direction is **growing** +**and** whose recent estimated sales are **above zero**, then rank by estimated +30-day sales. + +- **Drop the "recently listed" gate on Shopee.** A probe of live data showed the + strongest cross-border items were created years ago, so a recency gate empties + the list. +- **Guard against absurd percentages.** The sold counters are rounded, so a tiny + absolute move can look like enormous growth. Require a meaningful volume of + recent sales before calling an item fast-growing, and sanity-cap any growth + figure you report rather than printing one that cannot be real. + +Keep the shortlist (about 10). ## Output -Respond in the seller's language (default pt-BR). The product list always renders -as a markdown table: +Respond in the seller's language (default pt-BR). Lead with a short intro line +naming the **marketplace** and the category, the fast-growth rule you applied, and +what "international" means here. The product list always renders as a markdown +table. + +**Mercado Livre:** | MLB | Nome | Vendedor | Preço | Vendas (semana) | Receita (semana) | Classificação | Avaliações | Tempo no ar | Frete grátis | Mercado Envios Full | Tipo de anúncio | Medalha | JoomPro | |---|---|---|--:|--:|--:|--:|--:|--:|:--:|:--:|---|---|---| @@ -74,14 +162,43 @@ as a markdown table: - The **MLB** identifier links to the item's JoomPulse page. - **JoomPro** is a general JoomPro search link (`https://joom.pro/pt-br/search`) for sourcing the item. -- State the fast-growth rule you applied, in one short line. -**Disclaimer (every report):** +**Shopee:** + +| Item | Nome | Loja | Preço | Vendas (30 dias) | Receita (30 dias) | Classificação | Avaliações | Tempo no ar | Nível da loja | +|---|---|---|--:|--:|--:|--:|--:|--:|---| + +- The **item** identifier links to the item on Shopee — **there is no JoomPulse + dashboard link for Shopee rows**, so never invent one. +- **Tempo no ar** comes from the date the item was created. +- **Nível da loja** is Official store / Preferred (Indicado) / Common. Never map a + shop tier onto a seller medal. +- **There is no JoomPro column on Shopee** — sourcing data is not available for + Shopee. Say that plainly instead of leaving the seller to wonder. +- Free shipping, Mercado Envios Full and listing type have **no Shopee + equivalent**: either drop these columns or show `—` in them. + +The sales and revenue columns are **not** the same window on the two +marketplaces: Mercado Livre reports weekly figures, Shopee reports 30-day figures +only — label the Shopee columns as 30 days and never present a 30-day figure +under a weekly heading. + +**Disclaimer (every report) — use the variant for the marketplace you queried.** + +Mercado Livre: > ⚠️ Vendas e receita são estimativas do JoomPulse com base no histórico de > anúncios — não são transações reais. Preço, classificação e avaliações são > histórico real do Mercado Livre. +Shopee: + +> ⚠️ Vendas e receita são estimativas do JoomPulse a partir dos contadores +> arredondados da própria Shopee — não são transações reais, e diferenças +> pequenas entre itens são ruído. Só itens com pelo menos uma venda no histórico +> são rastreados, então esta lista é um piso. Preço, classificação e avaliações +> são histórico real da Shopee. + ## Visualization When the client can render inline visuals, present metric cards and a chart; @@ -91,14 +208,18 @@ disclaimer always stays in the text. When inline visuals are available: -- **Three cards:** number of international products found, total estimated weekly - sales, and average ticket. -- **A horizontal bar** of the top ~10 international products by estimated weekly - revenue. Render the chart only when there are enough products (skip it under - about four), and never block on it. +- **Three cards:** number of international products found, total estimated sales + over the window in use — weekly on Mercado Livre, 30 days on Shopee — and + average ticket. Name the window on the card so the two are never confused. +- **A horizontal bar** of the top ~10 international products by estimated revenue + over that same window. Render the chart only when there are enough products + (skip it under about four), and never block on it. Presentation rules: render a chart only when the data supports it; any change -column uses a word header, never a bare "Δ". +column uses a word header, never a bare "Δ". If you show Mercado Livre seller +medals as coloured chips, keep the standard palette; on Shopee there are no +medals — write the shop tier as plain text and never colour it as if it were a +rung on a ladder. ## Notes & Guardrails @@ -106,7 +227,15 @@ The seller should never see a system or stack error — only a friendly next ste - **Few or no international items:** imported listings in some categories are high-ticket and low-rotation; if the shortlist is thin or has little estimated - movement, say so honestly instead of padding it. + movement, say so honestly instead of padding it. On Shopee, add that the list is + a lower bound — only items with at least one lifetime sale are tracked — so an + empty result is not proof the category has no cross-border supply. +- **Category not found or ambiguous name:** list the candidates with their level + and ask the seller to pick one. If nothing matches, check the other marketplace + before saying the category does not exist. +- **Empty fields:** show `—` for any missing value; never fabricate one. On + Shopee, free shipping, the fulfilment programme and the listing tier are always + `—` — that is an absent attribute, not a missing value, and never a "Não". - **Market data temporarily unavailable:** retry once quietly; if it is still down, say market data is temporarily unavailable and to try again. Never paste internal error text, HTTP codes, or field names to the seller. diff --git a/skills/product-change-monitor/SKILL.md b/skills/product-change-monitor/SKILL.md index ca3a8f3..8dc023d 100644 --- a/skills/product-change-monitor/SKILL.md +++ b/skills/product-change-monitor/SKILL.md @@ -1,32 +1,34 @@ --- name: product-change-monitor description: > - Monitors how one or a few Mercado Livre products or listings changed over a - period — by default week over week. Use it when a user wants to track how a - named product changes over time, given a Mercado Livre link, a JoomPulse link, - a Mercado Livre listing identifier, or a catalog product identifier. It returns - a change table: per product the current value and the difference versus about a - week ago for price, rating, and review count, plus the current estimated weekly - sales and revenue, logistics, listing type, seller medal, and time on air, with - a JoomPulse link per product. Triggers include: "monitor this product", "track - price changes", "what changed this week", "did the price drop", and the pt-BR - equivalents "monitorar este produto", "acompanhar este anúncio", "o preço caiu", - "variação de avaliações". Sales and revenue are JoomPulse estimates, not real - transactions; price, rating, and reviews are real history. For point-in-time - product and competitor analysis, use the single-product analysis skill. + Monitors how one or a few products changed over a period — by default week + over week — on JoomPulse: Mercado Livre (Brasil) or Shopee Brasil. Use when a + seller tracks a named product over time, given a marketplace or JoomPulse + link, or a listing, item or catalog identifier. Returns a change table: per + product the current value plus the difference versus about a week ago for + price, rating and review count, plus current estimated sales and revenue, time + on air and the marketplace's own seller and logistics attributes. Triggers: + "monitor this product", "track price changes", "what changed this week", "did + the price drop"; pt-BR "monitorar este produto", "o preço caiu", "variação de + avaliações", "monitorar este produto na Shopee", "acompanhar este item da + Shopee". Ask which marketplace when unclear; never mix the two. Sales and + revenue are JoomPulse estimates, not real transactions; price, rating and + reviews are real. For a point-in-time product and competitor read, use the + single-product analysis skill. --- -# Mercado Livre Product Change Monitor +# Product Change Monitor -This skill shows how **one** Mercado Livre (Brasil) product — or a few of them — -**changed over a period**, by default the last week. Given a product by a Mercado -Livre link, a JoomPulse link, a Mercado Livre listing identifier, or a catalog -product identifier, it reports for each product the current value **and the -change versus about a week ago** for the metrics that have real history (price, -rating, review count), plus the current snapshot for estimated weekly sales and -revenue, logistics, listing type, seller medal, and how long the listing has been -on air. The result is a change table with a JoomPulse link per product, plus a -downloadable spreadsheet. +This skill shows how **one** product — or a few of them — **changed over a +period**, by default the last week, on **Mercado Livre (Brasil) or Shopee +Brasil**, using JoomPulse market data. Given a product by a marketplace link, a +JoomPulse link, or a listing, item or catalog product identifier, it reports for +each product the current value **and the change versus about a week ago** for the +metrics that have real history (price, rating, review count), plus the current +snapshot for estimated sales and revenue, how long the listing has been on air, +and the seller and logistics attributes that marketplace actually has. The result +is a change table plus a downloadable spreadsheet; on Mercado Livre each row links +to its JoomPulse page, on Shopee each row links to the item on Shopee. This is different from a single point-in-time analysis. To size up a product and find the products that compete with it, use the single-product analysis skill. To @@ -37,33 +39,85 @@ the user names. ## Prerequisites - JoomPulse MCP access is configured for the current agent environment. -- The user provides one product (or a small set) as a Mercado Livre link, a - JoomPulse link, a Mercado Livre listing identifier, or a catalog product - identifier. +- The user provides a marketplace — Mercado Livre (Brasil) or Shopee Brasil — and + one product (or a small set) as a marketplace link, a JoomPulse link, or a + listing, item or catalog product identifier. - The available JoomPulse tools can look up a product's current market data and - its daily price and reviews history. + its price and reviews history on **either** marketplace. The shape of that + history differs: on Mercado Livre it is a daily series, on Shopee a record per + change (see Step 2). If JoomPulse MCP access is unavailable, stop and explain that the skill requires JoomPulse MCP setup before it can monitor a product's changes. ## Scope -- **Mercado Livre (Brasil) only.** Other marketplaces are out of scope. -- **Sales and revenue are JoomPulse estimates** derived from historical listing - data — not real transactions. Disclose this in every output. By contrast, - **price, rating, and review count are real history** from Mercado Livre — say - so, it is a strength of the report. +- **Mercado Livre (Brasil) and Shopee Brasil**, one at a time. Other marketplaces + are out of scope. +- **Sales and revenue are JoomPulse estimates** — not real transactions. Disclose + this in every output. By contrast, **price, rating, and review count are real + history** from the marketplace — say so, it is a strength of the report. The + estimates are built differently on each marketplace: on Mercado Livre from + historical listing data, on Shopee from the marketplace's own rounded sold + counters refined with review movement. Use the matching disclaimer. - **Read-only.** The skill does not sign in as the seller or modify any listing. - **Language:** detect the seller's language and respond in it. Default to pt-BR. - **Keep the workflow invisible.** The seller wants the answer, not a play-by- play. If one approach does not return data, switch to another quietly; only if every approach fails do you say one short, friendly sentence. +**Shopee data — what differs from Mercado Livre** + +- **Estimates come from Shopee's own rounded sold counters**, refined with review + movement. Treat small gaps between items as noise and never rank on a difference + of a few units. Price, rating and review count are real. +- **Coverage is not a census**: only items with at least one lifetime sale are + tracked, so any count is a lower bound and an absent item is not evidence it does + not sell. +- **History starts May 2026** — there is no long-run trend and no seasonal read. +- **Category analytics stop at three levels**; the item view reaches deeper. Say + which you used. +- **No seller medals** — Shopee has three mutually exclusive shop tiers: **Official + store**, **Preferred (Indicado)** and **Common**. There is no ladder; inventing + Shopee medals is fabrication. +- **No catalogue and no buy-box**, and an item belongs to one shop. +- **No fulfilment programme, no free-shipping flag and no listing tier** — show `—` + rather than guessing. +- **Concentration is measured differently** and thresholds do not transfer between + marketplaces. +- Item titles mix Portuguese, English and Chinese — search both languages. + ## Workflow +### Step 0 — Decide the marketplace + +JoomPulse covers **two separate marketplaces**: Mercado Livre (Brasil) and Shopee +Brasil. They are independent datasets with different coverage, history and +mechanics. Decide which one the request belongs to **before reading any data**: + +- **The seller said so.** "Shopee" means Shopee; "Mercado Livre", "MeLi" or "ML" + means Mercado Livre. +- **An identifier gives it away.** An identifier beginning `MLB` is Mercado Livre; + a bare 10–11 digit number is a Shopee item or shop. A `mercadolivre.com.br` link + is Mercado Livre, a `shopee.com.br` link is Shopee. If an identifier is not found + on the marketplace you assumed, check the other one before telling the seller it + does not exist. +- **The request only makes sense on one of them** — buy-box, catalogue position, + seller medals, a fulfilment programme or search keywords are Mercado Livre only. +- **Otherwise ask** — one short question, mentioning that both are available. + **Never guess and never default.** + +**Never mix data from the two marketplaces in one query, one table or one total.** +They are separate pipelines with different grains and estimate methods; a combined +figure is simply wrong. If the seller wants both, run the analysis twice and report +the two side by side, comparing direction and orders of magnitude — never exact +numbers. + ### Step 1 — Identify the product(s) -Resolve the input to one or more Mercado Livre listings: +Resolve the input to one or more listings on the marketplace chosen in Step 0. + +**Mercado Livre:** 1. From a Mercado Livre link, a JoomPulse link, or a pasted identifier, determine whether you have an individual **listing** or a **catalog product**. @@ -72,36 +126,73 @@ Resolve the input to one or more Mercado Livre listings: row, and note the buy-box competition (how many sellers compete). 3. Confirm the listing is active. If there is no market data for it, see Notes & Guardrails. -4. A JoomPulse store link is a whole store, not one product — ask for a specific - product link or identifier (whole-store work belongs to the gap-analysis - skill). Any other marketplace link cannot be resolved directly — ask for a - Mercado Livre or JoomPulse link or identifier. + +**Shopee:** + +1. From a Shopee item link or a pasted item identifier, resolve the **item** + directly. Shopee is item-grain with **no catalogue and no buy-box**, so there + is nothing to expand, no representative listing to pick and no buy-box + competition to report — do not carry those steps over. +2. There is no listing-status filter on Shopee — how recently the item was last + seen is what tells you whether it is still live, so check it and never monitor + a stale item as if it were live. If the item is not tracked, see Notes & + Guardrails. + +On both marketplaces: a JoomPulse store link is a whole store, not one product — +ask for a specific product link or identifier (whole-store work belongs to the +gap-analysis skill). A link from any other marketplace cannot be resolved +directly — ask for a Mercado Livre, Shopee or JoomPulse link or identifier. ### Step 2 — Collect current state and history, then compare -1. **Current snapshot** (from JoomPulse): product name, category, seller, listing - type, seller medal, logistics (Mercado Envios Full / free shipping), how long - the listing has been on air, and the estimated **weekly** sales and revenue. -2. **Real daily history** (from JoomPulse): price, rating, and review count over - roughly the last month, so a baseline a week back is reachable. -3. **Compare current versus about a week ago**, following this rule: - - The **current point** is the latest observation available on or before today. - - The **baseline** is the observation about seven days earlier. - - If there is no observation exactly seven days back, use the **nearest earlier +1. **Current snapshot** (from JoomPulse): + - **Mercado Livre:** product name, category, seller, listing type, seller + medal, logistics (Mercado Envios Full / free shipping), how long the listing + has been on air, and the estimated **weekly** sales and revenue. + - **Shopee:** item name, category, shop, shop tier (Official store / + Preferred (Indicado) / Common), how long the item has been on air — computed + from the date the item was created — and the estimated sales and revenue. + Shopee also reports **estimated sales week by week per item** (weeks start + on Monday): use it, it is the cleanest weekly read this marketplace offers + and a genuine Shopee strength for this skill. +2. **Real price and reviews history** (from JoomPulse): price, rating and review + count. The shape of that history is fundamentally different on the two + marketplaces: + - **Mercado Livre:** a **daily series** — pull roughly the last month, so a + baseline a week back is reachable. + - **Shopee:** a **step function, not daily rows** — a value is recorded only + when it **changes**, and it holds until the next record. History starts + **May 2026**, so the lookback window is shorter than a year; do not ask for + a year of trend. +3. **Compare current versus about a week ago.** The **current point** is the + latest value in force on or before today; the **baseline** is the value in + force about seven days earlier. How you reach that baseline differs: + - **Mercado Livre:** the baseline is the observation about seven days back. If + there is no observation exactly seven days back, use the **nearest earlier observation within tolerance** (roughly up to two weeks back in total) and - **state which date was actually used** — never silently substitute it. - - If no comparable earlier observation exists within tolerance, show the - current value only and say the period comparison is not available for that - metric. Do not invent a baseline. -4. Estimated sales and revenue are already **weekly** figures, so present them as - the current week's value; they carry no period-over-period difference. + **state which date was actually used** — never silently substitute it. If no + comparable earlier observation exists within tolerance, show the current + value only and say the period comparison is not available for that metric. + Do not invent a baseline. + - **Shopee:** **carry forward** the most recent record dated on or before the + target day — that is the value that was in force then. Look back **as far as + needed**; there is no two-week tolerance and no giving up, because an absent + record means the value **did not change**, so the difference is **0**, never + "unavailable". Silence is information here, so never report a Shopee metric + as uncomparable just because no record sits near the target day. +4. Estimated sales and revenue are **current-window** figures — weekly on Mercado + Livre, and on Shopee the current week of the week-by-week series — so present + them as the current value; they carry no period-over-period difference. ## Output Respond in the seller's language. Present the result with no commentary about how it was produced. Use plain markdown so it renders cleanly in any client. -**Change table** — one row per monitored product, with these columns: +Lead with a short line naming the **marketplace** that was monitored. + +**Change table (Mercado Livre)** — one row per monitored product, with these +columns: - Product / listing identifier - Name @@ -122,13 +213,35 @@ it was produced. Use plain markdown so it renders cleanly in any client. - Seller medal - A JoomPulse link for the product +**Change table (Shopee)** — same shape, with the marketplace's own columns: + +- Item identifier, linked to the item on Shopee — **there is no JoomPulse + dashboard link for Shopee rows**, so never invent one +- Name +- Category +- Shop +- Price, Rating and Reviews — current value with the change in the cell, exactly + as above. A metric with no record in the period changed by `0`; never show it + as unavailable +- Estimated sales (current week, weeks starting Monday) +- Estimated revenue — label the window you actually show +- Time on air — computed from the date the item was created +- Shop tier — Official store / Preferred (Indicado) / Common +- Free shipping, Mercado Envios Full and listing type have **no Shopee + equivalent**: either drop these columns or show `—` in them. Never map a shop + tier onto a seller medal + Do **not** put a delta symbol or "(Δ)" in any column header — it confuses sellers; the change belongs inside the cell. Below the table, state the period actually -compared (for example "today versus seven days ago") and surface any baseline -date that was not exactly the target, so the comparison is transparent. You may +compared (for example "today versus seven days ago"). On Mercado Livre also +surface any baseline date that was not exactly the target, so the comparison is +transparent; on Shopee, when the carried-forward record is older than the target +day, give its date and say the value simply had not changed since. You may translate the column headers into the seller's language. -**Disclaimer (every report):** +**Disclaimer (every report) — use the variant for the marketplace you queried.** + +Mercado Livre: > ⚠️ Sales and revenue are JoomPulse **estimates** based on historical listing > data — they are **not** actual transactions. Price, rating, and reviews are @@ -136,6 +249,17 @@ translate the column headers into the seller's language. > com base no histórico de anúncios — **não são transações reais**. Preço, > classificação e avaliações são histórico real do Mercado Livre. +Shopee: + +> ⚠️ Sales and revenue are JoomPulse **estimates** built from Shopee's own +> rounded sold counters — they are **not** actual transactions, and small +> movements are noise. Price, rating, and reviews are real Shopee history, and +> that history starts in May 2026. / Vendas e receita são **estimativas** do +> JoomPulse a partir dos contadores arredondados da própria Shopee — **não são +> transações reais**, e variações pequenas são ruído. Preço, classificação e +> avaliações são histórico real da Shopee, e esse histórico começa em maio de +> 2026. + **Download** — offer a downloadable spreadsheet (`.xlsx` plus `.csv`) of the change table. @@ -145,15 +269,24 @@ The seller should never see a system or stack error — only a friendly next ste - **Product not tracked in JoomPulse / no sales:** JoomPulse tracks products that have sales, so a product may not be tracked. Say so and offer to try a different - link or identifier; you cannot build a history for an untracked product. + link or identifier; you cannot build a history for an untracked product. On + Shopee only items with at least one lifetime sale are tracked, so an untracked + item is not proof it does not exist. If an identifier is not found, check the + other marketplace before telling the seller it does not exist. - **New listing or too little history:** if there is less than about a week of data, show the current snapshot and explain that the period comparison is not - available yet; suggest re-running in a few days to start a trend. -- **Catalog product:** the daily history is per listing, so resolve a catalog - product to its listing(s) first; if several sellers compete, monitor the - representative listing and mention the buy-box competition. + available yet; suggest re-running in a few days to start a trend. On Shopee, + first make sure you are not mistaking a step function for missing data — no + record simply means no change — and remember the history itself only starts in + May 2026, so an older baseline may be unreachable for that reason alone. +- **Catalog product (Mercado Livre only):** the daily history is per listing, so + resolve a catalog product to its listing(s) first; if several sellers compete, + monitor the representative listing and mention the buy-box competition. Shopee + has no catalogue and no buy-box, so none of this applies there. - **Unknown flags:** when a logistics flag (such as Mercado Envios Full) is - unknown, show it as unknown — do not assume "no". + unknown, show it as unknown — do not assume "no". On Shopee free shipping, the + fulfilment programme and the listing tier are always `—`: that is an absent + attribute, not a missing value, and never a "Não". - **Market data temporarily unavailable:** retry once quietly; if it is still down, say market data is temporarily unavailable. Never paste internal error text, HTTP codes, or field names to the seller. diff --git a/skills/pulse-find-exact-same-product/SKILL.md b/skills/pulse-find-exact-same-product/SKILL.md index 42dcda8..08a7fa8 100644 --- a/skills/pulse-find-exact-same-product/SKILL.md +++ b/skills/pulse-find-exact-same-product/SKILL.md @@ -1,17 +1,27 @@ --- name: pulse-find-exact-same-product description: > - Finds product listings that appear to represent the same real-world product as a - reference item. Use this skill when a user wants to find duplicate listings, - match a product across listings, identify identical products by title or URL, - compare product photos against marketplace listings, or find the same product - on Mercado Livre. + Finds the listings that appear to represent the same real-world product as a + reference item, on JoomPulse — Mercado Livre (Brasil) or Shopee Brasil. Use it + to find duplicate listings, match a product across listings from a title, a + link or an identifier, or check whether a product is already being sold on the + other marketplace. Triggers: "find the same product", "duplicate listings", + "is this product already on Shopee", "find this item on Shopee"; pt-BR "achar + o mesmo produto", "anúncios duplicados", "esse produto já existe na Shopee", + "procurar esse item na Shopee". Ask which marketplace when unclear; never mix + the two. On Mercado Livre the shared catalogue anchors a match; Shopee has no + shared catalogue, so matching is a short-token title search confirmed by + brand, category and a plausible price band, and photo search is unsupported + there. --- # Find Exact Same Product -This skill helps find listings that appear to represent the same real-world -product as a reference product. +This skill finds listings that appear to represent the same real-world product +as a reference product, on **Mercado Livre (Brasil) or Shopee Brasil**, using +JoomPulse market data. The seller picks a marketplace and hands over a reference +— a title, a link, an identifier or a picture — and the skill returns the +listings it can confirm are the same product, each with a short reason. "The same product" means the candidate listing matches the reference item's identity: brand, model, variant, color, size, capacity, pack count, bundle @@ -19,63 +29,189 @@ contents, and other defining attributes visible from the provided product data. Formatting, casing, punctuation, and translation differences are acceptable when the underlying product is clearly the same. +What confirms that identity differs by marketplace. On Mercado Livre several +sellers can list the very same catalogue product, so the shared catalogue is the +strongest anchor available. On Shopee nothing links different shops' listings of +one product, and an item belongs to a single shop, so a match has to be built +from a title search and then confirmed on attributes. + ## Prerequisites - JoomPulse MCP access is configured for the current agent environment. -- The user provides a product title, product URL, product identifier, or product - image. -- The available JoomPulse tools can search marketplace listings and return - enough product data to compare candidates. +- The user provides a marketplace — Mercado Livre (Brasil) or Shopee Brasil — + and a reference product: a title, a product link, a product identifier, or a + product image. +- The available JoomPulse tools can search marketplace listings on **either** + marketplace and return enough product data to compare candidates: title, + category, price, seller or shop, rating and review count, and, where the + marketplace records it, brand. +- The image route needs an image-based product search, which exists on Mercado + Livre only. If JoomPulse MCP access is unavailable, stop and explain that the skill requires JoomPulse MCP setup before it can search or compare products. +## Scope + +- **Mercado Livre (Brasil) and Shopee Brasil**, one at a time. Other + marketplaces are out of scope. +- **What anchors a match differs.** On Mercado Livre, the listings of one + catalogue product are the reference set. On Shopee there is no shared + catalogue identifier linking different sellers' listings of the same product, + so that anchor does not exist: matching is a title search plus attribute + confirmation. +- **A title-only match is not a confirmed match** on Shopee. Confirm on brand + plus category plus a plausible price band, and label anything weaker as a + likely candidate, not a match. +- **The photo route is unsupported on Shopee** — there is no image-similarity + search. Say so plainly instead of attempting it. +- **An absent match is not proof** the product is not sold on Shopee: coverage + includes only items with at least one lifetime sale, and brand is recorded for + tracked items only. +- **Read-only.** The skill does not sign in as the seller or modify any listing. +- **Language:** detect the seller's language and respond in it. Default to pt-BR. +- **Keep the workflow invisible.** The seller wants the answer, not a play-by- + play. If one approach does not return data, switch to another quietly; only if + every approach fails do you say one short, friendly sentence. + +**Shopee data — what differs from Mercado Livre** + +- **Estimates come from Shopee's own rounded sold counters**, refined with review + movement. Treat small gaps between items as noise and never rank on a difference + of a few units. Price, rating and review count are real. +- **Coverage is not a census**: only items with at least one lifetime sale are + tracked, so any count is a lower bound and an absent item is not evidence it does + not sell. +- **History starts May 2026** — there is no long-run trend and no seasonal read. +- **Category analytics stop at three levels**; the item view reaches deeper. Say + which you used. +- **No seller medals** — Shopee has three mutually exclusive shop tiers: **Official + store**, **Preferred (Indicado)** and **Common**. There is no ladder; inventing + Shopee medals is fabrication. +- **No catalogue and no buy-box**, and an item belongs to one shop. +- **No fulfilment programme, no free-shipping flag and no listing tier** — show `—` + rather than guessing. +- **Concentration is measured differently** and thresholds do not transfer between + marketplaces. +- Item titles mix Portuguese, English and Chinese — search both languages. + ## Workflow -1. Resolve the reference product. - - If the user provides a title, use it directly as the reference. - - If the user provides a product URL or identifier, fetch the available - product details first. - - If the user provides an image, use the available image-based product search - workflow to generate candidate listings. - -2. Search for candidate listings. - - Use JoomPulse product search tools to find plausible candidates. - - Treat search results as candidate generation, not final truth. - - Prefer a compact candidate set first, then broaden only when recall is - clearly too low. - -3. Enrich candidates. - - Fetch product attributes, title, seller/listing metadata, images, and links - when available. - - Keep enough source data to explain why a candidate was accepted or rejected. - -4. Decide exact matches. - - Accept a candidate only when the defining attributes match the reference. - - Reject candidates when brand, model, size, color, capacity, pack count, - bundle contents, or other defining attributes differ. - - If data is insufficient for a confident match, do not mark it as exact. - - Do not rely on title similarity alone when important attributes are missing - or ambiguous. - -5. Return results. - - List confirmed matches with product links when available. - - Include a short rationale for each accepted match. - - If there are no confident matches, say so clearly and summarize what was - checked. - - When useful, include rejected near-matches separately with the key reason - they were rejected. +### Step 0 — Decide the marketplace + +JoomPulse covers **two separate marketplaces**: Mercado Livre (Brasil) and Shopee +Brasil. They are independent datasets with different coverage, history and +mechanics. Decide which one the request belongs to **before reading any data**: + +- **The seller said so.** "Shopee" means Shopee; "Mercado Livre", "MeLi" or "ML" + means Mercado Livre. +- **An identifier gives it away.** An identifier beginning `MLB` is Mercado Livre; + a bare 10–11 digit number is a Shopee item or shop. A `mercadolivre.com.br` link + is Mercado Livre, a `shopee.com.br` link is Shopee. If an identifier is not found + on the marketplace you assumed, check the other one before telling the seller it + does not exist. +- **The request only makes sense on one of them** — buy-box, catalogue position, + seller medals, a fulfilment programme or search keywords are Mercado Livre only. +- **Otherwise ask** — one short question, mentioning that both are available. + **Never guess and never default.** + +**Never mix data from the two marketplaces in one query, one table or one total.** +They are separate pipelines with different grains and estimate methods; a combined +figure is simply wrong. If the seller wants both, run the analysis twice and report +the two side by side, comparing direction and orders of magnitude — never exact +numbers. + +### Step 1 — Resolve the reference product + +- If the user provides a **title**, use it directly as the reference. +- If the user provides a **link or an identifier**, fetch the available product + details first. A Mercado Livre listing code or link resolves on Mercado Livre; + a Shopee link carries two bare numeric identifiers — the shop and the item — + and resolves on Shopee. +- If the user provides an **image**: + - On Mercado Livre, use the available image-based product search workflow to + generate candidate listings. + - On Shopee there is **no image-similarity search** — say so plainly rather + than attempting one. You may still read the picture yourself, describe what + you see (brand, product type, colour, pack size) and search on those words, + but label the result as a search by your own reading of the photo, never as + an image match. +- Echo back what you captured — the marketplace and the reference product — so + the user can correct it before you search. + +### Step 2 — Search for candidate listings + +- Use JoomPulse product search to find plausible candidates. Treat search + results as candidate generation, not final truth. +- **Mercado Livre:** start from the listings of the same catalogue product, then + widen to a title search inside the category if that set is thin. +- **Shopee:** title search is a **literal substring match**, and item titles mix + Portuguese, English and Chinese. So: + - search several **short tokens** instead of one long precise phrase — a long + phrase typically returns nothing at all; + - try both the Portuguese and the English wording of the same token; + - **scope the search to a category**, because a short generic token on its own + comes back full of unrelated bundles and accessories. +- Prefer a compact candidate set first, then broaden only when recall is clearly + too low. + +### Step 3 — Enrich candidates + +- Fetch title, category, price, images, seller or shop, rating, review count, + the attributes the marketplace records, and the link for each candidate. +- **Mercado Livre:** the catalogue product and the listing attributes carry most + of the identifying detail. +- **Shopee:** brand is recorded only for tracked items, so expect it to be + missing on part of the set; also check how recently each item was last seen, so + a stale row is never presented as a live listing. +- Keep enough source data to explain why a candidate was accepted or rejected. + +### Step 4 — Decide the matches + +- Accept a candidate only when the defining attributes match the reference. +- Reject candidates when brand, model, size, color, capacity, pack count, + bundle contents, or other defining attributes differ. +- **On Shopee, confirm a match on brand plus category plus a plausible price + band — never on the title alone.** A title-only match is not a confirmed + match: report it as a likely candidate and say what is still unverified. Where + brand is absent, a likely candidate is the strongest claim available. +- If data is insufficient for a confident match, do not mark it as exact. +- Do not rely on title similarity alone when important attributes are missing + or ambiguous. + +### Step 5 — Return the results + +- List confirmed matches with their links — the JoomPulse page on Mercado Livre, + the item's own Shopee link on Shopee. **There is no JoomPulse dashboard link + for Shopee rows**, so never invent one. +- Include a short rationale for each accepted match. +- If there are no confident matches, say so clearly and summarize what was + checked, including which wordings were tried. On Shopee, add that this is not + proof the product is not sold there — coverage includes only items with at + least one lifetime sale. +- When useful, include rejected near-matches separately with the key reason + they were rejected. ## Output Format -Use a concise table when there are multiple candidates: +Respond in the seller's language. Lead with a short line naming the +**marketplace** and the reference product. Use a concise table when there are +multiple candidates: | Result | Product | Link | Why it matches | | --- | --- | --- | --- | -| Match | Product title | Product URL | Same brand, model, size, and variant | +| Match | Product title | Product link | Same brand, model, size, and variant | + +- **Mercado Livre:** the product column carries the listing code, and the link + points at its JoomPulse page. +- **Shopee:** the product column carries the item title and its shop, and the + link is the item's own Shopee link, built from the two numeric identifiers for + the shop and the item. A row is a **Match** only when brand, category and + price band agree; otherwise call it a **likely candidate** and name what is + still unverified. For a single match, a short paragraph with the product link and rationale is -enough. +enough. Empty field → `—`; never guess or fabricate. ## Notes @@ -85,3 +221,16 @@ enough. details in the final answer. - If the user asks for bulk matching, process items one by one and make uncertainty explicit for each item. +- **Never mix the two marketplaces in one table.** If the seller wants to know + whether a Mercado Livre product is also on Shopee, run the search twice and + report the two sides separately. +- **No image-similarity search on Shopee:** say so in one short sentence and + offer the token search based on your own reading of the photo instead. Never + imply a photo match was performed. +- **Nothing found on Shopee:** an empty result is a floor, not a verdict — + coverage includes only items with at least one lifetime sale, and a literal + title search misses the wordings you did not try. Offer to try other tokens + or another category. +- **Market data temporarily unavailable:** retry once quietly; if it is still + down, say market data is temporarily unavailable and to try again shortly. + Never paste internal error text, HTTP codes, or field names to the seller. diff --git a/skills/seller-copilot/references/which-marketplace.md b/skills/seller-copilot/references/which-marketplace.md index d25a45c..b1f0b06 100644 --- a/skills/seller-copilot/references/which-marketplace.md +++ b/skills/seller-copilot/references/which-marketplace.md @@ -76,14 +76,23 @@ nearest real alternative** — never substitute the other marketplace's figure. ## Which files to read once decided -- **Mercado Livre** → the unprefixed reference files, and the focused Mercado Livre skills in - this repo where one already does the job. -- **Shopee** → the `shopee-` prefixed reference files. - -**The focused skills in this repo are Mercado Livre only.** Every one of them scopes itself to -Mercado Livre, so handing a Shopee question to one returns Mercado Livre data for a Shopee -seller — a wrong answer that looks right. For Shopee there is no focused skill to defer to: use -the `shopee-` references and do the analysis here. +- **Mercado Livre** → the unprefixed reference files, and the focused skills in this repo where + one already does the job. +- **Shopee** → the `shopee-` prefixed reference files, and the focused skills that cover Shopee. + +**Most focused skills in this repo now cover both marketplaces.** Each one decides the +marketplace first and then reads that marketplace's own data, so a Shopee question handed to one +is answered with Shopee data. Check the skill's own scope before deferring to it. + +**Four are Mercado Livre only, by design:** + +- **keywords and search demand** — Shopee has no search data at all; +- **buy-box / catalogue comparison** — Shopee has no catalogue and no buy-box; +- **brand rankings** — Shopee brand coverage is too incomplete to rank; +- **top sellers in a category** — Shopee has no per-seller revenue within a category yet. + +For those four, do not hand a Shopee question over: name the gap and offer the nearest real +alternative from the `shopee-` references. ## Things that differ enough to catch you out diff --git a/skills/seller-overview-tracker/SKILL.md b/skills/seller-overview-tracker/SKILL.md index a5080e8..bd1c279 100644 --- a/skills/seller-overview-tracker/SKILL.md +++ b/skills/seller-overview-tracker/SKILL.md @@ -1,31 +1,37 @@ --- name: seller-overview-tracker description: > - Snapshot tracker for one Mercado Livre (Brasil) seller via JoomPulse — estimated monthly - revenue and sales, listing count, sales trend, reputation, seller medal, categories covered, - and cancellation rate. Each run builds today's snapshot table and offers it for download; to - see what changed, the user sends the seller's table from a previous period and the skill - shows the metric-by-metric difference (old → new). The baseline is whatever table the user - supplies — no hidden session memory. Use it to track one specific seller over time. - Triggers: "track this seller", "monitor this store", "what changed for this seller", - "compare this seller with last period", and the pt-BR "monitorar este vendedor", "acompanhar - esta loja", "o que mudou nesse vendedor". Sales and revenue are JoomPulse estimates, not - real transactions. To rank many sellers in a category and track how that ranking moves, use - the top-sellers-in-category skill. Mercado Livre (Brasil) only. + Snapshot tracker for one seller on JoomPulse — Mercado Livre (Brasil) or Shopee + Brasil. Pulls store name, estimated monthly revenue and sales, listing count, + sales trend, categories, location, and the seller's reputation or buyer rating; + medal, cancellation rate and 60/365-day sales are Mercado Livre only. Each run + builds today's snapshot table and offers it for download; to see what changed, + the user sends the seller's table from a previous period and the skill shows the + difference per metric. The baseline is whatever table the user supplies — no + hidden session memory. Triggers: "track this seller", "monitor this store", + "what changed for this seller"; pt-BR "monitorar este vendedor", "acompanhar + esta loja", "o que mudou nesse vendedor", "monitorar esta loja na Shopee", + "acompanhar este vendedor da Shopee". Ask which marketplace when unclear; never + mix the two. Sales and revenue are JoomPulse estimates, not real transactions. + To rank many sellers in a category, use the top-sellers-in-category skill. --- # Seller Overview Tracker -This skill tracks **one Mercado Livre (Brasil) seller over time** — its estimated -monthly revenue and sales, listing count, sales trend, reputation, seller medal, -the categories it covers, and its cancellation rate. +This skill tracks **one seller over time** on **Mercado Livre (Brasil) or Shopee +Brasil** — its estimated monthly revenue and sales, listing count, sales trend, +average ticket and average price, the categories it covers, its location, and how +buyers rate it. On Mercado Livre it also carries the seller medal, the cancellation +rate and the rolling 60-day and 365-day sales; **none of those three last fields +exist on Shopee**, where the shop tier stands in for the medal. Each run builds **today's snapshot table** for the seller and offers it as a **downloadable table**. To see what changed, the user **supplies the seller's table from a previous period** (the one this skill produced before); the skill compares the two and shows the difference per metric. **The baseline is whatever table the user provides — there is no hidden session memory and nothing is stored -server-side.** The seller is identified by a store link or a seller identifier. +server-side.** The seller is identified by a store link or a seller identifier on +either marketplace. It is different from ranking work: to rank many sellers in a category and track how that ranking moves, use the top-sellers-in-category skill; to analyze one product, use @@ -34,74 +40,143 @@ the single-product analysis skill. This skill follows **one** seller. ## Prerequisites - JoomPulse MCP access is configured for the current agent environment. -- The user provides one seller as a Mercado Livre store link or a seller identifier. +- The user provides a marketplace — Mercado Livre (Brasil) or Shopee Brasil — + and one seller as a store link or a seller identifier on that marketplace. - For a period comparison, the user supplies a previous table that this skill - produced for the same seller (pasted or uploaded). Without it, the skill produces - a standalone snapshot. -- The available JoomPulse tools can look up that seller's current market snapshot. + produced for the same seller **on the same marketplace** (pasted or uploaded). + Without it, the skill produces a standalone snapshot. +- The available JoomPulse tools can look up that seller's current market snapshot on + **either** marketplace. On Shopee the shop's estimated revenue and sales are not + published as one store-level figure — the tools report them per item, so the skill + builds the shop total up from its items. If JoomPulse MCP access is unavailable, stop and explain that the skill requires JoomPulse MCP setup before it can monitor a seller. ## Scope -- **Mercado Livre (Brasil) only.** Other marketplaces are out of scope. +- **Mercado Livre (Brasil) and Shopee Brasil**, one at a time. Other marketplaces + are out of scope. - **Sales and revenue are JoomPulse estimates** — estimated monthly revenue, estimated monthly sales, average ticket, and average price are not real - transactions. Disclose this in every output. By contrast, the rolling 60-day - and 365-day sales counts, the sales trend, and the cancellation rate are real - Mercado Livre data. + transactions. Disclose this in every output. + - **On Mercado Livre**, by contrast, the rolling 60-day and 365-day sales counts, + the sales trend, and the cancellation rate are real Mercado Livre data. + - **On Shopee every sales figure is an estimate** — there is no real-data + counterpart, so the Mercado Livre sentence above must never appear in a Shopee + output. Only price, the buyer rating and the review count are real. - **Read-only.** The skill never signs in as the seller or modifies a listing; it does not store the snapshot — the user keeps the downloadable table and brings it back next period. - **Language:** respond in pt-BR by default; mirror another language only if the user clearly uses it. - **The baseline is user-supplied.** Never claim a change without a previous table - to compare against, and never infer or fabricate one from memory. + to compare against, and never infer or fabricate one from memory. The previous + table must be for the **same seller on the same marketplace**. - **Keep the workflow invisible.** The user wants the answer, not a play-by-play. If one approach does not return data, retry quietly; only if it still fails do you say one short, friendly sentence. +**Shopee data — what differs from Mercado Livre** + +- **Estimates come from Shopee's own rounded sold counters**, refined with review + movement. Treat small gaps between items as noise and never rank on a difference + of a few units. Price, rating and review count are real. +- **Coverage is not a census**: only items with at least one lifetime sale are + tracked, so any count is a lower bound and an absent item is not evidence it does + not sell. +- **History starts May 2026** — there is no long-run trend and no seasonal read. +- **Category analytics stop at three levels**; the item view reaches deeper. Say + which you used. +- **No seller medals** — Shopee has three mutually exclusive shop tiers: **Official + store**, **Preferred (Indicado)** and **Common**. There is no ladder; inventing + Shopee medals is fabrication. +- **No catalogue and no buy-box**, and an item belongs to one shop. +- **No fulfilment programme, no free-shipping flag and no listing tier** — show `—` + rather than guessing. +- **Concentration is measured differently** and thresholds do not transfer between + marketplaces. +- Item titles mix Portuguese, English and Chinese — search both languages. + ## Workflow +### Step 0 — Decide the marketplace + +JoomPulse covers **two separate marketplaces**: Mercado Livre (Brasil) and Shopee +Brasil. They are independent datasets with different coverage, history and +mechanics. Decide which one the request belongs to **before reading any data**: + +- **The seller said so.** "Shopee" means Shopee; "Mercado Livre", "MeLi" or "ML" + means Mercado Livre. +- **An identifier gives it away.** An identifier beginning `MLB` is Mercado Livre; + a bare 10–11 digit number is a Shopee item or shop. A `mercadolivre.com.br` link + is Mercado Livre, a `shopee.com.br` link is Shopee. If an identifier is not found + on the marketplace you assumed, check the other one before telling the seller it + does not exist. +- **The request only makes sense on one of them** — buy-box, catalogue position, + seller medals, a fulfilment programme or search keywords are Mercado Livre only. +- **Otherwise ask** — one short question, mentioning that both are available. + **Never guess and never default.** + +**Never mix data from the two marketplaces in one query, one table or one total.** +They are separate pipelines with different grains and estimate methods; a combined +figure is simply wrong. If the seller wants both, run the analysis twice and report +the two side by side, comparing direction and orders of magnitude — never exact +numbers. + ### Step 1 — Resolve the seller and pull today's snapshot -1. Resolve the seller from the store link or seller identifier the user provided. - If given a store link, resolve it to the seller once. -2. Use JoomPulse to pull the current snapshot for that one seller: store name, - estimated monthly revenue, estimated monthly sales, sales trend, cancellation - rate, listing count, rolling 60-day and 365-day sales, the categories covered, - seller medal, reputation, average ticket and average price, and location. -3. If the seller is not found, say so plainly and stop — invent nothing. +1. Resolve the seller from the store link or seller identifier the user provided, + **on the marketplace settled in Step 0**. If given a store link, resolve it to + the seller once. +2. Use JoomPulse to pull the current snapshot for that one seller. + - **Mercado Livre:** store name, estimated monthly revenue, estimated monthly + sales, sales trend, cancellation rate, listing count, rolling 60-day and + 365-day sales, the categories covered, seller medal, reputation, average + ticket and average price, and location. + - **Shopee:** shop name, the categories the shop covers, its location, its + buyer rating and review count, average ticket and average price, and the + shop's item count. **Build the shop's estimated revenue and sales up from + its items** — there is no store-level figure to read, and the result is an + estimate, so label it one. For the sales trend, count how many of the shop's + items are growing, stable and falling. **Cancellation rate and the rolling + 60-day and 365-day sales counts do not exist on Shopee** — do not look for a + substitute and do not derive one. +3. If the seller is not found, check the other marketplace before saying so; if it + is on neither, say so plainly and stop — invent nothing. ### Step 2 — Present today's snapshot and offer it for download -Lay out the snapshot fields as a table, headed with the store name and the date. -This table is the deliverable — and **offer it as a downloadable file (`.csv` / -`.xlsx`)** so the user can save it and bring it back next period as the baseline. -If any field comes back empty, show `—`; never substitute a guess. Add the JoomPulse -seller dashboard link. On a standalone snapshot there is **no change column and no -color-dot legend** — just field and current value. +Lay out the snapshot fields as a table, headed with the store name, the +**marketplace** and the date. This table is the deliverable — and **offer it as a +downloadable file (`.csv` / `.xlsx`)** so the user can save it and bring it back +next period as the baseline. If any field comes back empty, show `—`; never +substitute a guess. On Mercado Livre add the JoomPulse seller dashboard link; on +Shopee link the shop on Shopee instead — **there is no JoomPulse dashboard link +for Shopee**, so never invent one. On a standalone snapshot there is **no change +column and no color-dot legend** — just field and current value. ### Step 3 — Offer comparison, and compare if a previous table is supplied Invite the user to send a previous table for the same seller to compare periods. -**If they provide one**, parse its values, align by field to today's snapshot, and +**If they provide one**, check it is for the same seller **on the same +marketplace**, then parse its values, align by field to today's snapshot, and render a comparison table with the difference per field. A difference **requires both an old and a new value** for the same field — if a field is missing or -unreadable in the supplied table, show `—`, never a fabricated trend. If no previous -table is supplied, the snapshot stands on its own and the user is told to save it -for next time. +unreadable in the supplied table, show `—`, never a fabricated trend. On Shopee, +remember the three fields that do not exist there stay `—` on both sides and can +never yield a change. If no previous table is supplied, the snapshot stands on its +own and the user is told to save it for next time. ## Output Respond in pt-BR by default. Present the result with no commentary about how it was -produced. +produced. Lead with a short line naming the **marketplace** and the store. **Snapshot (always):** a markdown table `| Campo | Valor atual |` for the rows below, plus a downloadable `.csv` / `.xlsx` of the same data. -The snapshot / comparison table carries these rows (pt-BR labels): +**Snapshot / comparison rows (Mercado Livre)** — pt-BR labels: - Nome da loja - Receita média mensal (estimada) @@ -118,16 +193,52 @@ The snapshot / comparison table carries these rows (pt-BR labels): - Localização (cidade, estado, país) - Link JoomPulse do vendedor +**Snapshot / comparison rows (Shopee)** — same shape, with the marketplace's own +fields: + +- Nome da loja +- Receita média mensal (estimada) — **built up from the shop's items**, never + read as one store-level figure; always label it an estimate +- Vendas médias mensais (estimadas) — same build-up, same label +- Tendência de vendas — how many of the shop's items are **growing, stable or + falling** (for example `12 em alta · 30 estáveis · 8 em queda`). It is a mix, + not a single percentage — never compress it into one figure +- Taxa de cancelamento — **`—`: no Shopee equivalent exists** +- Anúncios — counts only items with **at least one lifetime sale**, so it + under-counts the shop's listings; say so +- Vendas (60 dias) — **`—`: no Shopee equivalent exists** +- Vendas (365 dias) — **`—`: no Shopee equivalent exists** +- Categorias — the categories the shop covers +- Nível da loja (Official store / Preferred (Indicado) / Common) — three **mutually + exclusive tiers, not a ladder**. Never map a tier onto a seller medal +- Avaliação dos compradores (0–5 estrelas), com o número de avaliações — this is + **not** the Mercado Livre reputation thermometer; it is a star rating, not a + colour ladder. Say so explicitly rather than presenting them as the same field +- Ticket médio / preço médio +- Localização +- Link da loja na Shopee — **there is no JoomPulse dashboard link for Shopee**, so + never invent one + +For the three rows with **no Shopee equivalent at all** — cancellation rate, sales +over the last 60 days and sales over the last 365 days — show `—` and state plainly +that the data does not exist for Shopee. **Never imply zero, and never present an +estimate in their place.** + **Comparison (only when a previous table is supplied):** a markdown table `| Campo | Era | Agora |`. Put the change (figure, percentage, or percentage point) inside the **Agora** cell, prefixed with a semantic color dot: -- 🟢 **good:** revenue up, sales up, listings up, medal improved, reputation - improved, cancellation rate **down**. -- 🔴 **bad:** revenue down, sales down, listings down, medal worse, reputation - worse, cancellation rate **up**. +- 🟢 **good:** revenue up, sales up, listings up, medal improved, reputation or buyer + rating improved, cancellation rate **down**. +- 🔴 **bad:** revenue down, sales down, listings down, medal worse, reputation or + buyer rating worse, cancellation rate **up**. - The **cancellation rate is inverted** — down = 🟢, up = 🔴. - **Categorias** moving is neutral context — show the change with **no color dot**. +- **On Shopee the shop tier is not a rung** — the three tiers are mutually + exclusive, so a tier that changed is neutral context with no dot, and "moved up a + tier" or "moved up a medal" phrasing must not be used. The Shopee sales trend is a + mix of growing, stable and falling items, so report how that mix shifted rather + than colouring one number. Column headers are words (`Campo | Era | Agora`), never a bare "Δ" symbol. Show the color-dot legend (🟢/🔴) **only** in the comparison table, where the dots actually @@ -135,14 +246,28 @@ appear — never on a plain snapshot. Close with a short **Principais insights** section: with a comparison, interpret what moved; on a standalone snapshot, frame it as the starting picture with no trend -claims. +claims. On Shopee, note that history starts May 2026, so there is no long-run trend +and no seasonal read. -**Disclaimer (every report):** +**Disclaimer (every report) — use the variant for the marketplace you queried.** + +Mercado Livre: > ⚠️ Receita e vendas são estimativas do JoomPulse com base no histórico de > anúncios — não são transações reais. / Revenue and sales are JoomPulse estimates > based on historical listing data — not actual transactions. +Shopee: + +> ⚠️ **Todos** os números de vendas e receita são estimativas do JoomPulse, a partir +> dos contadores arredondados da própria Shopee — não são transações reais, e +> diferenças pequenas são ruído. Só itens com pelo menos uma venda no histórico são +> rastreados, então a contagem de anúncios é um piso. Preço, avaliação e número de +> avaliações são reais. / **Every** sales and revenue figure is a JoomPulse estimate +> built from Shopee's own rounded sold counters — not actual transactions, and small +> gaps are noise. Only items with at least one lifetime sale are tracked, so the +> listing count is a lower bound. Price, rating, and reviews are real. + Keep it concise — no methodology, no internal jargon, and do not explain these rules to the user. @@ -154,21 +279,28 @@ present) always render as markdown in the response text, and the downloadable fi mirrors what is shown. - **When the client can render inline visuals**, present **metric cards** for the - key current metrics — for example estimated monthly revenue, estimated monthly - sales, listings, cancellation rate, and medal / reputation. With a comparison, you - may annotate each card with its `era → agora` change. + key current metrics — on Mercado Livre, for example estimated monthly revenue, + estimated monthly sales, listings, cancellation rate, and medal / reputation; on + Shopee, estimated monthly revenue and sales (built up from items), listings, buyer + rating, and shop tier. With a comparison, you may annotate each card with its + `era → agora` change. **Never show a card for a field that does not exist on the + marketplace** — no cancellation-rate or 60/365-day card on Shopee. - **Otherwise** (plain terminal, no visual support), output the same information as a markdown table plus a short text summary. Same numbers, no visual. - **Round all displayed numbers** and use **pt-BR number and currency formatting** (for example `R$ 1,38 mi`, `7.900`, `+1,3 p.p.`) everywhere — cards and table. -- Use a consistent medal palette: platina = purple, ouro = amber, prata = blue, sem - medalha = white with a thin border (white needs the border to stay visible on a - light background). +- On Mercado Livre, use a consistent medal palette: platina = purple, ouro = amber, + prata = blue, sem medalha = white with a thin border (white needs the border to + stay visible on a light background). **On Shopee there are no medals** — write the + shop tier as plain text and never colour it as if it were a rung on a ladder. +- The Shopee sales trend is a **mix** of growing, stable and falling items; if you + chart it, chart the three counts side by side, never a single percentage. - **No synthesized trend line from a single snapshot** (there is no server-side history). Only if the user supplies several past-period tables may you plot a - simple line across those periods. + simple line across those periods — and on Shopee no such line can reach back + before May 2026, where the history starts. -Example comparison table (only when a previous table is supplied): +Example comparison table, **Mercado Livre** (only with a previous table): | Campo | Era | Agora | |---|---|---| @@ -179,6 +311,18 @@ Example comparison table (only when a previous table is supplied): | Taxa de cancelamento | 2,1% | 🔴 3,4% · ↑ +1,3 p.p. | | Categorias | 12 | 14 · +2 | +Example comparison table, **Shopee** (same shape, marketplace's own fields): + +| Campo | Era | Agora | +|---|---|---| +| Receita mensal (est.) | R$ 180 mil | 🟢 R$ 214 mil · ↑ +19% | +| Vendas/mês (est.) | 3.100 | 🔴 2.850 · ↓ −8% | +| Tendência de vendas | 10 alta · 34 est. · 6 queda | 14 alta · 28 est. · 8 queda | +| Nível da loja | Common | Preferred (Indicado) | +| Avaliação dos compradores | 4,6 (1.204 aval.) | 🟢 4,8 (1.410 aval.) · ↑ | +| Taxa de cancelamento | — | — (não existe na Shopee) | +| Vendas (60 dias) | — | — (não existe na Shopee) | + Presentation rules: column headers are words, never a bare "Δ" symbol; show the color-dot legend only when those dots appear (the comparison table); render a chart only when the data supports it. @@ -189,12 +333,23 @@ The user should never see a system or stack error — only a friendly next step. Translate any failure into one short, friendly sentence, and retry once quietly on a transient hiccup. -- **Seller not found:** state it plainly, stop, and invent nothing. +- **Marketplace unclear:** ask one short question naming both before reading any + data. Never guess and never default. +- **Seller not found:** check the other marketplace first; if it is on neither, + state it plainly, stop, and invent nothing. - **No previous table supplied:** render today's snapshot only (no change column, no legend) and invite the user to save it for next time. -- **Supplied table is for a different seller, malformed, or unreadable:** say so - plainly and fall back to the snapshot only; do not force a misaligned comparison. +- **Supplied table is for a different seller, a different marketplace, malformed, or + unreadable:** say so plainly and fall back to the snapshot only; do not force a + misaligned comparison, and never compare a Shopee table against a Mercado Livre + one. - **Empty or failed pull:** say the data is temporarily unavailable and to try again. Never paste internal error text, HTTP codes, or field names to the user. - **A single field empty but the seller is found:** show `—` for that field and keep the rest. +- **Fields that do not exist on Shopee:** cancellation rate and sales over the last + 60 and 365 days are absent attributes, not missing values. Show `—`, say the data + does not exist for Shopee, and never fill the gap with a zero or an estimate. +- **Shopee listing count:** it covers only items with at least one lifetime sale, so + it under-counts the shop's listings — say so rather than presenting it as + complete. diff --git a/skills/top-brand-position-tracker/SKILL.md b/skills/top-brand-position-tracker/SKILL.md index 73fe95a..7ad016b 100644 --- a/skills/top-brand-position-tracker/SKILL.md +++ b/skills/top-brand-position-tracker/SKILL.md @@ -51,7 +51,11 @@ JoomPulse MCP setup before it can rank brands and track their positions. ## Scope -- **Mercado Livre (Brasil) only.** Other marketplaces are out of scope. +- **Mercado Livre (Brasil) only.** JoomPulse also covers Shopee Brasil, but + **Shopee brand coverage is incomplete by construction** — only items with tracked + sales carry a brand, so brands are systematically missing and a ranking would + imply a completeness the data cannot support. Brand shares and brand leaderboards + must not be computed for Shopee; this analysis exists only for Mercado Livre. - **Sales and revenue are JoomPulse estimates** derived from historical listing data — not real transactions. Disclose this in every output. By contrast, **review count is real Mercado Livre history** — say so, it is a strength of the @@ -226,6 +230,13 @@ separator (`1.250`). Keep the ⚠️ estimate disclaimer on every output. The seller should never see a system or stack error — only a friendly next step. +- **The seller asks about Shopee:** say plainly that Shopee brand data is too + incomplete to rank — only items with tracked sales carry a brand, so a + leaderboard would look authoritative while missing whole brands. Do not produce a + Shopee brand ranking or brand share. Offer instead what Shopee data does support: + category structure and concentration, or the best-selling items in the category. + If the marketplace is unclear, ask first — an identifier beginning `MLB` is + Mercado Livre, a bare 10–11 digit number is Shopee. - **No category given or an ambiguous name:** ask for the category (name, identifier, or JoomPulse link) before going further. - **No active listings or no brands in the category:** say no brand data is diff --git a/skills/top-keywords-in-my-category/SKILL.md b/skills/top-keywords-in-my-category/SKILL.md index 797047b..945e76a 100644 --- a/skills/top-keywords-in-my-category/SKILL.md +++ b/skills/top-keywords-in-my-category/SKILL.md @@ -10,7 +10,8 @@ description: > for my listings", and the pt-BR equivalents "palavras-chave mais buscadas", "termos em alta na categoria", "o que as pessoas pesquisam", "melhores palavras-chave para meus anúncios". The keywords and ranks are real search-trend - data, not estimates. For category market size and opportunity, use the + data, not estimates. Mercado Livre (Brasil) only — Shopee has no search-demand + data, so a Shopee request cannot be answered here. For category market size and opportunity, use the category-opportunity-index skill; for ranking the sellers in a category, use the top-sellers-in-category skill. --- @@ -39,7 +40,11 @@ JoomPulse MCP setup before it can list a category's keywords. ## Scope -- **Mercado Livre (Brasil) only.** Other marketplaces are out of scope. +- **Mercado Livre (Brasil) only.** JoomPulse also covers Shopee Brasil, but + **Shopee has no search-keyword or search-demand data at all**, so this analysis + exists only for Mercado Livre. Never answer a Shopee keyword question with + Mercado Livre terms, and never substitute a count of competing items for search + demand — that measures supply, not what shoppers type. - **Real data, not an estimate.** The keywords, ranks, and competing-product counts come from Mercado Livre search trends — say so; do not add the sales estimate disclaimer that other skills use. @@ -103,6 +108,12 @@ The seller should never see a system or stack error — only a friendly next ste - **No keywords for the category:** say plainly that no trending terms were found and suggest a broader or adjacent category. +- **The seller asks about Shopee:** say plainly that search-keyword data does not + exist for Shopee, so there is nothing to rank — do not improvise a substitute. + Offer the nearest real alternative instead: Shopee category analytics, or the + best-selling items in the Shopee category by estimated recent sales. If it is + unclear which marketplace they mean (an identifier beginning `MLB` is Mercado + Livre, a bare 10–11 digit number is Shopee), ask before answering. - **Data temporarily unavailable:** retry once quietly; if it is still down, say the data is temporarily unavailable and to try again. Never paste internal error text, HTTP codes, or field names to the seller. diff --git a/skills/unbranded-products-in-category/SKILL.md b/skills/unbranded-products-in-category/SKILL.md index 086d071..cc92755 100644 --- a/skills/unbranded-products-in-category/SKILL.md +++ b/skills/unbranded-products-in-category/SKILL.md @@ -1,28 +1,31 @@ --- name: unbranded-products-in-category description: > - Finds products with no brand (unbranded / no-name / generic) in one Mercado Livre (Brasil) - category via JoomPulse — an opening to enter with your own brand / private label, since - buyers there aren't anchored to a brand name. Asks for a category, lists the active no-brand - listings ranked by estimated weekly demand, and returns a product table (price, estimated - weekly sales and revenue, rating, reviews, time on air, shipping, listing type, seller - medal) with a JoomPulse link per item. Triggers: "unbranded products", "products without a - brand", "private-label opportunities", and the pt-BR "produtos sem marca", "genéricos que - vendem", "oportunidade de marca própria". Sales and revenue are JoomPulse estimates, not - real transactions. NOT for ranking brands (use top-brand-position-tracker), brand-new - listings (use new-growing-products-in-category), high-demand low-rated products (use high- - demand-low-quality-finder), or niches without platinum sellers (use uncontested-niche- - finder). + Finds products with no brand (unbranded / no-name / generic) in one category on + JoomPulse — Mercado Livre (Brasil) or Shopee Brasil: an opening for your own brand + / private label, where buyers aren't brand-anchored. Asks for a marketplace and a + category, ranks the no-brand listings by estimated demand, and returns a product + table. Triggers: "unbranded products", "products without a + brand", "private-label opportunities", "unbranded products on Shopee"; pt-BR + "produtos sem marca", "genéricos que vendem", "oportunidade de marca própria", + "produtos sem marca na Shopee". Ask which marketplace when unclear; never mix the + two. Sales and revenue are JoomPulse estimates, not real transactions; price, + rating and reviews are real. On Shopee the unbranded set is a lower bound. NOT for + ranking brands (use top-brand-position-tracker), new listings (use + new-growing-products-in-category), high-demand low-rated products (use + high-demand-low-quality-finder), or niches without platinum sellers (use + uncontested-niche-finder). --- # Unbranded Products In Category This skill surfaces the **products that have no brand** (unbranded / no-name / -generic) in one Mercado Livre (Brasil) category — the listings where the brand is -empty. These are spots where a seller can enter with their **own brand / private -label**, because buyers there aren't anchored to a brand name. For each it shows -price, estimated weekly sales and revenue, rating, reviews, time on air, shipping, -listing type and seller medal, with a JoomPulse link per item. +generic) in one category on **Mercado Livre (Brasil) or Shopee Brasil** — the +listings where no brand is attached. These are spots where a seller can enter with +their **own brand / private label**, because buyers there aren't anchored to a +brand name. For each it shows price, estimated sales and revenue, rating, reviews, +time on air, and the seller's or shop's standing. On Mercado Livre each row links +to its JoomPulse page; on Shopee each row links to the item on Shopee. It is the opposite of ranking a category's brands (for that, use the top-brand-position-tracker skill). For fresh listings use the @@ -33,53 +36,144 @@ use the uncontested-niche-finder skill. ## Prerequisites - JoomPulse MCP access is configured for the current agent environment. -- The user names a category (free text is fine). -- The available JoomPulse tools can return the active listings in a category, tell - which of them have no brand, and provide each listing's price, estimated weekly - sales and revenue, rating, reviews, time on air, logistics, listing type and - seller medal. +- The user provides a marketplace — Mercado Livre (Brasil) or Shopee Brasil — and + names a category (free text is fine). +- The available JoomPulse tools can return the listings in a category and resolve a + category name on **either** marketplace, tell which listings have no brand + attached, and provide each listing's price, estimated sales and revenue, rating, + reviews, and time on air. On Mercado Livre they also report listing status, + logistics, listing type and the seller medal; on Shopee, the shop tier, the date + the item was created and the date it was last seen. If JoomPulse MCP access is unavailable, stop and explain that the skill requires JoomPulse MCP setup before it can find unbranded products. ## Scope -- **Mercado Livre (Brasil) only.** Other marketplaces are out of scope. -- **Sales and revenue are JoomPulse estimates** derived from historical listing - data — not real transactions. By contrast, price, rating, and review count are - real history. Disclose the estimate caveat in every output. +- **Mercado Livre (Brasil) and Shopee Brasil**, one at a time. Other marketplaces + are out of scope. +- **Sales and revenue are JoomPulse estimates** — not real transactions. By + contrast, price, rating, and review count are real history. Disclose the estimate + caveat in every output. The estimates are built differently on each marketplace: + on Mercado Livre from historical listing data, on Shopee from the marketplace's + own rounded sold counters refined with review movement. Use the matching + disclaimer. - **Read-only.** The skill never writes or modifies anything, and does not render product images. - **Language:** detect the seller's language and respond in it. Default to pt-BR. - **Keep the workflow invisible.** Show `—` for any missing value; never fabricate. +**Shopee data — what differs from Mercado Livre** + +- **Estimates come from Shopee's own rounded sold counters**, refined with review + movement. Treat small gaps between items as noise and never rank on a difference + of a few units. Price, rating and review count are real. +- **Coverage is not a census**: only items with at least one lifetime sale are + tracked, so any count is a lower bound and an absent item is not evidence it does + not sell. +- **History starts May 2026** — there is no long-run trend and no seasonal read. +- **Category analytics stop at three levels**; the item view reaches deeper. Say + which you used. +- **No seller medals** — Shopee has three mutually exclusive shop tiers: **Official + store**, **Preferred (Indicado)** and **Common**. There is no ladder; inventing + Shopee medals is fabrication. +- **No catalogue and no buy-box**, and an item belongs to one shop. +- **No fulfilment programme, no free-shipping flag and no listing tier** — show `—` + rather than guessing. +- **Concentration is measured differently** and thresholds do not transfer between + marketplaces. +- Item titles mix Portuguese, English and Chinese — search both languages. + ## Workflow +### Step 0 — Decide the marketplace + +JoomPulse covers **two separate marketplaces**: Mercado Livre (Brasil) and Shopee +Brasil. They are independent datasets with different coverage, history and +mechanics. Decide which one the request belongs to **before reading any data**: + +- **The seller said so.** "Shopee" means Shopee; "Mercado Livre", "MeLi" or "ML" + means Mercado Livre. +- **An identifier gives it away.** An identifier beginning `MLB` is Mercado Livre; + a bare 10–11 digit number is a Shopee item or shop. A `mercadolivre.com.br` link + is Mercado Livre, a `shopee.com.br` link is Shopee. If an identifier is not found + on the marketplace you assumed, check the other one before telling the seller it + does not exist. +- **The request only makes sense on one of them** — buy-box, catalogue position, + seller medals, a fulfilment programme or search keywords are Mercado Livre only. +- **Otherwise ask** — one short question, mentioning that both are available. + **Never guess and never default.** + +**Never mix data from the two marketplaces in one query, one table or one total.** +They are separate pipelines with different grains and estimate methods; a combined +figure is simply wrong. If the seller wants both, run the analysis twice and report +the two side by side, comparing direction and orders of magnitude — never exact +numbers. + ### Step 1 — Resolve the category Ask for a category if none was given, then use JoomPulse to match the free text to -a category. If several plausible matches come back, list the top candidates (name -and depth level) and let the user choose — do not guess between unrelated categories. +a category **on the chosen marketplace**. If several plausible matches come back, +list the top candidates (name and depth level) and let the user choose — do not +guess between unrelated categories. On Shopee, category analytics stop at three +levels — if the seller names a deeper niche, work it through the item view instead +and say which you used. ### Step 2 — Find the unbranded products -Use JoomPulse to get the category's **active** listings that have **no brand** -(brand empty / unbranded). Rank them by estimated weekly demand (estimated weekly -revenue, or weekly sales), highest first, and keep the strongest ~20–30. +Use JoomPulse to get the category's listings that have **no brand attached** (brand +empty / unbranded), rank them by estimated demand, highest first, and keep the +strongest ~20–30. + +- **Mercado Livre:** take the **active** listings and rank by estimated weekly + demand (estimated weekly revenue, or weekly sales). +- **Shopee:** items carry an explicit "has a brand attached" signal, so the no-brand + filter ports over directly. There is no listing-status filter here — how recently + an item was last seen is what tells you whether it is still live, so check it and + never present a stale row as a live opportunity. Estimated sales and revenue cover + the **last 30 days**, not a week, so rank by estimated 30-day revenue and label + those columns as 30 days. +- **On Shopee the unbranded set is a lower bound.** Brand information exists only + for items that are tracked at all, and only items with at least one lifetime sale + are tracked. Never quote the count or the share of unbranded items as complete, + and never claim that some percentage of the category has no brand. ## Output -Respond in the seller's language (default pt-BR). The product list always renders -as a markdown table: +Respond in the seller's language (default pt-BR). Lead with a one-line summary (the +**marketplace**, the category and how many unbranded products were found), sort by +estimated demand, and end with the disclaimer. The product list always renders as a +markdown table. + +**Product table (Mercado Livre):** | MLB | Nome | Vendedor | Preço | Vendas (semana) | Receita (semana) | Classificação | Avaliações | Tempo no ar | Frete grátis | Mercado Envios Full | Tipo de anúncio | Medalha do vendor | |---|---|---|--:|--:|--:|--:|--:|--:|:--:|:--:|---|---| - The **MLB** identifier links to the item's JoomPulse page. -- Lead with a one-line summary (category + how many unbranded products were found), - sort by estimated weekly demand, and end with the disclaimer. -**Disclaimer (every report):** +**Product table (Shopee)** — same shape, with the marketplace's own columns: + +| Item | Nome | Loja | Preço | Vendas (30 dias) | Receita (30 dias) | Classificação | Avaliações | Tempo no ar | Nível da loja | +|---|---|---|--:|--:|--:|--:|--:|--:|---| + +- The item identifier links to the item on Shopee — **there is no JoomPulse + dashboard link for Shopee rows**, so never invent one. +- **Tempo no ar** is computed from the date the item was created. +- **Nível da loja** is the shop tier — Official store / Preferred (Indicado) / + Common. Never map a shop tier onto a seller medal. +- Free shipping, Mercado Envios Full and the listing tier have **no Shopee + equivalent**: either drop those columns or show `—` in them, never a "Não". +- The sales window differs: weekly on Mercado Livre, 30 days on Shopee. Never + present a 30-day figure under a weekly heading. +- Say in the text that the Shopee list is a **lower bound** — a brand is recorded + only for tracked items, and only items with at least one lifetime sale are + tracked — so it is not the complete set of unbranded items in the category, and no + share of the category can be claimed from it. + +**Disclaimer (every report) — use the variant for the marketplace you queried.** + +Mercado Livre: > ⚠️ Vendas e receita são estimativas do JoomPulse com base no histórico de > anúncios — não são transações reais. Preço, classificação e avaliações são @@ -87,6 +181,19 @@ as a markdown table: > based on historical listing data — not actual transactions. Price, rating, and > reviews are real Mercado Livre history. +Shopee: + +> ⚠️ Vendas e receita são estimativas do JoomPulse a partir dos contadores +> arredondados da própria Shopee — não são transações reais, e diferenças pequenas +> entre itens são ruído. Só itens com pelo menos uma venda no histórico são +> rastreados, e a marca só é conhecida para itens rastreados: esta lista de produtos +> sem marca é um piso, não a categoria inteira. Preço, classificação e avaliações +> são histórico real da Shopee. / Sales and revenue are JoomPulse estimates built +> from Shopee's own rounded sold counters — not actual transactions, and small gaps +> between items are noise. Only items with at least one lifetime sale are tracked, +> and a brand is known only for tracked items: this unbranded list is a lower bound, +> not the whole category. Price, rating, and reviews are real Shopee history. + ## Visualization When the client can render inline visuals, present metric cards and a chart; @@ -96,14 +203,18 @@ surface, and the ⚠️ disclaimer always stays in the text. No product images. When inline visuals are available: -- **Three cards:** number of unbranded products found, total estimated weekly - sales, and average ticket. -- **A horizontal bar** of the top ~10 unbranded products by estimated weekly - revenue. Render the chart only when there are enough products (skip it under - about four), and never block on it. +- **Three cards:** number of unbranded products found — on Shopee label it as a + lower bound — total estimated sales for the window in use, and average ticket. +- **A horizontal bar** of the top ~10 unbranded products by estimated revenue — + weekly on Mercado Livre, 30-day on Shopee; name the window on the chart. Render + the chart only when there are enough products (skip it under about four), and + never block on it. Presentation rules: render a chart only when the data supports it; any column with -movement uses a word header, never a bare "Δ". +movement uses a word header, never a bare "Δ". The medal palette (platina = purple, +ouro = amber, prata = blue, sem medalha = white with a thin border) is Mercado Livre +only — on Shopee write the shop tier as plain text and never colour it as if it were +a rung on a ladder. ## Notes & Guardrails @@ -111,9 +222,14 @@ The seller should never see a system or stack error — only a friendly next ste - **No unbranded products in the category:** the category may be brand-dominated — say so plainly and suggest a broader or adjacent category. Never fabricate rows. -- **Ambiguous category name:** list the candidates and ask the user to choose. + On Shopee, add that the list is a lower bound — a brand is recorded only for + tracked items, and only items with at least one lifetime sale are tracked — so an + empty result is not proof that the whole category is branded. +- **Ambiguous category name:** list the candidates and ask the user to choose. If + nothing matches, check the other marketplace before saying it does not exist. - **Market data temporarily unavailable:** retry once quietly; if it is still down, say market data is temporarily unavailable and to try again. Never paste internal error text, HTTP codes, or field names to the seller. - **Never silently limit coverage** — if the category is larger than what you pulled, say the table covers the strongest unbranded products, not all of them. + On Shopee say it twice over: the coverage itself is partial. diff --git a/skills/uncontested-niche-finder/SKILL.md b/skills/uncontested-niche-finder/SKILL.md index d57cd30..7117773 100644 --- a/skills/uncontested-niche-finder/SKILL.md +++ b/skills/uncontested-niche-finder/SKILL.md @@ -1,64 +1,79 @@ --- name: uncontested-niche-finder description: > - Finds low-competition niche products on Mercado Livre (Brasil) — active listings in deep - sub-categories (deeper than the third level) of a chosen category that have no platinum - seller at all, surfaced via JoomPulse. Use it when a seller wants uncontested niches, gaps - without strong incumbents, or where to enter without fighting a dominant platinum seller. - Triggers (EN): "uncontested niche", "low-competition products", "categories without platinum - sellers", "find a niche to enter"; (pt-BR): "nicho sem concorrência", "produtos sem vendedor - platinum", "nicho pouco disputado", "subcategorias sem platinum". It returns one table of - niche products, each with a competition signal (number of sellers) and a JoomPulse link. - Sales and revenue are JoomPulse estimates, not real transactions; price, rating, and reviews - are real history. For one product and its competitors use the ml-product-analysis skill; for - fast-growing deep categories rather than products use the growing-leaf-category-tracker - skill. + Finds low-competition niche products in the deep sub-categories of one category + on JoomPulse — Mercado Livre (Brasil) or Shopee Brasil. Keeps only the deep + niches with no dominant incumbent: no platinum seller on Mercado Livre, no + Official store (Shopee Mall) seller on Shopee. Returns one table of niche + products, each with a competition signal (how many sellers). Use when a seller + wants uncontested niches or where to enter without fighting an incumbent. + Triggers: "uncontested niche", "low-competition products", "find a niche to + enter"; pt-BR "nicho sem concorrência", "produtos sem vendedor platinum", + "nicho pouco disputado na Shopee", "nicho sem loja oficial na Shopee". Ask which + marketplace when unclear; never mix the two. Sales and revenue are JoomPulse + estimates, not real transactions; price, rating and reviews are real. For one + product and its competitors use the ml-product-analysis skill; for fast-growing + deep categories, the growing-leaf-category-tracker skill. --- # Uncontested Niche Finder -This skill finds products in **deep sub-categories** of a chosen Mercado Livre -(Brasil) category — sub-categories deeper than the third level — that have **no -platinum seller at all** among their listings. These are genuinely -platinum-free niches a seller can enter without fighting a dominant incumbent. -Given a category by name or identifier, it surfaces the active listings in those -deep niches, and ranks them by estimated traction so the strongest uncontested -opportunities surface first. - -A truly uncontested niche is a **whole deep sub-category with zero platinum -sellers** — not merely the non-platinum listings inside a sub-category that -still has platinum sellers elsewhere. Dropping individual platinum-held listings -is not enough: if any platinum seller is active in the sub-category, that niche -is contested, so the skill keeps only the deep sub-categories that have no -platinum seller present. If keeping only platinum-free sub-categories would leave -too few results, the skill may also show non-platinum listings from sub- -categories that still have platinum sellers — but it labels those plainly as -**non-platinum listings (platinum sellers still present in the category)** and -does not call them uncontested. +This skill finds products in **deep sub-categories** of a chosen category — on +**Mercado Livre (Brasil) or Shopee Brasil** — where the whole deep sub-category +has **no dominant incumbent** among its listings. On Mercado Livre the incumbent +test is **no platinum seller at all**; on Shopee, which has no seller medals, it +is **no Official store (Shopee Mall) seller at all**. Given a marketplace and a +category by name or identifier, it surfaces the active listings in those deep +niches, and ranks them by estimated traction so the strongest uncontested +opportunities surface first. On Mercado Livre each row links to its JoomPulse +page; on Shopee each row links to the item on Shopee. + +A truly uncontested niche is a **whole deep sub-category with zero incumbents of +that kind** — not merely the listings without one inside a sub-category that +still has them elsewhere. Dropping individual incumbent-held listings is not +enough: if any platinum seller (Mercado Livre) or any Official store (Shopee) is +active in the sub-category, that niche is contested, so the skill keeps only the +deep sub-categories with none present. If keeping only those would leave too few +results, the skill may also show the non-incumbent listings from sub-categories +that still have one — but it labels those plainly as **non-platinum listings +(platinum sellers still present in the category)** on Mercado Livre, or +**listings outside an Official store (Official stores still present in the +category)** on Shopee, and does not call them uncontested. This is different from broad assortment work. To size up one product and the products that compete with it, use the ml-product-analysis skill. To find the fast-growing deep **categories** under a category (rather than the products inside them), use the growing-leaf-category-tracker skill. This skill answers "where can -I enter without facing a platinum seller?" for a category the seller names. +I enter without facing a dominant incumbent?" for a category the seller names, on +the marketplace they choose. ## Prerequisites - JoomPulse MCP access is configured for the current agent environment. -- The user provides one category, as a name or a category identifier. -- The available JoomPulse tools can resolve a category, walk its deep - sub-categories, and list the active product listings within them. +- The user provides a marketplace — Mercado Livre (Brasil) or Shopee Brasil — and + one category, as a name or a category identifier. +- The available JoomPulse tools can resolve a category on **either** marketplace, + reach the levels below it, and list the active product listings within them, + with the standing of the seller behind each listing — the seller medal on + Mercado Livre, the shop tier on Shopee. +- On Shopee, category analytics stop at three levels, so the deep set is built + from the deeper category path the items themselves carry; the competition signal + for a deep niche comes from the view of the sellers in a category, pinned to one + category at a time. If JoomPulse MCP access is unavailable, stop and explain that the skill requires JoomPulse MCP setup before it can find uncontested niches. ## Scope -- **Mercado Livre (Brasil) only.** Other marketplaces are out of scope. -- **Sales and revenue are JoomPulse estimates** derived from historical listing - data — not real transactions. Disclose this in every output. By contrast, - **price, rating, and review count are real Mercado Livre history** — say so, it - is a strength of the report. +- **Mercado Livre (Brasil) and Shopee Brasil**, one at a time. Other marketplaces + are out of scope. +- **Sales and revenue are JoomPulse estimates** — not real transactions. Disclose + this in every output. By contrast, **price, rating, and review count are real + history** from the marketplace — say so, it is a strength of the report. The + estimates are built differently on each marketplace: on Mercado Livre from + historical listing data, on Shopee from the marketplace's own rounded sold + counters refined with review movement. Use the matching disclaimer. - **Read-only.** The skill does not sign in as the seller or modify any listing. - **Language:** detect the seller's language and respond in it. Default to pt-BR. - **Keep the workflow invisible.** The seller wants the niches, not a play-by- @@ -66,53 +81,123 @@ JoomPulse MCP setup before it can find uncontested niches. every approach fails do you say one short, friendly sentence. Never fill gaps from general knowledge. +**Shopee data — what differs from Mercado Livre** + +- **Estimates come from Shopee's own rounded sold counters**, refined with review + movement. Treat small gaps between items as noise and never rank on a difference + of a few units. Price, rating and review count are real. +- **Coverage is not a census**: only items with at least one lifetime sale are + tracked, so any count is a lower bound and an absent item is not evidence it does + not sell. +- **History starts May 2026** — there is no long-run trend and no seasonal read. +- **Category analytics stop at three levels**; the item view reaches deeper. Say + which you used. +- **No seller medals** — Shopee has three mutually exclusive shop tiers: **Official + store**, **Preferred (Indicado)** and **Common**. There is no ladder; inventing + Shopee medals is fabrication. +- **No catalogue and no buy-box**, and an item belongs to one shop. +- **No fulfilment programme, no free-shipping flag and no listing tier** — show `—` + rather than guessing. +- **Concentration is measured differently** and thresholds do not transfer between + marketplaces. +- Item titles mix Portuguese, English and Chinese — search both languages. + ## Workflow +### Step 0 — Decide the marketplace + +JoomPulse covers **two separate marketplaces**: Mercado Livre (Brasil) and Shopee +Brasil. They are independent datasets with different coverage, history and +mechanics. Decide which one the request belongs to **before reading any data**: + +- **The seller said so.** "Shopee" means Shopee; "Mercado Livre", "MeLi" or "ML" + means Mercado Livre. +- **An identifier gives it away.** An identifier beginning `MLB` is Mercado Livre; + a bare 10–11 digit number is a Shopee item or shop. A `mercadolivre.com.br` link + is Mercado Livre, a `shopee.com.br` link is Shopee. If an identifier is not found + on the marketplace you assumed, check the other one before telling the seller it + does not exist. +- **The request only makes sense on one of them** — buy-box, catalogue position, + seller medals, a fulfilment programme or search keywords are Mercado Livre only. +- **Otherwise ask** — one short question, mentioning that both are available. + **Never guess and never default.** + +**Never mix data from the two marketplaces in one query, one table or one total.** +They are separate pipelines with different grains and estimate methods; a combined +figure is simply wrong. If the seller wants both, run the analysis twice and report +the two side by side, comparing direction and orders of magnitude — never exact +numbers. + ### Step 1 — Resolve the category and find its deep sub-levels 1. **Ask the user for a category** (a name or a category identifier). If given a - name, use JoomPulse to resolve it to a category, matching on the category - name. If several categories match, briefly list the candidates (name and - level) and ask which one is meant. -2. **Find every sub-category deeper than the third level** that sits under the - chosen category. Use JoomPulse to walk down the category tree from the chosen - branch and collect the descendant categories below the third level. Keep that - set of deep category identifiers for the next step. -3. If the chosen category is itself at or above the third level and has no - descendants below it, tell the user there are no deep sub-levels for it and - offer to run on a broader category. - -### Step 2 — Keep only the platinum-free deep sub-categories + name, use JoomPulse to resolve it to a category **on the chosen marketplace**, + matching on the category name. If several categories match, briefly list the + candidates (name and level) and ask which one is meant. +2. **Build the set of levels deeper than the third** under the chosen category. + - **Mercado Livre:** use JoomPulse to walk down the category tree from the + chosen branch and collect the descendant categories below the third level. + Keep that set of deep category identifiers for the next step. + - **Shopee:** deep niches do exist, but only through the item view — Shopee's + category analytics stop at three levels, while the items themselves carry a + category path several levels deeper, and populated fourth-level leaves are + real. So build the deep set from **the items' own deeper category path** + rather than the category tree, and always say which level you worked at. +3. If the chosen category is itself at or above the third level and has nothing + deeper beneath it, tell the user there are no deep sub-levels for it and offer + to run on a broader category. + +### Step 2 — Keep only the uncontested deep sub-categories 1. Use JoomPulse to list the **active product listings** in those deep - sub-categories. For each listing collect: name, category, seller, listing - type, seller medal, logistics (frete grátis), price, estimated **weekly** - sales and revenue, rating, review count, time on air, and — where available — - how many sellers compete on the listing. -2. **Decide which deep sub-categories are genuinely uncontested.** A deep sub- - category is uncontested only when it has **no platinum seller at all** among - its listings. Group the listings by their deep sub-category, check each group - for any platinum seller, and **keep only the sub-categories with zero platinum - sellers.** Do not merely drop the platinum-held listings from a sub-category - that still has platinum sellers — that sub-category is contested and its other - listings are not uncontested. -3. From the platinum-free sub-categories, keep the listings that are real, funded + sub-categories. + - **Mercado Livre:** for each listing collect name, category, seller, listing + type, seller medal, logistics (frete grátis), price, estimated **weekly** + sales and revenue, rating, review count, time on air, and — where available + — how many sellers compete on the listing. + - **Shopee:** collect name, the deeper category path the item itself carries, + shop, shop tier (Official store / Preferred (Indicado) / Common), price, + estimated sales and revenue **over the last 30 days**, rating, review count, + the date the item was created — this is what time on air is computed from — + and the date it was last seen. There is no listing-status filter on Shopee, + so how recently an item was last seen is what tells you whether it is still + live; check it and never present a stale row as a live opportunity. Free + shipping and listing tier have no Shopee equivalent. The competition signal + — how many sellers are in the niche — comes from the view of the sellers in + a category, pinned to one deep category at a time. +2. **Decide which deep sub-categories are genuinely uncontested.** Group the + listings by their deep sub-category and check each group for the incumbent that + matters on that marketplace: + - **Mercado Livre:** a deep sub-category is uncontested only when it has **no + platinum seller at all** among its listings. **Keep only the sub-categories + with zero platinum sellers.** + - **Shopee:** there are no medals and no ladder, so the platinum wording does + not carry across. A deep niche is uncontested only when it has **no Official + store (Shopee Mall) seller at all** — the three shop tiers are mutually + exclusive (Official store / Preferred (Indicado) / Common). **Keep only the + niches with zero Official stores.** + + Do not merely drop the incumbent-held listings from a sub-category that still + has one — that sub-category is contested and its other listings are not + uncontested. +3. From the uncontested sub-categories, keep the listings that are real, funded niches — those with estimated sales above zero — and rank them so the - strongest uncontested opportunities lead (by estimated weekly revenue by - default). If nothing has estimated sales, fall back to listing the active - listings in the platinum-free sub-categories and say so. These are the - **uncontested niches.** -4. **If keeping only platinum-free sub-categories leaves too few results**, you - may additionally include the non-platinum listings from sub-categories that - still have platinum sellers — but present them in a clearly separate, labelled - group, **"non-platinum listings (platinum sellers still present in the - category)"**, and do **not** call them uncontested. Always lead with the - genuinely platinum-free niches. -5. If every deep sub-category has at least one platinum seller (none are - platinum-free), report that the deep sub-categories are already contested by - platinum sellers, suggest a sibling category, and — if helpful — offer the - non-platinum listings under the labelled non-uncontested group described - above. + strongest uncontested opportunities lead: by estimated **weekly** revenue on + Mercado Livre, by estimated **30-day** revenue on Shopee. If nothing has + estimated sales, fall back to listing the active listings in those + sub-categories and say so. These are the **uncontested niches.** +4. **If keeping only the uncontested sub-categories leaves too few results**, you + may additionally include the non-incumbent listings from sub-categories that + still have one — but present them in a clearly separate, labelled group, + **"non-platinum listings (platinum sellers still present in the category)"** on + Mercado Livre or **"listings outside an Official store (Official stores still + present in the category)"** on Shopee, and do **not** call them uncontested. + Always lead with the genuinely uncontested niches. +5. If every deep sub-category has at least one incumbent, report that the deep + sub-categories are already contested — by platinum sellers on Mercado Livre, by + Official stores on Shopee — suggest a sibling category, and — if helpful — + offer the non-incumbent listings under the labelled non-uncontested group + described above. ## Output @@ -120,8 +205,11 @@ Respond in the seller's language. Present the result with no commentary about ho it was produced. The product table always renders as markdown so it reads cleanly in any client. -**Niche table** — one row per uncontested niche product (from the platinum-free -deep sub-categories), with these columns: +Lead with a short intro line naming the **marketplace** and the category — and on +Shopee, the category level you actually worked at. + +**Niche table (Mercado Livre)** — one row per uncontested niche product (from the +platinum-free deep sub-categories), with these columns: - Product / listing identifier (rendered as a JoomPulse link for the product) - Name @@ -141,20 +229,56 @@ deep sub-categories), with these columns: come only from platinum-free sub-categories per Step 2) - A JoomPulse link for the product -Put the JoomPulse link on the product identifier in each row. When a cell is +**Niche table (Shopee)** — the same shape, with the marketplace's own columns: + +- Item identifier, linked to the item on Shopee — **there is no JoomPulse + dashboard link for Shopee rows**, so never invent one +- Name +- Category — the deeper path the item itself carries; say which level it is +- Shop +- Price +- Estimated sales (30 days) +- Estimated revenue (30 days) +- **Number of sellers** in the niche — the competition signal (show `—` when it + is not available) +- Rating +- Reviews +- Time on air (days) — computed from the date the item was created +- Shop tier — Official store / Preferred (Indicado) / Common; uncontested rows + carry only Preferred (Indicado) or Common, never Official store +- Free shipping and listing type have **no Shopee equivalent**: either drop these + columns or show `—` in them. Never map a shop tier onto a seller medal. + +The sales columns are **not** the same window on the two marketplaces: Mercado +Livre reports weekly figures, Shopee reports 30-day figures only — label the +Shopee columns as 30 days and never present a 30-day figure under a weekly +heading. + +Put the marketplace link on the product identifier in each row. When a cell is empty, show `—` rather than guessing. Below the table, briefly state what "uncontested niche" means here: sub-categories deeper than the third level that -have **no platinum seller at all** among their listings. You may translate the +have **no platinum seller at all** among their listings on Mercado Livre, or **no +Official store (Shopee Mall) seller at all** on Shopee. You may translate the column headers into the seller's language. -**If you also include the fallback group** (non-platinum listings from sub- -categories that still have platinum sellers, used only when the platinum-free set -is too small), put it in a clearly separate, labelled section titled -**"non-platinum listings (platinum sellers still present in the category)"**. -Use the same columns, but do **not** call these rows uncontested — be explicit -that platinum sellers are still active in those sub-categories. +**On Shopee, state this next to the verdict itself, not only in the guardrails:** +only items with at least one lifetime sale are tracked, so an Official store +whose items have never sold is invisible in the data — an "uncontested" verdict +can therefore be false. Present it as the best available read, not as proof that +no Official store is in the niche. + +**If you also include the fallback group** (listings without the incumbent, taken +from sub-categories that still have one, used only when the uncontested set is too +small), put it in a clearly separate, labelled section — titled **"non-platinum +listings (platinum sellers still present in the category)"** on Mercado Livre, or +**"listings outside an Official store (Official stores still present in the +category)"** on Shopee. Use the same columns, but do **not** call these rows +uncontested — be explicit that the incumbent is still active in those +sub-categories. + +**Disclaimer (every report) — use the variant for the marketplace you queried.** -**Disclaimer (every report):** +Mercado Livre: > ⚠️ Sales and revenue are JoomPulse **estimates** based on historical listing > data — they are **not** actual transactions. Price, rating, and reviews are @@ -162,6 +286,18 @@ that platinum sellers are still active in those sub-categories. > com base no histórico de anúncios — **não são transações reais**. Preço, > classificação e avaliações são histórico real do Mercado Livre. +Shopee: + +> ⚠️ Sales and revenue are JoomPulse **estimates** built from Shopee's own +> rounded sold counters — they are **not** actual transactions, and small gaps +> between items are noise. Only items with at least one lifetime sale are +> tracked, so this list is a lower bound. Price, rating, and reviews are real +> Shopee history. / Vendas e receita são **estimativas** do JoomPulse a partir +> dos contadores arredondados da própria Shopee — **não são transações reais**, e +> diferenças pequenas entre itens são ruído. Só itens com pelo menos uma venda no +> histórico são rastreados, então esta lista é um piso. Preço, classificação e +> avaliações são histórico real da Shopee. + ## Visualization When the client can render inline visuals, present metric cards and, when the @@ -173,49 +309,62 @@ data supports it, and skip it otherwise. **Cards** — three summary cards: - **Produtos encontrados** — the count of uncontested niche rows in the table - (non-platinum, in deep sub-categories). + (from the deep sub-categories with no incumbent). - **Subnichos cobertos** — the count of distinct deep sub-categories actually represented in the results. - **Ticket médio** — the average price across the listed rows, in pt-BR currency formatting (for example `R$ 1.234`). -**Chart** — a horizontal bar of the top niche products by estimated weekly -revenue, strongest uncontested niches first, each bar labelled with a short -product name. **Skip the bar entirely when there are fewer than four products** — -show only the cards and the table. +**Chart** — a horizontal bar of the top niche products by estimated revenue — +weekly on Mercado Livre, 30-day on Shopee, and label the axis with the window you +used — strongest uncontested niches first, each bar labelled with a short product +name. **Skip the bar entirely when there are fewer than four products** — show +only the cards and the table. **Otherwise (no inline visuals)**: render the three cards as a short text block, one line each, and — only when there are four or more products — a tiny text list -of the top niches by estimated weekly revenue. **Never block on visuals**; if -inline rendering is unavailable or fails, fall straight through to the markdown -output. Round numbers and use pt-BR formatting (for example `R$ 1.234`, `1.234 -vendas`). +of the top niches by estimated revenue over that same window. **Never block on +visuals**; if inline rendering is unavailable or fails, fall straight through to +the markdown output. Round numbers and use pt-BR formatting (for example `R$ +1.234`, `1.234 vendas`). If you show Mercado Livre seller medals as coloured +chips, keep the standard palette; on Shopee there are no medals, so write the +shop tier as plain text and never colour it as a rung on a ladder. ## Notes & Guardrails The seller should never see a system or stack error — only a friendly next step. -- **No deep sub-categories:** if the chosen category has no sub-levels deeper - than the third level, say so and offer to run on a broader category. -- **No platinum-free sub-categories:** if every deep sub-category has at least - one platinum seller, report that the deep sub-categories are already contested - by platinum sellers and suggest a sibling category. You may still offer the - non-platinum listings, but only under the labelled "non-platinum listings - (platinum sellers still present in the category)" group — never as uncontested. -- **Too few platinum-free niches:** if the genuinely platinum-free sub-categories - yield too few results, you may add the non-platinum listings from sub- - categories that still have platinum sellers, in the separate labelled group - above — always lead with the platinum-free niches and never relabel the - fallback group as uncontested. +- **No deep sub-categories:** if the chosen category has nothing deeper than the + third level, say so and offer to run on a broader category. On Shopee, reach + the deeper levels through the item view before concluding there are none. +- **No uncontested sub-categories:** if every deep sub-category has at least one + platinum seller (Mercado Livre) or one Official store (Shopee), report that the + deep sub-categories are already contested and suggest a sibling category. You + may still offer the non-incumbent listings, but only under the labelled + fallback group — never as uncontested. +- **Shopee coverage limits the verdict:** only items with at least one lifetime + sale are tracked, so an Official store whose items have not sold does not + appear at all and an "uncontested" verdict can be false. Say this in the output + itself, every time. Likewise, there is no listing-status filter — judge whether + an item is still live by how recently it was last seen. +- **Too few uncontested niches:** if the genuinely uncontested sub-categories + yield too few results, you may add the non-incumbent listings from sub- + categories that still have one, in the separate labelled group above — always + lead with the uncontested niches and never relabel the fallback group as + uncontested. - **No funded listings:** if no listing has estimated sales, list the active - listings in the platinum-free sub-categories instead and say the niche has + listings in the uncontested sub-categories instead and say the niche has little measured traction. - **Unknown flags:** when a logistics flag such as frete grátis is unknown, show - it as unknown — do not assume "no". + it as unknown — do not assume "no". On Shopee, free shipping and the listing + tier are always `—`: an absent attribute, not a missing value, and never a + "Não". - **Many deep sub-categories:** when the deep category set is large, gather the - listings in batches and merge the results before ranking. + listings in batches and merge the results before ranking. On Shopee the + competition signal is pinned to one category at a time, so collect it per niche + and merge. - **Market data temporarily unavailable:** retry once quietly; if it is still down, say market data is temporarily unavailable. Never paste internal error text, HTTP codes, or field names to the seller. - **Never silently limit coverage** — if you cover only some of the deep - sub-categories, say so. + sub-categories, say so, and on Shopee say which category level you used.