diff --git a/skills/category-monitor/SKILL.md b/skills/category-monitor/SKILL.md index 359d8c2..dedc57d 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. @@ -158,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 @@ -180,11 +185,20 @@ 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. +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. - **Mercado Livre** rows: **Vendas (estimadas), Produtos, Produtos de catálogo, Vendedores, Distribuição de medalhas, Monopolização**. diff --git a/skills/category-opportunity-index/SKILL.md b/skills/category-opportunity-index/SKILL.md index 9ea9469..a28cda9 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 @@ -173,13 +177,22 @@ 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 - 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,17 @@ 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 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: @@ -236,6 +257,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 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..0630205 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,18 @@ 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). + +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):** diff --git a/skills/growing-leaf-category-tracker/SKILL.md b/skills/growing-leaf-category-tracker/SKILL.md index 7ff9bb6..84dfe0b 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. @@ -134,8 +138,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,41 +150,121 @@ 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 -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 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 | -|---|--:|--:|--:|--:| - -- 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 +329,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. diff --git a/skills/high-demand-low-quality-finder/SKILL.md b/skills/high-demand-low-quality-finder/SKILL.md index a5e72f9..276086b 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. @@ -155,13 +159,26 @@ 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 -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. + +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/ml-product-analysis/SKILL.md b/skills/ml-product-analysis/SKILL.md index 8fd5187..862c2cb 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 @@ -236,14 +239,25 @@ 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. ## 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: + +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. @@ -277,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 @@ -287,11 +303,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.** @@ -315,10 +332,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/my-product-vs-catalog/SKILL.md b/skills/my-product-vs-catalog/SKILL.md index c4a8691..9bd5328 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,16 @@ 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 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 b1ddfaa..bb8a81f 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,17 @@ 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, 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 @@ -205,8 +218,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 +299,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..25ca6d9 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,18 @@ 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. + +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:** diff --git a/skills/product-change-monitor/SKILL.md b/skills/product-change-monitor/SKILL.md index 8dc023d..7fc9df3 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,17 @@ 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. + +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. @@ -231,13 +244,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.** @@ -260,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/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..ee6affa 100644 --- a/skills/seller-copilot/SKILL.md +++ b/skills/seller-copilot/SKILL.md @@ -94,7 +94,10 @@ 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, 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 @@ -323,8 +326,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 @@ -343,6 +347,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/seller-overview-tracker/SKILL.md b/skills/seller-overview-tracker/SKILL.md index e111d0f..ff1d363 100644 --- a/skills/seller-overview-tracker/SKILL.md +++ b/skills/seller-overview-tracker/SKILL.md @@ -60,16 +60,22 @@ 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. - **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**. @@ -148,12 +154,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 @@ -170,11 +178,21 @@ 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 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. +below, plus — where the client can produce files — a downloadable `.csv` / +`.xlsx` of the same data. **Snapshot / comparison rows (Mercado Livre)** — pt-BR labels: @@ -191,7 +209,8 @@ below, plus a downloadable `.csv` / `.xlsx` of the same data. - 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: @@ -216,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 d2e255f..e56357d 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. @@ -105,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 @@ -129,8 +133,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 @@ -160,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. @@ -214,8 +220,16 @@ 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, 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-keywords-in-my-category/SKILL.md b/skills/top-keywords-in-my-category/SKILL.md index 2777f02..2a9402b 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,20 +70,33 @@ 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: - -| 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). +Respond in the language of the seller's request (default pt-BR). The keywords +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 | +|--:|---| + +- **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 fd2a401..a5aca1b 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. 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,10 +54,15 @@ 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. +- **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. @@ -73,11 +79,46 @@ 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). -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. +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 and the seller copies it back instead — 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 @@ -96,14 +137,50 @@ leaderboard. The change column header is a word ("Variação"), never a bare "Δ ## Output -Respond in the seller's language (default pt-BR). - -**Leaderboard (always):** a markdown table, plus a downloadable `.csv` / `.xlsx`: - -| Vendedor | Vendas méd. (mês) | Receita média (mês) | Vendas 365d | Cancel rate | Sales trend | Marcas | Produtos (todos) | Produtos (com venda) | Envio internacional | Classic | Premium | -|---|--:|--:|--:|--:|--:|--:|--:|--:|--:|--:|--:| - -- The **Vendedor** name links to the seller's JoomPulse page. +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`: + +| 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) | +|---|:--|--:|--:|--:|--:|--:|--:|--:|--:|--:|--:|--:| + +- **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 + 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. **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 +225,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 +249,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. diff --git a/skills/unbranded-products-in-category/SKILL.md b/skills/unbranded-products-in-category/SKILL.md index 4449b4b..165603b 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,18 @@ 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. + +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):** diff --git a/skills/uncontested-niche-finder/SKILL.md b/skills/uncontested-niche-finder/SKILL.md index 8dedc7f..3420bdf 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 @@ -180,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 @@ -201,9 +213,17 @@ 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. + +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. @@ -256,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 seller's language. +"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