Skill: noxinfluencer/nox-influencer-marketing (version 0.1.9)

--- name: noxinfluencer description: Runs NoxInfluencer creator and marketing-ops workflows via CLI, including creator discovery for influencer marketing, creator marketing, UGC, social media marketing, and affiliate marketing; creator evaluation, contact retrieval, video tracking, campaigns, collections, CRM channels, email/message tasks, brand monitoring, and exports. Use when the user needs NoxInfluencer creator discovery, creator evaluation, outreach operations, campaign/collection operations, brand monitoring, or account setup. metadata: {"openclaw":{"requires":{"env":["NOXINFLUENCER_API_KEY"],"bins":["noxinfluencer"]},"primaryEnv":"NOXINFLUENCER_API_KEY","install":[{"kind":"node","package":"@noxinfluencer/cli","bins":["noxinfluencer"]}],"homepage":"https://www.noxinfluencer.com/skills"}} --- # NoxInfluencer Full-workflow creator and marketing-ops skill for influencer discovery, due diligence, outreach-ready contact retrieval, campaign video monitoring, campaign/collection operations, CRM/email/message operations, brand monitoring, and exports across YouTube, TikTok, and Instagram. The user interacts through natural language. Execute CLI commands yourself and report results in plain language. Never expose raw commands to the user. ## When to Use - User wants to find, evaluate, or contact creators / influencers / KOLs - User wants NoxInfluencer campaign, collection, CRM, email/message, export, or brand-monitor operations - User needs to set up NoxInfluencer access or check quota - User wants to monitor video campaign performance - User hits an auth, quota, or CLI error ## What This Skill Does Not Do - Draft outreach emails, negotiation copy, or partnership messages from scratch - Send email/message tasks or update CRM records without explicit user approval - Make final campaign budget allocation, media-plan, or partnership decisions - Generate creative briefs or interpret video content beyond available platform metrics - Operate external CRM, email, messaging, spreadsheet, or ad platforms outside NoxInfluencer - Replace legal or commercial review of contracts, disputes, or brand-safety decisions ## Core Principles ### Agent-First The user does not operate the CLI. You do. Run commands silently, tell the user the result. Only share URLs when the user needs to take action in a browser (register, get a key, subscribe). ### CLI Self-Description The CLI is self-describing — use it instead of memorizing parameters: - **Parameters**: `noxinfluencer schema <cmd>` (e.g., `schema creator.search`; quoted path form `schema 'creator search'` also works) - **Help**: `noxinfluencer <cmd> --help` - **Diagnostics**: `noxinfluencer doctor` - **Command-tree check**: `noxinfluencer schema --all` must include `campaign`, `collection`, `email`, `message`, `crm`, `brand-monitor`, `export`, and `agent` - **Exit codes**: `noxinfluencer agent exit-codes` - **Preview**: `--dry-run` (shows request without executing) - **Language routing**: `--lang zh` switches all URLs to `cn.noxinfluencer.com` ## Command Quick Reference | User intent | CLI command | |-------------|-------------| | Search creators | `noxinfluencer creator search` | | Creator overview / links | `noxinfluencer creator profile [creator_id]` or first-call `--url` / `--platform --channel-id` | | Audience analysis | `noxinfluencer creator audience [creator_id]` or first-call `--url` / `--platform --channel-id` | | Content analysis | `noxinfluencer creator content [creator_id]` or first-call `--url` / `--platform --channel-id` | | Cooperation / pricing signals | `noxinfluencer creator cooperation [creator_id]` or first-call `--url` / `--platform --channel-id` | | Get contact info | `noxinfluencer creator contacts [creator_id]` or first-call `--url` / `--platform --channel-id` | | Check quota | `noxinfluencer quota` | | Check setup health | `noxinfluencer doctor` | | Check membership plans | `noxinfluencer pricing` | | Inspect exact flags | `noxinfluencer schema <cmd>` | | List monitoring projects | `noxinfluencer monitor list` | | Create monitoring project | `noxinfluencer monitor create` | | Add monitored video | `noxinfluencer monitor add-task` | | List monitored videos | `noxinfluencer monitor tasks` | | Get task-level history points | `noxinfluencer monitor history` | | Get project summary | `noxinfluencer monitor summary` | | Campaign list / detail / dashboard | `noxinfluencer campaign list`, `campaign get`, `campaign dashboard` | | Create or update campaign | `noxinfluencer campaign create`, `campaign update` | | Collection list / detail / items | `noxinfluencer collection list`, `collection get`, `collection items` | | Collection batch operations | `noxinfluencer collection batch-* validate/preview/apply` | | Refresh / unlock collection data | `noxinfluencer collection refresh-* validate/preview/apply`, `collection unlock-audience` | | Add collection to NoxInfluencer CRM | `noxinfluencer collection add-to-crm validate/preview/apply` | | CRM channel operations | `noxinfluencer crm list`, `crm get`, `crm update`, `crm groups ...` | | Email task operations | `noxinfluencer email list`, `email get`, `email create`, `email send`, `email schedule` | | Message thread operations | `noxinfluencer message list`, `message get`, `message draft`, `message send`, `message schedule` | | Brand monitor overview | `noxinfluencer brand-monitor list`, `brand-monitor get` | | Brand competition / strategy reads | `noxinfluencer brand-monitor competition-matrix`, `cooperate-matrix`, `influencer-portrait`, `defense-gap` | | Brand product signals | `noxinfluencer brand-monitor product-*` | | Brand assets / exports | `noxinfluencer brand-monitor influencer-list`, `content-list`, `tag-list`, `product-list`, `*-export` | | Export task status / download | `noxinfluencer export list`, `export get`, `export download` | | Stable automation exit codes | `noxinfluencer agent exit-codes` | Add `--detail` for expanded creator analysis when the user needs deeper evidence. Add `--lang zh` for Chinese users. Use `schema <cmd>` when you need exact flags or required fields. If the user does not already have a `creator_id`, the first read call may use `--url` or `--platform --channel-id`; after that, prefer the returned `data.creator_id`. All creator read responses include a unified creator identity block: `creator_id`, `creator_name`, `channel_handle`, `channel_url`, and `social_media`. `monitor add-task` and `monitor tasks` may also expose `creator_id`, `creator_name`, `channel_handle`, and `channel_url` for the monitored creator when the upstream task data includes them. For marketing-ops commands, many workflows are JSON-first and use `--body-file`. Mutations default to dry-run; only use `--force` after the user has explicitly approved the target object and the action. See `{baseDir}/references/marketing-ops.md` and `{baseDir}/references/brand-monitor.md`. --- ## 1. Getting Started Run `noxinfluencer doctor` first, then `noxinfluencer schema --all` to verify the current command tree. Guide through only what's missing: 1. **No CLI installed or stale command tree** → Tell user to run `npm install -g @noxinfluencer/cli@latest` in their terminal. Treat the install as stale if `schema --all` does not include the 0.4+ command groups: `campaign`, `collection`, `email`, `message`, `crm`, `brand-monitor`, `export`, and `agent`. If reinstalling the latest npm package still lacks those command groups, stop marketing-ops workflows and report a CLI package / command-tree mismatch instead of retrying the same command. In the same reply, directly provide the browser steps they must do themselves: - English register: `https://www.noxinfluencer.com/signup?userType=brand&service=%2Fskills%2Fdashboard` - English API key: `https://www.noxinfluencer.com/skills/dashboard` - Chinese register: `https://cn.noxinfluencer.com/signup?userType=brand&service=%2Fskills%2Fdashboard` - Chinese API key: `https://cn.noxinfluencer.com/skills/dashboard` Prefer a host-provided secret first: `skills.entries.noxinfluencer.apiKey` in OpenClaw maps to `NOXINFLUENCER_API_KEY`. If no secret channel is available, ask for a one-time handoff only through the safest available channel, then configure with `noxinfluencer auth --key-stdin` rather than putting the key in argv, logs, or echoed messages. 2. **CLI installed, no API key** → Check whether `NOXINFLUENCER_API_KEY` / `skills.entries.noxinfluencer.apiKey` is already available before asking for manual input. Run `doctor` and prefer CLI-provided hints / URLs. Only fall back to the static register + API key links above if the CLI output is incomplete. 3. **Everything configured** → Run `quota`, tell them the current Skill quota snapshot and any obvious blocking issues. ### Quota and Billing Run `quota` yourself and report the current Skill quota snapshot. Important: - Any API-backed skill call can consume the account's remaining Skill quota - The same call may also depend on underlying SaaS-side quota or entitlement for that capability - A request can therefore fail because Skill quota is exhausted, or because the underlying SaaS quota / permission is unavailable If quota is low or exhausted, the error response's `action` field includes the billing URL. Pass it to the user. --- ## 2. Discovering Creators Turn an open-ended search into a usable shortlist. ### Clarification Strategy Do not search immediately if the request is too broad. Ask for 2–3 critical filters at a time: 1. **Platform** — YouTube, TikTok, or Instagram? 2. **Niche / keywords** — what content area? 3. **Region** — which countries or markets? 4. **Creator size** — follower range? 5. **Contactability** — does email availability matter? Stop asking once the request is specific enough. If the user provided most filters upfront, search directly. ### Search Execution Use `noxinfluencer schema creator.search` to discover available filter parameters. The quoted single-argument form `noxinfluencer schema 'creator search'` is equivalent. Key decisions: - Multi-platform requests require separate searches per platform - Add `--has_email true` when the user's intent is commercial outreach - Start with one search, refine if results are too noisy - For "show more", "next page", "继续", or similar follow-ups, rerun the same search with the next `page_num` and the prior response's `data.search_after`; prefer `--body-file -` with a JSON body so the cursor array is passed exactly. If using flags, shell-quote `--search_after` and every bracketed array filter. If there is no cursor or the last page was already reached, say there are no more results See `{baseDir}/references/search-filters.md` for filter selection semantics by user intent. ### Shortlist Presentation Present results as a visible, comparable shortlist — not a raw JSON dump. For each candidate: nickname, platform, followers, engagement rate, average views, country, top tags. Rules: - 3–5 candidates first - Make rows easy to compare at a glance - If results are noisy, say so and ask for one more narrowing filter - State if `--has_email true` was used, but do not imply email was already retrieved - Include: why candidates match, filters applied, the next-step suggestion, and remaining Skill quota when the response includes it and it changes the user's next decision --- ## 3. Analyzing Creators Help the user decide whether a creator is worth pursuing. Lead with a verdict, not a wall of numbers. ### Workflow 1. Confirm which creator to analyze (prefer `creator_id` from prior search or a prior read response; if absent, the first read call may use `--url` or `--platform --channel-id`). 2. If user asked about a specific concern, check that dimension first. 3. If the user only needs channel or social links, run `creator profile` first; it may already return the unified creator identity block, including `channel_url` and `social_media`. 4. If no specific concern, follow default order: profile → audience → content → cooperation (all with `--detail` flag). 5. Platform-aware skip: TikTok and Instagram often have partial cooperation/pricing data. Skip `creator cooperation --detail` unless the user explicitly asks for pricing or brand-history signals, or the primary platform is YouTube. See `{baseDir}/references/platform-support.md`. 6. For content analysis in Chinese context, add `--language zh`. 7. Return verdict first, then supporting evidence. Use `noxinfluencer schema creator.<dimension>` (e.g., `schema creator.profile`). The quoted single-argument form (for example `schema 'creator profile'`) is equivalent. ### Verdict Framework Always lead with one of these four conclusions: 1. **High-priority collaboration candidate** — no dispute signal, healthy audience, competitive performance, no pricing friction 2. **Viable, but with clear risks** — workable overall, 1–2 notable concerns 3. **Needs manual review before proceeding** — mixed evidence or data incomplete 4. **Not a priority collaboration candidate** — multiple weak signals See `{baseDir}/references/verdict-heuristics.md` for detailed heuristic rules and output structure. ### Interpretation Rules - Dispute history and negative cooperation signals are decision-critical — always surface them. - Benchmark position is context, not the sole determinant. - Evaluate pricing relative to performance, audience quality, and cooperation signals. - When evidence is mixed, prefer "Needs manual review" over false confidence. - When only one dimension was checked, present as a scoped judgment, not a full verdict. ### Escalation Rules - One bad dimension → explain the tradeoff, don't force a hard reject. - Multiple weak dimensions → clear cautionary verdict. - User asks about one dimension → stay focused, but mention obvious red flags. --- ## 4. Retrieving Contacts Retrieve contact info for a specific creator. Intentionally narrow — gets contact data, nothing more. 1. Confirm which creator (prefer `creator_id` from prior search or a prior read response; if absent, the first read call may use `--url` or `--platform --channel-id`). 2. Run the contacts command. 3. Return only the contact info and quality signal. ### Quality Interpretation | `email_quality` | Meaning | |-----------------|---------| | `1` | High-quality contact signal | | `2` | Normal contact signal | | `0` | Low-confidence or unverified contact signal | If email is null, clearly say no reliable email is currently available. If email exists but quality is `0`, return it with cautionary wording and tell the user it needs manual verification. Do not add outreach recommendations or restate creator metrics. --- ## 5. Tracking Performance Manage video monitoring projects and tracked videos. Operational only — manages monitoring, not performance judgment. ### Workflow 1. List projects first when the target project is unclear. 2. Create a project when user wants a new one. 3. If user wants to create AND monitor in one request, create first then add task. 4. For project overview, use summary. 5. For specific videos, use task list. 6. When the user needs day-by-day or hour-by-hour performance for one monitored video, first use `monitor tasks` to identify the `task_id`, then use `monitor history`. Use `noxinfluencer schema monitor.<subcommand>` for parameter details. Write operations default to dry-run — use `--force` to execute. ### Project Identification - Prefer `project_id` over `project_name` after the first lookup. - If project names collide, show disambiguation: project_id, name, created time, platforms, monitor count. - Once a project is selected, keep using that `project_id` until user switches. ### Output Rules - Project lists: name, project_id, platforms, monitor count - Summaries: monitor count, total views/likes/comments, avg engagement, platform breakdown - Task lists: creator name, video title, views, engagement rate, status; include `creator_id`, `channel_handle`, and `channel_url` when present - Task history: task_id, granularity, latest metrics, and ordered history points from `data.items` - Do not turn outputs into performance verdicts If `monitor add-task` or `monitor tasks` returns `creator_id`, preserve it for later creator read follow-ups instead of asking the user to search again. ### Status Codes | Status | Meaning | |--------|---------| | `loading` | Initializing | | `monitoring` | Actively collecting data | | `completed` | Monitoring period ended | | `video restricted` | Video unavailable | | `invalid link` | URL could not be resolved | --- ## 6. Marketing Ops Operate NoxInfluencer campaign, collection, CRM, email, message, and export workflows. Stay operational: retrieve state, prepare changes, preview impact, then apply only after approval. ### Workflow 1. Identify the target domain: campaign, collection, CRM channel/group, email task, message thread, or export. 2. Read current state first when the target ID is unclear (`list`, `get`, `dropdown`, `dashboard`, or equivalent). 3. For first email outreach to known creator email addresses, use the email-task path: `email create` → `email recipients add/replace` → `email content save` → `email sender update` if needed → `email send` or `email schedule`. Do not require a message thread or CRM channel for this path. 4. Use `message send` or `message schedule` only for existing `thread_id` replies. If the user gives an email task ID, resolve it with `message list --business_kind email_task --business_id <task_id>` before `message get`. If no thread exists, offer the email-task path when reliable email addresses are available. 5. For JSON-first commands, run `schema <cmd>` and prepare the minimal `--body-file` object required by the CLI. 6. For staged workflows, run `validate` first, then `preview`, then `apply --force` only after user approval. 7. For direct mutations such as `create`, `update`, `delete`, `send`, `schedule`, `archive`, or `restore`, rely on dry-run first unless the user has already approved the exact action. 8. For async exports, create the export task, poll with `export get` or `export list`, then download with `export download --output` only when ready. Do not draft outreach copy. If the user asks to send or schedule an email task or message, confirm the task/thread, recipients, sender, scheduled time, and content are already approved. See `{baseDir}/references/marketing-ops.md` for domain routing, mutation guardrails, and export handling. --- ## 7. Brand Monitoring Use brand-monitor commands for owned/competitor brand analysis and brand asset exports. This is distinct from creator due diligence: it starts from `brand_id`, not `creator_id`. ### Workflow 1. List or get brand monitors when `brand_id` is unclear. 2. Use matrix/strategy reads for brand-level analysis: competition, cooperation, influencer portrait, defense gap, and product signals. 3. Use asset list commands for raw influencer/content/tag/product rows; these are JSON-first and usually require `--body-file`. 4. Product signal commands currently support YouTube only. Do not run them for TikTok or Instagram unless the CLI schema later shows support. 5. Use export commands for downloadable brand assets; follow up through shared `export` commands. 6. Treat `add`, `unlock-base`, `unlock-high`, and all `*-export` commands as mutations or async job creation: dry-run first, `--force` only after approval. See `{baseDir}/references/brand-monitor.md` for command routing and platform boundaries. --- ## Workflow Routing | User intent | Start with | |-------------|-----------| | Find creators, broad sourcing | § 2. Discovering Creators | | Evaluate a specific creator | § 3. Analyzing Creators | | Get email or contact details | § 4. Retrieving Contacts | | Set up monitoring for a video | § 5. Tracking Performance | | Manage campaigns, collections, CRM, email/message tasks, or exports | § 6. Marketing Ops | | Analyze or export brand-monitor data | § 7. Brand Monitoring | | Setup, quota, billing, errors | § 1. Getting Started | Natural progression: discover → analyze → contact → monitor → operate. But users can enter at any point. ## Error Handling For API-backed failures (`quota`, `pricing`, `creator`, `monitor`, `campaign`, `collection`, `email`, `message`, `crm`, `brand-monitor`, `export`), use the CLI response's `action` field when present: - `action.url` — where the user should go - `action.hint` — what to do Local/helper commands (`auth`, `doctor`, `schema`, `env`, `agent exit-codes`) may not include `action`. Read their native output directly instead of assuming the API error envelope. For unexpected failures, run `doctor` as a first diagnostic step. ## References - `{baseDir}/references/cli-response-format.md` — response envelope differences and error action handling - `{baseDir}/references/marketing-ops.md` — campaign, collection, CRM, email/message, export workflows and mutation guardrails - `{baseDir}/references/brand-monitor.md` — brand monitor routing, YouTube-only product signals, export boundaries - `{baseDir}/references/platform-support.md` — data availability by platform - `{baseDir}/references/search-filters.md` — filter selection by user intent - `{baseDir}/references/verdict-heuristics.md` — detailed due-diligence rules and output structure

path: references/marketing-ops.md
content: # Marketing Ops Workflows

Use this reference for NoxInfluencer campaign, collection, CRM, email, message, and export operations. Keep command parameters runtime-discovered with `noxinfluencer schema <cmd>`.

## Domain Routing

| User intent | Start with |
|-------------|------------|
| Find or inspect campaigns | `campaign list`, `campaign get`, `campaign dashboard`, `campaign dropdown` |
| Create or change campaign skeleton data | `campaign init`, `campaign create`, `campaign update`, `campaign delete` |
| Find or inspect collections | `collection list`, `collection get`, `collection items`, `collection resources` |
| Batch move/copy/delete/label collection members | `collection batch-* validate`, then `preview`, then `apply` |
| Refresh collection base/email data or unlock audience | `collection refresh* validate`, then `preview`, then `apply` |
| Add one whole collection and platform slice to CRM | `collection add-to-crm validate`, then `preview`, then `apply` |
| Query or update NoxInfluencer CRM channels | `crm list`, `crm get`, `crm update`, `crm groups ...` |
| Send first email outreach to known creator emails | `email create`, then `email recipients add/replace`, `email content save`, optional `email sender update`, then `email send` or `email schedule` |
| Manage email tasks | `email list`, `email drafts`, `email get`, `email create`, `email update`, `email recipients ...`, `email content ...`, `email sender ...` |
| Send or schedule an existing email task | `email send`, `email schedule`, `email cancel` |
| Manage message threads | `message list`, `message get`, `message projects`, `message labels`, `message coop ...`, `message draft ...` |
| Send or schedule an existing message reply | `message send`, `message schedule`, `message cancel` |
| Inspect or download async exports | `export list`, `export get`, `export download` |

## Outreach Routing

- If the user has reliable creator email addresses from `creator contacts`, use the email-task path. Create or select an email task, add explicit recipients with `email recipients add/replace`, save user-approved content with `email content save`, set sender if needed, read back task and recipients, then ask for final approval before `email send --force` or `email schedule --force`.
- If the user wants in-platform DM/message, `message send` and `message schedule` require an existing `thread_id`. If the user only has an email task ID, use `message list --business_kind email_task --business_id <task_id>` to resolve the thread first. Without a thread, say that starting a new message thread is not exposed by the CLI and offer the email-task path if email contacts exist.
- `crm add-to-email` is only for adding existing NoxInfluencer CRM channels to an existing email task. Do not treat CRM as required when the user already has explicit email addresses.

## CRM Update Semantics

- `crm update` / `crm batch-update` may auto-create a NoxInfluencer CRM channel for valid platform `creator_id` tokens when updating cooperation status or labels. For label-only updates, the service uses the default cooperation status before applying labels.
- Owner-only or archive-only updates do not auto-create CRM channels. Treat missing-channel failures as real failures, not successful skips.
- For batch previews and applies, report `existing_count`, `will_create_count`, and `created_count` when present; do not infer success only from requested IDs.

## Mutation Rules

- Write commands default to dry-run. Treat dry-run output as a preview, not completion.
- Use `--force` only after the user has approved the exact object and action.
- For staged workflows, always run `validate` before `preview`, and `preview` before `apply --force`.
- For `send` and `schedule`, confirm the task/thread, recipient scope, sender identity, scheduled time when relevant, and content approval before execution.
- Do not draft outreach or negotiation copy. If content is missing, ask the user for approved content or hand off to a writing task without invoking NoxInfluencer write commands.
- Do not operate external CRM, email, messaging, or spreadsheet platforms. These commands only affect NoxInfluencer-owned objects.

## JSON-First Commands

Many marketing-ops commands intentionally keep complex selectors in JSON bodies. When a schema requires `--body-file`:

1. Run `noxinfluencer schema <cmd>` to inspect required fields and usage notes.
2. Prepare the minimal JSON body needed for the user's request.
3. Prefer the CLI's validate/preview stages when available.
4. Preserve stable opaque IDs from responses (`campaign_id`, `collection_id`, `creator_id`, `thread_id`, `task_id`, `export_id`) for follow-up calls.

## Export Handling

- Export creation is async and usually returns `export_id`.
- Poll with `export get` or inspect with `export list`.
- Only run `export download <export_id> --output <path>` when the export is ready.
- Download writes binary data to the requested file path, not stdout. Report the output path and file metadata after completion.


path: references/verdict-heuristics.md
content: # Verdict Heuristics Reference

Detailed heuristic rules and output structure for creator due-diligence verdicts.

## Verdict Levels

### 1. High-priority collaboration candidate

All of the following hold:

- No meaningful dispute signal
- Audience quality is healthy (authenticity status is positive, no suspicious audience dominance)
- Performance is competitive for the niche (benchmark rank is above median)
- Pricing and cooperation signals do not show obvious friction (reasonable response time, acceptable pricing range)

### 2. Viable, but with clear risks

Overall profile is workable, but one or two notable concerns exist:

- Weak cooperation signals (low cooperation score, few brand partnerships)
- Performance volatility (high wave value, inconsistent engagement)
- Questionable pricing efficiency (large gap between first and final price)
- Audience demographic mismatch for the stated campaign goal

### 3. Needs manual review before proceeding

The evidence is mixed and a firm recommendation would be misleading:

- Commercial reasonableness cannot be judged confidently from available data
- One critical dimension is unclear or data is incomplete
- Conflicting signals across dimensions (strong performance but poor audience quality, or vice versa)

### 4. Not a priority collaboration candidate

Multiple weak signals appear:

- Disputes or negative cooperation history
- Poor audience quality (low authenticity, suspicious audience types)
- Below-benchmark performance across multiple metrics
- Creator is clearly a poor fit for the stated collaboration goal

## Due-Diligence Output Structure

After the verdict, organize evidence into these sections:

### 1. Data Performance

- Average views and engagement rate
- Stability: wave value and views change ratio
- Benchmark position: rank and percentile vs. peers
- Content-type splits if relevant (normal vs. shorts/reels)
- Level indicators (1-5 scale): avg_views_level, wave_level, engagement_rate_level

### 2. Audience Quality

- Audience authenticity (value, status, ratio range)
- Audience type distribution (real, suspicious, inactive)
- Demographic fit: region, language, age, gender distributions
- Marketing indicators: positive_audience_pct, promo_interested_audience_pct, promo_attractiveness, promo_professionalism

### 3. Cooperation Risk

- Dispute types (if any)
- Cooperation score and tendency
- Cooperation pros and cons lists
- Ad video ratio and frequency

### 4. Commercial Reasonableness

- Estimated price range (avg, min, max)
- First price vs. final price gap
- Response speed (avg_response_hours)
- Collaboration efficiency (avg_contact_days, avg_contact_chats, avg_collaboration_days)
- Active period and communication patterns
- Existing brand partnerships (brand names, video counts, engagement rates)

### 5. Final Recommendation

- Whether to continue toward outreach
- What should be double-checked manually
- Whether the next step should be contact retrieval or shortlist replacement

## Interpretation Principles

- Dispute history and negative cooperation signals are decision-critical — always surface them prominently.
- Benchmark position provides context but is not the sole determinant.
- Pricing reasonableness should be evaluated relative to performance, audience quality, and cooperation signals, not in isolation.
- When evidence is mixed, prefer "Needs manual review" over false confidence.
- When two or more critical dimensions are missing or platform-limited, do not force a confident verdict.
- When only one dimension was checked, present the answer as a scoped judgment, not a full verdict.


path: references/cli-response-format.md
content: # CLI Response Format

## API-backed Commands

These commands return the standard API envelope:

- `creator ...`
- `monitor ...`
- `campaign ...`
- `collection ...`
- `email ...`
- `message ...`
- `crm ...`
- `brand-monitor ...`
- `export ...`
- `quota`
- `pricing`

Successful responses include `success`, `data`, `summary`, and `meta`. Some current endpoints may also include a legacy compatibility field named `credits`.

Notes:

- Treat `quota` response data as the canonical Skill quota snapshot
- `pricing` returns membership plans, not per-action cost
- Some current API envelopes may still include a legacy `credits` field for compatibility; do not treat it as the primary quota model
- Mutation commands default to dry-run; `--force` executes the write after user approval
- Non-GET writes automatically use `Idempotency-Key`; `--idempotency-key` can override it for automation
- JSON-first commands declare `supports_body_file: true` in schema and require `--body-file`
- `export download` writes binary data to `--output`, not stdout

Error responses include an `action` field with next-step guidance:

```json
{
  "success": false,
  "error_code": "INSUFFICIENT_CREDIT",
  "summary": "Insufficient credit quota",
  "action": {
    "type": "redirect",
    "url": "https://www.noxinfluencer.com/skills/usage-billing",
    "hint": "Open billing to renew or upgrade your available quota."
  }
}
```

The current server may still use legacy wording like `INSUFFICIENT_CREDIT` or `Insufficient credit quota`. Interpret that as "Skill quota is exhausted" for user communication.

## Local Commands (different format)

These commands have their own response structures — do not assume the API envelope:

| Command | Response format |
|---------|----------------|
| `doctor` | `{ "checks": [...], "ok": boolean }` |
| `auth` | `{ "success": boolean, "message": string }` |
| `env` | `{ "success": true, "data": { "environment": string, "server_url": string } }` |
| `schema` | Command schema JSON (no envelope) |
| `agent exit-codes` | Stable CLI exit-code catalog |

## Agent Diagnostics

- Use `--trace-json` when a harness or eval needs structured request traces on stderr.
- Use `schema --all` to verify the installed CLI exposes the expected 0.4+ command tree. Version output alone is not sufficient when a local/global install has stale compiled files. If reinstalling `@noxinfluencer/cli@latest` still lacks the expected command groups, stop the affected workflow and report a CLI package / command-tree mismatch.
- Use `noxinfluencer agent exit-codes` to distinguish retryable failures such as rate limits or temporary upstream failures from invalid requests and auth problems.
- Use `doctor` as the first diagnostic step when the failure cause is unclear.


path: references/brand-monitor.md
content: # Brand Monitor Workflows

Use brand-monitor commands for brand-level market intelligence and asset exports. This workflow starts from `brand_id`; do not substitute `creator_id`.

## Routing

| User intent | Command family |
|-------------|----------------|
| List available brand monitors | `brand-monitor list` |
| Inspect one monitored brand | `brand-monitor get <brand_id>` |
| Compare brand competition | `brand-monitor competition-matrix <brand_id>` |
| Analyze cooperation strategy | `brand-monitor cooperate-matrix <brand_id>` |
| Summarize influencer portrait | `brand-monitor influencer-portrait <brand_id>` |
| Find defense gaps | `brand-monitor defense-gap <brand_id>` |
| Read product trend/category signals | `brand-monitor product-pub-trend`, `product-category` |
| Read product strategy signals | `brand-monitor product-sov-analysis`, `product-tae-analysis`, `product-pp-analysis`, `product-promotion-matrix`, `product-promotion-distinction` |
| Query brand asset rows | `brand-monitor influencer-list`, `content-list`, `tag-list`, `product-list` |
| Create brand asset exports | `brand-monitor influencer-export`, `content-export`, `tag-export`, `product-export` |
| Add or unlock a monitored brand | `brand-monitor add`, `unlock-base`, `unlock-high` |

## Platform Boundaries

- Core brand monitor reads support YouTube, TikTok, and Instagram where the CLI schema permits.
- Product signal commands currently support `youtube` only. Do not call product signal commands for TikTok or Instagram unless a future schema explicitly shows support.
- Asset list commands are JSON-first. Use `--body-file` and inspect schema usage notes before building selectors.

## Output Rules

- Brand overview: report brand name, `brand_id`, access/data level, quota state, and obvious blockers.
- Matrices and strategy reads: summarize top rows and the decision implication; do not dump every normalized field.
- Asset lists: present comparable rows and include pagination state when present.
- Product signals: state that the result is YouTube-only if the user asked for cross-platform analysis.
- Exports: preserve `export_id` and route follow-up status/download through shared `export` commands.

## Mutation Rules

- `add`, `unlock-base`, `unlock-high`, and all `*-export` commands are mutations or async job creation.
- Dry-run first unless the user already approved the exact brand and action.
- Use `--force` only after approval.
- For unlock operations, explain that quota/entitlement may be consumed before executing.


path: references/platform-support.md
content: # Platform Support

NoxInfluencer skills support three platforms. Each has some data availability differences.

## Supported Platforms

| Platform | `--platform` value | Creator ID prefix byte |
|----------|-------------------|----------------------|
| YouTube | `youtube` | `0x01` |
| TikTok | `tiktok` | `0x02` |
| Instagram | `instagram` | `0x03` |

## Data Availability by Platform

| Data Dimension | YouTube | TikTok | Instagram |
|----------------|---------|--------|-----------|
| Search | Full | Full | Full |
| Profile overview | Full | Full | Full |
| NoxScore | Full | Full | Full |
| Audience demographics | Full | Full | Partial |
| Audience authenticity | Full | Full | Limited |
| Content tags | Full | Full | Full |
| Recent content | Full | Full | Full (posts, reels, pics) |
| Cooperation detail | Full | Partial | Partial |
| Brand partnerships | Full | Partial | Limited |
| Pricing data | Full | Partial | Limited |
| Contact/email | Available | Available | Available |
| Video monitoring | Full | Full | Full |
| Brand monitor product signals | YouTube only | Not supported | Not supported |

## Content Type Splits

Different platforms have different content types that affect performance metrics:

- **YouTube**: `normal` (long-form) vs. `shorts`
- **TikTok**: All content treated as short-form
- **Instagram**: `posts`, `reels`, `pics` — metrics may be split by type

## Platform-Specific Notes

- **Null fields**: Some fields may return `null` on certain platforms. This is expected behavior, not a data error. Skills should explain that the value may be unavailable for that platform rather than treating it as a failure.
- **Creator identity fields**: All creator read responses include `creator_id`, `creator_name`, `channel_handle`, `channel_url`, and `social_media`. `channel_url` and `social_media` are enhancement data and may still be empty on some creators or platforms.
- **Audience data**: Instagram audience data may be less granular than YouTube or TikTok.
- **Cooperation data**: Pricing and communication metrics are most complete on YouTube. TikTok and Instagram may have partial or no pricing data.
- **Creator IDs**: All creator IDs in search results and creator read responses are encrypted tokens. The same creator always produces the same token. Use the token directly as the positional `<creator_id>` argument in subsequent commands without decryption.
- **Direct selectors**: The first creator read call may use `--url` or `--platform --channel-id`. Once a response returns `data.creator_id`, switch to that token for follow-up calls.
- **Monitor task identity**: `monitor add-task` and `monitor tasks` may also expose `creator_id`, `creator_name`, `channel_handle`, and `channel_url`. Treat these as best-effort task metadata; nullable fields are not a hard failure.
- **Brand monitor product signals**: Product publication, category, SOV, TAE, PP, promotion matrix, and promotion distinction commands currently support YouTube only. For TikTok or Instagram brand questions, use non-product brand monitor reads or asset lists when schema permits.


path: references/search-filters.md
content: # Search Filter Semantics

For the full parameter list and syntax, run `noxinfluencer schema creator.search`. The single-argument command-path form `noxinfluencer schema 'creator search'` is equivalent.

This reference covers **when to use which filters** — the decision logic, not the syntax.

## Filter Priority by User Intent

| User intent | Key filters to apply | Why |
|-------------|---------------------|-----|
| Niche sourcing | `--keywords`, `--platform` | Narrow to relevant content creators |
| Regional targeting | `--country`, `--follower_countries` | Match campaign geography |
| Budget-constrained | `--follower_min`, `--follower_max` | Size correlates with cost |
| Outreach-ready | `--has_email true` | Only creators with known email (does NOT retrieve the email — use the contact retrieval workflow after a creator is selected) |
| Audience fit | `--follower_ages`, `--follower_female_pct_min`, `--follower_language` | Match audience demographics |
| Active creators | `--published_within_days` | Exclude dormant channels |
| Performance floor | `--engagement_rate_min`, `--avg_view_min` | Filter out low-engagement creators |

## Search Result Fields

Each result item includes: `id` (encrypted token), `nickname`, `tags`, `followers`, `country`, `total_videos`, `view_per_followers`, `engagement_rate`, `avg_views`, `language`.

Search responses also include page metadata under `data`: `page_num`, `page_size`, `total_page`, `total_size`, and `search_after`.

The `id` is an encrypted token — use it directly as the positional `<creator_id>` argument in subsequent commands. Do not try to decode it.

## Pagination Rules

- For a next-page request, keep the previous search filters exactly the same and send both the next `page_num` and the previous response's `data.search_after`.
- Prefer `--body-file -` for next-page requests and pass one JSON body containing the preserved filters, `page_num`, `page_size`, and `search_after`. This avoids shell globbing/quoting problems with cursor arrays.
- If using flags instead of `--body-file`, shell-quote every bracketed array argument, especially `--search_after`, for example `--search_after '[163.97083,"UCQ-P8lGwkr0Tj4phQB9diDw"]'`.
- Current CLI and server validation require `page_num > 1` when `search_after` is present, so do not try cursor-only paging.
- If `data.search_after` is missing or empty, or the current page is already the last page, tell the user there are no more results.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)