client-finder/SKILL.md

---
name: client-finder
description: "找客户、找买家、开发客户、cold outreach。当用户说"帮我找XX客户"、"找XX买家"、"开发XX客户"、"find clients for XX"时使用此 skill。通过 Google Maps 搜索目标行业的潜在客户，自动获取联系方式（邮箱/电话/网站），完成后自动触发邮件编写。"
---

# Client Finder

Skill-credit + ecom run-flow: query expansion → `/ecom/cold-outreach/run-flow`.
Execution mode is fire-and-return: start workflow fast and return accepted immediately; terminal callbacks are handled by backend webhook delivery.

> Auth (CLIENT_KEY) is loaded automatically from `~/.openclaw/.env` by auth-runtime. No need to pass it.

## Run Skill

```bash
<skill-dir>/scripts/cliet-finder.sh "office machine" "us"
```

Optional: provide LLM-generated query expansion JSON:

```bash
QUERY_EXPANSION_JSON='{"expandedQueries":["office machine supplier us","office equipment distributor us"],"primaryQuery":"office machine supplier us"}' \
<skill-dir>/scripts/cliet-finder.sh "office machine" "us"
```

Dry-run (no network calls):

```bash
<skill-dir>/scripts/cliet-finder.sh "office machine" "us" --dry-run
```

## Required Inputs

- `query` (string)
- `country` (optional, default `us`)

Optional:

- `QUERY_EXPANSION_JSON` (optional LLM expansion input)

## Reference

Load and follow [references/cliet-finder.md](references/cliet-finder.md) as the detailed workflow spec.
For expansion behavior, also follow [references/query-expansion-spec.md](references/query-expansion-spec.md).
For client onboarding and billing flow (Chinese), read [how-to-use.md](how-to-use.md).

## Execution Checklist

1. Normalize input query.
- Trim whitespace.
- Remove leading `cold-outreach:` prefix (case-insensitive).

2. Exchange runtime token.
- auth-runtime handles this automatically via `~/.openclaw/.env`.
- Calls `POST /auth/skill-credit/session` with `CLIENT_KEY`, caches token with TTL.

3. Expand query.
- Build candidate queries from skill logic (`rule`) or `QUERY_EXPANSION_JSON` (`llm`).
- Select one `primaryQuery`.
- Fallback policy: if expansion fails, use normalized raw query as `primaryQuery` and continue.

4. Execute workflow.
- Call `POST /ecom/cold-outreach/run-flow` with runtime `accessToken`:
  - `query` = `primaryQuery`
  - `country`
- Require `workflowId` in response.

5. Return accepted immediately.
- Return JSON with `workflowStatus = "accepted"` and `workflowId`.
- Backend pushes terminal callback to webhook bound on the client key.

## Output Contract (Strict)

- Final answer must be JSON only. No prose, no markdown table, no repeated preface.
- Follow `output_schema.json` exactly.
- `error` is `null` when success; short string when failed.
- If fallback is used, populate:
  - `expansionStatus = "failed"`
  - `expansionSource = "raw_query"`
  - `usedFallbackQuery = true`
  - `expansionError` with short reason

## Constraints

- Use this skill for query expansion + `/ecom/cold-outreach/run-flow` orchestration only.
- Do not trigger `/mail/compose` or any mail compose flow in this skill.
- Do not implement local monitor, local finalize, or local hook event emission.