--- name: easykol description: >- Use when the user wants to discover, evaluate, or research creators / KOLs / influencers on YouTube, TikTok, or Instagram. Covers creator discovery (natural-language search, lookalikes), creator profiling, audience analysis (age/gender/region/fake-follower rate), bulk email extraction, video analysis, email templates, connected senders, outreach sending and result queries, and account setup. Use when the user mentions finding influencers, checking a creator's audience, getting creator emails, analyzing a video, or setting up EasyKOL access, managing EasyKOL email templates or sending outreach emails. metadata: {"openclaw":{"requires":{"bins":["node"]},"homepage":"https://app.easykol.com/skills"}} --- # EasyKOL Full-workflow creator intelligence skill for influencer discovery, creator profiling, audience analysis, bulk email extraction, and video analytics across YouTube, TikTok, and Instagram, with email template and outreach management. The user interacts through natural language. Call the EasyKOL API using the bundled `{baseDir}/scripts/api.cjs` script and report results in plain language. It needs only Node.js 18.3+; no `easykol` installation, npm package publication or npm login is needed. Run operations with `node "{baseDir}/scripts/api.cjs" [options]`. `{baseDir}` is this installed skill directory, not the caller's working directory. Never expose raw operations, JSON or credentials in the user-facing answer. ## When to Use - User wants to find creators / influencers / KOLs matching a description - User wants to find creators similar to an existing one - User wants to check a creator's profile, follower count, or contact info - User wants audience demographics: age, gender, region, or fake-follower rate - User wants to bulk-extract emails for a list of creator URLs - User wants to analyze a video (views, likes, author) - User needs to set up EasyKOL access or check remaining quota ## What This Skill Does Not Do - Post content, send DMs, or interact with social platforms - Return content not yet in the EasyKOL database - Make final campaign-budget or partnership decisions - Work in a chat environment that cannot execute the bundled Node.js script ## Core Principles ### Agent-First The agent operates the bundled script. Run operations silently and report results in plain language. Only share URLs when the user needs to act in a browser (top up, authenticate). ### API Helper Self-Description The API helper documents itself — use it rather than memorising parameters: - **Command schema**: `node "{baseDir}/scripts/api.cjs" schema ` (e.g. `schema kol`, `schema search-v2`) - **Full command tree**: `node "{baseDir}/scripts/api.cjs" schema --all` - **Exit codes**: `node "{baseDir}/scripts/api.cjs" exit-codes` - **Diagnostics**: `node "{baseDir}/scripts/api.cjs" doctor` ## Routing Cheat Sheet | User intent | Command | |-------------|---------| | Read a search task / continue its next batch | `task --task-id` / `search-next --task-id` (same source mode and filters) | | Find creators matching a description | `search-v2 --mode fast|standard|beta` (default fast); `parse-v2 --mode` for optional preview | | Find creators similar to a URL | `similar` | | Get a creator's profile by URL | `kol` | | Get a creator's audience breakdown | `audience` | | Get emails for a list of creator URLs | `emails` | | Analyze a video / post by URL | `video` | | Manage email templates, senders or outreach | `email-*`; read `references/email.md` | | Check remaining credits | `quota` | | Setup / diagnostics | `auth`, `doctor` | For exact flags always run `node "{baseDir}/scripts/api.cjs" schema ` first. --- ## 1. Getting Started At session start, run `node "{baseDir}/scripts/api.cjs" doctor`. This checks Node.js, existing configuration and connectivity without installing anything. 1. Reuse the existing `~/.easykol/config.json` (or `EASYKOL_CONFIG_DIR`) when it belongs to the intended account. Never silently switch accounts. 2. If a key or email is missing, use the user's API key and email. Read the key from stdin with `node "{baseDir}/scripts/api.cjs" auth --key-stdin --email `. Do not put secrets in command arguments, output or source files. Reuse safely stored credentials before asking for information already available. 3. Run `node "{baseDir}/scripts/api.cjs" quota` and report blocking issues. Update the Skill from its GitHub installation source when an update is needed, then re-read `SKILL.md` and `references/quota-heuristics.md`. Do not install or upgrade `@easykol/cli`. The bundled script and references update together. --- ## 2. Discovering Creators Turn a natural-language request into a shortlist of relevant creators. ### Choose a Mode The bundled helper calls the deployed external V2 API. Read `{baseDir}/references/search-modes.md` for the request / result contract. | User intent | Mode | Existing web pipeline | Target per batch | |-------------|------|-----------------------|------------------| | Quick shortlist, no specified mode | `fast` (default; tell the user) | mode 8 historical, stored data + text relevance, background refresh | 60 | | Normal / standard search | `standard` | mode 8 regular, profile relevance + realtime refresh and hard-filter recheck | 50 | | Beta / Pro, product promotion fit or visual screening | `beta` | mode 7, product requirements + optional visual screening | 50 | Never silently substitute modes. Beta permits exactly one batch per request. For existing search tasks preserve their mode and filters; read `{baseDir}/references/pro-pagination.md` before continuation. ### Search Workflow 1. Preflight the user's hard requirements. Search supports creator platform, region/language, follower/performance range, recent activity, creator gender, contact presence, content taxonomy and stored TikTok Shop presence. Audience demographics require separate `audience` analysis; unsupported metrics such as TikTok Shop fulfilment rate must remain unverified. Do not convert an unsupported hard condition to a keyword and claim verification. 2. Infer platform, countries and requested mode from context. Ask for a critical missing platform once. Put all target countries in one `--regions` list; omit filters the user did not specify rather than inventing thresholds. Consumer target age/gender belongs to Beta `--product` / `--audience`, not creator filters. 3. Submit one `search-v2` by default. The API helper obtains a free mode-specific preparation and quote before the paid request. `parse-v2` is optional for showing / editing the plan, not a required user confirmation stage. The user's existing authorization applies to all necessary steps within their stated scope and budget. 4. Keep the returned `taskId` and `idempotencyKey`. `search-v2` waits for readable results by default; `--no-wait` returns immediately. A timeout is not a failed search. Resume `task --task-id ` for free; if submission outcome is uncertain, recover `search-v2 --idempotency-key ` from the saved local journal. Never start a replacement paid search because polling timed out. 5. Present the requested number from the readable results, dedup by `kolId` / URL, and verify supported hard conditions against returned fields. Missing metrics, `screening=unverified`, or unsupported requirements remain unverified. Describe partial candidates honestly. Contact presence does not prove a public or deliverable email; count actual non-empty emails when required. For taxonomy filters and explicit empty keyword behavior, read `{baseDir}/references/search-filters.md`. TikTok Shop is a stored-data hard filter, not a live storefront check. If a filtered request returns zero, compare one-filter variants and inspect `effectiveParameters` / funnel counts before blaming numeric ranges. In fast mode, distinguish a true empty candidate pool from virtual-project exclusion degradation. `RESULT_READY` means results may be read, not that processing/settlement completed. `COMPLETED` with `settlement.pending=true` still awaits refund reconciliation. Unknown stage counts are `null`, not zero. Never label a failed or unfinished task as zero recall or treat unknown judgments as rejection. ### Reading More Results and Continuing - `task --task-id --offset 50 --limit 50` reads another stored page **for free**. Exhaust the existing task's `nextOffset` before requesting another paid batch. - When the authorized target needs another batch, wait for `COMPLETED`, then `search-next --task-id ` using a new idempotency key. It inherits mode, platform and filters. Continue serially from each returned child task; do not branch from an older parent or launch parallel continuations. - Stop when the user's requested number is reached. A batch target is not a guaranteed quantity. Explain a shortfall without automatically changing modes, weakening filters or running unrelated searches. ### Budget Control The API helper reserves the **server quote**, not the number of displayed rows. One task point equals 10 raw quota. The shared rolling API helper search budget defaults to 50 raw quota (5 points) per 2-hour window; finalized refunds reconcile on task reads. Use `{baseDir}/references/quota-heuristics.md` for details. Use one batch by default. For a user-authorized larger plan, sum the quoted batch costs and continue within that authorization; do not request repeated permission at every stage. If the plan exceeds the user's approved scope/budget or the API helper returns exit 8, explain the extra cost and obtain approval before `--confirm-spend`. Existing explicit approval persists across turns; never invent it. For distinct niches, use focused sentences with shared country/filter settings, merge and dedup the results. Every search has its own batch quote: reducing the number shown does **not** reduce its price. Keep the combined plan within the user's authorized budget. `estimatedTotal` is not a complete candidate pool. ### Legacy Compatibility `search` / `parse` keep their original V1 names, options and behavior. They do not share the V2 search contract or support task continuation. `more-words` is also a V1 utility. Do not silently use them when V2 returns 404 or a mode-specific request fails; report the backend/version mismatch. Existing profile, video, emails, similar and audience commands continue using their existing endpoints. ### Lookalike Discovery Use `node "{baseDir}/scripts/api.cjs" similar --url ` when the user wants creators similar to a specific channel. This is async and takes ~30s; tell the user you are searching. Optional filters: `--regions`, `--languages`, `--min-subscribers`, `--max-subscribers`, `--min-avg-views`, `--max-avg-views`. `--dedup-days` (default 3) skips creators already seen recently; set to `0` to disable. Present results the same way as `search` results. --- ## 3. Evaluating a Creator Help the user decide whether a creator is worth pursuing. Lead with a summary, not a wall of numbers. ### Profile Run `node "{baseDir}/scripts/api.cjs" kol --url ` to fetch the creator's current profile: nickname, follower count, avg performance, region, language, and email (if on file). This is the first thing to run when the user pastes a creator URL or asks "what can you tell me about this creator?" ### Audience Analysis Run `node "{baseDir}/scripts/api.cjs" audience --url ` to fetch: - **Portrait**: age distribution (under18 / 18–25 / 25–45 / above45) and gender split - **Region**: top audience countries with T1/T2/T3 development level - **Fake followers**: suspected fake rate, fake count, total sample size Results are cached for 30 days — the command returns immediately on a cache hit. A new analysis is async and takes up to 2 min. Tell the user you are fetching the analysis if it takes time. Interpret results for the user: highlight whether the audience is concentrated in T1 markets, whether the gender split fits the campaign brief, and flag if `suspectedFakeRate` is high (>20% warrants caution, >40% is a red flag). Do not use audience analysis to claim an exact age range that the result does not contain. The standard buckets include `18–25` and `25–45`; they cannot establish `25–40 ≥ 60%`. Audience analysis is a per-creator verification step, not a search filter, unless the API explicitly supports that filter. --- ## Email Templates, Connected Mailboxes and Outreach Use `references/email.md` for template creation/updates, stage follow-up templates, automatic follow-up sequences, connected sender configuration, sending, and sent result queries. These commands require the matching backend release; verify the helper schema before use. Permission to draft or configure does not authorize actual email delivery. Existing authorization persists; do not repeatedly ask for it. For `email-send`, network errors, timeouts and 5xx can mean uncertain delivery: **never apply the generic retry rule below to email sending**. Read records first. New mailbox binding and reauthorization remain in the web flow. ## 4. Retrieving Emails **Important distinction**: `node "{baseDir}/scripts/api.cjs" kol` already returns the creator's visible email from the platform profile. Do NOT run `node "{baseDir}/scripts/api.cjs" emails` just because the user asks about a creator's email or contact info for a single creator — `kol` covers that. Use `node "{baseDir}/scripts/api.cjs" emails` when the user explicitly wants to **bulk-extract** contact emails for a list of creator URLs, or wants an exported Excel file of contacts. This is async (~60s). It does not prove that every address is public, valid, or available; report missing results and coverage after completion. ``` node "{baseDir}/scripts/api.cjs" emails --tt-urls node "{baseDir}/scripts/api.cjs" emails --yt-urls node "{baseDir}/scripts/api.cjs" emails --ins-urls ``` Flags can be combined for mixed-platform batches. Costs 1 quota per 5 URLs (rounded up). The command returns a `downloadUrl` for an Excel file. Tell the user the file is ready and share the URL. --- ## 5. Analyzing a Video Run `node "{baseDir}/scripts/api.cjs" video --url ` to fetch video metadata: title, view count, like count, comment count, share count, Instagram Repost count when supplied, publish date, author name, and author follower count. `shareCount` is the share metric (the Instagram paper-plane action); `repostCount` is Instagram's distinct double-arrow Repost metric. For Instagram, both fields are sourced from the v3 post-detail response; v5 values are not used. For either field, `null` means the v3 endpoint did not provide that metric (it is not a measured zero). Do not combine or substitute these fields. Supported: YouTube videos, TikTok posts, Instagram reels/posts. Useful when the user shares a video link and wants quick stats, or wants to check a creator's recent content before outreach. --- ## Error Handling Sending is never retried automatically, including on 429, network errors, timeouts or 5xx. Recover paid search using the original key/task. Retry a failed read at most once with backoff; other mutations require checking the existing result first. For all failures, use the API helper response: - `action.url` — where the user should go (top up, authenticate) - `action.hint` — what to do next | Exit code | Meaning | What to do | |-----------|---------|------------| | 2 | Not authenticated | Run `node "{baseDir}/scripts/api.cjs" auth --key-stdin --email ` | | 3 | Quota exhausted | Stop, tell user, share `action.url` if present | | 4 | Feature not in plan | Explain, suggest upgrade | | 5 | Network error | Retry reads once; recover the original paid task; never resend email | | 6 | Bad parameters | Re-read `node "{baseDir}/scripts/api.cjs" schema `, fix flags, retry | | 7 | Rate limit | Back off for reads; check mutation outcome before any repeat | | 8 | Search session budget | Stop, ask user; retry with `--confirm-spend` only if approved | For async commands (`similar`, `emails`, `audience`), if the command times out (exit 1 with "timed out"), tell the user the task is taking longer than expected and suggest retrying with `--timeout 300`. Run `node "{baseDir}/scripts/api.cjs" doctor` as a first diagnostic when the cause is unclear. ## References - `{baseDir}/references/email.md` — templates, automatic follow-ups, connected mailboxes, sending and result checks - `{baseDir}/references/pro-pagination.md` — Pro single-page retrieval, task continuation, and helper/API boundaries - `{baseDir}/references/search-filters.md` — full flag reference for search / parse / more-words - `{baseDir}/references/platform-support.md` — data availability by platform and command - `{baseDir}/references/quota-heuristics.md` — billing details per command - `{baseDir}/references/async-tasks.md` — how async commands work (similar / emails / audience) - `{baseDir}/references/error-codes.md` — exit codes and output envelope