Update to JoomPulse

{
  "name": "top-brand-position-tracker",
  "description": "Ranks the brands within one Mercado Livre (Brasil) category by estimated weekly revenue and tracks how each brand's position changes between periods, using JoomPulse. Each run builds today's brand-ranking table and offers it for download; to see how positions moved, the user sends a brand table from a previous period and the skill shows each brand's movement (rose, fell, new, or out). The baseline is whatever table the user supplies — no hidden session memory. Use it to see the top brands in a category and which are rising or falling. Triggers: \"top brands in this category\", \"which brands are growing\", \"brand ranking\", and the pt-BR \"principais marcas da categoria\", \"ranking de marcas\", \"quais marcas estão crescendo\". Mercado Livre (Brasil) only; sales and revenue are JoomPulse estimates, not real transactions. To rank sellers (shops) rather than brands use the top-sellers-in-category skill; for category market size use the category-opportunity-index skill.",
  "included_files": [],
  "skill_md_contents": "---\nname: top-brand-position-tracker\ndescription: >\n  Ranks the brands within one Mercado Livre (Brasil) category by estimated weekly revenue and\n  tracks how each brand's position changes between periods, using JoomPulse. Each run builds\n  today's brand-ranking table and offers it for download; to see how positions moved, the user\n  sends a brand table from a previous period and the skill shows each brand's movement (rose,\n  fell, new, or out). The baseline is whatever table the user supplies — no hidden session\n  memory. Use it to see the top brands in a category and which are rising or falling.\n  Triggers: \"top brands in this category\", \"which brands are growing\", \"brand ranking\", and\n  the pt-BR \"principais marcas da categoria\", \"ranking de marcas\", \"quais marcas estão\n  crescendo\". Mercado Livre (Brasil) only; sales and revenue are JoomPulse estimates, not real\n  transactions. To rank sellers (shops) rather than brands use the top-sellers-in-category\n  skill; for category market size use the category-opportunity-index skill.\n---\n\n# Top brand position tracker\n\nThis skill ranks the **brands** inside one Mercado Livre (Brasil) category by\nestimated weekly revenue and **tracks how each brand's position in that ranking\nmoves over time**. It aggregates each brand's active listings into a leaderboard.\n\nEach run builds **today's brand-ranking table** for the category and offers it as\na **downloadable table**. To see how positions moved, the user **supplies a brand\ntable from a previous period** (the one this skill produced before); the skill\nmatches brands by name and shows each brand's position movement. **The baseline is\nwhatever table the user provides — there is no hidden session memory and nothing\nis stored server-side.** A standalone run is the ranking only: no movement column\nand no legend.\n\nThis is different from ranking sellers or sizing a category. To rank **sellers\n(shops)** in a category, or to track how a seller leaderboard moves over time, use\nthe seller-ranking skills. To report a category's market size and opportunity\n(estimated GMV, sales, number of sellers, average ticket), use the category\nopportunity skill. This skill answers **\"which brands lead this category, and how\ndid their positions move since a previous table?\"**\n\n## Prerequisites\n\n- JoomPulse MCP access is configured for the current agent environment.\n- The user provides the category to analyze — a category name, a category\n  identifier, or a JoomPulse category link.\n- For a period comparison, the user supplies a previous brand table that this skill\n  produced for the same category (pasted or uploaded). Without it, the skill\n  produces a standalone ranking.\n- The available JoomPulse tools can look up the active listings in a category\n  along with their estimated weekly sales and revenue, review counts, and prices.\n\nIf JoomPulse MCP access is unavailable, stop and explain that the skill requires\nJoomPulse MCP setup before it can rank brands and track their positions.\n\n## Scope\n\n- **Mercado Livre (Brasil) only.** Other marketplaces are out of scope.\n- **Sales and revenue are JoomPulse estimates** derived from historical listing\n  data — not real transactions. Disclose this in every output. By contrast,\n  **review count is real Mercado Livre history** — say so, it is a strength of the\n  report.\n- **Read-only.** The skill never signs in as the seller and never modifies\n  anything; it does not store the ranking — the user keeps the downloadable table\n  and brings it back next period.\n- **The baseline is user-supplied.** Never claim a position change without a\n  previous table to compare against, and never infer or fabricate one from memory.\n- **Language:** respond in pt-BR by default. If the seller clearly writes in\n  another language, mirror it; otherwise pt-BR.\n- **Keep the workflow invisible.** The seller wants the ranking, not a play-by-\n  play. If one approach does not return data, switch to another quietly; only if\n  every approach fails do you say one short, friendly sentence.\n\n## Workflow\n\n### Step 1 — Resolve the category, gather listings, aggregate brands\n\n1. **Ask the seller for the category** if it was not given — a category name, a\n   category identifier, or a JoomPulse category link. If only a name is given,\n   resolve it to the matching current category (and its depth level) with\n   JoomPulse, and confirm the match with the seller if it is ambiguous.\n2. **Use JoomPulse to fetch every active listing in the category**, with each\n   listing's brand, estimated weekly sales and revenue, review count, and price.\n   For a large category, broaden coverage in passes rather than silently capping —\n   and if coverage is partial, say it was broad rather than presenting it as\n   complete.\n3. **Group the listings by brand and aggregate per brand.** Before grouping,\n   **normalize brand names** — trim and unify casing, fold obvious variants and\n   spellings of the same brand together, and standardize generic placeholders (for\n   example \"Outro\" / \"Sem marca\") — so one brand is not split across rows. Use this\n   same canonical form again when matching brands across periods. Drop listings\n   with no brand; if unbranded listings are material, mention how many had no brand\n   rather than letting an unnamed bucket top the ranking. For each brand compute:\n   - **GMV estimado (semana)** — total estimated weekly revenue across the brand's\n     listings.\n   - **Vendas est. (semana)** — total estimated weekly sales across the listings.\n   - **Anúncios** — number of active listings for the brand.\n   - **Avaliações** — total review count (real history).\n   - **Preço médio** — average listing price (optional supporting column).\n4. **Rank the brands by estimated weekly revenue, descending,** to assign each\n   brand its position (1 = top). If the seller asks to rank by units sold instead,\n   rank by estimated weekly sales and say so. Keep roughly the top 20–30 brands\n   for the table.\n\n### Step 2 — Present today's ranking and offer it for download\n\nRender today's brand-ranking table (head it with the category name and the date).\nThis table is the deliverable — and **offer it as a downloadable file (`.csv` /\n`.xlsx`)** so the user can save it and bring it back next period as the baseline.\nOn a standalone ranking there is **no movement column and no legend** — just the\nranking.\n\n### Step 3 — Offer comparison, and compare if a previous table is supplied\n\nInvite the user to send a previous brand table for the same category to compare\npositions. **If they provide one**, match brands by canonical name (see Step 1)\nand for each brand compare its previous position with its current one:\n\n- rose N places → rose by N\n- fell N places → fell by N\n- same position → unchanged\n- not in the previous table → new\n- in the previous table but absent now → list it below the table as *\"saiu do\n  ranking\"* — do not fabricate a position for it.\n\nA position change **requires both a previous and a current position** for the same\nbrand — never invent a trend. If no previous table is supplied, the ranking stands\non its own (no movement column) and the user is told to save it for next time.\n\n## Output\n\nRespond in the seller's language (pt-BR by default), with no commentary about how\nthe result was produced. Use plain markdown so it renders cleanly in any client.\n\nThere is **one canonical brand-ranking table**, used everywhere (in the response\ntext and mirrored by the downloadable file). One row per brand, sorted by current\nposition, with these columns:\n\n- **Posição** — current rank (1, 2, 3 …).\n- **Variação** — *(comparison only)* how the brand's position moved versus the\n  supplied previous table. **Omit this column entirely on a standalone ranking** —\n  with no previous table there is no movement to show.\n- **Marca** — the brand.\n- **GMV estimado (semana)** — the brand's estimated weekly revenue (estimate).\n- **Vendas est. (semana)** — the brand's estimated weekly sales (estimate).\n- **Anúncios** — listing count for the brand.\n- **Avaliações** — total review count (real history).\n- **Preço médio** — average listing price, or `—` if unavailable.\n\nSo a **standalone ranking** has the columns `Posição | Marca | GMV estimado\n(semana) | Vendas est. (semana) | Anúncios | Avaliações | Preço médio`; a\n**comparison** adds the `Variação` column right after `Posição`.\n\nIn the `Variação` cell (comparison only), mark each brand:\n\n- 🟢 **subiu no ranking**\n- 🔴 **caiu no ranking**\n- 🆕 **novo** (não estava no ranking anterior)\n- = **sem mudança**\n\nThe change column header is the **word `Variação`** — never a bare delta symbol.\n\nBelow the table, include the category's **JoomPulse link**. On a comparison, state\nthe period being compared (for example *\"Comparado com a tabela de 12/06\"*). On a\nstandalone ranking, invite the user to save the table and send it back next period\nto see how positions moved.\n\n**Disclaimer (every report):**\n\n> ⚠️ **Vendas e receita são estimativas** do JoomPulse com base no histórico de\n> anúncios — não são transações reais. **Avaliações são histórico real** do\n> Mercado Livre.\n\n## Visualization\n\nLayer a visual summary on top of the markdown table — never instead of it. The\nvisuals summarize; the **ranked table is always the deliverable**. Pick the path\nby surface and never block waiting for a visual.\n\n**When the client can render inline visuals,** present metric cards plus the bar\nchart:\n\n- **Three cards:**\n  - **Marcas ativas** — the number of named brands in the ranking.\n  - **Líder** — the #1 brand's name and its **share %** of total estimated weekly\n    revenue across the ranked brands.\n  - **Maior alta** — the brand that climbed the most and how many positions it\n    rose. **Only with a comparison** (a previous table supplied); on a standalone\n    ranking, drop this card or replace it with a neutral one — for example **GMV\n    total estimado (semana)** of the ranked brands — never fabricate a rise.\n- **Horizontal bar chart:** the top ~10 brands by **GMV estimado (semana)**,\n  descending. Use a neutral single-hue ramp — this bar ranks size, it does not\n  signal good or bad, so no semantic green/red.\n\n**Otherwise (a terminal or any client without inline visuals),** present the same\nthree cards as a short text block (label and value per line) and let the markdown\ntable itself carry the ranking. Do not attempt a visual widget; never block\nwaiting for one.\n\n**Tables always render as markdown,** on every surface — the ranked table lives in\nthe response text, never inside a rendered visual.\n\n### Ranked table (always markdown, both surfaces)\n\nThe ranked table is the **one canonical brand-ranking table defined in Output** —\nthe same columns, in pt-BR, on every surface. It lives in the response text, never\ninside a rendered visual.\n\n- **Standalone ranking:** columns `Posição | Marca | GMV estimado (semana) |\n  Vendas est. (semana) | Anúncios | Avaliações | Preço médio` — **no `Variação`\n  column and no legend** (with no symbols in the table a legend only adds noise).\n- **Comparison (a previous table supplied):** add the `Variação` column right after\n  `Posição`. The change column header is the **word `Variação`** — never a bare\n  delta symbol. Cell markers:\n  - 🟢 **subiu no ranking**\n  - 🔴 **caiu no ranking**\n  - 🆕 **novo** (não estava no ranking anterior)\n  - = **sem mudança**\n- **Show the marker legend (🟢 / 🔴 / 🆕 / =) only in the comparison**, where those\n  markers actually appear — never on a standalone ranking.\n\nRender the bar chart only when the data supports it; if there are too few brands\nto be meaningful, skip the chart and keep the table.\n\n**Formatting (both surfaces):** round numbers and format in pt-BR — revenue as\n`R$ 1,2 mi` / `R$ 850 mil` / `R$ 4.300`; counts with `.` as the thousands\nseparator (`1.250`). Keep the ⚠️ estimate disclaimer on every output.\n\n## Notes & Guardrails\n\nThe seller should never see a system or stack error — only a friendly next step.\n\n- **No category given or an ambiguous name:** ask for the category (name,\n  identifier, or JoomPulse link) before going further.\n- **No active listings or no brands in the category:** say no brand data is\n  available for this category right now, and offer to try a different or broader\n  category.\n- **Mostly unbranded listings:** rank only the named brands, and mention how many\n  listings had no brand rather than letting an unnamed bucket dominate the top.\n- **Market data temporarily unavailable:** retry once quietly; if it is still\n  down, say market data is temporarily unavailable and suggest re-running. Never\n  paste internal error text, HTTP codes, or field names to the seller.\n- **No previous table supplied:** render today's ranking only (no movement column,\n  no legend) and invite the user to save it for next time.\n- **Supplied table is for a different category, malformed, or unreadable:** say so\n  plainly and fall back to the standalone ranking; do not force a misaligned\n  comparison.\n- **Never silently limit coverage** — if the category is large and only part of it\n  was scanned, say the coverage was broad rather than presenting it as complete.\n"
}