Top Sellers In Category

---
name: top-sellers-in-category
description: >
  Ranks the top sellers in one Mercado Livre (Brasil) category by estimated average monthly
  revenue via JoomPulse, and returns a downloadable leaderboard — per seller: estimated
  monthly sales and revenue, 365-day completed sales, cancellation rate, sales trend, brands,
  product counts, international shipping, and listing-type counts, with a JoomPulse link each.
  It can also track how the ranking moved: supply a previous-period leaderboard for the same
  category and it shows each seller's movement (rose / fell / new) plus the biggest movers.
  Triggers: "top sellers in this category", "biggest stores in a category", "rank sellers by
  revenue", and the pt-BR "principais vendedores da categoria", "maiores lojas da categoria",
  "quem mais vende nessa categoria". Sales and revenue are JoomPulse estimates, not real
  transactions. To monitor one seller over time use the seller-overview-tracker skill; to rank
  brands use the top-brand-position-tracker skill.
---

# Top Sellers In Category

This skill returns the **top sellers in one Mercado Livre (Brasil) category**,
ranked by estimated average monthly revenue. For each seller it shows estimated
average monthly sales and revenue, completed sales over the last 365 days,
cancellation rate, sales trend, brands, how their products split between all
listings and listings with sales, international shipping, and classic versus
premium listing counts.

By default it produces **today's leaderboard** as a downloadable table. It can
also show **how the ranking moved over time**: if you supply a previous-period
leaderboard that this skill produced for the same category, it compares the two
and reports each seller's movement (rose / fell / new) plus the biggest movers.
**The baseline is the table you supply — there is no hidden session memory.**

To monitor a single named seller over time, use the seller-overview-tracker skill.
To rank brands rather than sellers, use the top-brand-position-tracker skill.

## Prerequisites

- JoomPulse MCP access is configured for the current agent environment.
- The user names a category (free text is fine).
- For a period comparison, the user supplies a previous leaderboard that this
  skill produced for the same category (pasted or uploaded). Without it, the skill
  produces a standalone leaderboard.
- The available JoomPulse tools can find the sellers active in a category and
  return each seller's profile (estimated average monthly sales and revenue,
  last-365-day completed sales, cancellation rate, sales trend, brands, listing
  distribution, international shipping, classic and premium listing counts).
  Seller medal — used to color the chart — and reputation are read when available.

If JoomPulse MCP access is unavailable, stop and explain that the skill requires
JoomPulse MCP setup before it can rank a category's sellers.

## 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. Cancellation rate and last-365-day completed sales
  are real history. Disclose the estimate caveat in every output.
- **Read-only.** The skill never writes or modifies anything; it does not store the
  leaderboard — 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 movement without a previous
  leaderboard to compare against, and never infer or fabricate one from memory.

## Workflow

### Step 1 — Resolve the category and find its sellers

Ask for a category if none was given, then use JoomPulse to match the free text to
a category and find the sellers active in it.

### Step 2 — Rank by estimated average monthly revenue

Rank the sellers by **estimated average monthly revenue**, highest first. Keep a
sensible top (default about 50, up to about 100 on request), and treat the count
as a cap — show fewer if fewer exist.

### Step 3 — Present today's leaderboard and offer it for download

Render the leaderboard 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 leaderboard there is **no movement column and no legend**.

### Step 4 — Offer comparison, and compare if a previous leaderboard is supplied

Invite the user to send a previous leaderboard for the same category to compare
periods. **If they provide one**, align by seller and report:

- a **Variação** column per seller: 🟢 subiu N / 🔴 caiu N / 🆕 novo / = igual, and
  note sellers that **left** the top in a short "saíram do top" line;
- a short **Destaques** block — biggest risers 🟢 and biggest fallers 🔴.

A movement **requires both an old and a new position/value** for the same seller —
no previous entry means "novo", never a fabricated trend. Show the 🟢/🔴 legend
**only** in the comparison (where the markers actually appear), never on a plain
leaderboard. The change column header is a word ("Variação"), never a bare "Δ".

## Output

Respond in the seller's language (default pt-BR).

**Leaderboard (always):** a markdown table, plus a downloadable `.csv` / `.xlsx`:

| Vendedor | Vendas méd. (mês) | Receita média (mês) | Vendas 365d | Cancel rate | Sales trend | Marcas | Produtos (todos) | Produtos (com venda) | Envio internacional | Classic | Premium |
|---|--:|--:|--:|--:|--:|--:|--:|--:|--:|--:|--:|

- The **Vendedor** name links to the seller's JoomPulse page.

**Comparison (only when a previous leaderboard is supplied):** the same table plus
a **Variação** column, and a **Destaques** block (maiores altas / maiores quedas).

**Disclaimer (every report):**

> ⚠️ Vendas e receita são estimativas do JoomPulse com base no histórico de
> anúncios — não são transações reais. Taxa de cancelamento e vendas dos últimos
> 365 dias são dados reais do Mercado Livre.

## Visualization

**Render the visuals every time the data supports them.** As soon as the analysis
is done, present the cards and charts described below as a **self-contained visual
panel** — an artifact where the client renders artifacts, an inline widget where
it renders widgets. Do not ask permission first, do not describe the panel instead
of drawing it, and do not offer it as an optional extra: the cards and charts are
part of the answer, not a follow-up.

- **Order:** the cards first, then the charts, then the written read.
- **The data table always stays markdown in the response text**, never inside the
  panel — the panel carries cards and charts only.
- **The estimate disclaimer always stays in the response text** as well.
- **Skip an individual chart when its own data threshold is not met** (each
  threshold is stated below): a chart nobody can read is worse than no chart.
  Skipping one chart never means skipping the panel.
- **Only the cards and charts specified below.** Do not invent extra ones, and do
  not promote a categorical value to a bar — a chip or plain text is the honest
  rendering for it.
- **If no visual surface is available at all**, fall back to the markdown table
  plus the same figures written as text cards. Never block on visuals, and never
  leave the answer without its numbers.

The panel contains:

- **Four cards:** number of sellers in the category (and how many have sales), the
  leader's share of the shortlist's revenue, the average monthly revenue across
  the top, and the average ticket.
- **A horizontal bar** of the top ~10 sellers by estimated average monthly revenue,
  **colored by seller medal** — platina = purple, ouro = amber, prata = blue, sem
  medalha = white with a thin border (white needs the border to stay visible on a
  light background). Include a small legend mapping color to medal. When one seller
  dwarfs the rest, you may show that leader as a separate highlighted figure and
  chart the remaining leaders so the medal colors stay readable.
- **A small "registered versus with sales" comparison** for sellers and for
  products, to show how much of the supply actually converts.

Presentation rules: use the medal palette consistently; render a chart only when
the data supports it; the movement/Variação column uses a word header, never a bare
"Δ", and its 🟢/🔴 legend appears only when a comparison is shown.

## Notes & Guardrails

The seller should never see a system or stack error — only a friendly next step.

- **No previous leaderboard supplied:** render today's leaderboard only (no
  movement 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 leaderboard only; do not force a misaligned comparison.
- **Small sample:** if only a few sellers come back, say so rather than implying it
  is the whole category.
- **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** — state the top cap you used.