iftechio/easykol-skills

easykol

Use when the user wants to discover, evaluate, or research creators / KOLs / influencers on YouTube, TikTok, or Instagram.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/iftechio/easykol-skills --skill easykol

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

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" <operation> [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 <cmd> (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 intentCommand
Read a search task / continue its next batchtask --task-id / search-next --task-id (same source mode and filters)
Find creators matching a description`search-v2 --mode faststandardbeta (default fast); parse-v2 --mode` for optional preview
Find creators similar to a URLsimilar
Get a creator's profile by URLkol
Get a creator's audience breakdownaudience
Get emails for a list of creator URLsemails
Analyze a video / post by URLvideo
Manage email templates, senders or outreachemail-*; read references/email.md
Check remaining creditsquota
Setup / diagnosticsauth, doctor

For exact flags always run node "{baseDir}/scripts/api.cjs" schema <cmd> 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.

  1. 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 <email>. Do not put secrets in command arguments, output or source files. Reuse safely stored credentials before asking for information already available.

  1. 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 intentModeExisting web pipelineTarget per batch
Quick shortlist, no specified modefast (default; tell the user)mode 8 historical, stored data + text relevance, background refresh60
Normal / standard searchstandardmode 8 regular, profile relevance + realtime refresh and hard-filter recheck50
Beta / Pro, product promotion fit or visual screeningbetamode 7, product requirements + optional visual screening50

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.

  1. 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.

  1. 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.

  1. 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 <id> for free; if submission outcome is uncertain, recover search-v2 --idempotency-key <original-key> from the saved local journal. Never start a replacement paid search because polling timed out.

  1. 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 <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 <latest-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 <profile-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 <profile-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 <profile-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 <url1,url2,...>
node "{baseDir}/scripts/api.cjs" emails --yt-urls <url1,url2,...>
node "{baseDir}/scripts/api.cjs" emails --ins-urls <url1,url2,...>

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 <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 codeMeaningWhat to do
2Not authenticatedRun node "{baseDir}/scripts/api.cjs" auth --key-stdin --email <email>
3Quota exhaustedStop, tell user, share action.url if present
4Feature not in planExplain, suggest upgrade
5Network errorRetry reads once; recover the original paid task; never resend email
6Bad parametersRe-read node "{baseDir}/scripts/api.cjs" schema <cmd>, fix flags, retry
7Rate limitBack off for reads; check mutation outcome before any repeat
8Search session budgetStop, 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