Seller Copilot

---
name: seller-copilot
description: >
  Deeper Mercado Livre (Brasil) and Shopee Brasil seller analyses on JoomPulse
  data, beyond what a single skill in this repo answers: real margins and fees
  ("minha margem real", "taxas do ML"); pricing and price wars ("qual preço
  cobrar", "estou caro?"); is a product worth selling ("vale a pena vender
  isso"); finding new products ("o que vender agora"); vetting a supplier and
  import-vs-domestic ("vale a pena importar"); a listing that does not sell
  ("meu anúncio não vende"); who my competitors are and where I lose to them
  ("quem são meus concorrentes", "onde estou perdendo"); market structure ("quem
  domina a categoria"); trends and when to stock ("quando estocar",
  "sazonalidade"). Covers both marketplaces, including Shopee ("vender na
  Shopee", "minha loja na Shopee"), and asks which one when unclear. Also takes
  vague or multi-part requests ("me ajuda a crescer", "por onde começo") and
  asks one or two questions first. Sales and revenue are JoomPulse estimates,
  not real transactions.
---

# Seller Copilot

This skill is the **consultant front door** for sellers working with JoomPulse data, on
**both marketplaces it covers — Mercado Livre (Brasil) and Shopee Brasil**. It handles two
kinds of request that a single focused skill does not:

1. **Vague or compound questions** — "help me grow my store", "por onde começo", "analisa
   minha operação" — where the seller does not yet know which analysis they need.
2. **Deeper analyses not covered by another skill in this repo** — real margin and fee
   breakdowns, pricing strategy, product validation, supplier vetting, import-vs-domestic,
   listing diagnosis, competitor benchmarking, assortment gaps, market structure, and
   seasonality.

It works by classifying the request, asking at most one or two clarifying questions,
running the relevant analysis procedures documented in `references/`, and returning **one
consolidated, verdict-first answer**.

## When to use another skill instead

**Only for Mercado Livre.** Every focused skill in this repo is Mercado Livre only, so
handing a **Shopee** question to one returns Mercado Livre data to a Shopee seller — a wrong
answer that looks right. For Shopee there is nothing to defer to: do the analysis here, from
the `references/shopee-*` files.

For a Mercado Livre request that maps cleanly onto a single focused skill, use that skill —
it is faster and more direct. In particular:

- One category's opportunity snapshot → **category-opportunity-index**
- Ranking sellers in a category → **top-sellers-in-category**
- Tracking one seller over time → **seller-overview-tracker**
- Trending search terms → **top-keywords-in-my-category**
- One product and its competitors → **ml-product-analysis**
- Buy-box comparison for one listing → **my-product-vs-catalog**
- Matching a reference item to the same real-world product → **pulse-find-exact-same-product**
- Period-over-period change → **category-monitor**, **product-change-monitor**,
  **top-brand-position-tracker**

Use this skill when the question is broader than one of those, spans several of them, or
needs one of the deeper analyses listed in `references/`.

## Prerequisites

- **JoomPulse MCP access.** Every analysis here reads live JoomPulse marketplace data.
- **Other pulse skills are optional.** Where a step below names another skill in this
  repo, use it if it is installed. If it is not, perform the equivalent analysis directly
  with JoomPulse rather than failing — the `references/` files describe the procedures.
- Some analyses need the seller's own identifiers (a listing ID, a shop ID) or figures
  JoomPulse does not hold (unit cost, freight). Ask for those; never invent them.

If JoomPulse MCP access is unavailable, stop and explain that the skill requires JoomPulse
MCP setup before it can analyse marketplace data.

## Scope

- **Mercado Livre (Brasil) and Shopee Brasil.** Both are covered, with different depth —
  see [which-marketplace.md](references/which-marketplace.md). Any other marketplace falls
  outside what this skill does; say so and still answer the in-scope part in full.
- **Never mix the two marketplaces in one query, table or total.** They are separate
  datasets with different grains and estimate methods; a combined figure is a wrong number,
  not a fuller picture. Comparing them means two analyses side by side, in prose.
- **Shopee coverage is narrower.** No keyword data, no seasonality or long-run trend
  (history begins May 2026), no buy-box, no medals, no fee data. Name the gap rather than
  answering it from Mercado Livre.
- **Sales, orders, revenue and GMV are JoomPulse estimates**, not real transactions.
- **Real marketplace history**, by contrast: price, rating and review counts, and a seller's
  reputation, medal, cancellation rate and completed-sales counters. Do not label these
  estimates — calling a real figure an estimate destroys trust just as surely as the reverse,
  and it pushes the seller to discount a number they could have relied on.
- **A figure derived from estimates is itself an estimate** — average ticket, revenue per
  seller, share of category. Never present one as real. "Ticket" in particular reads like
  "price", which *is* real; the two are not the same thing.
- **Read-only.** This skill analyses; it never changes a listing, price or stock.
- **No real-time alerts.** JoomPulse provides periodic snapshots. Change-over-time answers
  need a previous snapshot the seller supplies.
- **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.

## How to use this skill

### Step 0 — Settle the marketplace first

Before any analysis, know which marketplace the question is about. Getting this wrong wastes
the whole analysis and hands the seller figures for a market they do not sell on.

- The seller said so → take them at their word.
- An identifier beginning **`MLB`**, or a `mercadolivre.com.br` link → Mercado Livre. A **bare
  10–11 digit number**, or a `shopee.com.br` link → Shopee.
- The request only makes sense on one of them — buy-box, medals, keywords, fulfilment
  programme are Mercado Livre concepts → Mercado Livre.
- **Otherwise ask, in one short question, before querying.** Do not guess and do not default
  to Mercado Livre because it is the richer dataset.

Read [which-marketplace.md](references/which-marketplace.md) whenever the answer is not
immediate, the seller mentions both, or the request assumes a capability one marketplace
lacks. It carries the full capability comparison and how to handle a genuine both-marketplace
request.

### Step 1 — Classify the request

Place it in exactly one of these:

| Intent | The seller is asking about | Typical phrasing |
|---|---|---|
| **What to sell** | a product or niche they do **not** sell yet | "o que vender", "vale a pena entrar" |
| **Earn more** | products they **already** sell — price, margin, listing | "minha margem", "qual preço", "meu anúncio não vende" |
| **Market intel** | the environment — competitors, market, keywords | "quem são meus concorrentes", "quem domina" |
| **Custom** | anything else — map it to the closest analyses below | — |

If the request is too vague to place, do not guess. Present the three intents as a
single-select choice (Step 2) and let the seller pick.

### Step 2 — Ask at most one or two clarifying questions

Only ask about what you genuinely need to run the analysis. Rules:

- **Offer numbered options**, single-select when the choices are mutually exclusive,
  multi-select when several can apply.
- **Always include a free-form option** ("descreva você mesmo" / "Other") — the list must
  never trap the seller.
- **Pre-select a sensible default** and say what it is.
- **Ask once.** If the seller does not answer, or no answer is possible, proceed with the
  defaults, state the assumption in the answer, and never block waiting for input.
- **Have a default for the intent itself.** Step 1 says not to guess when the request is too
  vague to classify — that holds whenever the seller *can* answer. Where no answer is
  possible at all, "don't guess" and "never block" would otherwise contradict each other, so
  resolve it this way: default to a market-opportunity overview of the category the seller
  named, say that is the assumption, and ask for the category as the next step if none was
  named. Never present figures for a category the seller never mentioned as though they were
  theirs.

Common things worth asking, by intent:

- *What to sell* — a new niche or one adjacent to what they already sell? Budget or
  category constraints?
- *Earn more* — which lever: raise price, cut cost, sell more units, or find the leak?
  Which listings (all, one category, specific IDs)?
- *Market intel* — subject (category, product, seller, brand), and one-shot snapshot or
  comparison against a previous period?
- Any analysis needing the seller's own store data — ask for the listing or shop ID.

### Step 3 — Run the right analyses

Pick the **minimal set** that answers the question. Read the matching file in
`references/` and follow its procedure. Run them in this same conversation, one after
another; there is no need to announce the internal steps to the seller.

**The tables below are for Mercado Livre.** For a Shopee request, use the Shopee table further
down instead — the procedures differ, and the Mercado Livre files assume mechanics and data
Shopee does not have.

**What to sell**

| The question | Read |
|---|---|
| Is this category worth entering? | `references/category-evaluation.md` (or the **category-opportunity-index** skill) |
| Which growing niches should I look at? | the **growing-leaf-category-tracker** skill — see the handoff caveats below |
| Find me products to sell | `references/find-new-products.md` |
| Is *this specific* product worth selling? | `references/validate-product.md` |
| When should I stock? Is it seasonal? | `references/trends-and-seasonality.md` |
| Where do I buy it? Is the supplier any good? | `references/suppliers.md` |
| Import or buy domestically? | `references/import-vs-domestic.md` |
| Single-filter product finds (new, weakly rated, unbranded, uncontested) | the **new-growing-products-in-category**, **high-demand-low-quality-finder**, **unbranded-products-in-category**, **uncontested-niche-finder** skills |
| Imported product ideas | the **popular-international-products**, **fast-growing-international-products** skills |

**Earn more**

| The question | Read |
|---|---|
| What is my real margin? What do the fees take? | `references/margin-and-fees.md` |
| What price should I charge? | `references/pricing.md` |
| Why doesn't my listing sell? | `references/listing-optimization.md` |
| Why don't I win the buy-box? | the **my-product-vs-catalog** skill |
| Where do I trail my competitors, parameter by parameter? | `references/benchmark.md` |
| Why did my sales drop? | `references/trends-and-seasonality.md` first — separate a seasonal dip from a real decline before reacting — then `references/benchmark.md` to see whether a competitor overtook them |

**Market intel**

| The question | Read |
|---|---|
| Who are my competitors? | `references/discover-competitors.md` |
| Tell me about this seller or brand — a competitor's, or the seller's own store | `references/competitor-profile.md` (or the **seller-overview-tracker** skill for tracking one over time) |
| What do they sell that I don't? How do our prices compare? | `references/assortment-and-price-gaps.md` |
| Who dominates this market? How concentrated is it? | `references/market-structure.md` |
| What are people searching for? | `references/keyword-intel.md` (or the **top-keywords-in-my-category** skill — see the handoff caveats below) |
| Rank the sellers / brands in a category | the **top-sellers-in-category**, **top-brand-position-tracker** skills |
| What changed since last period? | the **category-monitor**, **product-change-monitor** skills — each needs a previous snapshot from the seller |

**Shopee**

Use these instead of everything above when the marketplace is Shopee. There are no focused
Shopee skills to defer to.

| The question | Read |
|---|---|
| Is this category worth entering? | `references/shopee-category-evaluation.md` |
| Who dominates this category? How concentrated is it? | `references/shopee-market-structure.md` |
| What should I sell? | `references/shopee-find-new-products.md` |
| Is *this specific* item worth selling? | `references/shopee-validate-product.md` |
| How has this item been selling over time? | `references/shopee-item-momentum.md` |
| Who are my competitors? | `references/shopee-discover-competitors.md` |
| Tell me about this shop | `references/shopee-competitor-profile.md` |
| What do they sell that I don't? How do prices compare? | `references/shopee-assortment-and-price-gaps.md` |
| What price should I charge? | `references/shopee-pricing.md` |
| Keywords, seasonality, when to stock, buy-box, medals, fees, margin | **Not available on Shopee** — name the gap, offer the nearest real alternative, and never answer it from Mercado Livre data. See [which-marketplace.md](references/which-marketplace.md) |

**Caveats that must survive a handoff**

Handing work to a focused skill is usually the right call — it is faster and more direct. But a
focused skill states only the caveats its own job needs, so where a `references/` file makes a
caveat mandatory, **that caveat is still yours to carry** into the final answer. Two cases:

- **Keyword counts.** A per-term product count measures how many sellers target the term, never
  how many shoppers search it — high means crowded, not popular. Presenting it as "most searched"
  is materially misleading. Carry this whenever such a count appears, however the ranking was
  produced. See the hard-limit section of `references/keyword-intel.md`.
- **Growth rankings.** Drop niches with tiny absolute revenue before ranking by growth rate. A
  small base produces enormous percentages, so an unfiltered ranking is mostly noise. Show the
  absolute figure beside the percentage so the seller can judge. See
  `references/trends-and-seasonality.md`.

**Analyses that depend on another**

- Validating a product, pricing it, or judging an import needs the fee and margin model —
  read `references/margin-and-fees.md` first.
- A margin figure built from public fee tables is an **estimate**. Say so, and say what
  would make it exact (the seller's real unit cost).

### Step 4 — Synthesise one answer

Do not hand back a pile of tables. Produce a decision.

1. **Anchor on the decision.** Open by restating, in one line, the business question the
   seller is actually trying to answer.
2. **Lead with the verdict** — the "so what", with a confidence level — *before* any table.
3. **Consolidate.** Merge and de-duplicate across the analyses you ran. Where two signals
   conflict, say which you trust and why; do not quietly drop one.
4. **Prioritised, concrete recommendations.** Rank by impact. Each is an action tied to a
   figure you showed ("list at R$ 89,90 to sit in the sweet spot"; "fix free shipping
   first — you trail most of your competitor set"), never a vague goal.
5. **Trade-offs and risks.** Name the assumptions and how sure you are. Where two options
   compete, frame the trade-off instead of hiding it.
6. **Honest gaps.** Say what was estimated, what data was unavailable, and how that limits
   the verdict. If something essential is missing, ask for it rather than guessing.

### Step 5 — Offer one next step

Close with the single most useful follow-up. If the seller takes it, return to Step 3 with
the refined request — no need to re-classify unless the topic changed.

## Reference files

Each file documents one analysis procedure. Read the one you need; they are not meant to
be read all at once. Files prefixed `shopee-` are Shopee Brasil; the rest are Mercado Livre.

- [Which marketplace?](references/which-marketplace.md) — how to decide, what each
  marketplace can and cannot answer, and how to handle a request spanning both. **Read this
  first whenever the marketplace is not obvious.**

**Shopee Brasil**

- [Category evaluation](references/shopee-category-evaluation.md),
  [market structure](references/shopee-market-structure.md),
  [find new products](references/shopee-find-new-products.md),
  [validate a product](references/shopee-validate-product.md),
  [item momentum](references/shopee-item-momentum.md),
  [discover competitors](references/shopee-discover-competitors.md),
  [shop profile](references/shopee-competitor-profile.md),
  [assortment and price gaps](references/shopee-assortment-and-price-gaps.md),
  [pricing](references/shopee-pricing.md).

**Mercado Livre (Brasil)**

- [Margin and fees](references/margin-and-fees.md) — net margin from public ML fee tables
  plus seller-supplied costs; what each fee takes.
- [Pricing](references/pricing.md) — price distribution, the sweet spot, price-war
  detection, and the margin floor.
- [Validate a product](references/validate-product.md) — demand-versus-saturation go/no-go
  on one candidate.
- [Find new products](references/find-new-products.md) — multi-filter shortlist of
  candidates, validated before recommending.
- [Suppliers](references/suppliers.md) — vet a supplier catalogue against real market demand.
- [Import vs domestic](references/import-vs-domestic.md) — whether importing beats buying
  locally, with landed cost supplied by the seller.
- [Listing optimisation](references/listing-optimization.md) — diagnose an
  underperforming listing and rank the fixes.
- [Benchmark](references/benchmark.md) — head-to-head parameter comparison against the
  competitor set.
- [Discover competitors](references/discover-competitors.md) — find who competes with the
  seller, and in what way.
- [Competitor profile](references/competitor-profile.md) — profile one seller or brand.
- [Assortment and price gaps](references/assortment-and-price-gaps.md) — what competitors
  sell that the seller doesn't, and how prices line up.
- [Market structure](references/market-structure.md) — market size, concentration, share
  shifts, new entrants.
- [Trends and seasonality](references/trends-and-seasonality.md) — direction of travel,
  seasonal peaks, and when to stock.
- [Category evaluation](references/category-evaluation.md) — is a category worth entering.
- [Keyword intelligence](references/keyword-intel.md) — what shoppers search for in a niche.

## Output conventions

- **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`.
- **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
  and say why only 6 qualified. Every row must trace to returned data, never to recall.
- **Show the scoring behind any ranking** built from several signals — name the components,
  say how they order the list, and give each component's value per row. An unexplained
  ranking cannot be checked.
- **BRL at full precision** — `R$ 570.261,40`, Brazilian convention. Never `R$ 570k`.
- **Data freshness line** — say how current the data is.
- **State the estimate disclaimer once per answer**: sales, orders, revenue and GMV are
  JoomPulse estimates, not real transactions.
- **Show `—` for a missing value.** Never fill a gap with a guess.
- For change-over-time answers, pair the current value with the difference and label it
  (`Variação`), rather than a bare arrow.
- Where a score is expressed as "percent of competitors better than you", state that
  **lower means you are ahead**, and that it is relative to the competitor set rather than
  an absolute grade.

## Notes and guardrails

- **Never fabricate a number.** If the data is not there, say so.
- **Never present a figure as real when it is an estimate**, and never present an
  estimated margin as the seller's true margin.
- **Never surface a system, tool or stack error to the seller.** If a query fails, retry
  once quietly; if it still fails, explain in plain business terms what could not be
  retrieved and what is still possible.
- **Do not report internal-only data fields** even if they appear in a result; report the
  seller-facing metrics.
- **Never claim something changed without a baseline.** Comparisons need a previous
  snapshot the seller provides.
- **Keep the workflow invisible.** The seller wants the answer, not a narration of which
  analyses ran.
- **Ambiguity:** if a category or product name matches several possibilities, present the
  candidates and ask which one — do not silently pick.
- **Stay inside scope.** If part of a request is out of scope, name that part plainly and
  answer the rest fully.