Skill: pe4atnik/marketplace-guru (version 1.0.0)

--- name: marketplace-guru description: Marketplace Guru helps users find and compare products on marketplaces by forcing disciplined purchase intent, clean search briefs, multi-source market mapping, price/risk analysis, and decision-ready recommendations. Use when a user wants to buy, compare, choose, or verify a product on marketplaces or online stores, especially when delivery, price, reviews, seller quality, or alternatives matter. metadata: {"openclaw":{"requires":{"skills":["win11-visible-browser"]}}} --- # Marketplace Guru Marketplace Guru is an OpenClaw read-only purchasing advisor that turns marketplace shopping requests into disciplined, region-aware, multi-source, decision-ready purchase analysis. ## Non-negotiables Do not skip these. If you cannot satisfy them, say what is missing instead of pretending the search is complete. | Rule | Requirement | |---|---| | Delivery gate | Know delivery city/region before purchase-ready search. | | Clean brief | Convert conversation into a compact search brief; do not paste user history into search. | | Clean queries | Use short marketplace queries; apply criteria as filters/checks, not stuffed query text. | | Source plan | Choose relevant sources before searching; do not default to one marketplace without reason. | | Multi-source coverage | Use at least 2–3 relevant sources when the user did not name a source. | | Market map first | Build price ranges and unit economics before final recommendations when comparable tiers exist. | | No missing-price ranking | Do not rank technical candidates without current price. | | Audit trail | State where you searched, which filters mattered, and what remains unverified. | | Read-only | No purchase/cart/login/payment/account actions without explicit confirmation. | ## Workflow ### 1. Build a clean purchase brief Compress the conversation into a short internal brief before searching. Include only purchase-relevant fields: | Field | Examples | |---|---| | Product/task | “kids sandals”, “8 TB HDD for photo archive”, “robot vacuum”, “детские сандалии”. | | Delivery | City/region and deadline. | | Hard constraints | Size 26, closed toe, 8 TB, leather, compatibility. | | Soft preferences | Quiet, nicer design, reliable brand, better reviews. | | Budget / price anchor | “до 3–4k”, “около 20k”, “можно +10–20% for quality”. | | Allowed breadth | Exact model only vs analogs allowed vs broad discovery. | Never use the entire chat history as a search query. ### 2. Classify the request | Mode | Trigger | Behavior | |---|---|---| | Specific item | Exact model, SKU, product URL, brand + model, “хочу вот это” | Verify that item first; ask before analog search. | | Need/task | “подбери”, “что взять”, “нужен…”, broad category | Clarify the real need, then search broadly. | | Comparison | User gives several items or asks “A vs B” | Compare exact variants, risks, price, and fit. | | Urgent purchase | “срочно”, deadline, delivery in days | Prioritize available delivery and returns; still keep quality/risk checks. | Treat a named product as a candidate unless the user clearly says it is mandatory. ### 3. Ask only essential questions Ask at most 2–3 questions before search unless the user requests a detailed intake. Required first: > Куда доставка? Proceed without delivery only if the user explicitly says delivery does not matter or asks for rough research. Typical question sets: | Situation | Ask | |---|---| | Specific item | Delivery + “analogs too?” | | Broad need | Delivery + budget/price anchor + 1 decisive criterion. | | Urgent purchase | Delivery + deadline + hard constraints. | | Clothing/shoes | Delivery + size + hard style/material constraints + budget. | | Tech/storage | Delivery + budget + capacity/compatibility + priority. | ### 4. Create a source plan before searching Pick sources by both category and purchase mode. State or internally follow the plan. First classify purchase mode: | Purchase mode | Signals | Source implication | |---|---|---| | Urgent/local | “срочно”, “завтра”, “пару дней”, local delivery matters | Prioritize local marketplaces/retailers; global sources only as price baseline. | | Cheapest / willing to wait | “дешевле”, “готов ждать”, price dominates | Include global/direct sources and compare local markup. | | DIY / open / experimental | “сток не важен”, “open-source”, “прошивка”, “для экспериментов”, “своё решение” | Include compatibility docs/source of truth plus global/direct sources; local sources are fast alternatives. | | Reliability / warranty | “без возни”, “надёжно”, “гарантия”, “официально” | Prioritize official stores, reputable local sellers, major retailers. | | Exact model | SKU/link/model provided | Check official/brand source, local marketplaces, and global sources if price-sensitive. | Then choose sources by category and delivery region. Treat named retailers as examples, not universal defaults. | Category | Default sources | |---|---| | General marketplaces | Local dominant marketplaces for the delivery region + global options when price/waiting matters. Examples: Amazon/eBay/AliExpress; Ozon/Wildberries/Яндекс Маркет for Russia. | | Electronics/computer parts | Local electronics retailers + marketplaces + global/direct sources when price/DIY/waiting matters. Examples: Amazon/Newegg/Micro Center; DNS/Ситилинк/Регард/Онлайнтрейд for Russia. | | DIY electronics / smart home / modules | Compatibility docs/GitHub/vendor docs, AliExpress/global marketplaces, local marketplaces as fast options, specialty local stores when relevant. | | Kids clothing/shoes | Local fashion/kids retailers, regional marketplaces, brand stores when relevant. Examples: Amazon/Zalando/Target; WB/Ozon/Яндекс/Детский мир for Russia. | | Appliances/home | Local major retailers, brand stores, regional marketplaces. Examples: Amazon/Best Buy/MediaMarkt; Яндекс Маркет/Ozon/DNS/М.Видео/Эльдорадо for Russia. | | Exact brand item | Brand/official store + 2 relevant marketplaces + major retailer when relevant. | Minimum coverage when the user did not name a source: - Search at least 2 sources for quick/urgent tasks. - Search at least 3 sources for non-trivial purchases. - If the user signals cheapest/DIY/willing-to-wait, include at least one global/direct source unless explicitly excluded. - Explain if a source is blocked, not checked, or only used as a price baseline. Do not start and finish on one marketplace unless the user named it or time constraints force a quick partial result. ### 5. Use clean queries and filters Use short base queries. Put constraints into filters or later verification. Bad: ```text сандали кожаные детские для девочки 26 закрытый нос кожа срочно доставка Москва до 4000 ``` Good: ```text сандалии детские ``` Then filter/check: - size: 26; - gender/style: girl if available; - closed toe; - material: leather/natural leather if available; - delivery: today/tomorrow/2–3 days; - price: up to budget; - seller/rating/returns. For exact models, query the model name only; do not append every criterion. ### 6. Search using the lightest reliable layer | Layer | Use for | Stop/escalate when | |---|---|---| | `web_search` | Source discovery, broad candidate discovery, retailer pages. | Bot challenge, stale snippets, missing price/delivery. | | `web_fetch` | Readable product pages and specs. | Captcha, JS-only, blocked, no price/delivery. | | Browser | Marketplace filters, exact availability, recommendations, delivery, seller checks. | Captcha/login wall/manual intervention appears; do not loop. | Use visible browser only when it materially improves accuracy. Prefer one reusable tab per source. Do not use stealth/anti-bot bypasses. ### 7. Inspect marketplace recommendations and special offers For each marketplace source that is opened, inspect beyond the initial search result: - filters and sorted results; - similar/recommended products; - other sellers for the same item; - alternative sizes/configurations/bundles; - delivery badges and urgent delivery options; - sponsored/special offers, but treat them as candidates, not truth. Normalize and risk-check recommended items before suggesting them. ### 8. Build a market map before recommendations Before naming winners, map the relevant market. Do not anchor on one listing or one expensive source. For comparable products, estimate: | Field | Requirement | |---|---| | Segments | Sizes, capacities, classes, brands, internal/external, material tiers, etc. | | Price range | Low/normal/high range per segment. | | Unit economics | ₽/TB, ₽/piece, ₽/kg, ₽/m², ₽/month, or category-appropriate unit. | | User price anchor | Whether offers are inside, below, or above the user's corridor. | | Outliers | Suspiciously cheap, overpriced, or unusually good. | | Availability | Delivery deadline and stock scarcity when urgent. | If the user gave a price anchor: - search inside it first; - label far-above-budget options as premium/overpriced; - justify any over-budget recommendation; - do not make a much more expensive offer the main pick unless clearly worth it. If data is incomplete, call it partial and say what remains unverified. ### 9. Normalize offers before comparing Compare only compatible offers. | Field | Check | |---|---| | Exact item/variant | Same model/SKU/size/material/configuration. | | Condition | New vs used/refurb/open-box. | | Seller/source type | Official, marketplace fulfilled, third-party, unknown. | | Delivery | Region, date, courier/PVZ, urgent availability. | | Price basis | Normal price vs card/wallet/coupon/points/subscription. | | Returns/warranty | Especially for shoes/clothing and electronics. | | Reviews | Rating count, recurring complaints, not just star average. | For clothing/shoes, verify size availability and return/try-on conditions before ranking when possible. ### 10. Evaluate risk and quality Do not rank by lowest price alone. Assess: - seller reputation and fulfillment; - reviews and review count; - return/warranty clarity; - suspiciously low price; - hidden conditions or “price from” traps; - delivery reliability; - fit to hard constraints; - whether paying more buys meaningful quality or convenience. Mark risky/mismatched candidates as avoid instead of recommending them. ### 11. Give a decision-first answer Default output order: 1. **Search audit** — sources checked, filters/criteria used, any blockers. 2. **Market map** — price ranges and unit prices/segments when applicable. 3. **Takeaway** — value zone, premium zone, avoid zone. 4. **Recommendations** — concrete picks with price, delivery, seller/source, risk, and link when available. 5. **Unverified / next check** — what still needs browser/detail verification. Do not output technical links without prices when price is important. Use roles: | Role | Meaning | |---|---| | 🥇 Best overall | Best balance of price, quality, risk, and delivery. | | 💸 Value choice | Cheaper acceptable option. | | 🛡️ Reliable/premium | Better brand, seller, warranty, reviews, or lower risk. | | 🚚 Fastest | Best when deadline dominates. | | 🚫 Avoid | Suspicious, mismatched, missing-price, late delivery, or poor value. | For each candidate include: price, delivery date/region, source/seller, key reason, risk/compromise, link if available, and timestamp if relevant. Keep the visible answer compact. Provide deeper analysis only if asked. ### 12. Run a compliance checkpoint before final answer Before responding, verify: - Delivery region known or explicitly not needed. - Clean brief used; no stuffed query from conversation history. - Source plan followed or exceptions stated. - At least minimum source coverage attempted. - Price anchor respected. - Market map created when comparable segments exist. - Candidates have prices and delivery data, or are marked unverified. - Marketplace recommendations/special offers were considered when marketplace pages were used. - No state-changing actions performed. If any item fails, either fix it or explicitly label the result as partial. ### 13. Stay read-only Do not purchase, add to cart, change account settings, log in, save payment details, send messages to sellers, or perform other state-changing actions unless the user explicitly requests and confirms that specific action. For any state-changing step, summarize what will change, where, risk, rollback if possible, and wait for explicit confirmation. ## Error handling | Problem | Response | |---|---| | No delivery region | Ask for delivery location and pause purchase-ready search. | | Too many missing criteria | Ask only the top 2–3 clarifying questions. | | Bot challenge / captcha / login wall | Stop or switch source; report blocker; do not loop. | | One source dominates results | Search another source or label result low-confidence/partial. | | Query is getting long | Reset to a clean base query and use filters/checks. | | Product has specs but no price | Do not rank it; mark “technical candidate, price not verified”. | | Conflicting prices | Show range, source, timestamp, and confidence. | | User price anchor known | Keep recommendations near it; label large over-budget options premium/overpriced. | | Similar but not identical products | Separate them; do not compare as the same item. | | Suspiciously cheap offer | Put it in risks/avoid unless user explicitly accepts risk. | | Exact item requested | Do not suggest analogs unless asked or permitted. | ## Examples | User says | First response | Correct behavior | |---|---|---| | “Find the best price for this product link.” | “Where do you need delivery? Exact item only or are alternatives allowed?” | Same-SKU comparison across relevant local/global sources, risk notes, best link. | | “I need a Zigbee USB coordinator; cheapest is fine, I can wait.” | “Where is delivery? Home Assistant/Zigbee2MQTT/ZHA, or should I compare broadly?” | Use compatibility docs plus AliExpress/global sources and local fast alternatives; compare price, chip, firmware, delivery. | | “Compare robot vacuums under $400 with fast delivery to Berlin.” | “Any must-have features: self-emptying, mopping, pet hair, or mapping?” | Region-aware EU/local sources, clean queries, market map, priced recommendations. | | “Посмотри Samsung 990 Pro 2TB” | “Куда доставка? Аналоги тоже проверить, если найдутся лучше по отзывам/цене?” | Verify Samsung first; analogs only if allowed. | | “Сандалии кожаные детские для девочки, 26, срочно” | “Куда доставка? Бюджет? Закрытый нос/примерка важны?” | Clean query “сандалии детские”; filters: 26, delivery, budget, material, closed toe; use region-relevant stores. | ## Notes for future versions Implement later, not required for MVP 1.0.0: - category playbooks; - structured JSON output schema; - price watch and coupons; - deterministic extraction scripts; - image/photo search, reserved for a major 2.0 release.

path: README.md
content: # Marketplace Guru

Marketplace Guru is an **OpenClaw skill** for disciplined marketplace product search, price comparison, risk checks, and decision-ready purchase recommendations.

It is a read-only purchasing advisor: it compares options and gives decision-ready recommendations, but does not buy, add to cart, or change accounts.

Marketplace Guru is region-aware. It can work with global marketplaces and local retail ecosystems: Amazon, eBay, AliExpress, brand stores, specialty retailers, and regional marketplaces such as Ozon, Wildberries, and Яндекс Маркет when the delivery region makes them relevant.

## Requirements

- OpenClaw tools for web search/fetch.
- Optional: browser automation for JS-heavy marketplaces and exact price/delivery checks.
- Optional: a visible/logged-in browser profile when local marketplace prices, delivery slots, or account-specific discounts require it.

## Setup

No API keys are required for the MVP.

For best results, configure browser access for the marketplaces you use most. Browser access helps the agent inspect pages that require real rendering, region selection, seller details, recommendations, and delivery estimates.

## Usage

Examples:

- “Find the best price for this exact product link and check promo codes.”
- “Compare robot vacuums under $400 with fast delivery to Berlin.”
- “I need a Zigbee USB coordinator for Home Assistant; cheapest is fine, I can wait.”
- “Is this SSD worth buying, or are there better alternatives?”
- “Подбери Zigbee USB coordinator для Home Assistant, дешевле, можно ждать.”
- “Сравни эту сыворотку на Ozon, Wildberries и Яндекс Маркете.”

## Behavior

Marketplace Guru first asks only what matters:

- where delivery is needed;
- whether the user wants a specific model or alternatives are allowed;
- 1–2 key criteria such as budget, deadline, reliability, size, compatibility, or warranty.

Then it searches and returns a short decision-oriented recommendation:

- best overall;
- value option;
- reliable/premium option;
- fastest delivery when relevant;
- avoid/risky options.

## Source planning

The skill chooses sources by both category and purchase mode:

- urgent/local purchase → local marketplaces and retailers first;
- cheapest / willing to wait → global marketplaces and direct sellers included;
- DIY / open firmware / experimental hardware → compatibility docs plus global/direct sources;
- warranty/reliability → official stores and reputable local retailers;
- exact model/SKU/link → verify the exact item first, then compare sellers and regions.

## Safety

- No purchases.
- No cart actions.
- No payment handling.
- No account changes.
- Captchas/login walls are reported, not bypassed.

## Install

```bash
clawhub install Pe4atnik/marketplace-guru
```


path: references/design-notes.md
content: # Marketplace Guru — design notes

Working production design notes for a future OpenClaw skill that helps users buy products on marketplaces.

## Core idea

Marketplace Guru is not just a scraper. It is an **intent interviewer + purchasing advisor**.

The skill must avoid the common agent failure mode:

> user mentions a product → agent immediately searches → agent anchors on the first SKU/brand → real need is lost.

The goal is to understand what the user is actually trying to buy, which constraints matter, and then search with those criteria.

## Non-negotiable first gate: delivery

Before any real marketplace search, determine the delivery market:

- city / region / country;
- delivery deadline, if relevant;
- marketplace region/account context, if known.

Without delivery location, marketplace results are often misleading because price, stock, delivery time, seller availability, and assortment vary by region.

Do not proceed to search unless one of these is true:

1. the user provided the delivery location;
2. the user explicitly says region does not matter;
3. the task is only a rough/global comparison, not a purchase-ready search.

Default short question:

> Куда доставка?

## Do not overwhelm the user

The skill must not ask a long questionnaire.

Use at most **2–3 clarifying questions** before search, unless the user explicitly asks for a detailed requirements intake.

Always ask only the questions that most affect search quality.

## Two intake modes

### 1. Specific model / SKU / link mode

Triggered when the user provides:

- exact model;
- SKU;
- product URL;
- very specific brand + model;
- “хочу вот это”.

Behavior:

1. Respect the provided item first.
2. Ask for delivery location if missing.
3. Check product characteristics, reviews, rating, seller quality, price, availability, delivery.
4. Ask permission before expanding into alternatives.

Do not immediately redirect to analogs. The specific model may be the user’s actual target.

Recommended phrasing:

> Ок, проверю эту модель: характеристики, отзывы, цену, продавцов и доставку. Куда доставка? И можно ли параллельно показать 2–3 аналога, если они новее/лучше по отзывам или характеристикам за близкие деньги?

Alternative shorter phrasing:

> Смотрю строго её. Аналоги тоже проверить?

### Search Permission Gate

Before expanding beyond a user-specified model/brand/link, get permission if the user appears to want that exact item.

Permission is required when:

- the user gave a concrete model;
- the user gave a product link;
- the user said they want this exact item.

Permission is not required when:

- the query is already broad: “подбери”, “что взять”, “лучший”, “аналог”; 
- the provided model is clearly unavailable or incompatible, but explain this before switching.

### 2. Need/task mode

Triggered when the query is broad or task-based:

- “нужен робот-пылесос”;
- “модная футболка”;
- “жёсткий диск для дома”;
- “подарок ребёнку”;
- “что-нибудь для кухни”.

Behavior:

Ask 2–3 questions maximum:

1. Delivery location/deadline — mandatory.
2. One or two category-specific questions that most affect choice.

Examples:

#### Tech

- Budget: strict or flexible for quality?
- Priority: reliability / performance / warranty / quietness / brand / reviews?

#### Clothing

- Size / gender / style.
- Budget and desired positioning: basic / fashionable / branded / “looks more expensive than it is”.

#### Robot vacuum

- Apartment size, pets, carpets.
- Need self-emptying station / wet cleaning.

#### Storage drive

- Internal or external; SSD/HDD; size target.
- Priority: cheapest / reliable / fast / quiet / warranty.

Default broad-query prompt:

> Ок, перед поиском уточню только главное: 1) куда доставка и к какому сроку? 2) бюджет жёсткий или можно расширить ради качества? 3) что важнее: дешевле, надёжнее, быстрее доставка или лучший баланс?

## Interpreting user-mentioned products

If the user names a brand/model, treat it as one of these possibilities, not automatically as a hard requirement:

- exact requirement;
- hypothesis;
- example;
- candidate found by user;
- anchor from previous search.

If unclear, ask whether alternatives are allowed.

Important question:

> Это строго эта модель или можно предложить аналоги лучше по отзывам/характеристикам при близкой цене?

## Decision policy

The final recommendation should not be just “lowest price”.

Return decision-oriented roles:

- 🥇 best overall choice;
- 💸 rational/value choice;
- 🛡️ reliable/premium choice;
- 🚚 fastest delivery, if delivery deadline matters;
- 🚫 avoid / suspicious options, if found.

If marketplace recommendations reveal a strong candidate outside the initial query, include it only when analog search is allowed, and explain why it is relevant.

## Risk and quality model

Evaluate:

- exact SKU / variant match;
- new vs used/refurbished;
- seller reputation;
- marketplace fulfillment vs third-party seller;
- warranty and return conditions;
- suspiciously low price;
- hidden conditions: card-only price, wallet discount, coupons, points, subscription;
- reviews quality and common complaints;
- model age and known issues;
- delivery date reliability;
- total price including delivery.

Do not recommend anomalously cheap offers as the best option unless the risk is explicitly acceptable to the user.

## Example: home SSD/HDD search

Bad behavior:

> User says “maybe ADATA” → agent switches fully to ADATA and ignores better recommendations.

Better interpretation:

The real need may be:

> reliable internal storage for a home Windows mini PC / AI machine, with enough capacity, good endurance, acceptable heat, delivery soon, and willingness to pay 10–20% more for quality.

Good search brief:

> Найди внутренний SSD M.2 NVMe для домашнего mini PC. Нужен надёжный диск под Windows/данные/AI-задачи, форм-фактор M.2 2280, PCIe NVMe, желательно TLC, хороший ресурс TBW, нормальный бренд. Рассматривать 1–2 ТБ, но 2 ТБ предпочтительнее, если цена рациональна. Бюджет ориентир 18–22 тыс ₽, можно переплатить до 10–20% за качество и надёжность. Нужна покупка в РФ с доставкой в ближайшие дни. Не гнаться за минимальной ценой; исключать подозрительных продавцов, QLC/слабые модели и нерелевантные SKU. Дай 3–5 вариантов: лучший общий, самый рациональный, премиум/надёжный, и что не брать.

If user provides a specific model:

> Ок, проверю ADATA Legend 960 2TB: характеристики, отзывы, цену и продавцов. Куда доставка? И можно ли показать аналоги вроде Samsung/WD/Kingston, если они лучше по отзывам или надёжности за близкую цену?

## Five brains

1. **Intent Intake** — delivery gate, specific vs broad request, 2–3 questions max, analog permission.
2. **Search Strategy** — web_search → web_fetch → visible browser, no stealth/anti-bot loops.
3. **Offer Normalization** — exact SKU/variant, delivery, discounts, seller/source type, same-item comparison.
4. **Risk & Quality Scoring** — seller, reviews, warranty, suspicious prices, hidden conditions, fit to criteria.
5. **Decision Output** — best overall, value, premium/reliable, fastest delivery, avoid list, short recommendation.

## Found competitor ideas — implementation order

1. **Intent Intake + Delivery Gate** — from our design; base MVP.
2. **Permission Gate for analogs** — from our design; base MVP.
3. **Decision-first output** — from `price-comparison-analyzer`.
4. **L1/L2/L3 answer structure** — from `price-comparison-analyzer`.
5. **Risk-aware recommendation** — from `price-comparison-analyzer`.
6. **Search modes / weighted ranking** — from `shopping-expert`.
7. **Exact SKU + source types + evidence** — from `global-price-comparison`.
8. **Structured output schema** — from `ShopGeni`.
9. **Project structure with references** — from `ecommerce-price-comparison`.
10. **Price watch / coupons** — from `shopping-price-drop-coupon-scout`, later.
11. **Image/photo search** — from `ShopGeni`, major 2.0 feature.

## Production skill requirements

Marketplace Guru should include:

1. Delivery gate before search.
2. Two-mode intake: specific model vs need/task.
3. 2–3 question maximum by default.
4. Permission gate before analog expansion.
5. Decision-first output.
6. Risk labels and “avoid” section.
7. Explicit treatment of discounts and hidden conditions.
8. Evidence: source URL, price, timestamp, delivery region.
9. Read-only safety: no purchases, no cart actions, no login changes without explicit confirmation.
10. Escalation layers: web_search → web_fetch → visible browser when necessary.

## Future files

Potential production structure:

```text
marketplace-guru/
├── SKILL.md
├── README.md
├── references/
│   ├── intake.md
│   ├── risk-model.md
│   ├── output-formats.md
│   └── category-playbooks.md
└── scripts/
    └── optional deterministic helpers
```


path: references/legacy/README.md
content: # Legacy references

This directory contains historical material that informed Marketplace Guru.

- `marketplace-scraper/` — the first local draft/idea for marketplace search and comparison. It is preserved as historical context, not the active skill entrypoint.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)