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 01/11] 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 fbed3957b4226912e12666e7c73e98ec1dd2b073 Mon Sep 17 00:00:00 2001 From: Nikita Andreev <73538828+fiharet34@users.noreply.github.com> Date: Tue, 8 Sep 2026 11:46:11 +0100 Subject: [PATCH 02/11] Fix growing-leaf-category-tracker: show the number the ranking is built on, and stop the floor moving between runs The skill ranked niches by month-over-month growth and was forbidden from displaying it - Output said "exactly these five columns ... not a displayed column" while Presentation rules prescribed a header for that column and the panel required the growth figure on a card. On a text surface it appeared nowhere: one run showed fifteen rows with the leader called "o maior salto" and no percentage anywhere. Both growth columns are now displayed. The size floor was invented per run. Two runs on one category, minutes apart, chose R$ 1.000.000 and R$ 300.000, and the second run's leader sat below the first run's floor - so the same question returned a different top niche. The floor is now the greater of R$ 300 mil and 0,02% of the parent category's estimated monthly revenue, which is stated in the output. A fixed figure cannot serve both marketplaces: Mercado Livre ranks deep leaf niches, Shopee ranks whole level-3 categories. Also: revenue and unit growth read together, since a niche can grow revenue while selling fewer units; concentration and revenue per seller as columns, and seasonality as a Mercado Livre reading only, because Shopee carries none; identifier-based navigation on both marketplaces, replacing a per-category link that does not resolve; full money precision on Mercado Livre with Shopee exempt, its figures being rebuilt from rounded counters; exact coverage counts; a category-specific disclaimer with the monthly lag; retry after a pause; and an empty result separated from an outage. --- skills/growing-leaf-category-tracker/SKILL.md | 126 +++++++++++++++--- 1 file changed, 104 insertions(+), 22 deletions(-) diff --git a/skills/growing-leaf-category-tracker/SKILL.md b/skills/growing-leaf-category-tracker/SKILL.md index 7ff9bb6..e7af4b2 100644 --- a/skills/growing-leaf-category-tracker/SKILL.md +++ b/skills/growing-leaf-category-tracker/SKILL.md @@ -134,8 +134,10 @@ deepest level the marketplace actually supports: 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. +number of active sellers, the month-over-month growth of **both revenue and +units**, the concentration of orders on the leading seller, and revenue per +seller. Every reported column exists on both marketplaces, but concentration is +computed differently on each — never compare that figure across 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 @@ -144,14 +146,64 @@ the figures describe. ### Step 3 — Keep the fast-growing ones 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), then order the kept niches by revenue growth, +fastest first. + +**Apply a size floor before ranking, and state it.** Month-over-month growth +explodes off a near-zero base: a niche going from R$ 200 to R$ 1.600 reads +700% +and leads the table over one that added hundreds of thousands. Set the floor +**relative to the parent the seller named** — at least **0,02% of that category's +estimated monthly revenue, and never below R$ 300 mil**. A fixed figure cannot +serve both marketplaces, because they rank different units: deep leaf niches on +Mercado Livre against whole level-3 categories on Shopee, which are far larger. +Say under the table which floor was used and how many niches it excluded. Without +a stated floor the same category returns a different leader from run to run. + +**Read revenue growth and unit growth together.** A niche can grow revenue while +selling *fewer* units: the gain came from a higher average ticket, not from more +demand, and a seller who wants volume should not enter it — say so plainly. The +reverse, units growing faster than revenue, means the average price is falling: +easier to enter, margin under pressure. Flag both cases. + +**Collapse a parent and its dominant child** — Mercado Livre only, since Shopee +has nothing below the level being ranked. A deep tree ranks a sub-category and its +own child separately, so a parent holding nearly all its revenue in one child +appears twice and reads as two opportunities. Where a child accounts for almost +all of its parent's revenue, keep one row, name the other beside it, and say they +are the same niche — twelve rows should mean twelve choices. + +**Identify the surviving row by the same identifier every time.** Where a pair is +collapsed, keep the row under the **parent** and name the child beside it. The +identifier is the only way the seller can find the niche again, and the table is +meant to be saved and compared next period — the same niche appearing under two +different identifiers across runs defeats the purpose of showing one. + +**Then say which of the ranked niches is actually enterable.** Growth alone is not +room: + +- **Concentration.** Where one seller holds a large share of the category's + orders, strong growth is not open space; name those niches and say the seller + would be taking on a dominant incumbent. +- **Revenue per seller.** A large, fast-growing niche split across tens of + thousands of sellers is worth less than a smaller one with few. Name the best + and the worst rather than leaving the columns to be divided by hand. +- **Seasonality — Mercado Livre only.** Where the category is marked seasonal with + a known peak month, say whether the growth is the start of the ramp (time to + position) or the middle of the curve (entering behind it). **Shopee carries no + seasonality data**: do not infer it there, and where the calendar suggests a + season say that as timing, not as data. + +Lead the written read with the most enterable niches — strong growth with low +concentration — not simply the fastest-growing. + +Keep levels and changes distinct: use the always-positive monthly totals for size, +and never present a change figure as if it were a total. 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. +the most recent month with the one before it and read nothing longer-run into it — +which makes the floor matter more there, not less, because a short history makes a +percentage noisier. ## Output @@ -163,22 +215,43 @@ 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 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. +| Categoria | Cresc. receita | Cresc. vendas | Qtd. vendedores | Receita (mês est.) | Vendas (mês est.) | Monopolização | Receita/vendedor | +|---|--:|--:|--:|--:|--:|:--|--:| + +- **Exactly these eight columns on both marketplaces.** Concentration and revenue + per seller are what turn a growth list into an entry decision, so they belong in + every run rather than only the ones where they occur to you. +- **Show the growth the ranking is built on** — never rank on a number the table + does not display. Both growth columns are month-over-month. +- **Monopolização** carries the tier and the raw value together, as `Baixa (0,180)` + — the tier alone hides how close two niches are. +- **Full precision in the money columns on Mercado Livre** — `R$ 468.400,35`, never + `R$ 468 mil`: this is a ranking, and rounding collapses the rows into each other. + **Shopee is exempt.** Its figures are rebuilt from the platform's own rounded + sold counters, so exact digits there would be false precision — round Shopee + money to thousands and say once that the source is rounded. +- **Identify each row by its category ID beside the name.** Neither marketplace has + a working per-category deep link: on Shopee there is none at all, and on Mercado + Livre a URL carrying a category identifier resolves to the same general + categories page. So give the seller the route in one line below the table and + **never render a per-row URL as though it opened that niche** — the ID is what + lets them find it, and a link that lands somewhere general while looking specific + is worse than none. +- Under the table, state the size floor used, the period compared, and how many + niches were read against how many the ranking shows. **Give those counts + exactly, never rounded or hedged** — "about 900" cannot be checked against the + data, and a coverage claim nobody can audit is worth little more than none. **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. +> ⚠️ Receita, vendas e crescimento da categoria são estimativas de mercado do +> JoomPulse — não são transações reais, e o crescimento mês a mês herda essa +> margem de erro. A base mensal de categorias pode ter até ~31 dias de defasagem. +> / Category revenue, sales, and growth are JoomPulse market estimates — not +> actual transactions, and the month-over-month growth inherits that margin of +> error. The monthly category data can lag by up to ~31 days. Shopee: @@ -243,7 +316,16 @@ The seller should never see a system or stack error — only a friendly next ste 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 - 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 you rank only some of the niches, say so. +- **Missing values.** Show `—` for any figure that is unavailable, and never print + `0` for something that was simply not measured. +- **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. +- **An empty result is not a failure.** A category with no niches above the floor + is an answer — say that, and offer to lower the floor or widen the parent. Never + report a genuine empty result as an outage. +- **Never silently limit coverage.** State how many niches were read against how + many the ranking shows. Where the pull can be ordered by growth, one page is + enough for a top-N and nothing unread grows faster — say so; otherwise page until + a pull comes back short. From aa63a7cfdf492b2f2aec11756e65e0c5f77be4a2 Mon Sep 17 00:00:00 2001 From: Nikita Andreev Date: Wed, 9 Sep 2026 13:46:36 +0100 Subject: [PATCH 03/11] Fix category-opportunity-index: stop pt-BR literals overriding the skill's own language rule The skill tells the model to detect the seller's language and respond in it, then supplies the report step as (pt-BR) and the badge, indicators table and disclaimer as Portuguese literals. Asked in English against the live connector, it returned an entirely Portuguese report: the concrete literals win over the language rule. - drop (pt-BR) from the Step 4 heading, which contradicted the Language rule - say the badge and table labels are a template to translate, keeping the structure, the emoji and the R$ money formatting - tell the disclaimer which half of its 'pt-BR / English' pair to emit Behaviour for pt-BR sellers is unchanged. --- skills/category-opportunity-index/SKILL.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/skills/category-opportunity-index/SKILL.md b/skills/category-opportunity-index/SKILL.md index 9ea9469..457bbe7 100644 --- a/skills/category-opportunity-index/SKILL.md +++ b/skills/category-opportunity-index/SKILL.md @@ -173,7 +173,7 @@ Do not draw a trend and do not pass three points off as one: state plainly that 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) +### Step 4 — Build the report 1. Lead with the **opportunity index**, prominently: 🟢 alto / 🟡 médio / 🔴 baixo (show `—` if it is missing), noting the marketplace, the category name @@ -207,6 +207,12 @@ 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. +The badge and the table labels below are written in pt-BR because that is the +default. They are a template, not literal strings: when the seller writes in +another language, translate them and keep the structure, the emoji and the `R$` +money formatting, which stays the same in every language because the marketplace +trades in reais. + **Opportunity badge** — a heading line naming the marketplace, the category and the month the figures cover, for example: @@ -236,6 +242,9 @@ cells show `—`. **Resumo** — the 2–4 sentence interpretation described in the workflow. **Disclaimer (every report) — use the variant for the marketplace you queried.** +Each variant below carries the pt-BR wording and the English wording separated by +` / `. Emit only the half that matches the seller's language — never both halves and +never the slash. Mercado Livre: From 468d5c442b85caeea66562e16f355a1513cc02d5 Mon Sep 17 00:00:00 2001 From: Nikita Andreev Date: Wed, 9 Sep 2026 14:25:18 +0100 Subject: [PATCH 04/11] Name the request, not the seller, as the language the answer follows MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every skill carries the rule "detect the seller's language and respond in it. Default to pt-BR". In a seller portal that reads as the *store's* language: the store is Brazilian, its listings are Portuguese, and the model resolves "the seller's language" to pt-BR no matter what language the seller typed. Asked in English against the live connector, category-opportunity-index returned an entirely Portuguese report while the assistant's own prose stayed English — the skill was followed correctly, the instruction was ambiguous. The previous commit on this branch blamed the pt-BR literals in the report template. That diagnosis was wrong: with an explicit "write in English" the same template rendered fully in English, so the literals never dominated. The rule's wording was the whole defect. - restate the Language rule in all 18 skills: write in the language of the message being answered, default pt-BR only when unclear, and never infer the language from the store, its listings or the marketplace - point the "Respond in the seller's language" lines at the seller's request - category-opportunity-index: say at the report step that the pt-BR wording is a template, and label 'alto/medio/baixo' and 'resumo' as pt-BR wording - my-product-vs-catalog, new-growing-products-in-category, seller-overview- tracker, top-brand-position-tracker: drop the remaining pt-BR pins and say the headers and labels are a template to translate Verified against the live JoomPulse connector: an English question to category-opportunity-index and to top-keywords-in-my-category now returns an English report with R$ and pt-BR number formatting intact, and the same question in Portuguese still returns the pt-BR report unchanged. --- skills/category-monitor/SKILL.md | 11 +++-- skills/category-opportunity-index/SKILL.md | 49 ++++++++++++------- .../SKILL.md | 13 +++-- skills/growing-leaf-category-tracker/SKILL.md | 17 ++++--- .../high-demand-low-quality-finder/SKILL.md | 12 +++-- skills/ml-product-analysis/SKILL.md | 22 +++++---- skills/my-product-vs-catalog/SKILL.md | 22 +++++++-- .../new-growing-products-in-category/SKILL.md | 28 ++++++++--- .../popular-international-products/SKILL.md | 14 ++++-- skills/product-change-monitor/SKILL.md | 26 ++++++---- skills/pulse-find-exact-same-product/SKILL.md | 12 +++-- skills/seller-copilot/SKILL.md | 8 +-- skills/seller-overview-tracker/SKILL.md | 18 +++++-- skills/top-brand-position-tracker/SKILL.md | 22 ++++++--- skills/top-keywords-in-my-category/SKILL.md | 12 +++-- skills/top-sellers-in-category/SKILL.md | 8 ++- .../unbranded-products-in-category/SKILL.md | 14 ++++-- skills/uncontested-niche-finder/SKILL.md | 18 ++++--- 18 files changed, 218 insertions(+), 108 deletions(-) diff --git a/skills/category-monitor/SKILL.md b/skills/category-monitor/SKILL.md index 359d8c2..e0eda23 100644 --- a/skills/category-monitor/SKILL.md +++ b/skills/category-monitor/SKILL.md @@ -66,8 +66,11 @@ JoomPulse MCP setup before it can monitor a category. - **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. +- **Language:** write in the language of the message you are answering, and + default to pt-BR only when that is unclear. Never infer the language from the + store, its listings or the marketplace — those are Brazilian whatever + language the seller writes in, so a seller who asks in English gets the whole + report in English. - **The baseline is user-supplied.** Never claim a change without a previous table to compare against, and never infer or fabricate one from memory. @@ -180,8 +183,8 @@ an incomplete month. ## Output -Respond in the seller's language (default pt-BR). Name the marketplace the -figures came from. +Respond in the language of the seller's request (default pt-BR). Name the +marketplace the figures came from. **Snapshot (always):** a markdown table `| Métrica | Valor atual |`, plus a downloadable `.csv` / `.xlsx` of the same data. diff --git a/skills/category-opportunity-index/SKILL.md b/skills/category-opportunity-index/SKILL.md index 457bbe7..5cd5591 100644 --- a/skills/category-opportunity-index/SKILL.md +++ b/skills/category-opportunity-index/SKILL.md @@ -21,13 +21,14 @@ description: > 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. +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 summary, in the language the seller wrote in, 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 @@ -59,8 +60,11 @@ JoomPulse MCP setup before it can report a category's opportunity index. 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. +- **Language:** write in the language of the message you are answering, and + default to pt-BR only when that is unclear. Never infer the language from the + store, its listings or the marketplace — those are Brazilian whatever + language the seller writes in, so a seller who asks in English gets the whole + report in English. - **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. Never fill gaps @@ -175,11 +179,20 @@ month-over-month change instead. ### Step 4 — Build the report -1. Lead with the **opportunity index**, prominently: 🟢 alto / 🟡 médio / 🔴 - baixo (show `—` if it is missing), noting the marketplace, the category name - and level, and the month the figures describe. +Write the whole report in the language of the message you are answering — not +the language of the store or its listings, which are Brazilian either way. +Every Portuguese word in this step and in Output is a pt-BR template: translate +the badge wording, the table headers, the section labels and the disclaimer. +Keep the emoji, the table structure and `R$` exactly as they are. When the +message is in English, no Portuguese is left anywhere in the report. + +1. Lead with the **opportunity index**, prominently: 🟢 alto / 🟡 médio / 🔴 baixo + — pt-BR wording, translated for any other language, emoji unchanged — (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 +3. Write a 2–4 sentence summary — labelled **Resumo** in pt-BR — that + interprets the opportunity index together with concentration and growth: - What the level means — high implies good room for new sellers; low implies little relative upside. @@ -203,9 +216,9 @@ month-over-month change instead. ## Output -Respond in the seller's language, default pt-BR, with no commentary about how the -report was produced. The indicators table always renders as markdown so it shows -cleanly in any client. +Respond in the language of the seller's request, default pt-BR, with no +commentary about how the report was produced. The indicators table always +renders as markdown so it shows cleanly in any client. The badge and the table labels below are written in pt-BR because that is the default. They are a template, not literal strings: when the seller writes in @@ -243,8 +256,8 @@ cells show `—`. **Disclaimer (every report) — use the variant for the marketplace you queried.** Each variant below carries the pt-BR wording and the English wording separated by -` / `. Emit only the half that matches the seller's language — never both halves and -never the slash. +` / `. Emit only the half that matches the language of the seller's request — +never both halves and never the slash. Mercado Livre: diff --git a/skills/fast-growing-international-products/SKILL.md b/skills/fast-growing-international-products/SKILL.md index 064c008..b38c79f 100644 --- a/skills/fast-growing-international-products/SKILL.md +++ b/skills/fast-growing-international-products/SKILL.md @@ -53,7 +53,11 @@ JoomPulse MCP setup before it can find international products. 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. +- **Language:** write in the language of the message you are answering, and + default to pt-BR only when that is unclear. Never infer the language from the + store, its listings or the marketplace — those are Brazilian whatever + language the seller writes in, so a seller who asks in English gets the whole + report in English. - **Keep the workflow invisible.** Show `—` for any missing value; never fabricate. **Shopee data — what differs from Mercado Livre** @@ -149,9 +153,10 @@ weekly ranking**. Label it plainly as a *top-by-revenue fallback*, never call it ## Output -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). +Respond in the language of the seller's request (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):** diff --git a/skills/growing-leaf-category-tracker/SKILL.md b/skills/growing-leaf-category-tracker/SKILL.md index 7ff9bb6..a45b8f0 100644 --- a/skills/growing-leaf-category-tracker/SKILL.md +++ b/skills/growing-leaf-category-tracker/SKILL.md @@ -62,7 +62,11 @@ JoomPulse MCP setup before it can find growing niches. 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. +- **Language:** write in the language of the message you are answering, and + default to pt-BR only when that is unclear. Never infer the language from the + store, its listings or the marketplace — those are Brazilian whatever + language the seller writes in, so a seller who asks in English gets the whole + report in English. - **Keep the workflow invisible.** Surface the answer, not the steps. Never fill gaps from general knowledge; show `—` for any missing value. @@ -155,11 +159,12 @@ 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. 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. +Respond in the language of the seller's request (default pt-BR), with no +commentary about how the 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: diff --git a/skills/high-demand-low-quality-finder/SKILL.md b/skills/high-demand-low-quality-finder/SKILL.md index a5e72f9..c70ef41 100644 --- a/skills/high-demand-low-quality-finder/SKILL.md +++ b/skills/high-demand-low-quality-finder/SKILL.md @@ -59,7 +59,11 @@ JoomPulse MCP setup before it can find opportunities. 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. +- **Language:** write in the language of the message you are answering, and + default to pt-BR only when that is unclear. Never infer the language from the + store, its listings or the marketplace — those are Brazilian whatever + language the seller writes in, so a seller who asks in English gets the whole + report in English. - **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. @@ -159,9 +163,9 @@ needs. Pull a generous set so the filters have room to work. ## Output -Respond in the seller's language. Present the result with no commentary about how -it was produced. The product table always renders as markdown so it displays -cleanly in any client. +Respond in the language of the seller's request. Present the result with no +commentary about how it was produced. The product table always renders as +markdown so it displays cleanly in any client. Lead with a short intro line naming the **marketplace**, the category and the rating threshold actually applied. diff --git a/skills/ml-product-analysis/SKILL.md b/skills/ml-product-analysis/SKILL.md index 8fd5187..103b6fc 100644 --- a/skills/ml-product-analysis/SKILL.md +++ b/skills/ml-product-analysis/SKILL.md @@ -58,8 +58,11 @@ JoomPulse MCP setup before it can analyze a product or find competitors. - **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 - pt-BR. +- **Language:** write in the language of the message you are answering, and + default to pt-BR only when that is unclear. Never infer the language from the + store, its listings or the marketplace — those are Brazilian whatever + language the seller writes in, so a seller who asks in English gets the whole + report in English. - **Keep the workflow invisible.** The seller wants the answer, not a play-by- play. Do the analysis quietly and present only the result. If one approach to finding the product or its competitors does not work, switch to another @@ -242,8 +245,8 @@ Both the keyword and photo paths feed the same analog pipeline: ## 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: +Respond in the language of the seller's request. 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, naming the **marketplace**. 2. The subject product card. @@ -287,11 +290,12 @@ rating, reviews, favourites, cross-border shipping, photo count, shop tier, and 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. +You may translate the column headers and card labels into the language of the +seller's request. 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.** diff --git a/skills/my-product-vs-catalog/SKILL.md b/skills/my-product-vs-catalog/SKILL.md index c4a8691..4078cdb 100644 --- a/skills/my-product-vs-catalog/SKILL.md +++ b/skills/my-product-vs-catalog/SKILL.md @@ -19,9 +19,10 @@ description: > # Mercado Livre — My Product vs. Catalog (Buy-Box Competitiveness) This skill compares the seller's **own** Mercado Livre (Brasil) listing against -**the available competing listings of the same catalog product** — the sellers competing -for the same buy-box — and tells the seller, in pt-BR, where they win, where they -lose, and **what to fix first** to win the buy-box and convert more. +**the available competing listings of the same catalog product** — the sellers +competing for the same buy-box — and tells the seller, in the language of their +request, where they win, where they lose, and **what to fix first** to win the +buy-box and convert more. Given a product by a Mercado Livre link, a JoomPulse link, a Mercado Livre listing identifier, or a catalog product identifier, it identifies the seller's listing and @@ -63,7 +64,11 @@ JoomPulse MCP setup before it can compare a listing against its catalog. review count, logistics, and seller attributes are real Mercado Livre data — say so, it is a strength of the report. - **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. +- **Language:** write in the language of the message you are answering, and + default to pt-BR only when that is unclear. Never infer the language from the + store, its listings or the marketplace — those are Brazilian whatever + language the seller writes in, so a seller who asks in English gets the whole + report in English. - **Keep the workflow invisible.** The seller wants the answer, not a play-by-play. If one lookup returns nothing, switch approaches quietly; only if everything fails do you say one short, friendly sentence. @@ -116,7 +121,14 @@ Each parameter gets one status, with a colour marker so it reads at a glance: ## Output -Respond in pt-BR, leading with the verdict: +Respond in the language of the seller's request, default pt-BR, leading with +the verdict: + +The section headings and labels below are written in pt-BR because that is the +default. They are a template, not literal strings: when the seller writes in +another language, translate them and keep the structure, the emoji and the `R$` +money formatting, which stays the same in every language because the +marketplace trades in reais. 1. **Veredito** — two to four sentences: where the seller wins, where they lose, their buy-box position, and the single top priority. diff --git a/skills/new-growing-products-in-category/SKILL.md b/skills/new-growing-products-in-category/SKILL.md index b1ddfaa..ed8f831 100644 --- a/skills/new-growing-products-in-category/SKILL.md +++ b/skills/new-growing-products-in-category/SKILL.md @@ -55,7 +55,11 @@ JoomPulse MCP setup before it can find new growing products in a category. 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. +- **Language:** write in the language of the message you are answering, and + default to pt-BR only when that is unclear. Never infer the language from the + store, its listings or the marketplace — those are Brazilian whatever + language the seller writes in, so a seller who asks in English gets the whole + report in English. - **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. @@ -153,8 +157,15 @@ numbers. ## 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. +Respond in the language of the seller's request. Present the result with no +commentary about how it was produced. Use plain markdown so it renders cleanly +in any client. + +The column headers and labels below are written in pt-BR because that is the +default. They are a template, not literal strings: when the seller writes in +another language, translate them and keep the structure, the emoji and the `R$` +money formatting, which stays the same in every language because the +marketplace trades in reais. 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 @@ -205,8 +216,8 @@ marketplaces: Mercado Livre reports weekly and monthly figures, Shopee reports 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. +Livre, as Shopee item links on Shopee. You may translate the column headers +into the language of the seller's request. **Disclaimer (every report) — use the variant for the marketplace you queried.** @@ -286,9 +297,10 @@ 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. + larger day-on-air window or a lower monthly-sales floor). Keep it in the + language of the seller's request. 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. If nothing matches, check the other marketplace before saying the category does not exist. diff --git a/skills/popular-international-products/SKILL.md b/skills/popular-international-products/SKILL.md index d753fae..63e8c26 100644 --- a/skills/popular-international-products/SKILL.md +++ b/skills/popular-international-products/SKILL.md @@ -53,7 +53,11 @@ JoomPulse MCP setup before it can find international products. 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. +- **Language:** write in the language of the message you are answering, and + default to pt-BR only when that is unclear. Never infer the language from the + store, its listings or the marketplace — those are Brazilian whatever + language the seller writes in, so a seller who asks in English gets the whole + report in English. - **Keep the workflow invisible.** Surface the answer, not the steps. Show `—` for any missing value; never fabricate one. @@ -149,10 +153,10 @@ Keep the shortlist (about 10). ## Output -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. +Respond in the language of the seller's request (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:** diff --git a/skills/product-change-monitor/SKILL.md b/skills/product-change-monitor/SKILL.md index 8dc023d..8609439 100644 --- a/skills/product-change-monitor/SKILL.md +++ b/skills/product-change-monitor/SKILL.md @@ -61,7 +61,11 @@ JoomPulse MCP setup before it can monitor a product's changes. 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. +- **Language:** write in the language of the message you are answering, and + default to pt-BR only when that is unclear. Never infer the language from the + store, its listings or the marketplace — those are Brazilian whatever + language the seller writes in, so a seller who asks in English gets the whole + report in English. - **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. @@ -186,8 +190,9 @@ directly — ask for a Mercado Livre, Shopee or JoomPulse link or identifier. ## 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. +Respond in the language of the seller's request. 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 line naming the **marketplace** that was monitored. @@ -231,13 +236,14 @@ columns: 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"). 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. +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"). 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 language of the seller's +request. **Disclaimer (every report) — use the variant for the marketplace you queried.** diff --git a/skills/pulse-find-exact-same-product/SKILL.md b/skills/pulse-find-exact-same-product/SKILL.md index 9bbe1a1..e02717c 100644 --- a/skills/pulse-find-exact-same-product/SKILL.md +++ b/skills/pulse-find-exact-same-product/SKILL.md @@ -69,7 +69,11 @@ JoomPulse MCP setup before it can search or compare products. 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. +- **Language:** write in the language of the message you are answering, and + default to pt-BR only when that is unclear. Never infer the language from the + store, its listings or the marketplace — those are Brazilian whatever + language the seller writes in, so a seller who asks in English gets the whole + report in English. - **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. @@ -194,9 +198,9 @@ numbers. ## Output Format -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: +Respond in the language of the seller's request. 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 | | --- | --- | --- | --- | diff --git a/skills/seller-copilot/SKILL.md b/skills/seller-copilot/SKILL.md index d73e16b..f5b61be 100644 --- a/skills/seller-copilot/SKILL.md +++ b/skills/seller-copilot/SKILL.md @@ -94,7 +94,8 @@ MCP setup before it can analyse marketplace data. - **Not available from JoomPulse:** supplier or landed cost, true unit cost, return and refund rates, and traffic or conversion funnels. If the question depends on one of these, say so and ask the seller to supply the figure — do not estimate it silently. -- **Match the seller's language.** One language per answer, no mixing. +- **Match the language of the seller's request.** One language per answer, no + mixing. ## How to use this skill @@ -323,8 +324,9 @@ be read all at once. Files prefixed `shopee-` are Shopee Brasil; the rest are Me - **One-line caption above every table**, saying what it shows — scope, sort order, and snapshot date. - **Verdict before table**, always. -- **Portuguese column labels** with the prose in the seller's language: `Vendas estimadas`, - `Receita estimada`, `Preço`, `Oportunidade`, `Monopolização`, `Tendência`. +- **Portuguese column labels** with the prose in the language of the seller's + request: `Vendas estimadas`, `Receita estimada`, `Preço`, `Oportunidade`, + `Monopolização`, `Tendência`. - **Top 10 rows by default** (all, if fewer than 10). When more exist, **state the total and offer the rest or a CSV** — never truncate silently. Equally, **never pad a list to reach the requested count**: if the seller asked for 10 and the data yields 6, return 6 diff --git a/skills/seller-overview-tracker/SKILL.md b/skills/seller-overview-tracker/SKILL.md index e111d0f..bcee9d0 100644 --- a/skills/seller-overview-tracker/SKILL.md +++ b/skills/seller-overview-tracker/SKILL.md @@ -68,8 +68,11 @@ JoomPulse MCP setup before it can monitor a seller. - **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. +- **Language:** write in the language of the message you are answering, and + default to pt-BR only when that is unclear. Never infer the language from the + store, its listings or the marketplace — those are Brazilian whatever + language the seller writes in, so a seller who asks in English gets the whole + report in English. - **The baseline is user-supplied.** Never claim a change without a previous table to compare against, and never infer or fabricate one from memory. The previous table must be for the **same seller on the same marketplace**. @@ -170,8 +173,15 @@ 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. Lead with a short line naming the **marketplace** and the store. +Respond in the language of the seller's request, default pt-BR. Present the +result with no commentary about how it was produced. Lead with a short line +naming the **marketplace** and the store. + +The table headers and field labels below are written in pt-BR because that is +the default. They are a template, not literal strings: when the seller writes +in another language, translate them and keep the structure, the emoji and the +`R$` money formatting, which stays the same in every language because the +marketplace trades in reais. **Snapshot (always):** a markdown table `| Campo | Valor atual |` for the rows below, plus a downloadable `.csv` / `.xlsx` of the same data. diff --git a/skills/top-brand-position-tracker/SKILL.md b/skills/top-brand-position-tracker/SKILL.md index d2e255f..da657a9 100644 --- a/skills/top-brand-position-tracker/SKILL.md +++ b/skills/top-brand-position-tracker/SKILL.md @@ -65,8 +65,11 @@ JoomPulse MCP setup before it can rank brands and track their positions. and brings it back next period. - **The baseline is user-supplied.** Never claim a position change without a previous table to compare against, and never infer or fabricate one from memory. -- **Language:** respond in pt-BR by default. If the seller clearly writes in - another language, mirror it; otherwise pt-BR. +- **Language:** write in the language of the message you are answering, and + default to pt-BR only when that is unclear. Never infer the language from the + store, its listings or the marketplace — those are Brazilian whatever + language the seller writes in, so a seller who asks in English gets the whole + report in English. - **Keep the workflow invisible.** The seller wants the ranking, 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. @@ -129,8 +132,9 @@ on its own (no movement column) and the user is told to save it for next time. ## Output -Respond in the seller's language (pt-BR by default), with no commentary about how -the result was produced. Use plain markdown so it renders cleanly in any client. +Respond in the language of the seller's request (pt-BR by default), with no +commentary about how the result was produced. Use plain markdown so it renders +cleanly in any client. There is **one canonical brand-ranking table**, used everywhere (in the response text and mirrored by the downloadable file). One row per brand, sorted by current @@ -214,8 +218,14 @@ the response text, never inside a rendered visual. ### Ranked table (always markdown, both surfaces) The ranked table is the **one canonical brand-ranking table defined in Output** — -the same columns, in pt-BR, on every surface. It lives in the response text, never -inside a rendered visual. +the same columns on every surface. It lives in the response text, never inside +a rendered visual. + +The column headers and labels below are written in pt-BR because that is the +default. They are a template, not literal strings: when the seller writes in +another language, translate them and keep the structure, the emoji and the `R$` +money formatting, which stays the same in every language because the +marketplace trades in reais. - **Standalone ranking:** columns `Posição | Marca | GMV estimado (semana) | Vendas est. (semana) | Anúncios | Avaliações | Preço médio` — **no `Variação` diff --git a/skills/top-keywords-in-my-category/SKILL.md b/skills/top-keywords-in-my-category/SKILL.md index 2777f02..2e1a7df 100644 --- a/skills/top-keywords-in-my-category/SKILL.md +++ b/skills/top-keywords-in-my-category/SKILL.md @@ -49,7 +49,11 @@ JoomPulse MCP setup before it can list a category's keywords. counts come from Mercado Livre search trends — say so; do not add the sales estimate disclaimer that other skills use. - **Read-only.** The skill never writes or modifies anything. -- **Language:** detect the seller's language and respond in it. Default to pt-BR. +- **Language:** write in the language of the message you are answering, and + default to pt-BR only when that is unclear. Never infer the language from the + store, its listings or the marketplace — those are Brazilian whatever + language the seller writes in, so a seller who asks in English gets the whole + report in English. - **Keep the workflow invisible.** Show `—` for any missing value; never fabricate. ## Workflow @@ -66,9 +70,9 @@ rank and its competing-product count. Sort by rank, best position first. ## Output -Respond in the seller's language (default pt-BR). The keywords always render as a -markdown table, sorted by position. The headers below are the pt-BR default and -may be rendered in the seller's language: +Respond in the language of the seller's request (default pt-BR). The keywords +always render as a markdown table, sorted by position. The headers below are +the pt-BR default and may be rendered in the language of the seller's request: | Posição | Palavra-chave | Produtos (oferta) | |--:|---|--:| diff --git a/skills/top-sellers-in-category/SKILL.md b/skills/top-sellers-in-category/SKILL.md index fd2a401..a2c6944 100644 --- a/skills/top-sellers-in-category/SKILL.md +++ b/skills/top-sellers-in-category/SKILL.md @@ -56,7 +56,11 @@ JoomPulse MCP setup before it can rank a category's sellers. 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. +- **Language:** write in the language of the message you are answering, and + default to pt-BR only when that is unclear. Never infer the language from the + store, its listings or the marketplace — those are Brazilian whatever + language the seller writes in, so a seller who asks in English gets the whole + report in English. - **The baseline is user-supplied.** Never claim a movement without a previous leaderboard to compare against, and never infer or fabricate one from memory. @@ -96,7 +100,7 @@ leaderboard. The change column header is a word ("Variação"), never a bare "Δ ## Output -Respond in the seller's language (default pt-BR). +Respond in the language of the seller's request (default pt-BR). **Leaderboard (always):** a markdown table, plus a downloadable `.csv` / `.xlsx`: diff --git a/skills/unbranded-products-in-category/SKILL.md b/skills/unbranded-products-in-category/SKILL.md index 4449b4b..0f29882 100644 --- a/skills/unbranded-products-in-category/SKILL.md +++ b/skills/unbranded-products-in-category/SKILL.md @@ -60,7 +60,11 @@ JoomPulse MCP setup before it can find unbranded products. 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. +- **Language:** write in the language of the message you are answering, and + default to pt-BR only when that is unclear. Never infer the language from the + store, its listings or the marketplace — those are Brazilian whatever + language the seller writes in, so a seller who asks in English gets the whole + report in English. - **Keep the workflow invisible.** Show `—` for any missing value; never fabricate. **Shopee data — what differs from Mercado Livre** @@ -140,10 +144,10 @@ strongest ~20–30. ## Output -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. +Respond in the language of the seller's request (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):** diff --git a/skills/uncontested-niche-finder/SKILL.md b/skills/uncontested-niche-finder/SKILL.md index 8dedc7f..4ffe878 100644 --- a/skills/uncontested-niche-finder/SKILL.md +++ b/skills/uncontested-niche-finder/SKILL.md @@ -75,7 +75,11 @@ JoomPulse MCP setup before it can find uncontested niches. 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. +- **Language:** write in the language of the message you are answering, and + default to pt-BR only when that is unclear. Never infer the language from the + store, its listings or the marketplace — those are Brazilian whatever + language the seller writes in, so a seller who asks in English gets the whole + report in English. - **Keep the workflow invisible.** The seller wants the niches, 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. Never fill gaps @@ -201,9 +205,9 @@ numbers. ## Output -Respond in the seller's language. Present the result with no commentary about how -it was produced. The product table always renders as markdown so it reads -cleanly in any client. +Respond in the language of the seller's request. Present the result with no +commentary about how it was produced. The product table always renders as +markdown so it reads cleanly in any client. Lead with a short intro line naming the **marketplace** and the category — and on Shopee, the category level you actually worked at. @@ -257,9 +261,9 @@ 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 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. +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 language of the seller's request. **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 From e6a4d92a7625ba48e55504fb3ed18a56949a8391 Mon Sep 17 00:00:00 2001 From: Nikita Andreev Date: Wed, 9 Sep 2026 16:11:06 +0100 Subject: [PATCH 05/11] Offer the spreadsheet only where the client can produce one MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Four skills present a downloadable `.csv` / `.xlsx` as part of the deliverable without saying what to do where the client cannot write files. In a portal-style host — a web UI whose agent has a fixed tool surface and no file output — the skill duly offers a download that never arrives, and for the three trackers that offer is load-bearing: they ask the seller to bring the file back next period as the baseline. The skills already hedge this way for visuals ("if no visual surface is available at all, fall back to the markdown table"), so this applies the same shape to files: offer the download where the client can produce files, and otherwise let the markdown table stand as the deliverable rather than promising a file. The trackers already accept a pasted table as the baseline, so nothing is lost. - category-monitor, top-brand-position-tracker, top-sellers-in-category: make the download conditional and say the table stands on its own without it - ml-product-analysis: same for the analogs spreadsheet; the `.csv` mentions in its input routing are untouched, since those describe what the seller supplies No change where files are available. --- skills/category-monitor/SKILL.md | 15 +++++++++------ skills/ml-product-analysis/SKILL.md | 9 +++++---- skills/top-brand-position-tracker/SKILL.md | 9 +++++---- skills/top-sellers-in-category/SKILL.md | 11 +++++++---- 4 files changed, 26 insertions(+), 18 deletions(-) diff --git a/skills/category-monitor/SKILL.md b/skills/category-monitor/SKILL.md index e0eda23..779a8ea 100644 --- a/skills/category-monitor/SKILL.md +++ b/skills/category-monitor/SKILL.md @@ -161,10 +161,12 @@ Two Shopee-specific cautions: 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. +This table is the deliverable. **Where the client can produce files, also offer +it as a downloadable `.csv` / `.xlsx`** so the user can save it and bring it +back next period as the baseline; where it cannot, the markdown table stands on +its own — never offer a download you cannot deliver. 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 @@ -186,8 +188,9 @@ an incomplete month. Respond in the language of the seller's request (default pt-BR). Name the marketplace the figures came from. -**Snapshot (always):** a markdown table `| Métrica | Valor atual |`, plus a -downloadable `.csv` / `.xlsx` of the same data. +**Snapshot (always):** a markdown table `| Métrica | Valor atual |`, plus — +where the client can produce files — a downloadable `.csv` / `.xlsx` of the +same data. - **Mercado Livre** rows: **Vendas (estimadas), Produtos, Produtos de catálogo, Vendedores, Distribuição de medalhas, Monopolização**. diff --git a/skills/ml-product-analysis/SKILL.md b/skills/ml-product-analysis/SKILL.md index 103b6fc..4abb783 100644 --- a/skills/ml-product-analysis/SKILL.md +++ b/skills/ml-product-analysis/SKILL.md @@ -319,10 +319,11 @@ Shopee: > 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. 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. +**Download** — where the client can produce files, offer a downloadable +spreadsheet (`.xlsx` plus `.csv`) of the 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 diff --git a/skills/top-brand-position-tracker/SKILL.md b/skills/top-brand-position-tracker/SKILL.md index da657a9..e934615 100644 --- a/skills/top-brand-position-tracker/SKILL.md +++ b/skills/top-brand-position-tracker/SKILL.md @@ -108,10 +108,11 @@ JoomPulse MCP setup before it can rank brands and track their positions. ### Step 2 — Present today's ranking and offer it for download Render today's brand-ranking table (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 ranking there is **no movement column and no legend** — just the -ranking. +This table is the deliverable. **Where the client can produce files, also offer +it as a downloadable `.csv` / `.xlsx`** so the user can save it and bring it +back next period as the baseline; where it cannot, the markdown table stands on +its own — never offer a download you cannot deliver. On a standalone ranking +there is **no movement column and no legend** — just the ranking. ### Step 3 — Offer comparison, and compare if a previous table is supplied diff --git a/skills/top-sellers-in-category/SKILL.md b/skills/top-sellers-in-category/SKILL.md index a2c6944..29c732e 100644 --- a/skills/top-sellers-in-category/SKILL.md +++ b/skills/top-sellers-in-category/SKILL.md @@ -80,9 +80,11 @@ 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**. +This table is the deliverable. **Where the client can produce files, also offer +it as a downloadable `.csv` / `.xlsx`** so the user can save it and bring it +back next period as the baseline; where it cannot, the markdown table stands on +its own — never offer a download you cannot deliver. On a standalone +leaderboard there is **no movement column and no legend**. ### Step 4 — Offer comparison, and compare if a previous leaderboard is supplied @@ -102,7 +104,8 @@ leaderboard. The change column header is a word ("Variação"), never a bare "Δ Respond in the language of the seller's request (default pt-BR). -**Leaderboard (always):** a markdown table, plus a downloadable `.csv` / `.xlsx`: +**Leaderboard (always):** a markdown table, plus — where the client can produce +files — 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 | |---|--:|--:|--:|--:|--:|--:|--:|--:|--:|--:|--:| From 33327d069bfe6cc99675042d8a5809bad2a17037 Mon Sep 17 00:00:00 2001 From: Nikita Andreev Date: Wed, 9 Sep 2026 16:38:39 +0100 Subject: [PATCH 06/11] Say plainly that no Portuguese may remain when the request is in English MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The note added earlier — "the labels below are a template, not literal strings" — does not work on its own. Tested against the live connector, an English question to top-sellers-in-category came back with English prose over a wholly Portuguese table: `Vendedor`, `Receita est.`, `Ticket médio`, values `ouro` / `sim`, and a pt-BR disclaimer. The model reads a descriptive note as background and the column spec as the thing to reproduce. What did work, in category-opportunity-index, was the checkable sentence at the end of its report step: when the request is in English, no Portuguese is left anywhere. Every copy of the note now carries that sentence, and names the row values and the disclaimer rather than only the headers, since those are what leaked. Retested afterwards: the same question returns `Seller`, `Est. revenue (1m)`, `Avg. ticket`, values `platinum` / `yes`, and the English disclaimer, with `R$` and the pt-BR number formatting intact. - add the note to category-monitor, ml-product-analysis and top-sellers-in-category, which show pt-BR tables and had none - unify the wording across all eight skills that carry it --- skills/category-monitor/SKILL.md | 8 ++++++++ skills/category-opportunity-index/SKILL.md | 12 +++++++----- skills/ml-product-analysis/SKILL.md | 8 ++++++++ skills/my-product-vs-catalog/SKILL.md | 12 +++++++----- skills/new-growing-products-in-category/SKILL.md | 12 +++++++----- skills/seller-overview-tracker/SKILL.md | 12 +++++++----- skills/top-brand-position-tracker/SKILL.md | 12 +++++++----- skills/top-sellers-in-category/SKILL.md | 8 ++++++++ 8 files changed, 59 insertions(+), 25 deletions(-) diff --git a/skills/category-monitor/SKILL.md b/skills/category-monitor/SKILL.md index 779a8ea..dedc57d 100644 --- a/skills/category-monitor/SKILL.md +++ b/skills/category-monitor/SKILL.md @@ -188,6 +188,14 @@ an incomplete month. Respond in the language of the seller's request (default pt-BR). Name the marketplace the figures came from. +The column headers, labels and disclaimers below are written in pt-BR because +that is the default. They are a template, not literal strings: when the seller +writes in another language, translate all of them — the headers, row values +such as `sim` / `não` / `ouro`, and the disclaimer — and keep the structure, +the emoji and the `R$` money formatting, which stays the same in every language +because the marketplace trades in reais. When the request is in English, no +Portuguese is left anywhere in the answer. + **Snapshot (always):** a markdown table `| Métrica | Valor atual |`, plus — where the client can produce files — a downloadable `.csv` / `.xlsx` of the same data. diff --git a/skills/category-opportunity-index/SKILL.md b/skills/category-opportunity-index/SKILL.md index 5cd5591..a28cda9 100644 --- a/skills/category-opportunity-index/SKILL.md +++ b/skills/category-opportunity-index/SKILL.md @@ -220,11 +220,13 @@ Respond in the language of the seller's request, default pt-BR, with no commentary about how the report was produced. The indicators table always renders as markdown so it shows cleanly in any client. -The badge and the table labels below are written in pt-BR because that is the -default. They are a template, not literal strings: when the seller writes in -another language, translate them and keep the structure, the emoji and the `R$` -money formatting, which stays the same in every language because the marketplace -trades in reais. +The column headers, labels and disclaimers below are written in pt-BR because +that is the default. They are a template, not literal strings: when the seller +writes in another language, translate all of them — the headers, row values +such as `sim` / `não` / `ouro`, and the disclaimer — and keep the structure, +the emoji and the `R$` money formatting, which stays the same in every language +because the marketplace trades in reais. When the request is in English, no +Portuguese is left anywhere in the answer. **Opportunity badge** — a heading line naming the marketplace, the category and the month the figures cover, for example: diff --git a/skills/ml-product-analysis/SKILL.md b/skills/ml-product-analysis/SKILL.md index 4abb783..b743894 100644 --- a/skills/ml-product-analysis/SKILL.md +++ b/skills/ml-product-analysis/SKILL.md @@ -248,6 +248,14 @@ Both the keyword and photo paths feed the same analog pipeline: Respond in the language of the seller's request. The visible reply contains only the result, in this order, with no commentary about how it was produced: +The column headers, labels and disclaimers below are written in pt-BR because +that is the default. They are a template, not literal strings: when the seller +writes in another language, translate all of them — the headers, row values +such as `sim` / `não` / `ouro`, and the disclaimer — and keep the structure, +the emoji and the `R$` money formatting, which stays the same in every language +because the marketplace trades in reais. When the request is in English, no +Portuguese is left anywhere in the answer. + 1. An optional one-line framing sentence, naming the **marketplace**. 2. The subject product card. 3. The ranked analogs table. diff --git a/skills/my-product-vs-catalog/SKILL.md b/skills/my-product-vs-catalog/SKILL.md index 4078cdb..9bd5328 100644 --- a/skills/my-product-vs-catalog/SKILL.md +++ b/skills/my-product-vs-catalog/SKILL.md @@ -124,11 +124,13 @@ Each parameter gets one status, with a colour marker so it reads at a glance: Respond in the language of the seller's request, default pt-BR, leading with the verdict: -The section headings and labels below are written in pt-BR because that is the -default. They are a template, not literal strings: when the seller writes in -another language, translate them and keep the structure, the emoji and the `R$` -money formatting, which stays the same in every language because the -marketplace trades in reais. +The column headers, labels and disclaimers below are written in pt-BR because +that is the default. They are a template, not literal strings: when the seller +writes in another language, translate all of them — the headers, row values +such as `sim` / `não` / `ouro`, and the disclaimer — and keep the structure, +the emoji and the `R$` money formatting, which stays the same in every language +because the marketplace trades in reais. When the request is in English, no +Portuguese is left anywhere in the answer. 1. **Veredito** — two to four sentences: where the seller wins, where they lose, their buy-box position, and the single top priority. diff --git a/skills/new-growing-products-in-category/SKILL.md b/skills/new-growing-products-in-category/SKILL.md index ed8f831..bb8a81f 100644 --- a/skills/new-growing-products-in-category/SKILL.md +++ b/skills/new-growing-products-in-category/SKILL.md @@ -161,11 +161,13 @@ Respond in the language of the seller's request. Present the result with no commentary about how it was produced. Use plain markdown so it renders cleanly in any client. -The column headers and labels below are written in pt-BR because that is the -default. They are a template, not literal strings: when the seller writes in -another language, translate them and keep the structure, the emoji and the `R$` -money formatting, which stays the same in every language because the -marketplace trades in reais. +The column headers, labels and disclaimers below are written in pt-BR because +that is the default. They are a template, not literal strings: when the seller +writes in another language, translate all of them — the headers, row values +such as `sim` / `não` / `ouro`, and the disclaimer — and keep the structure, +the emoji and the `R$` money formatting, which stays the same in every language +because the marketplace trades in reais. When the request is in English, no +Portuguese is left anywhere in the answer. 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 diff --git a/skills/seller-overview-tracker/SKILL.md b/skills/seller-overview-tracker/SKILL.md index bcee9d0..2a4a297 100644 --- a/skills/seller-overview-tracker/SKILL.md +++ b/skills/seller-overview-tracker/SKILL.md @@ -177,11 +177,13 @@ Respond in the language of the seller's request, default pt-BR. Present the result with no commentary about how it was produced. Lead with a short line naming the **marketplace** and the store. -The table headers and field labels below are written in pt-BR because that is -the default. They are a template, not literal strings: when the seller writes -in another language, translate them and keep the structure, the emoji and the -`R$` money formatting, which stays the same in every language because the -marketplace trades in reais. +The column headers, labels and disclaimers below are written in pt-BR because +that is the default. They are a template, not literal strings: when the seller +writes in another language, translate all of them — the headers, row values +such as `sim` / `não` / `ouro`, and the disclaimer — and keep the structure, +the emoji and the `R$` money formatting, which stays the same in every language +because the marketplace trades in reais. When the request is in English, no +Portuguese is left anywhere in the answer. **Snapshot (always):** a markdown table `| Campo | Valor atual |` for the rows below, plus a downloadable `.csv` / `.xlsx` of the same data. diff --git a/skills/top-brand-position-tracker/SKILL.md b/skills/top-brand-position-tracker/SKILL.md index e934615..533411c 100644 --- a/skills/top-brand-position-tracker/SKILL.md +++ b/skills/top-brand-position-tracker/SKILL.md @@ -222,11 +222,13 @@ The ranked table is the **one canonical brand-ranking table defined in Output** the same columns on every surface. It lives in the response text, never inside a rendered visual. -The column headers and labels below are written in pt-BR because that is the -default. They are a template, not literal strings: when the seller writes in -another language, translate them and keep the structure, the emoji and the `R$` -money formatting, which stays the same in every language because the -marketplace trades in reais. +The column headers, labels and disclaimers below are written in pt-BR because +that is the default. They are a template, not literal strings: when the seller +writes in another language, translate all of them — the headers, row values +such as `sim` / `não` / `ouro`, and the disclaimer — and keep the structure, +the emoji and the `R$` money formatting, which stays the same in every language +because the marketplace trades in reais. When the request is in English, no +Portuguese is left anywhere in the answer. - **Standalone ranking:** columns `Posição | Marca | GMV estimado (semana) | Vendas est. (semana) | Anúncios | Avaliações | Preço médio` — **no `Variação` diff --git a/skills/top-sellers-in-category/SKILL.md b/skills/top-sellers-in-category/SKILL.md index 29c732e..cb7f1b3 100644 --- a/skills/top-sellers-in-category/SKILL.md +++ b/skills/top-sellers-in-category/SKILL.md @@ -104,6 +104,14 @@ leaderboard. The change column header is a word ("Variação"), never a bare "Δ Respond in the language of the seller's request (default pt-BR). +The column headers, labels and disclaimers below are written in pt-BR because +that is the default. They are a template, not literal strings: when the seller +writes in another language, translate all of them — the headers, row values +such as `sim` / `não` / `ouro`, and the disclaimer — and keep the structure, +the emoji and the `R$` money formatting, which stays the same in every language +because the marketplace trades in reais. When the request is in English, no +Portuguese is left anywhere in the answer. + **Leaderboard (always):** a markdown table, plus — where the client can produce files — a downloadable `.csv` / `.xlsx`: From 31ffd8dd34a8113ca189652006465c666eceb10d Mon Sep 17 00:00:00 2001 From: Nikita Andreev Date: Thu, 10 Sep 2026 07:01:15 +0100 Subject: [PATCH 07/11] Carry the same translate-the-labels note in every skill that has labels Nine skills still had pt-BR headers, row values or disclaimers with nothing telling the model to translate them, so an English question got English prose over a Portuguese table whenever the model did not translate of its own accord. top-keywords-in-my-category is the clearest case, and it ships: it said "the headers below are the pt-BR default and may be rendered in the language of the seller's request". That is permission, not an instruction. It happened to translate under test, which is luck rather than behaviour -- the same wording shape failed outright in top-sellers-in-category until the note was added there. Every skill with pt-BR labels now carries the same note, ending in the checkable sentence that made the difference: when the request is in English, no Portuguese is left anywhere in the answer. Seventeen of the eighteen carry it; pulse-find-exact-same-product has no pt-BR labels and needs none. Retested against the live connector: an English question to top-keywords-in-my-category now returns Position / Keyword / Products (supply) with no Portuguese anywhere, and the keywords themselves stay in Portuguese, which is right -- they are real Brazilian search terms. --- skills/fast-growing-international-products/SKILL.md | 8 ++++++++ skills/growing-leaf-category-tracker/SKILL.md | 8 ++++++++ skills/high-demand-low-quality-finder/SKILL.md | 8 ++++++++ skills/popular-international-products/SKILL.md | 8 ++++++++ skills/product-change-monitor/SKILL.md | 8 ++++++++ skills/seller-copilot/SKILL.md | 8 ++++++++ skills/top-keywords-in-my-category/SKILL.md | 11 +++++++++-- skills/unbranded-products-in-category/SKILL.md | 8 ++++++++ skills/uncontested-niche-finder/SKILL.md | 8 ++++++++ 9 files changed, 73 insertions(+), 2 deletions(-) diff --git a/skills/fast-growing-international-products/SKILL.md b/skills/fast-growing-international-products/SKILL.md index b38c79f..0630205 100644 --- a/skills/fast-growing-international-products/SKILL.md +++ b/skills/fast-growing-international-products/SKILL.md @@ -158,6 +158,14 @@ 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). +The column headers, labels and disclaimers below are written in pt-BR because +that is the default. They are a template, not literal strings: when the seller +writes in another language, translate all of them — the headers, row values +such as `sim` / `não` / `ouro`, and the disclaimer — and keep the structure, +the emoji and the `R$` money formatting, which stays the same in every language +because the marketplace trades in reais. When the request is in English, no +Portuguese is left anywhere in the answer. + **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 | diff --git a/skills/growing-leaf-category-tracker/SKILL.md b/skills/growing-leaf-category-tracker/SKILL.md index a45b8f0..1b0d4e7 100644 --- a/skills/growing-leaf-category-tracker/SKILL.md +++ b/skills/growing-leaf-category-tracker/SKILL.md @@ -166,6 +166,14 @@ 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 column headers, labels and disclaimers below are written in pt-BR because +that is the default. They are a template, not literal strings: when the seller +writes in another language, translate all of them — the headers, row values +such as `sim` / `não` / `ouro`, and the disclaimer — and keep the structure, +the emoji and the `R$` money formatting, which stays the same in every language +because the marketplace trades in reais. When the request is in English, no +Portuguese is left anywhere in the answer. + The ranking always renders as a markdown table: | Categoria | Qtd. vendedores | Receita (mês est.) | Vendas (mês est.) | Produtos | diff --git a/skills/high-demand-low-quality-finder/SKILL.md b/skills/high-demand-low-quality-finder/SKILL.md index c70ef41..afce930 100644 --- a/skills/high-demand-low-quality-finder/SKILL.md +++ b/skills/high-demand-low-quality-finder/SKILL.md @@ -167,6 +167,14 @@ Respond in the language of the seller's request. Present the result with no commentary about how it was produced. The product table always renders as markdown so it displays cleanly in any client. +The column headers, labels and disclaimers below are written in pt-BR because +that is the default. They are a template, not literal strings: when the seller +writes in another language, translate all of them — the headers, row values +such as `sim` / `não` / `ouro`, and the disclaimer — and keep the structure, +the emoji and the `R$` money formatting, which stays the same in every language +because the marketplace trades in reais. When the request is in English, no +Portuguese is left anywhere in the answer. + Lead with a short intro line naming the **marketplace**, the category and the rating threshold actually applied. diff --git a/skills/popular-international-products/SKILL.md b/skills/popular-international-products/SKILL.md index 63e8c26..25ca6d9 100644 --- a/skills/popular-international-products/SKILL.md +++ b/skills/popular-international-products/SKILL.md @@ -158,6 +158,14 @@ 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. +The column headers, labels and disclaimers below are written in pt-BR because +that is the default. They are a template, not literal strings: when the seller +writes in another language, translate all of them — the headers, row values +such as `sim` / `não` / `ouro`, and the disclaimer — and keep the structure, +the emoji and the `R$` money formatting, which stays the same in every language +because the marketplace trades in reais. When the request is in English, no +Portuguese is left anywhere in the answer. + **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 | diff --git a/skills/product-change-monitor/SKILL.md b/skills/product-change-monitor/SKILL.md index 8609439..a750fb3 100644 --- a/skills/product-change-monitor/SKILL.md +++ b/skills/product-change-monitor/SKILL.md @@ -194,6 +194,14 @@ Respond in the language of the seller's request. Present the result with no commentary about how it was produced. Use plain markdown so it renders cleanly in any client. +The column headers, labels and disclaimers below are written in pt-BR because +that is the default. They are a template, not literal strings: when the seller +writes in another language, translate all of them — the headers, row values +such as `sim` / `não` / `ouro`, and the disclaimer — and keep the structure, +the emoji and the `R$` money formatting, which stays the same in every language +because the marketplace trades in reais. When the request is in English, no +Portuguese is left anywhere in the answer. + Lead with a short line naming the **marketplace** that was monitored. **Change table (Mercado Livre)** — one row per monitored product, with these diff --git a/skills/seller-copilot/SKILL.md b/skills/seller-copilot/SKILL.md index f5b61be..3123020 100644 --- a/skills/seller-copilot/SKILL.md +++ b/skills/seller-copilot/SKILL.md @@ -345,6 +345,14 @@ be read all at once. Files prefixed `shopee-` are Shopee Brasil; the rest are Me **lower means you are ahead**, and that it is relative to the competitor set rather than an absolute grade. +The column headers, labels and disclaimers below are written in pt-BR because +that is the default. They are a template, not literal strings: when the seller +writes in another language, translate all of them — the headers, row values +such as `sim` / `não` / `ouro`, and the disclaimer — and keep the structure, +the emoji and the `R$` money formatting, which stays the same in every language +because the marketplace trades in reais. When the request is in English, no +Portuguese is left anywhere in the answer. + ## Notes and guardrails - **Never fabricate a number.** If the data is not there, say so. diff --git a/skills/top-keywords-in-my-category/SKILL.md b/skills/top-keywords-in-my-category/SKILL.md index 2e1a7df..9016f3b 100644 --- a/skills/top-keywords-in-my-category/SKILL.md +++ b/skills/top-keywords-in-my-category/SKILL.md @@ -71,8 +71,15 @@ rank and its competing-product count. Sort by rank, best position first. ## Output Respond in the language of the seller's request (default pt-BR). The keywords -always render as a markdown table, sorted by position. The headers below are -the pt-BR default and may be rendered in the language of the seller's request: +always render as a markdown table, sorted by position. + +The column headers, labels and disclaimers below are written in pt-BR because +that is the default. They are a template, not literal strings: when the seller +writes in another language, translate all of them — the headers, row values +such as `sim` / `não` / `ouro`, and the disclaimer — and keep the structure, +the emoji and the `R$` money formatting, which stays the same in every language +because the marketplace trades in reais. When the request is in English, no +Portuguese is left anywhere in the answer. | Posição | Palavra-chave | Produtos (oferta) | |--:|---|--:| diff --git a/skills/unbranded-products-in-category/SKILL.md b/skills/unbranded-products-in-category/SKILL.md index 0f29882..165603b 100644 --- a/skills/unbranded-products-in-category/SKILL.md +++ b/skills/unbranded-products-in-category/SKILL.md @@ -149,6 +149,14 @@ 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. +The column headers, labels and disclaimers below are written in pt-BR because +that is the default. They are a template, not literal strings: when the seller +writes in another language, translate all of them — the headers, row values +such as `sim` / `não` / `ouro`, and the disclaimer — and keep the structure, +the emoji and the `R$` money formatting, which stays the same in every language +because the marketplace trades in reais. When the request is in English, no +Portuguese is left anywhere in the answer. + **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 | diff --git a/skills/uncontested-niche-finder/SKILL.md b/skills/uncontested-niche-finder/SKILL.md index 4ffe878..cb07f76 100644 --- a/skills/uncontested-niche-finder/SKILL.md +++ b/skills/uncontested-niche-finder/SKILL.md @@ -209,6 +209,14 @@ Respond in the language of the seller's request. Present the result with no commentary about how it was produced. The product table always renders as markdown so it reads cleanly in any client. +The column headers, labels and disclaimers below are written in pt-BR because +that is the default. They are a template, not literal strings: when the seller +writes in another language, translate all of them — the headers, row values +such as `sim` / `não` / `ouro`, and the disclaimer — and keep the structure, +the emoji and the `R$` money formatting, which stays the same in every language +because the marketplace trades in reais. When the request is in English, no +Portuguese is left anywhere in the answer. + Lead with a short intro line naming the **marketplace** and the category — and on Shopee, the category level you actually worked at. From 1f09092d2d63992e05e7c6b49f4a7e7f2a3b314d Mon Sep 17 00:00:00 2001 From: Nikita Andreev Date: Thu, 10 Sep 2026 10:19:41 +0100 Subject: [PATCH 08/11] Make the remaining two download offers conditional as well An audit of all eighteen skills found two the earlier pass missed. product-change-monitor offers a downloadable spreadsheet of the change table, and seller-overview-tracker offers one twice, neither with a fallback for a client that cannot write files. seller-overview-tracker is the one that matters: like the other trackers, the file is load-bearing there. It tells the seller to save the table and bring it back next period as the baseline, so on a host with no file output the seller is promised the mechanism the whole skill depends on and never gets it. Those trackers already accept a pasted table, so nothing is lost by saying so. Same shape as the other four: offer the download where the client can produce files, and otherwise let the markdown table stand as the deliverable. --- skills/product-change-monitor/SKILL.md | 4 ++-- skills/seller-overview-tracker/SKILL.md | 17 ++++++++++------- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/skills/product-change-monitor/SKILL.md b/skills/product-change-monitor/SKILL.md index a750fb3..7fc9df3 100644 --- a/skills/product-change-monitor/SKILL.md +++ b/skills/product-change-monitor/SKILL.md @@ -274,8 +274,8 @@ Shopee: > 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. +**Download** — where the client can produce files, offer a downloadable +spreadsheet (`.xlsx` plus `.csv`) of the change table. ## Notes & Guardrails diff --git a/skills/seller-overview-tracker/SKILL.md b/skills/seller-overview-tracker/SKILL.md index 2a4a297..8dfd5da 100644 --- a/skills/seller-overview-tracker/SKILL.md +++ b/skills/seller-overview-tracker/SKILL.md @@ -151,12 +151,14 @@ numbers. ### Step 2 — Present today's snapshot and offer it for download 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 +**marketplace** and the date. This table is the deliverable. **Where the client +can produce files, also offer it as a downloadable `.csv` / `.xlsx`** so the +user can save it and bring it back next period as the baseline; where it +cannot, the markdown table stands on its own — never offer a download you +cannot deliver. 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 @@ -186,7 +188,8 @@ because the marketplace trades in reais. When the request is in English, no Portuguese is left anywhere in the answer. **Snapshot (always):** a markdown table `| Campo | Valor atual |` for the rows -below, plus a downloadable `.csv` / `.xlsx` of the same data. +below, plus — where the client can produce files — a downloadable `.csv` / +`.xlsx` of the same data. **Snapshot / comparison rows (Mercado Livre)** — pt-BR labels: From 855d64d542abb5210350179aa155c7cfc5cdde77 Mon Sep 17 00:00:00 2001 From: Nikita Andreev Date: Thu, 10 Sep 2026 10:19:41 +0100 Subject: [PATCH 09/11] Give seller-copilot the whole language rule, not half of it seller-copilot states its conventions as a bullet list rather than the **Language:** heading the other skills use, so the earlier sweep passed over it. Its bullet already named the request rather than the seller, which is the ambiguity that caused the bug, but it lacked the two clauses that made the fix hold elsewhere: that the language is never inferred from the store or its listings, and that an English request leaves no Portuguese in the answer. Extended in its own bullet style rather than pasting the block the other skills carry, since this skill is a conventions document and not a report template. --- skills/seller-copilot/SKILL.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/skills/seller-copilot/SKILL.md b/skills/seller-copilot/SKILL.md index 3123020..ee6affa 100644 --- a/skills/seller-copilot/SKILL.md +++ b/skills/seller-copilot/SKILL.md @@ -95,7 +95,9 @@ MCP setup before it can analyse marketplace data. refund rates, and traffic or conversion funnels. If the question depends on one of these, say so and ask the seller to supply the figure — do not estimate it silently. - **Match the language of the seller's request.** One language per answer, no - mixing. + mixing, and never infer the language from the store or its listings — those are + Brazilian whatever language the seller writes in. When the request is in English, + no Portuguese is left anywhere in the answer. ## How to use this skill From 6fd0dbaa4cba53f8e0556670ce80bd40f0c342df Mon Sep 17 00:00:00 2001 From: Nikita Andreev Date: Thu, 10 Sep 2026 13:14:10 +0100 Subject: [PATCH 10/11] Five fixes the live pass found, each re-tested against the connector MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Running the pack against the real connector surfaced these; every one was re-run afterwards and the fix confirmed. top-keywords-in-my-category: drop the "Produtos (oferta)" column. The cube's own schema marks the only field that could fill it as unreliable and says not to surface it, so the column was always "—". Say no such count exists and forbid a substitute, or the next model invents a volume metric to fill the gap. ml-product-analysis: every analog row carries its links. The rule was already there and was ignored, so it now says what an incomplete row looks like. Also name the sort key in the answer: "demand" here means estimated revenue, and the sales column beside it will not descend with it. uncontested-niche-finder: run the incumbent check over every listing in the sub-category, not the set already narrowed to listings with sales, and state how many listings it covered. A category with a dormant platinum seller was being reported as uncontested, and the count is what makes the claim auditable. high-demand-low-quality-finder: cap the table at twelve rows and say how many matched. At twenty-five rows of fifteen columns the answer ran past the host's output limit and was cut mid-row, taking the disclaimer with it. top-sellers-in-category: label the two store-wide columns as store-wide. The 365-day sales and cancellation figures cover the whole store while every other column is category-scoped, so a reader compared a monthly category figure with a yearly store-wide one and concluded the category had collapsed. --- .../high-demand-low-quality-finder/SKILL.md | 7 ++++- skills/ml-product-analysis/SKILL.md | 11 +++++--- skills/top-keywords-in-my-category/SKILL.md | 26 ++++++++++++------- skills/top-sellers-in-category/SKILL.md | 10 +++++-- skills/uncontested-niche-finder/SKILL.md | 17 +++++++++--- 5 files changed, 51 insertions(+), 20 deletions(-) diff --git a/skills/high-demand-low-quality-finder/SKILL.md b/skills/high-demand-low-quality-finder/SKILL.md index afce930..276086b 100644 --- a/skills/high-demand-low-quality-finder/SKILL.md +++ b/skills/high-demand-low-quality-finder/SKILL.md @@ -159,7 +159,12 @@ needs. Pull a generous set so the filters have room to work. 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. +- Keep the top 12 rows for the table, and say how many matched in total so the + seller knows what was left out. This row carries fifteen columns and a link, + so it is long: at 25 rows the answer runs past what a host will emit and the + table is cut mid-row, losing the disclaimer with it. Twelve of the strongest + opportunities is more than anyone acts on in one sitting. If the seller asks + for more, give the next twelve rather than the whole list at once. ## Output diff --git a/skills/ml-product-analysis/SKILL.md b/skills/ml-product-analysis/SKILL.md index b743894..862c2cb 100644 --- a/skills/ml-product-analysis/SKILL.md +++ b/skills/ml-product-analysis/SKILL.md @@ -239,7 +239,10 @@ Both the keyword and photo paths feed the same analog pipeline: 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 + score. Say in one clause what the order is, because "demand" here means + estimated revenue and the estimated-sales column will not descend with it: a + reader who is not told assumes the table is sorted by the units column they + can see. Drop candidates with no sales. Present a single ranked list — do not 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. @@ -288,8 +291,10 @@ 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. +rating, and a links column holding the Mercado Livre and JoomPulse links. Every +row carries both: a row without them is incomplete, and a table whose subject +card has links while its rows do not is the specific failure to avoid, because +the seller cannot open a single competitor the table names. **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 diff --git a/skills/top-keywords-in-my-category/SKILL.md b/skills/top-keywords-in-my-category/SKILL.md index 9016f3b..2a9402b 100644 --- a/skills/top-keywords-in-my-category/SKILL.md +++ b/skills/top-keywords-in-my-category/SKILL.md @@ -81,16 +81,22 @@ the emoji and the `R$` money formatting, which stays the same in every language because the marketplace trades in reais. When the request is in English, no Portuguese is left anywhere in the answer. -| Posição | Palavra-chave | Produtos (oferta) | -|--:|---|--:| - -- **Posição** — the keyword's rank in the category's search trends. -- **Produtos (oferta)** — the number of active offers (listings) matching that - keyword, i.e. how many products currently compete for it. This is a real - search-trend count, not an estimate. - -Close with a short, optional takeaway (use the top terms in titles and ads; a high -competing-product count means a crowded term, a low one a more open opportunity). +| Posição | Palavra-chave | +|--:|---| + +- **Posição** — the keyword's rank inside the trend group being shown, counted + from 1. Read it from the per-group rank, not from a rank that runs across all + the groups a category has, or the first search term appears to rank sixth. + +There is no count of how many listings compete for a keyword, and no search +volume, traffic, impressions, click-through rate or competition score either. +The source marks the one field that looks like a competing-product count as +unreliable and not to be surfaced. Do not add a column for any of them, do not +leave an empty one in the table, and do not estimate them from anything else. + +Close with a short, optional takeaway — which terms to carry in titles and ads, +and what the shape of the list suggests about demand. Say nothing about how +crowded a term is: nothing in this data measures that. This is **real Mercado Livre search-trend data, not an estimate** — state that once, in place of the estimate disclaimer. diff --git a/skills/top-sellers-in-category/SKILL.md b/skills/top-sellers-in-category/SKILL.md index cb7f1b3..5c36117 100644 --- a/skills/top-sellers-in-category/SKILL.md +++ b/skills/top-sellers-in-category/SKILL.md @@ -115,10 +115,15 @@ Portuguese is left anywhere in the answer. **Leaderboard (always):** a markdown table, plus — where the client can produce files — 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 | +| Vendedor | Vendas méd. (mês) | Receita média (mês) | Vendas 365d (loja toda) | Cancelamento (loja toda) | Sales trend | Marcas | Produtos (todos) | Produtos (com venda) | Envio internacional | Classic | Premium | |---|--:|--:|--:|--:|--:|--:|--:|--:|--:|--:|--:| - The **Vendedor** name links to the seller's JoomPulse page. +- Every other column is the seller's figure **inside this category**, except + **Vendas 365d** and **Cancelamento**, which the source only measures across the + seller's whole store. Those two keep "loja toda" in the header in every language, + translated along with the rest: without it a reader compares a monthly category + figure against a yearly store-wide one and concludes the category collapsed. **Comparison (only when a previous leaderboard is supplied):** the same table plus a **Variação** column, and a **Destaques** block (maiores altas / maiores quedas). @@ -127,7 +132,8 @@ a **Variação** column, and a **Destaques** block (maiores altas / maiores qued > ⚠️ 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. +> 365 dias são dados reais do Mercado Livre e referem-se à loja inteira, não +> apenas a esta categoria. ## Visualization diff --git a/skills/uncontested-niche-finder/SKILL.md b/skills/uncontested-niche-finder/SKILL.md index cb07f76..3420bdf 100644 --- a/skills/uncontested-niche-finder/SKILL.md +++ b/skills/uncontested-niche-finder/SKILL.md @@ -184,6 +184,14 @@ numbers. 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. + + Run this check as its own query over **every** listing in the sub-category, + with no sales filter and no row cap in force. A set you have already narrowed + to listings with sales does not answer the question: an incumbent that sold + nothing last week is still active in the niche, and checking the narrowed set + is how a category with a dormant platinum seller gets reported as uncontested. + For each sub-category you call uncontested, say how many listings the check + covered; if you cannot state that number, you have not run the check. 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 on @@ -268,10 +276,11 @@ 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 on Mercado Livre, or -**no Official store (Shopee Mall) seller at all** on Shopee. You may translate -the column headers into the language of the seller's request. +"uncontested niche" means here: sub-categories deeper than the third level with +**no platinum seller active among their listings at all** on Mercado Livre, or +**no Official store (Shopee Mall) seller at all** on Shopee — counted across +every listing in the sub-category, including those with no sales. You may +translate the column headers into the language of the seller's request. **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 From ff570dca20d5a620008138bc17f07583070d8fe4 Mon Sep 17 00:00:00 2001 From: Nikita Andreev Date: Fri, 11 Sep 2026 13:45:16 +0100 Subject: [PATCH 11/11] Three fixes the live pass found - top-sellers-in-category: every seller ranked is a row of one markdown table -- never a numbered list, never leaders-in-table with the rest in prose, because the user saves this table and pastes it back next period. The Vendedor name is plain text: sellers have no JoomPulse dashboard page, so a URL built from a shopId 404s. Also restores PR #37's language wording, which the local merge of #35 resolved away. - seller-overview-tracker: the monthly sales trend is the change in JoomPulse's estimated sales, not real Mercado Livre data, so it carries the estimate caveat and never appears among the real figures. No seller link, for the same reason as above. - top-brand-position-tracker: a category has no JoomPulse page either, so the table carries no category link. Not pushed, and no PR for the table-shape rule: #35 rewrites the same region of that file, so a PR now would mean resolving the same conflict twice. --- skills/seller-overview-tracker/SKILL.md | 14 +++++--- skills/top-brand-position-tracker/SKILL.md | 3 +- skills/top-sellers-in-category/SKILL.md | 37 ++++++++++++++++------ 3 files changed, 38 insertions(+), 16 deletions(-) diff --git a/skills/seller-overview-tracker/SKILL.md b/skills/seller-overview-tracker/SKILL.md index 8dfd5da..ff1d363 100644 --- a/skills/seller-overview-tracker/SKILL.md +++ b/skills/seller-overview-tracker/SKILL.md @@ -60,8 +60,11 @@ JoomPulse MCP setup before it can monitor a seller. - **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. - - **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 Mercado Livre**, by contrast, the rolling 60-day and 365-day sales counts + and the cancellation rate are real Mercado Livre data. **The monthly sales trend + is not.** It is the month-over-month change in JoomPulse's estimated sales, so it + carries the estimate caveat like every other estimated figure — never list it + among the real ones. - **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. @@ -206,7 +209,8 @@ below, plus — where the client can produce files — a downloadable `.csv` / - Reputação (5 verde, a melhor … 1 vermelho, a pior) - Ticket médio / preço médio - Localização (cidade, estado, país) -- Link JoomPulse do vendedor +- Sem link -- **sellers have no JoomPulse dashboard page**, so never build one + from a shopId **Snapshot / comparison rows (Shopee)** — same shape, with the marketplace's own fields: @@ -231,8 +235,8 @@ fields: 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 +- Link da loja na Shopee — **there is no JoomPulse dashboard link for Shopee** + either, 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 diff --git a/skills/top-brand-position-tracker/SKILL.md b/skills/top-brand-position-tracker/SKILL.md index 533411c..e56357d 100644 --- a/skills/top-brand-position-tracker/SKILL.md +++ b/skills/top-brand-position-tracker/SKILL.md @@ -165,7 +165,8 @@ In the `Variação` cell (comparison only), mark each brand: The change column header is the **word `Variação`** — never a bare delta symbol. -Below the table, include the category's **JoomPulse link**. On a comparison, state +A category has no JoomPulse page, so the table carries no category link -- never +build one from a categoryId. On a comparison, state the period being compared (for example *"Comparado com a tabela de 12/06"*). On a standalone ranking, invite the user to save the table and send it back next period to see how positions moved. diff --git a/skills/top-sellers-in-category/SKILL.md b/skills/top-sellers-in-category/SKILL.md index d87e7ab..a5aca1b 100644 --- a/skills/top-sellers-in-category/SKILL.md +++ b/skills/top-sellers-in-category/SKILL.md @@ -5,7 +5,7 @@ description: > revenue via JoomPulse, and returns a downloadable leaderboard — per seller: estimated 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. + 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 @@ -58,7 +58,11 @@ JoomPulse MCP setup before it can rank a category's sellers. 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. +- **Language:** write in the language of the message you are answering, and + default to pt-BR only when that is unclear. Never infer the language from the + store, its listings or the marketplace — those are Brazilian whatever + language the seller writes in, so a seller who asks in English gets the whole + report in English. - **The baseline is user-supplied.** Never claim a movement without a previous leaderboard to compare against, and never infer or fabricate one from memory. @@ -133,7 +137,15 @@ leaderboard. The change column header is a word ("Variação"), never a bare "Δ ## Output -Respond in the seller's language (default pt-BR). +Respond in the language of the seller's request (default pt-BR). + +The column headers, labels and disclaimers below are written in pt-BR because +that is the default. They are a template, not literal strings: when the seller +writes in another language, translate all of them — the headers, row values +such as `sim` / `não` / `ouro`, and the disclaimer — and keep the structure, +the emoji and the `R$` money formatting, which stays the same in every language +because the marketplace trades in reais. When the request is in English, no +Portuguese is left anywhere in the answer. **Leaderboard (always):** a markdown table, plus — where the client can produce files — a downloadable `.csv` / `.xlsx`: @@ -141,8 +153,18 @@ files — a downloadable `.csv` / `.xlsx`: | Vendedor | Medalha | Vendas méd. (mês) | Receita média (mês) | Vendas 365d (loja toda) | Cancelamento (loja toda) | Crescimento mensal (loja toda) | Marcas | Produtos (todos) | Produtos (com venda) | Envio internacional (loja toda) | Clássico (loja toda) | Premium (loja toda) | |---|:--|--:|--:|--:|--:|--:|--:|--:|--:|--:|--:|--:| -- 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. +- **Every seller you rank is a row of that table.** If the surface is too narrow, + drop columns from the right — listing types first, then international shipping, + then brands — and say which you 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.** +- **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. 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 @@ -159,11 +181,6 @@ files — a downloadable `.csv` / `.xlsx`: 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).