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)
2. discover products with strong recent social momentum.

3. candidate example pattern: "TikTok made me buy it" + niche + last 7 days.

4. Social Evidence Scoring

5. score each candidate by recency, source diversity, and repeat mention frequency.

6. require at least 2 independent sources for shortlisting.

7. Regional Demand Check (goplaces)

8. check target-region relevance proxies.

9. prioritize products with cross-region consistency, not one-off spikes.

10. Market Data Gate (api-gateway)

11. attempt sales/competition metrics via connected provider.
12. 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)
2. find supplier options,
3. compare estimated COGS and shipping windows,

4. flag risky supplier signals (unclear shipping, no ratings, poor consistency).

5. Deployment

6. WooCommerce path: create product draft via api-gateway woocommerce endpoints.

7. Shopify path: if unavailable/maintenance, emit blocked deployment status and WooCommerce/manual fallback package.

8. Creative Output

9. generate product listing copy,
10. 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.