| name | sorftime-seller-agent |
| description | Sorftime Seller Agent — Expert-level cross-border e-commerce data analysis and product sourcing intelligence for Amazon, Walmart, TikTok Shop, 1688, Shopee, and TEMU sellers. A single skill that turns any MCP-enabled AI agent (Claude Code, OpenClaw, Cursor, Copilot) into a Sorftime marketplace intelligence expert. Covers product discovery, competitor analysis, keyword strategy, profit calculation, ASIN deep-dive, blue ocean finding, market intelligence, and more. Auto-adapts output for beginner, growing, and professional seller stages. |
| trigger | sorftime/product sourcing/competitor/keyword/profit/market intelligence/ASIN/category/blue ocean/seasonal/amazon/tiktok/shopee/temu/walmart/hidden profit/supply chain/monitor/analyze this data/review this product/content review/MCP debug/bridge/install/market panorama/competitor deep-dive/keyword strategy/blue ocean finder/listing audit/review mining/pricing strategy/traffic structure/negative review replacement/brand monopoly/brand gap/keyword scatter/lightweight profit/FBA fee/seasonal products/variant gap/new product burst/FBM to FBA/cross-platform price gap/listing optimization/price band/sweet spot/hidden profit index/ecommerce seller/seller tools/选品/竞品/关键词/利润/市场看板/ASIN/类目/蓝海/季节性/隐赚/货源/监控/closed-loop workflow/选品工作流/complete go-no-go/end-to-end product selection |
| version | 3.4.1 |
| user-invocable | true |
| metadata | {"openclaw":{"emoji":"🛒","requires":{"bins":["python3"],"env":["SORFTIME_MCP_KEY"]},"primaryEnv":"SORFTIME_MCP_KEY"}} |
Sorftime Seller Agent
One skill. Any AI agent. Instant marketplace intelligence for global sellers.
🔴 Language Rule (Mandatory)
Match the user's language. Always. If the user writes in English → respond in English. If the user writes in Chinese → respond in Chinese. Never mix. This overrides everything else in this skill.
Core Positioning
This skill is the single unified entry point for all Sorftime MCP capabilities. It integrates:
- MCP Bridge Layer: Direct access to Sorftime's full suite of data tools (current count in
references/tool-matrix.md, auto-synced)
- Intelligence Layer: Product discovery engine, competitor analysis, keyword optimization, profit calculation, monitoring & alerts
- Output Adaptation Layer: Auto-formats results by seller stage (Beginner / Growing / Professional)
- Content Quality Layer: Quality guidelines for AI-generated content output
- Platform Exploration Layer: Automated discovery of Sorftime modules and fields
Users describe what they need — the skill auto-routes to the right scripts and tool chains.
⚠️ MCP Parameter Name Traps (Must Read — Highest Frequency Pitfall)
The same business concept uses DIFFERENT parameter names across different Sorftime tools. With 86+ tools, parameter naming is not consistent between product, keyword, category, and cross-platform tools.
Always verify the actual inputSchema.properties of the target tool before calling it. Never guess parameter names based on what another tool uses.
Most common parameter mismatch errors:
| Concept | Product Tools Use | Keyword Tools Use | Category Tools Use | Cross-Platform Use |
|---|
| Search term | search_name | keyword | category_name / product_name | — |
| Marketplace | amz_site | keyword_support_site | amz_site | site |
| Category ID | node_id | — | top_node | node_id |
| Product ID | asin | — | — | product_id |
Typical failure scenarios:
- Using
product_search's search_name parameter on keyword_detail → fails. Correct: keyword
- Using
amz_site on keyword_list → fails. Correct: keyword_support_site
- Using
node_id on category_search_from_top_node → fails. Correct: top_node
How to avoid:
- Check Schema before calling:
mcp_client.py has built-in parameter validation + auto-correction. Common aliases (e.g. search_name → keyword) are auto-corrected with a stderr notification
- If it fails, check parameter names FIRST: An
isError response is most likely a wrong parameter name — not a server outage
- When adding new tools, add aliases: If new tools use different naming conventions, add a mapping in
scripts/utils/mcp_client.py's PARAM_ALIASES
🌐 Sorftime International Platform
Platform URL: https://open-intl.sorftime.com — the dedicated international platform for global sellers.
Registration & Account
| Item | Detail |
|---|
| Sign-Up | https://open-intl.sorftime.com → "Log In / Sign Up" |
| Login Methods | Google account (recommended) or email/password |
| Free Trial | New accounts receive free trial credits — start using MCP immediately without payment |
| Payment | PayPal (credit/debit cards via PayPal checkout) |
| MCP Key Location | After login → navigate to the MCP tab → copy your Key |
| Contact | Email: service@sorftime.com |
Product Access
| Product | Status | Description |
|---|
| MCP | ✅ Live | AI agent toolset — plug-and-play model integration for Claude, Cursor, etc. |
| CLI | 🔜 Coming Soon | Command-line client for scripting and batch processing |
| API | 🔜 Coming Soon | HTTP data interface for custom system integration |
Supported Platforms
Amazon · Walmart · Shopee · TikTok · TEMU · 1688 — across 21 global sites.
🚀 Agent Onboarding Protocol (Mandatory)
Goal: When a user first says "help me find products" or provides a Key, the agent MUST auto-detect → guide → install → retry, without throwing technical errors.
Trigger Conditions (any one triggers onboarding)
- User explicitly says configuration-related things: "configure Sorftime" / "first time" / "how to start" / "here's my key"
- User directly provides a Key (any string that looks like an API key)
- A data request fails with
[SORFTIME_ONBOARDING_REQUIRED] or SORFTIME_MCP_KEY not set
Execution Flow (must follow order)
Step 1 — Detect
Run python3 scripts/healthcheck.py to quickly determine which is missing: Key, dependencies, or MCP connection.
Step 2 — Guide to Get Key (if Key is missing)
If the user hasn't provided a Key, proactively provide the acquisition path:
- Registration URL: https://open-intl.sorftime.com — Sorftime International (overseas) platform
- Sign up with Google account or email/password
- After registration, navigate to the MCP page at https://open-intl.sorftime.com/mcp to copy your MCP Key
- New users get free trial credits upon registration — no payment required to start
- Payment options: PayPal (credit card via PayPal)
- Suggested phrasing: "Create a free account at open-intl.sorftime.com (Google login supported), grab your MCP Key from the MCP page, and I'll set everything up. New accounts come with free trial credits."
Step 3 — Auto-Install
Once you have the Key, immediately run:
python3 scripts/install.py --unattended --key <user-provided-Key>
--unattended ensures no interactive prompts- Result is JSON:
{"status":"ok","key_saved":true,"test_passed":true}
Step 4 — Mandatory Post-Success Action
- If onboarding was triggered by a data request (e.g. "help me find products") → MUST retry the original request and return results to the user
- If onboarding was an explicit user request → confirm success and provide a testable example (e.g.
get_time or a simple product search)
Step 5 — Failure Handling
If install.py returns test_passed: false or status: error:
- Check if the Key was copied completely (common: missing trailing characters)
- Confirm the Sorftime account has MCP service enabled
- Check network connectivity to
open-intl.sorftime.com
- Report the specific error to the user with next-step suggestions
First-Time User Guide (Simplified for Users)
| Step | User Action | Agent Action |
|---|
| 1 | Say "help me find products" or "configure Sorftime" | Detect configuration status |
| 2 | Create a free account at https://open-intl.sorftime.com (Google login or email). Go to MCP page and copy your Key. Send to agent. | Auto-run install.py --unattended --key <Key> |
| 3 | Wait 10-20 seconds | Auto-test connection, save config, retry original request |
| 4 | Start using immediately with free trial credits | — |
FAQ Quick Reference
| Problem | Solution |
|---|
| "[SORFTIME_ONBOARDING_REQUIRED]" | Immediately execute onboarding flow (Steps 1-4) |
| "Connection test failed" | Check Key completeness / account MCP status / network to open-intl.sorftime.com |
| Don't know where to get Key | Direct user to https://open-intl.sorftime.com → register (Google login supported) → MCP page → copy Key |
| "Schema is X days old" | Run python3 tests/auto_sync.py to pull latest tool schemas |
| How to pay / pricing | Direct user to https://open-intl.sorftime.com — PayPal supported. Free trial credits available on registration. |
Scenario Routing Table (Mandatory)
| User Says | Internal Route | Key Script |
|---|
| "find products" / "blue ocean" / "market opportunity" / "product discovery" | → Discovery Engine + Stage Adaptation | picker.py --mode <newbie|blueocean> |
| "analyze this ASIN" / "competitor analysis" / "traffic keywords" | → Competitor Analysis | analyst.py --mode competitor |
| "keyword research" / "long-tail keywords" / "search terms" | → Keyword Analysis | analyst.py --mode keyword |
| "calculate profit" / "break-even" / "FBA fees" | → Profit Calculator | calculator.py |
| "closed-loop workflow" / "选品工作流" / "complete go/no-go" / "end-to-end product selection" | → Closed-Loop Product Selection | Built-in workflow template |
| "monitor price" / "watch this product" / "daily report" | → Monitoring Engine | monitor.py --mode add/daily/alert |
| "TikTok/TEMU/Shopee + analysis" | → Multi-Platform Router | platform_router.py --platform <name> |
| "Walmart product discovery/analysis" | → Walmart Automation | walmart_picker.py / walmart_analyst.py |
| "review my content" / "quality check" | → Content Quality Guidelines | Execute guidelines flow (see below) |
| "configure Sorftime" / "first time" / "MCP Key" | → Auto Onboarding | install.py --unattended --key <KEY> |
| "explore Sorftime" / "what features exist" / "available fields" | → Platform Explorer | explorer/*.js + Playwright |
| "install/debug/run tests" / "MCP not connecting" | → Bridge Operations | install.py / run_tool_tests.py / healthcheck.py |
Methodology Card Routing (v3.0)
When users mention specific tactical scenarios, route to the corresponding methodology card for the complete analysis framework. Cards located in references/methodology-cards/.
| User Says | Route to Card | Key Script + Index |
|---|
| "analyze market" / "market panorama" / "is it worth it" | → comprehensive/market-panorama.md | picker.py + 11-dimension composite score |
| "competitor deep-dive" / "compare competitors" | → comprehensive/competitor-deepdive.md | analyst.py --mode competitor + Threat Index |
| "keyword strategy" / "keyword layout" / "search optimization" | → comprehensive/keyword-strategy.md | analyst.py --mode keyword + Opportunity Index |
| "find blue ocean" / "blue ocean categories" / "market gaps" | → comprehensive/blue-ocean-finder.md | picker.py --mode blueocean + Hidden Profit Index ⭐ |
| "listing audit" / "optimize listing" / "title optimization" | → comprehensive/listing-audit.md | Keyword Coverage Gap Index |
| "review analysis" / "negative review insights" / "buyer pain points" | → comprehensive/review-mining.md | Pain Point Severity Index |
| "pricing strategy" / "price positioning" / "price bands" | → comprehensive/pricing-position.md | Price Band Opportunity Index |
| "traffic analysis" / "traffic sources" / "organic traffic" | → comprehensive/traffic-structure.md | Organic Traffic Health Index |
| "hidden profit index" / "hidden profit" / "hidden gems" / "undervalued products" | → tactical/invisible-profit.md ⭐ (独家方法论) | potential_product + Sorftime 独家 Hidden Profit Index — 全维度加权综合评分，专门发现"评论少但卖得好、广告费低但利润高"的被忽视产品 |
| "low rating replacement" / "low rating opportunity" / "improve product" | → tactical/low-review-winner.md | Replacement Opportunity Index (full ranking, not maxRating≤4.2) |
| "brand monopoly" / "brand concentration" / "brand gap" | → tactical/brand-gap-entry.md | Brand Monopoly Vulnerability Index |
| "keyword scatter" / "search dispersion" / "traffic dispersion" | → tactical/keyword-scatter.md | Keyword Opportunity Index |
| "lightweight products" / "low FBA fee" / "high profit light goods" | → tactical/lightweight-profit.md | Profit Efficiency Index (full ranking, not minPrice≥$20) |
| "seasonal" / "holiday selection" / "peak season positioning" | → tactical/seasonal-position.md | Seasonal Boom Index |
| "variant gap" / "variant opportunity" / "missing child ASINs" | → tactical/variant-gap.md | Variant Gap Index |
| "new product burst" / "new bestseller" / "new product tracking" | → tactical/new-product-burst.md | New Product Burst Index |
| "FBM to FBA" / "fulfillment arbitrage" | → tactical/fbm-arbitrage.md | FBA Conversion Arbitrage Index |
| "cross-platform price gap" / "Walmart vs Amazon" | → tactical/cross-platform-gap.md ⭐ | Cross-Platform Price Gap Index (Sorftime exclusive dual-platform) |
| "listing optimization" / "poor listing" / "optimization takeover" | → tactical/poor-listing-grab.md | Listing Optimization Potential Index |
| "price band gap" / "pricing sweet spot" | → tactical/price-band-sweetspot.md | Demand Density ÷ Competitor Density |
Methodology Core Principle (Differentiator vs Competitors)
Full ranking, no hard thresholds. Each methodology card uses weighted index full-ranking — a $19.99 product won't disappear because it's $0.01 below a threshold, and a 4.3-star product won't be excluded for being 0.1 above a cutoff. Sellers see the complete picture and make their own decisions.
vs Other Solutions:
| Dimension | Other Solutions | Sorftime |
|---|
| Filtering | Hard thresholds (minPrice≥$20 AND maxRating≤4.2) — cliff effect | Full-ranking by composite index — no blind spots |
| Data Depth | Basic metrics | 160+ dimensions + proprietary indices |
| AI Integration | Limited, manual operation | MCP-native, 86 standardized tools for AI agents |
| Platform Coverage | Amazon only | 40+ platforms |
| Interface | GUI-heavy, steep learning curve | CLI + AI Agent, natural language |
🛡️ Parameter Discipline (READ BEFORE ANY TOOL CALL)
The #1 recurring failure: guessing parameters instead of checking the schema. This must stop.
Mandatory: Schema-First Protocol
Before calling ANY Sorftime MCP tool, you MUST verify exactly 3 things:
| # | Check | How |
|---|
| 1 | Required parameters | grep -A30 '"<tool_name>"' scripts/sorftime_bridge.py — read required array |
| 2 | Parameter names (case-sensitive!) | Same grep — read properties keys. node_id ≠ nodeId ≠ nodeid |
| 3 | Enum values | amz_site must be "US"/"GB"/"DE" etc., NOT "amazon.com" or "美国" |
Common Parameter Traps
| Wrong (Agent guesses) | Correct (Schema says) | Tool affected |
|---|
"yoga US" (free text) | {"node_id":"3743561","amz_site":"US"} | category_keywords |
"yoga US 7月" | {"node_id":"3743561","start_date":"2026-07-01","end_date":"2026-07-31","amz_site":"US"} | category_report_from_history |
"amzSite":"US" | "amz_site":"US" | Amazon tools |
"site":"US" | "amz_site":"US" | Amazon tools (not TikTok/Shopee) |
"keywordSupportSite" | "amz_site" (some tools), "keyword_support_site" (others) | Varies by tool |
Missing node_id entirely | node_id is required in category_keywords, category_report, etc. | Category tools |
Date "2025H1" | "2025-01-01" / "2025-06-30" (yyyy-MM-dd, max 40-day range) | category_report_from_history |
Quick Schema Lookup
python3 -c "
import json, ast, sys
src = open('scripts/sorftime_bridge.py').read()
# Find the tool schema block
start = src.index('\"name\": \"$TOOL_NAME\"')
block = src[start:start+3000]
# Parse out required params and properties
print(block)
"
If a Tool Returns "No relevant data" or Code=10
- DO NOT conclude "the tool is broken" or "data doesn't exist"
- DO re-check the 3 schema checks above
- DO test with the exact parameters from a known-working call
- Only after verifying correct parameters 3 times → then escalate as possible data gap
Workflow Templates (Built-in)
Closed-Loop Product Selection
Trigger: "closed-loop workflow", "选品工作流", "complete go/no-go", "end-to-end product selection"
/goal /sorftime-seller-agent Execute Closed-Loop Product Selection for {category} on {platform}. Seller: {stage}, ${budget}, {model}, country={cn|us|uk|de|other}. Rounds: {N}. Deliverable per acceptance criteria v3.0: confidence-labeled data, 7-member Seller Review Panel verdicts, Go/No-Go Decision Table, Risk Registry, First-Order Plan, copy-paste-ready /loop monitoring command.
Rounds parameter: {N}=1 means test one category and stop. {N}=3 means scan 3 categories. Seller controls depth vs speed.
MANDATORY PROTOCOL — DO NOT SKIP PHASES:
P0(T1-3): MANDATORY INTERACTION — DO NOT call any MCP tool until seller explicitly chooses a path.
Step 1: ASK+CONFIRM budget, platform, stage, model, SELLER COUNTRY.
Step 2: PRESENT BOTH PATHS in this exact format:
"Based on your profile ({stage}, ${budget}, {country} seller), two paths are available:
Path 1 (HPI Product Sniper): full-category HPI ranking → find undervalued individual products. Fast results.
Path 2 (Market Mapper): analyze subcategory competition first → pick products within winning categories. Strategic.
My recommendation: {Path X}, because {reason}. But you decide — Path 1, Path 2, or both?"
Step 3: WAIT for seller response. DO NOT proceed to PA until seller chooses.
Seller country is a FIRST-CLASS parameter — it changes sourcing, logistics, tax, risk, compliance. DO NOT assume all sellers are Chinese.
Seller country options:
cn = Chinese cross-border seller → 1688 sourcing, cross-border freight+duty, lower COGS, higher compliance/IP risk
us = US domestic seller → Alibaba.com or domestic wholesale, domestic shipping, higher COGS, lower compliance risk
uk = UK domestic seller → EU/UK suppliers, UK duty+20% VAT, UKCA compliance
de = German domestic seller → EU suppliers, EU duty+19% VAT, WEEE/GPSR/VerpackG mandatory
other = Other (ask seller for sourcing preference + logistics details)
Default recommendation (seller can say "Path 1", "Path 2", or "both"):
→ Path 1 fits best when: budget<$10K OR beginner OR arbitrage OR "I want one good product fast"
→ Path 2 fits best when: brand-owner OR factory OR professional OR "I need a category to build in"
→ "Both": growing stage $10K+, or seller wants maximum coverage → Path 2 first then Path 1 within each winner
→ Seller unsure: run Path 2 then Path 1
PA(T4-15): Path1=potential_product NO hard-threshold, safety AFTER rank, ≥10 products. Path2=category_report×N→11dim→top3 subcat→potential_product×node_id.
PB(T16-30): PARALLEL product_detail×N, product_trend×N×3, product_traffic_terms×N. WARNING: read exposure_position NOT organic_searched_percentage. product_reviews×TOP3, category_report.
PC(T31-45): Sorftime MCP ONLY has 1688 supply chain tools (5 endpoints). No Alibaba.com, no domestic wholesale.
ALL sellers use ali1688_similar_product — but ADAPT BY COUNTRY:
cn → CHINESE keywords (e.g. "瑜伽垫"). CNY pricing is native. Cross-border freight+duty.
us → ENGLISH keywords work (verified: "yoga mat" returns 100 results). Results in Chinese with CNY pricing — convert CNY→USD at ~0.14 rate. NOTE: 1688 is a Chinese platform, not a domestic supplier.
COGS fallback if 1688 returns unsuitable: price × 0.30 (US wholesale markup is higher than CN factory).
Logistics: sea freight + US duty + customs (US sellers importing from China — same as CN seller).
uk/de → ENGLISH keywords on 1688. Convert CNY→GBP/EUR. Add UK/EU import duty + VAT.
COGS fallback: price × 0.35 (EU wholesale).
WARNING for non-CN sellers: 1688 is a Chinese-language B2B platform. Results include Chinese titles, CNY prices, and China-based suppliers. Clearly label all 1688 data as [ESTIMATED: 1688 CN supplier, CNY→USD converted]. Recommend seller verify via Alibaba.com independently.
⚠️ ALL 1688 DATA IS FOR REFERENCE ONLY. NOT definitive sourcing. Bait pricing, quality variability, MOQ mismatch, and currency conversion are inherent limitations. Every cost line in this phase MUST carry a disclaimer: "Verify with actual supplier quote before committing capital."
Full landed cost PER COUNTRY. First-order qty=max(MOQ,30d×2.5).
PD(T46-55): Full P&L→TrueNet. ADJUST TAX BY SELLER COUNTRY:
cn → No US sales tax obligation (Amazon collects/remits). Return cost: disposal only (no domestic return address).
us → Sales tax nexus consideration. Return cost: domestic return address, restock/resell possible.
uk/de → VAT registered: input VAT recoverable on import. Return cost: EU mandatory 14-day withdrawal.
DO NOT APPLY VERDICT.
PE(T56-65): ADJUST RISK BY SELLER COUNTRY:
cn → HIGHER: compliance unfamiliarity (FCC/FDA/CPC), IP complaint vulnerability, account suspension risk, language barrier in customer service
us → LOWER: compliance familiarity, stronger IP enforcement access, domestic liability insurance available
uk/de → MEDIUM: product liability strict, WEEE/GPSR/UKCA mandatory, language-specific listing requirements
+4-tier+monopoly+seasonal+review+platform risks.
PD2(T66-80) MANDATORY: SPAWN 7 sub-agents IN PARALLEL as Seller Review Panel. Seat1(Peer: same stage+budget+model+COUNTRY)×2,Seat2(PeerAlt: same country, budget×0.8)×1,Seat3(Mentor: one stage up, SAME country)×1.5,Seat4(Conservative)×1,Seat5(Opportunity)×1,Seat6(PlatformSpec: platform+COUNTRY dynamics)×1.5,Seat7(FinAuditor: country-specific P&L, tax, duties)×1. Each:score5dim(0-10),vote GO/CAUTION/NO-GO with reasoning. GO=≥4/7 AND Seat6≠NO-GO. NOGO=≥4/7 OR Seat7 NO-GO with P&L evidence. Main agent FORBIDDEN from voting.
PF(T81-95): Decision Table([VERIFIED]/[ESTIMATED]/[ASSUMED]/[UNAVAILABLE]), Panel record, TOP3, Risk Registry, Budget, First-Order Plan, Raw Data.
🚫 ANTI-ABSOLUTISM RULE: NEVER use absolute language in conclusions. BANNED phrases: "this product WILL succeed", "guaranteed profit", "100% safe", "definitely", "certainly", "no risk".
REQUIRED qualifiers: "based on available data", "estimates suggest", "historical trends indicate", "panel assessment is", "verify independently before committing capital".
The Executive Summary MUST include: "All supply chain data is from 1688 (Chinese B2B platform) and is FOR REFERENCE ONLY. Financial projections are ESTIMATES based on current API data. Verify with actual supplier quotes, freight forwarders, and a small-batch PPC test before committing your full budget."
Every GO verdict MUST be accompanied by: "Proceed to supplier negotiation and sample order. Do NOT commit full capital until [specific condition] is verified."
PG(T96-100) MANDATORY: Output EXACT /loop command (NOT /goal):
`/loop 30d /sorftime-seller-agent Check {ASIN} on {platform}: product_detail(price/BSR/reviews/rating) + product_trend(SalesVolume)30d. Alerts: sales<30%proj D60->re-evaluate, ACoS>150%est D45->pause, rating<4.3->QC, stock<30d->reorder.`
Seat7(Financial Auditor) MUST return before final verdict — if timeout, retry with simplified P&L-only prompt.
Every panelist vote MUST include 2-3 sentence role-specific reasoning in the deliverable, not just the vote itself.
Save checkpoint EVERY phase. stop after {N*35} turns (1 round≈35 turns: PA10+PB15+PC15+PD10+PE10+PD210+PF10+PG5). If {N}=1, stop at product verdict for the single category.
DATA PERSISTENCE — ALL OUTPUTS MUST BE WRITTEN TO DISK:
Output directory: ${SORFTIME_OUTPUT_DIR:-~/Documents/sorftime}/{date}-{category}-{platform}/
(SORFTIME_OUTPUT_DIR env var overrides default; falls back to ~/Documents/sorftime)
Files to write after EVERY phase:
PA: {dir}/01-discovery.json (raw potential_product response + filtered shortlist)
PB: {dir}/02-verification.json (product_detail + trend + traffic + reviews per ASIN)
PC: {dir}/03-supply-chain.json (ali1688 results + landed cost calculations)
PD: {dir}/04-financials.json (full P&L per product)
PE: {dir}/05-risks.json (risk matrix per product)
PD2: {dir}/06-panel-verdict.json (all 7 panelist votes + reasoning + final verdict)
PF: {dir}/07-deliverable.md (complete Go/No-Go Decision Table + TOP3 + risk registry + budget + first-order plan in Markdown)
PG: {dir}/08-monitoring.sh (copy-paste-ready /loop command)
{dir}/workflow-state.md (checkpoint — resume if interrupted)
{dir}/README.md (index: scenario params, execution summary, data freshness)
After PF: Write the deliverable AS A STANDALONE .md FILE that the seller can open and read independently of this conversation. The file must include ALL tables, panel votes, risk registry, and budget plan. No "see above" or "as discussed" references — fully self-contained.
Execution Principles
- Identify first, then execute: Complex requests → use
router.py or persona.py to identify intent and seller stage, then route to methodology card
- Ask when information is insufficient: Never guess ASINs, keywords, or marketplaces — ask
- Schema freshness check: At the first Sorftime usage in each session, run
python3 scripts/healthcheck.py. If it reports "Schema is X days old" (>7 days), proactively notify the user: "Schema is X days old — new tools may be available on the server. Sync now?" — only sync after user confirmation (python3 tests/auto_sync.py). Never silently sync (involves file modification). If a tool call returns "not found" or "unsupported", the first step is to suggest syncing Schema
- Cache-first: Repeated queries auto-hit SQLite cache (
~/.sorftime-cache/)
- Structure results: Raw JSON must be formatted before presenting to users — never dump raw JSON
- Out of scope: Log unsupported requests to
~/.sorftime-cache/unsupported-requests.log and provide alternatives
- Batch scenarios: When users say "batch/bulk/monitor/scheduled", use MCP tools with batched calls + Python scripts; space requests appropriately to avoid rate limiting
I. Data Intelligence Layer (Discovery / Competitor / Profit / Monitoring)
1.1 Discovery Engine picker.py
python3 scripts/picker.py --mode newbie --platform amazon --site US --keyword "kitchen storage"
python3 scripts/picker.py --mode blueocean --platform amazon --site US --keyword "pet supplies"
python3 scripts/picker.py --mode blueocean --platform amazon --site US --keyword "yoga mat" --profile factory
python3 scripts/picker.py --mode blueocean --platform amazon --site US --keyword "dress" --allow-capital
python3 scripts/picker.py --profile-help
Auto-analysis dimensions:
- Brand monopoly (top 3 brands > 40% market share → alert)
- Amazon Basics penetration
- Low-review high-sales opportunities (reviews < 100 but high sales volume)
- Price wars (< $10 clustering → avoid)
- Beginner-friendliness (auto-apply reviews < 500, monopoly coefficient < 40%)
- Quantified risk summary: estimated return rate, initial capital requirement, inventory turnover days, brand concentration, new product survival rate, price dispersion
Four-Tier Risk Filtering System (v2.0):
| Risk Level | Category Coverage | Default Filter | Override Switch |
|---|
| 🔴 Hard Block | Food/beverage/supplements/medical devices/functional cosmetics/baby food/pesticides/alcohol | All profiles | --allow-hard (⚠️ not recommended) |
| 🟡 Capital-Intensive | Apparel/shoes/bags/jewelry/wigs/furniture/mattresses/large appliances/bicycles | Beginner + Growing | --allow-capital |
| 🟠 Operations-Complex | Electronics/liquids/flammables/IP-licensed/auto parts/safety equipment/BBQ grills/glass fragile items | Beginner only | --allow-ops |
| ⚠️ Trap Signals | Fake reviews/merged reviews/price wars/red ocean/seasonal/heavy goods/hijacking/size hell | All profiles | --skip-traps (⚠️ not recommended) |
Seller Profiles:
| Profile | Hard Block | Capital | Operations | Traps | Suitable For |
|---|
newbie | ✅ | ✅ | ✅ | ✅ | Beginners, limited capital |
grower | ✅ | ✅ | ❌ | ✅ | Growing sellers, moderate risk tolerance |
pro | ✅ | ❌ | ❌ | ✅ | Professional sellers with teams |
factory | ✅ | ❌ | ❌ | ✅ | Factory-direct, supply chain advantage |
brand | ✅ | ❌ | ❌ | ✅ | Brand owners, in-house compliance |
Other high-risk categories (not auto-filtered, but flagged during analysis):
- Accessories (hats/scarves/gloves/socks/belts): 5-15% return rate
- Eyewear/sunglasses: 10-20% return rate, prescription/style issues
- Phone cases/screen protectors: extreme red ocean, razor-thin margins, patent minefield
- Stationery/office supplies: low ASP, thin margins, commoditized
- Holiday decorations: extremely short sales window, post-season inventory risk
- Books/CD/DVD: low margins, shrinking market
Transparent filtering: Every excluded product shows its specific reason and risk level, helping sellers understand the rationale. Experienced sellers can use --profile or per-category overrides to see the full analysis.
1.2 Analyst Engine analyst.py
python3 scripts/analyst.py --mode competitor --platform amazon --site US --asin B08N5WRWNW
python3 scripts/analyst.py --mode keyword --platform amazon --site US --keyword "yoga mat"
python3 scripts/analyst.py --mode market --platform amazon --site US --node-id 1064954
1.3 Profit Calculator calculator.py
python3 scripts/calculator.py --platform amazon --price 29.99 --cost 8.5 --weight 1.2
Output: gross margin, break-even daily sales, return rate sensitivity. FBA fee is estimated by weight — verify with actual dimensional weight from product detail.
1.4 Monitoring Engine monitor.py
python3 scripts/monitor.py --mode add --type asin --value B08N5WRWNW --platform amazon --site US
python3 scripts/monitor.py --mode daily
python3 scripts/monitor.py --mode alert
1.5 Walmart Discovery Engine walmart_picker.py
python3 scripts/walmart_picker.py --mode blueocean --keyword "yoga mat"
python3 scripts/walmart_picker.py --mode newbie --keyword "kitchen storage"
python3 scripts/walmart_picker.py --mode blueocean --keyword "toy" --profile factory
Walmart-specific adaptations:
- Review threshold < 200 (Amazon is < 500), reflecting Walmart's overall lower review counts
- Auto-analyzes Walmart self-operated (1P) share, WFS penetration
- Reuses the four-tier risk filtering system
1.6 Walmart Analyst Engine walmart_analyst.py
python3 scripts/walmart_analyst.py --mode competitor --product-id 15689567602
python3 scripts/walmart_analyst.py --mode keyword --keyword "toilet paper"
python3 scripts/walmart_analyst.py --mode market --node-id 5438
II. Output Adaptation Layer (Seller Stage Detection & Formatting)
Must call persona.py first to identify stage:
python3 scripts/persona.py --text "I'm a beginner, looking for blue ocean products on Amazon US"
Then format by stage:
python3 scripts/stage_formatter.py --stage beginner --input /tmp/result.md
| Stage | Output Characteristics |
|---|
| beginner | Explains terminology, emphasizes "why this matters" and "what to do next" |
| growing | Highlights data changes, opportunities, competitive risk alerts |
| pro | Direct conclusions, recommends batch/API solutions, minimal preamble |
III. Content Quality Layer
When the user asks "review my content" / "quality check", follow these guidelines:
Step 1: Context-Aware Review
- Check if the content references specific data points without citing them
- Verify any competitive claims are substantiated
- Ensure tone and format match the intended audience (sellers, developers, etc.)
Step 2: Quality Dimensions
A. Factual Accuracy
Verify any data claims, statistics, or assertions against available Sorftime data.
B. Actionability
Does the content enable the reader to take a specific next step?
Vague advice → flag for improvement. Concrete, data-backed guidance → passes.
C. Brand Consistency
Does the content align with Sorftime's positioning as AI-Powered Marketplace Intelligence?
D. Audience Fit
Is the technical depth appropriate for the target audience (beginner/growing/pro)?
Step 3: Output Scoring (0-100)
| Score | Verdict |
|---|
| ≥ 75 | ✅ Ready to publish |
| 40-74 | 🔄 Needs revision (provide specific fixes) |
| < 40 | ❌ Do not publish (fundamental issues) |
IV. Platform Exploration Layer (Feature Map / Field Verification)
When user says "explore Sorftime" / "what features are available" / "available fields" / "verify fields":
node scripts/explorer/content-capture.js <url>
Core principles:
- One module at a time
- Existence ≠ usable — must click to verify
- Use checkbox to select data rows (5+ rows) to trigger comparison
- Save checkpoint after each tab switch
*.sorftime.com goes DIRECT (no proxy)
V. MCP Bridge & Operations Layer
5.1 Installation
python3 scripts/install.py
Auto-completes: virtual environment creation, CC/OpenClaw detection, prompts for SORFTIME_MCP_KEY, connection test, config snippet output.
5.2 Quick Tool Invocation
python3 scripts/sorftime_bridge.py --one-shot get_time '{}'
python3 scripts/sorftime_bridge.py --one-shot product_search '{"amz_site":"US","search_name":"kitchen storage"}'
python3 scripts/sorftime_bridge.py --one-shot potential_product '{"amz_site":"US"}'
python3 scripts/sorftime_bridge.py --one-shot potential_product '{"amz_site":"US","search_name":"yoga mat"}'
5.3 Full Test Suite
python3 tests/run_tool_tests.py
5.4 Schema Auto-Sync
When Sorftime MCP server updates tools (add/remove/modify schemas), the skill auto-detects and syncs.
python3 scripts/sync_manager.py full
python3 scripts/sync_manager.py diff
python3 tests/auto_sync.py
Sync scope:
scripts/sorftime_bridge.py — update _FALLBACK_CORE_TOOLS with latest server schemareferences/tool-matrix.md — regenerate categorized tool matrixtests/fixtures/*.yaml — update test case parameter structures~/.sorftime-cache/schema-store/ — versioned storage, supports rollback
Each sync auto-creates backup in .sync-backups/, with one-click rollback:
python3 scripts/sync_manager.py rollback YYYYMMDD_HHMMSS
5.5 Drift Detection
python3 tests/drift_detector.py
Compares local references/tool-matrix.md against scripts/sorftime_bridge.py's _FALLBACK_CORE_TOOLS. Alerts on inconsistency. Note: this checks local file consistency only, not against the server.
VI. Multi-Platform Parameter Quick Reference
| Platform | Marketplace Param | Product ID Param | Keyword Param | Category Param |
|---|
| Amazon | amz_site (AE/AU/BR/CA/DE/ES/FR/GB/IN/IT/JP/MX/SA/US) | asin | search_name | node_id |
| TikTok | site (US/GB/ID/JP/MY/PH/TH/VN) | product_id | — | node_id (⚠️ not category_id) |
| Shopee | site (MY/PH/VN/TH/ID/SG/TW/BR) | product_id | — | category_id |
| TEMU | site (US/EU) | product_id | — | category_id |
| Walmart | — (US only, no site param) | product_id | keyword | node_id |
| 1688 | — (China only) | product_id | — | — |
Amazon parameter name traps (3 different names for "marketplace"):
amz_site: 19 tools (product_search, product_detail, category_report, potential_product, etc.)keyword_support_site: 12 tools (keyword_detail, keyword_extends, keyword_search_results, keyword_list, etc.)site: 1 tool — product_customers_say (⚠️ exception to the Amazon convention)- All 14 Amazon sites verified in schema; SG is NOT in the enum (contrary to older docs).
Walmart Tool Usage Guide
Walmart marketplace parameter is always site, currently supports US. All Walmart tools prefixed with walmart_.
Core Query Tools:
| Tool | Required Fields | Optional Fields | Description |
|---|
walmart_keyword_search_results | keyword | page | Organic-ranking products (last 15 days) |
walmart_keyword_detail | keyword | — | Search volume/competition/avg price overview |
walmart_keyword_list | rank_min, rank_max | page | Hot keyword ranking (by monthly search volume) |
walmart_keyword_extends | keyword | page | Keyword expansion mining |
walmart_product_detail_by_product_id | product_id | — | Product detail (price/sales/rating/brand/attributes) |
walmart_product_traffic_terms | product_id | page | Reverse-lookup traffic keywords (with impression share/rank position) |
walmart_product_trend_by_product_id | product_id | trend_type, begin_date, end_date | Historical trends: SalesVolume/SalesAmount/Price/Rank/Reviews/Star |
walmart_product_variation_sales_by_product_id | product_id | begin_date, end_date, page | Child ASIN sales breakdown |
walmart_category_report_by_node_id | node_id | — | Real-time category Top 100 sales report |
Favorites Tools:
| Tool | Required Fields | Description |
|---|
walmart_favorite_keyword | keyword | Add keyword to favorites, optional dict for list name |
walmart_get_favorite_keyword | — | Query favorited keywords, optional dict (all for all) |
walmart_get_favorite_keyword_dict | — | Query favorites list names |
walmart_change_favorite_keyword | keyword, toDict | Move keyword to target list, optional fromDict |
walmart_del_favorite_keyword | keyword | Delete keyword, optional dict for specific list |
Key Field Notes:
trend_type enum values: SalesVolume / SalesAmount / Price / Rank / Reviews / Star — cannot use Chinese valuesrank_min/rank_max in walmart_keyword_list are required — server errors without themnode_id format: Walmart category IDs may contain underscores (e.g. 1072864_8490340), type string- Product detail's
NodeTree field can reverse-lookup category: ["Category Name", "node_id", "Date", "Rank"]
Known Limitations:
walmart_product_variation_sales_by_product_id: some products without variants return "no relevant data"walmart_category_report_by_node_id: invalid node_id returns "no relevant data" — extract valid IDs from NodeTree or search results- Favorites tools return "no relevant data" when keyword list is empty
VII. Gotchas
VIII. Tool Matrix
Complete tool list and counts in references/tool-matrix.md (auto-sync generated, always matches server).
Core frequently-used tools:
get_time, category_report, product_search, product_detail, product_reviews, product_variations, product_traffic_terms, keyword_detail, keyword_search_results, keyword_extends, potential_product, category_name_search, category_search_from_top_node, similar_product_feature, competitor_product_keywords, ali1688_similar_product, tiktok_category_report, tiktok_product_detail, sorftime_raw_call
Walmart core tools (14):
walmart_keyword_search_results, walmart_keyword_detail, walmart_keyword_list, walmart_keyword_extends, walmart_product_detail_by_product_id, walmart_product_traffic_terms, walmart_product_trend_by_product_id, walmart_product_variation_sales_by_product_id, walmart_category_report_by_node_id, walmart_favorite_keyword, walmart_get_favorite_keyword, walmart_get_favorite_keyword_dict, walmart_change_favorite_keyword, walmart_del_favorite_keyword
Walmart is US-only: none of the 15 Walmart tools have a site parameter — the marketplace is hardcoded to US. No parameter needed.
1688 is China-only: 5 tools, no site parameter. Factory-direct sourcing only.
TEMU currently supports US + EU only (2 sites). TEMU has the richest category-level filtering (40+ optional filter params on temu_category_search).
TikTok site availability varies: 8 sites in the schema, but VN returns "No data available" for category searches. GB/JP/ID/MY/PH/TH/US confirmed working.
IX. Cross-Platform Adaptation & Migration
This skill is cross-platform compatible, supporting macOS / Linux / Windows.
Environment Variables (Optional)
| Variable | Purpose | Default |
|---|
SORFTIME_MCP_KEY | MCP authentication key | Read from .env |
SORFTIME_CACHE_DIR | Cache/data directory | ~/.sorftime-cache (Windows: %LOCALAPPDATA%\sorftime-cache) |
SORFTIME_HTTP_TIMEOUT | MCP request timeout (seconds) | 30.0 |
SORFTIME_SCHEMA_AUTO_SYNC | Auto-sync Schema on startup | false |
SORFTIME_PROXY | HTTP proxy address | None |
SORFTIME_OUTPUT_DIR | Closed-Loop workflow output directory | ~/Documents/sorftime (macOS/Linux), %USERPROFILE%\Documents\sorftime (Windows) |
Migrating to a New Device
- Copy the skill directory to the new machine
- Ensure Python >= 3.10 is installed
- Run
python3 scripts/install.py to rebuild the virtual environment
- Provide
SORFTIME_MCP_KEY, or manually write to the skill root .env
Auto-Detected Agent Environments
Claude Code, OpenClaw, Cowork, Claude.ai Web, and other mainstream environments are auto-detected — no manual configuration needed.
Related Files
scripts/utils/platform_utils.py — Cross-platform utility functionsscripts/utils/version.py — Version managementrequirements.txt — Dependency list
