From b1ea98fedb0a2730692b4d247779178434a14f64 Mon Sep 17 00:00:00 2001 From: Nikita Andreev <73538828+fiharet34@users.noreply.github.com> Date: Tue, 8 Sep 2026 11:43:06 +0100 Subject: [PATCH 1/3] Fix top-sellers-in-category: rank against real sales, and stop reading buy-box position as idle stock Checks each estimate against the seller's real completed sales before placing a row: shops with no real trading history move out of the ranking into a labelled group, while a real business whose estimate runs high stays in with a caveat. Groups shops sharing a name stem and says whether that changes the leader, without asserting common ownership. Reframes the registered-versus-with-sales comparison as sellers only. On a catalog product only the buy-box holder shows sales, so the product gap measures buy-box position rather than idle inventory - and since the panel now renders every run, an unlabelled version of that chart would mislead every time. Also: medal as a column so the saved baseline can reproduce its own panel, the growth column named for the metric it carries, full money precision in a ranking, a missing-value rule, a width fallback that drops columns rather than the table, retry after a pause, and an empty result separated from an outage. --- skills/top-sellers-in-category/SKILL.md | 109 ++++++++++++++++++++---- 1 file changed, 91 insertions(+), 18 deletions(-) diff --git a/skills/top-sellers-in-category/SKILL.md b/skills/top-sellers-in-category/SKILL.md index fd2a401..1b1478a 100644 --- a/skills/top-sellers-in-category/SKILL.md +++ b/skills/top-sellers-in-category/SKILL.md @@ -3,8 +3,9 @@ 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. + monthly sales and revenue, 365-day completed sales, cancellation rate, month-over-month + sales growth, medal, 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 @@ -19,9 +20,9 @@ description: > 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. +cancellation rate, month-over-month sales growth, medal, 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 @@ -41,9 +42,9 @@ To rank brands rather than sellers, use the top-brand-position-tracker 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. + last-365-day completed sales, cancellation rate, month-over-month sales growth, + seller medal, brands, listing distribution, international shipping, classic and + premium listing counts). Reputation is 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. @@ -53,7 +54,8 @@ JoomPulse MCP setup before it can rank a category's sellers. - **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. + are real history. Disclose the estimate caveat in every output. **Use the real + figures to sanity-check the estimated ones**, never the other way round. - **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. @@ -73,6 +75,38 @@ 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. +**Check every row against real sales before ranking it.** The revenue figure is an +estimate; completed sales over the last year are real. Two different problems hide +here, and they need different handling — do not treat them alike: + +- **No real trading history.** A shop with a handful of listings and a seven-figure + monthly estimate against a few hundred completed sales, or none at all, is an + artifact of one listing with an odd counter rather than a business. **Move these + out of the ranking** into a short labelled group ("estimativa não confiável") + with the estimate, the real completed sales and the listing count side by side, + and say the ranking excludes them. Flagging them in a note while still ranking + them is not enough: it spends leaderboard positions on artifacts and pushes real + sellers out. +- **A real business with an inflated estimate.** A seller with tens of thousands of + completed sales is a genuine operation even where the estimate runs several times + its real pace. **Keep it in the ranking** and say beside it that the estimate + looks high against real volume, so its position may be too generous. Excluding a + seller with real trading history because an estimate is imprecise removes a + competitor the seller actually faces — a worse error than showing them too high. + +The distinction is the **real** figure, not the ratio: near-zero completed sales +means exclude, substantial completed sales means keep and caveat. Say how many +shops you examined to fill the ranking. + +**Name the shops that look like one company.** The ranking is of shops, not +companies, and a retailer may run several storefronts — a shared name with regional +suffixes is the usual tell. Where two or more rows share a name stem, group them in +a short note, give the combined estimated revenue, and say plainly whether that +combination would change the leader or the leader's share. **Do not assert common +ownership**: it is not verifiable here, and unrelated registration dates and +identifiers argue against a single operator as often as for one. Present it as an +alternative reading of the same rows, and leave the ranking itself by shop. + ### 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). @@ -100,10 +134,32 @@ 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. +| Vendedor | Medalha | Vendas méd. (mês) | Receita média (mês) | Vendas 365d | Taxa de cancelamento | Crescimento mensal | Marcas | Produtos (todos) | Produtos (com venda) | Envio internacional | Clássico | Premium | +|---|:--|--:|--:|--:|--:|--:|--:|--:|--:|--:|--:|--:| + +- The **Vendedor** name links to the seller's JoomPulse page. Headers are pt-BR by + default; translate them only when the seller writes in another language. +- **Full precision in the money columns** — `R$ 1.279.436,00`, never `R$ 1,28 mi`. + This is a ranking: rounding collapses the rows into each other, and a tail of + `R$ 0,7x mi` values cannot be ordered or audited by the reader. If the table is + too wide, drop a column rather than shortening a number. +- **Crescimento mensal is the seller's month-over-month sales growth** — the figure + the JoomPulse seller page shows. Name it that way rather than "trend", so it + cannot be confused with an older run-rate measure that is empty for most sellers. +- **Medalha is a column, not only a chart colour.** The downloadable file is the + baseline the seller brings back next period, so it has to carry every field the + report and its panel use — a file that cannot reproduce the chart is not a + baseline. +- **Say which figures are category-scoped and which are store-wide.** Sales, + revenue, brands and product counts are for this category; completed sales, + cancellation rate, growth, international shipping and the listing-type counts are + the whole store. That is why the listing-type counts do not add up to the category + product count, and it needs saying every time, not just when it looks odd. +- **If the table is too wide for the surface, drop columns from the right** — + listing types first, then international shipping, then brands — and say which were + dropped; the downloadable file always keeps all of them. **Never abandon the table + for a seller-by-seller list**: the whole point is that the user saves it and pastes + it back next period, and a list cannot be compared row against row. **Comparison (only when a previous leaderboard is supplied):** the same table plus a **Variação** column, and a **Destaques** block (maiores altas / maiores quedas). @@ -148,8 +204,15 @@ The panel contains: 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. +- **A small "registered versus with sales" comparison** for sellers — how many of + the category's sellers actually sell. **Do not chart the same comparison for + products, and never describe the product gap as stock sitting idle or failing to + convert.** On a catalog product only the seller holding the buy-box shows sales, + so every other seller of that product reads zero: a shop with thousands of + listings and a third of them "with sales" is mostly showing buy-box position, not + dead inventory. If the product split appears at all, label it buy-box coverage + and say what it is not — the panel renders every time now, so an unlabelled + version of this chart would mislead on every run rather than occasionally. 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 @@ -165,7 +228,17 @@ The seller should never see a system or stack error — only a friendly next ste 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. +- **Missing values.** Show `—` for any figure that is unavailable. Never print `0` + or `0,00%` for something unknown: a cancellation rate of `0,00%` on a seller with + no completed sales reads as a perfect record when nothing was measured at all. +- **Growth on a small base.** A percentage computed on a handful of real sales is + noise, not a trend. Show it, but say so beside it, and never lead the risers list + with one. +- **Market data temporarily unavailable:** retry once after a short pause rather + than immediately; if it still fails, say the service is busy and to try again in a + few minutes. Never paste internal error text, HTTP codes, or field names to the + seller. Name the downloadable file so the seller can find it, but never expose an + internal working path — a temporary or scratch directory is not a save location. +- **An empty result is not a failure.** A category with no sellers to rank is an + answer; say that and offer a broader category. Never report it as an outage. - **Never silently limit coverage** — state the top cap you used. From 0cf23ab980aebe884a3e66d8f9c566bffee62c89 Mon Sep 17 00:00:00 2001 From: Nikita Andreev Date: Fri, 11 Sep 2026 09:21:47 +0100 Subject: [PATCH 2/3] Stop linking seller names to a JoomPulse page that does not exist MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit pulse://overview rule 10 restricts the beginner-products/{id} template to listing ids and skips seller grain. This skill asks for the Vendedor name to link to "the seller's JoomPulse page". In a live run every one of those links was built from a shopId and 404ed — nine dead URLs in a single answer. Two places were promising it: - the presentation rule in the body, which now states the name is plain text and why; - the frontmatter description, which advertised "...listing-type counts, with a JoomPulse link each". That one matters more than it looks: descriptions are injected into the system prompt for skill selection, so the promise shipped even in conversations where this skill never loaded. Nothing else changes — no column, threshold or ranking rule is touched. --- skills/top-sellers-in-category/SKILL.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/skills/top-sellers-in-category/SKILL.md b/skills/top-sellers-in-category/SKILL.md index fd2a401..9c7d272 100644 --- a/skills/top-sellers-in-category/SKILL.md +++ b/skills/top-sellers-in-category/SKILL.md @@ -4,7 +4,7 @@ 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. + product counts, international shipping, and listing-type counts. 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 @@ -103,7 +103,9 @@ Respond in the seller's language (default pt-BR). | 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. +- **The Vendedor name is plain text.** Sellers have no JoomPulse page — the + dashboard link template is for listing ids only — so a URL built from a shopId + 404s. **Comparison (only when a previous leaderboard is supplied):** the same table plus a **Variação** column, and a **Destaques** block (maiores altas / maiores quedas). From a8a393d54ffd02d0ee27126ed1b451b3282d7de9 Mon Sep 17 00:00:00 2001 From: Nikita Andreev Date: Mon, 14 Sep 2026 13:53:01 +0100 Subject: [PATCH 3/3] Name the shapes that are not a leaderboard "Never abandon the table for a seller-by-seller list" left room for the shapes a live pass actually produced: the leaders in the table with the rest in prose, and a trailing "and below them, X, Y, Z" sentence. Both look like a leaderboard and neither can be compared row against row next period, which is the whole reason the seller keeps it. Names those shapes and ends with the check to apply before answering. Co-Authored-By: Claude Opus 5 (1M context) --- skills/top-sellers-in-category/SKILL.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/skills/top-sellers-in-category/SKILL.md b/skills/top-sellers-in-category/SKILL.md index 1b1478a..f515211 100644 --- a/skills/top-sellers-in-category/SKILL.md +++ b/skills/top-sellers-in-category/SKILL.md @@ -157,9 +157,12 @@ Respond in the seller's language (default pt-BR). product count, and it needs saying every time, not just when it looks odd. - **If the table is too wide for the surface, drop columns from the right** — listing types first, then international shipping, then brands — and say which were - dropped; the downloadable file always keeps all of them. **Never abandon the table - for a seller-by-seller list**: the whole point is that the user saves it and pastes - it back next period, and a list cannot be compared row against row. + dropped; the downloadable file always keeps all of them. Never move sellers into a + numbered list, a paragraph, or a trailing "and below them, X, Y, Z" sentence, and + never carry only the leaders in the table with the rest in prose. The user saves this + table and pastes it back next period, and a list cannot be compared row against row. + **If the sellers you ranked are not all rows of one markdown table, you have not + produced the leaderboard.** **Comparison (only when a previous leaderboard is supplied):** the same table plus a **Variação** column, and a **Destaques** block (maiores altas / maiores quedas).