product-research（product 研究）

Purpose

Identify product opportunities by combining:

1. social momentum,
2. regional demand checks,
3. marketplace competition/sales signals,
4. store deployment readiness.

This is an orchestration skill. It does not guarantee profitability.

Required Installed Skills

• tavily-search (inspected latest: 1.0.0)
• goplaces (inspected latest: 1.0.0)
• api-gateway (inspected latest: 1.0.29)
• Deployment target:

- woocommerce via api-gateway (supported), or - shopify (inspected latest 1.0.1, currently under maintenance)

Install/update:

npx -y clawhub@latest install tavily-search
npx -y clawhub@latest install goplaces
npx -y clawhub@latest install api-gateway
npx -y clawhub@latest install shopify
npx -y clawhub@latest update --all

Verify:

npx -y clawhub@latest list

Required Credentials

• TAVILY_API_KEY (trend and web data collection)
• GOOGLE_PLACES_API_KEY (regional demand proxy via goplaces)
• MATON_API_KEY (market/deployment APIs via api-gateway)

Preflight:

echo "$TAVILY_API_KEY" | wc -c
echo "$GOOGLE_PLACES_API_KEY" | wc -c
echo "$MATON_API_KEY" | wc -c

Mandatory behavior:

• Never fail silently on missing keys.
• Always return MissingAPIKeys with missing variables and blocked stages.
• Continue with non-blocked stages and mark output as Partial when needed.

Inputs the LM Must Collect First

• product_niche (example: pets)
• target_region (country/city scope)
• target_store (woocommerce or shopify)
• risk_tolerance (low, medium, high)
• max_cogs (maximum source cost)
• min_margin_target (percentage)
• shipping_time_limit_days
• ad_angle (problem-solution, UGC demo, before-after)

Do not propose deployment before constraints are explicit.

Tool Responsibilities

tavily-search

Use for trend and sourcing discovery:

• find viral product mentions and trend lists,
• gather social evidence summaries,
• locate supplier listings (AliExpress/Alibaba/web catalogs),
• extract competitor storefront/product page signals.

goplaces

Use for regional demand proxy checks:

• query related local businesses/search entities,
• compare demand-like signals across cities/regions,
• support geo-prioritization for launch/testing.

Important limitation:

• goplaces is a Places API interface, not direct social trend telemetry.
• Treat it as location demand context, not a standalone trend oracle.

api-gateway

Use for structured market and store operations when connections exist:

• marketplace/analytics connectors if available in user account,
• WooCommerce product draft creation,
• optional Search Console-like enrichment if connected.

Operational constraints from inspected skill:

• requires MATON_API_KEY
• requires active per-app OAuth connections (ctrl.maton.ai)
• API key alone is not sufficient

Capability disclosure:

• woocommerce is explicitly listed in inspected api-gateway references.
• shopify inspected skill is currently under maintenance and may be unavailable.
• helium 10 and jungle scout are not explicitly listed as native api-gateway app names in the inspected version.

Canonical Causal Signal Chain

1. Trend Scan (tavily-search)

• discover products with strong recent social momentum.
• candidate example pattern: "TikTok made me buy it" + niche + last 7 days.

1. Social Evidence Scoring

• score each candidate by recency, source diversity, and repeat mention frequency.
• require at least 2 independent sources for shortlisting.

1. Regional Demand Check (goplaces)

• check target-region relevance proxies.
• prioritize products with cross-region consistency, not one-off spikes.

1. Market Data Gate (api-gateway)

• attempt sales/competition metrics via connected provider.
• if Helium 10/Jungle Scout path is unavailable, trigger explicit gate message and fallback mode.

Required gate format:

• DataGateStatus: available or blocked
• Reason: missing key / missing connection / provider unsupported
• Action: exact remediation steps and link

If user requests Helium 10 discount onboarding:

• include user-provided affiliate URL when available,
• otherwise use placeholder explicitly as user action item: [HELIUM10_LINK_OR_COUPON].

If user requests Jungle Scout onboarding:

• include user-provided affiliate URL when available,
• otherwise use placeholder: [JUNGLESCOUT_LINK_OR_COUPON].

1. Sourcing Check (tavily-search)

• find supplier options,
• compare estimated COGS and shipping windows,
• flag risky supplier signals (unclear shipping, no ratings, poor consistency).

1. Deployment

• WooCommerce path: create product draft via api-gateway woocommerce endpoints.
• Shopify path: if unavailable/maintenance, emit blocked deployment status and WooCommerce/manual fallback package.

1. Creative Output

• generate product listing copy,
• generate one TikTok ad script matched to selected angle.

Output Contract

Always return:

• TrendCandidates

- shortlisted products - evidence score and sources

• MarketCheck

- competition/sales insight - DataGate status and provider path used

• SourcingTable

- supplier options - estimated COGS - shipping-time estimate - risk notes

• StoreDraft

- title - product description - key benefits - price suggestion - draft payload for woocommerce or shopify (if available)

• TikTokAdScript

- hook (first 2 seconds) - demo beats - CTA

• NextActions

- exact steps to publish and test

Quality Gates

Before final output, verify:

• trend evidence is recent and source-backed
• product economics satisfy user constraints
• deployment path is real (not assumed)
• unsupported integrations are explicitly disclosed
• missing keys/connections are clearly reported

If any gate fails, return Needs Revision with missing evidence/dependency list.

Failure Handling

• Missing TAVILY_API_KEY: return MissingAPIKeys, skip trend/sourcing web stages, ask for seed product URLs.
• Missing GOOGLE_PLACES_API_KEY: return MissingAPIKeys, skip regional-demand stage.
• Missing MATON_API_KEY: return MissingAPIKeys, skip gateway market/deployment stages.
• Missing api-gateway app connection (HTTP 400): keep pipeline running in analysis mode and provide connection setup steps.
• Shopify unavailable (maintenance): mark deployment as blocked and provide WooCommerce/manual import fallback.
• Helium 10/Jungle Scout unavailable via gateway: disclose unsupported provider path and continue with proxy competition analysis.

Guardrails

• Never claim a product is guaranteed to win.
• Never fabricate sales volume, margins, or review counts.
• Never hide blocked provider paths.
• Keep recommendations tied to observed evidence and declared assumptions.