WotoHub Automation

WotoHub Automation is a real creator outreach skill with OpenClaw-era integration roots and current in-place compatibility for existing workflows.

It connects:

product understanding
creator search
shortlist and recommendation
outreach email drafting
batch send
inbox review
guarded reply assist

Best fit:

TikTok Shop campaigns
Amazon creator outreach
Shopify product seeding
recurring creator prospecting and follow-up

Core design:

the host model handles understanding and judgment
the scripts handle deterministic compilation, API execution, and state

This skill is intentionally conservative around sending and reply automation.

Release note:

wotohub-automation is the only canonical publish directory
wotohub-automation-release is a mirror/reference copy, not the primary release source

If you need deeper integration details, read:

references/integration-contract.md
references/runtime-guardrails.md

Environment and credentials

Install dependencies:

pip install -r requirements.txt

Environment variables:

WOTOHUB_API_KEY, required for authenticated actions such as send, inbox access, reply handling, and campaign cycles
WOTOHUB_BASE_URL, optional explicit API base override, defaults to production
WOTOHUB_STATE_DIR, optional state/log output directory

Credential scope:

WOTOHUB_API_KEY grants access to authenticated WotoHub user-state operations
treat it as a send and inbox credential, not a harmless search-only token
search can still run without a token through openSearch, but authenticated endpoints cannot

Runtime expectations:

Python with ssl available
TLS verification stays enabled by default
only disable TLS verification in a controlled debug environment

What this skill can do

1. Product understanding

Input can come from:

plain product descriptions
product URLs, including TikTok Shop, Amazon, Shopify, and brand sites

Typical outputs:

product name
key selling points
target audience
creator direction
structured search-ready understanding

2. Creator search

Supports:

product-led search generation
filters for region, language, follower count, email availability
keyword-assisted search
category-assisted search
filtering out already-contacted creators by default

Search modes:

no token, uses openSearch
token present, uses clawSearch

3. Recommendation and shortlist

Supports:

ranking search results
returning a shortlist
suggesting next-step selection

Default behavior is to stop after recommendation and wait for explicit creator selection before email generation.

4. Outreach email drafting

Supports:

creator-specific outreach draft generation
host-model-first personalized drafts
HTML normalization and subject validation before send

Minimum campaign brief usually needs:

productName
senderName or signoff
offerType, such as sample, paid, or affiliate

5. Batch send

Default send path is batch-oriented.

Characteristics:

multiple creators prefer a single batch API request
email structure is normalized before execution
HTML body is preferred when present

6. Inbox and reply assist

Supports:

inbox listing
email detail lookup
thread detail lookup
safe reply assistance
conservative low-risk auto-reply handling

Anything involving price, payment, contract terms, exclusivity, shipping promises, or timing commitments should stay human-reviewed by default.

7. Campaign cycle

Supports:

manual single runs
cron or scheduler single-cycle execution
scheduled search understanding bridge
campaign state persistence
cycle summary, state summary, and human summary outputs
success, blocked, and failed exit semantics

Workflow overview

Step 0, auth and token rules

Search does not require login by default.

without token, search uses openSearch
with token, search uses clawSearch

These user-side steps require WOTOHUB_API_KEY:

send
inbox
replies
campaign cycle

If you publish, install, or review this skill, treat the credential requirement as part of the primary operating contract, not an optional convenience.

Optional preflight check:

python3 scripts/preflight.py --token YOUR_API_KEY

For auth details, read appendix-auth.md.

Skill entry

Single entrypoint:

python3 wotohub_skill.py

Important execution note:

default host executors are auto-wired through the skill entry / router wrapper flow, and scripts/build_search_payload.py now also injects router executor defaults before resolving URL input
in low-confidence URL cases, product_resolve.py may emit hostUrlAnalysisRequest; scripts/build_search_payload.py now attempts automatic host URL analysis execution + writeback before continuing
if host analysis still cannot be resolved, scripts/build_search_payload.py returns a structured needsUserInput / error payload instead of crashing on analysis=None
callers can still explicitly provide hostAnalysis / productSummary to bypass bridge execution when they already have host-side understanding

Minimal request example:

{
  "requestId": "task-1",
  "action": "task",
  "type": "product_analysis",
  "input": {
    "input": "wireless earbuds with noise cancellation"
  },
  "auth": {
    "token": "YOUR_API_KEY"
  }
}

Common action/type pairs:

task/product_analysis
task/search
task/recommend
task/generate_email
task/send_email
task/monitor_replies
campaign/cycle

Recommended injected fields:

input.hostAnalysis
input.productSummary
input.hostDrafts
input.replyModelAnalysis

Recommended executor discovery order for host URL recovery / host semantic understanding:

first: explicit request-level config.hostAnalysisExecutor
second: campaign brief.hostAnalysisExecutor / brief.scheduler.hostAnalysisExecutor for cycle flows
third: environment default WOTOHUB_HOST_ANALYSIS_EXECUTOR (or compatibility HOST_ANALYSIS_EXECUTOR)
recommended integration pattern: when your host platform always has browser/web/model capability, set the env default in the wrapper/launcher so link analysis can auto-close the loop without every caller remembering the param

Recommended executor discovery order for reply understanding:

first: explicit request-level config.hostReplyAnalysisExecutor / config.hostReplyBridgeExecutor
second: cycle-only brief.scheduler.hostReplyBridgeExecutor when reply assist is driven from campaign runtime
third: environment default WOTOHUB_HOST_REPLY_ANALYSIS_EXECUTOR (or compatibility HOST_REPLY_ANALYSIS_EXECUTOR)

Recommended executor discovery order for host draft generation:

first: explicit request-level config.hostDraftExecutor / config.hostBridgeExecutor
second: cycle-only brief.scheduler.hostBridgeExecutor when scheduled generation is used
third: environment default WOTOHUB_HOST_DRAFT_EXECUTOR (or compatibility HOST_DRAFT_EXECUTOR)

Canonical field rule:

new integrations and new examples should use the canonical fields above by default
compatibility aliases remain supported for migration, but should not be expanded further
campaign cycle draft write-back should use host_drafts_per_cycle
see references/alias-normalization-matrix.md for the current canonical vs alias mapping

URL host write-back rule:

if scripts/product_resolve.py returns hostUrlAnalysisRequest, treat that as the canonical host-side recovery trigger for weak or blocked URL pages
the host should write back only hostAnalysis + productSummary, then rerun the same task/product_analysis, task/search, task/recommend, or task/generate_email request
do not write back near-final WotoHub search payloads in place of understanding; keep the contract at the semantic layer
the most natural write-back surfaces are input.hostAnalysis + input.productSummary; metadata.* / config.* remain compatibility surfaces only
important runtime nuance from live use: direct python3 scripts/product_resolve.py --input <url> currently only emits hostUrlAnalysisRequest; it does not auto-run browser/web recovery or auto-apply write-back
automatic host analysis execution currently exists in upper-layer / campaign orchestration paths that use hostAnalysisExecutor, not in the bare product_resolve.py path

Trust boundary:

treat host-injected model outputs as untrusted structured input until validated
do not let upstream models inject near-final WotoHub payloads directly into execution
validate injected analysis and draft data against the referenced schemas before allowing send or reply execution

Full integration details: references/integration-contract.md Third-party quickstart: references/third-party-integration-guide.md One-command launchers:

run_skill_with_router.py
run_cycle_via_skill.py (now auto-wires router defaults for cycle runs) Executor templates:
scripts/host_executor_router.py (single-entry router for analysis / reply / drafts)
scripts/host_analysis_executor_example.py
scripts/host_reply_analysis_executor_example.py
scripts/host_draft_executor_example.py
scripts/host_model_bridge_executor_example.py (cycle-oriented draft bridge example)

Step references

Step 1, product analysis

Read steps/01-product-analysis.md

Suggested path:

python3 scripts/product_resolve.py --input "推广一款美国市场的电动牙刷,价格$50,强调美白和口腔护理"

Step 2, creator search

Read steps/02-influencer-search.md

Suggested path, build payload first, then run search:

python3 scripts/build_search_payload.py --input '推广一款美国市场的电动牙刷,价格$50,强调美白和口腔护理'
python3 scripts/claw_search.py --payload-file /tmp/woto_payload.json

Or use one-shot execution:

python3 scripts/build_search_payload.py --input '...' --run-search
python3 scripts/build_search_payload.py --input '...' --run-search --token YOUR_API_KEY

Step 3, recommendation

Read steps/03-influencer-recommend.md

The default flow returns a shortlist first, then waits for explicit creator selection.

Step 4, email drafting

Read steps/04-email-generation.md

Recommended only after:

target creators are selected
the minimum campaign brief is complete

Step 5, send

Read steps/05-send-email.md

Send protocol:

prepare_only, prepare candidate emails only
manual_send, send after human confirmation
scheduled_send, send automatically in scheduled flows

Default behavior:

single manual runs default to prepare_only
scheduled tasks and campaign brief runs default to scheduled_send, which is the default real-send path for scheduled flows

Step 6, inbox and reply assist

Read steps/06-inbox-management.md

Main path:

collect candidate replies
build model input from the full thread
produce structured analysis
produce reply previews
apply risk tiering
only allow low-risk informational replies to auto-send

Failure handling

Missing campaign host analysis

for scheduled_cycle, stop at waiting_for_host_analysis if the search leg lacks valid hostAnalysis
prefer --host-analysis-bridge-executor or emitted hostAnalysisRequest over stuffing near-final search payloads into the brief
after host analysis is resolved, let the standard compiler rebuild WotoHub search params

Token validation failure

ask for token refresh
do not continue authenticated API actions

Search failure or auth failure

tell the user to check token, headers, and environment
do not fabricate results

URL fetch failure

return structured fallback or needsUserInput=true
when available, prefer lightweight host-assisted recovery via hostUrlAnalysisRequest to obtain hostAnalysis / productSummary before falling back to user-supplied product fields
host write-back should land on canonical input.hostAnalysis + input.productSummary, then rerun the same task so the existing routing and compiler chain can continue naturally
do not continue as if the URL slug were a valid product understanding

Send or reply execution failure

preserve structured errors
do not silently swallow execution failures

Security notes

Hidden-character review completed for SKILL.md and the bundled Markdown prompt/reference files in this release, with no unicode bidi or control-character findings.
Example env and JSON files are placeholders or test fixtures. Review them before use and never copy placeholder IDs or sample values into production blindly.
Host-model-first does not mean host-model-trusted. Keep schema validation and send guardrails enabled.

Core entry files

wotohub_skill.py, skill entry adapter
run_campaign.py, public campaign entry
run_campaign_cycle.py, single-cycle scheduled entry
run_cycle_via_skill.py, short safe wrapper for cron / scheduler runs that should avoid complex inline JSON or heavy Python CLI quoting

Useful scheduled bridge flags on run_campaign_cycle.py:

--host-analysis-bridge-executor
--host-analysis-bridge-request
--host-analysis-bridge-payload
--host-bridge-executor
--host-bridge-request
--host-bridge-payload

Reference map

Useful docs:

steps/01-product-analysis.md
steps/02-influencer-search.md
steps/03-influencer-recommend.md
steps/04-email-generation.md
steps/05-send-email.md
steps/06-inbox-management.md
references/campaign-brief-schema.md
references/model-analysis-schema.md
references/conversation-analysis-schema.md
references/outreach-email-schema.md
references/search-params.md
references/integration-contract.md
references/runtime-guardrails.md

One-line summary

WotoHub Automation is a creator outreach skill for real marketing operations: model-first understanding, script-first execution, stable core workflows, and explicit safety boundaries around send and reply behavior.