easykol

EasyKOL

YouTube、TikTok、Instagram を横断して、インフルエンサーの発見、クリエイターのプロフィール確認、オーディエンス分析、メールアドレスの一括抽出、動画分析を行う、ワークフロー全体をカバーするクリエイターインテリジェンススキルです。

ユーザーは自然言語で操作します。CLI コマンドは自分で実行し、結果を平易な言葉で報告してください。CLI コマンドや JSON をそのままユーザーに見せないでください。

使用する場面

• 説明に合致するクリエイター／インフルエンサー／KOL を探したい場合
• 既存のクリエイターに似たクリエイターを探したい場合
• クリエイターのプロフィール、フォロワー数、連絡先情報を確認したい場合
• 年齢、性別、地域、偽フォロワー率など、オーディエンスの属性を知りたい場合
• クリエイター URL のリストからメールアドレスを一括抽出したい場合
• 動画（再生回数、いいね数、投稿者）を分析したい場合
• EasyKOL の利用を開始したい、または残りの利用枠を確認したい場合

このスキルで対応しないこと

• コンテンツの投稿、DM の送信、ソーシャルプラットフォームとのやり取り
• EasyKOL のデータベースにまだないコンテンツの取得
• キャンペーン予算や提携に関する最終判断
• アプローチメールや交渉文面の作成
• ChatGPT での使用（CLI の実行環境が必要です）

基本原則

エージェント優先

ユーザーは CLI を操作しません。操作するのはあなたです。コマンドを非表示で実行し、結果を平易な言葉で報告してください。ユーザーがブラウザーで操作する必要がある場合（チャージ、認証）に限り、URL を共有してください。

CLI による自己説明

CLI 自体に説明機能があります。パラメーターを暗記するのではなく、CLI を使ってください。

• コマンドのスキーマ：easykol schema <cmd>（例：schema kol、schema search-v2）
• コマンドツリー全体：easykol schema --all
• 終了コード：easykol exit-codes
• 診断：easykol doctor

コマンドの使い分け早見表

ユーザーの目的	コマンド
検索タスクの内容を確認する／次のバッチを続ける	task --task-id / search-next --task-id（同じソースモードとフィルター）
説明に合致するクリエイターを探す	`search-v2 --mode fast
URL に似たクリエイターを探す	similar
URL からクリエイターのプロフィールを取得する	kol
クリエイターのオーディエンスの内訳を取得する	audience
クリエイター URL のリストからメールアドレスを取得する	emails
URL から動画／投稿を分析する	video
残りのクレジットを確認する	quota
セットアップ／診断	auth、doctor、upgrade

正確なフラグを確認するには、必ず最初に easykol schema <cmd> を実行してください。

---

1. はじめに

EasyKOL のセッションを開始するたびに、まずツールを非表示で更新してください（ユーザーに尋ねず、失敗しない限り説明もしません）。

1. CLI がすでにインストールされている場合は、easykol upgrade を優先します。
2. それ以外の場合は、両方を実行します（可能な範囲で実行し、失敗しても続行してください）。

   npm install -g @easykol/cli@latest
   npx --yes skills update easykol -y
   

3. スキルの更新に成功したら、有料検索を実行する前に、このスキルの SKILL.md と references/quota-heuristics.md を再度読み込み、現在のセッションに予算ルールを反映させます。

次に easykol doctor を実行し、不足しているものだけを修正します。

1. CLI がない → npm install -g @easykol/cli@latest を実行するようユーザーに依頼します。
2. API キーがない（hasApiKey: false）→ ユーザーにキーとメールアドレスを尋ね、次を実行します。

   printf '%s' "<KEY>" | easykol auth --key-stdin --email <email>
   

   キーを位置引数として渡したり、ログに記録したりしないでください。
3. 設定済み → easykol quota を実行し、作業を妨げる問題があれば報告します。
4. doctor が updateAvailable: true を報告した場合、検索の前に easykol upgrade をもう一度実行します。

---

2. クリエイターを見つける

自然言語での依頼を、関連性の高いクリエイターの候補リストに変換します。

モードを選択する

CLI 0.2.0 以降と外部 V2 バックエンドを使用してください。リクエスト／結果の仕様については {baseDir}/references/search-modes.md をお読みください。

ユーザーの意図	モード	既存のウェブパイプライン	バッチあたりの目標
手早く候補を絞り込みたい。モードの指定なし	fast（デフォルト。ユーザーに伝えてください）	mode 8 historical、保存済みデータ＋テキストの関連性、バックグラウンド更新	60
通常／標準検索	standard	mode 8 regular、プロフィールの関連性＋リアルタイム更新とハードフィルターの再確認	50
ベータ版／Pro、商品のプロモーション適性または視覚的なスクリーニング	beta	mode 7、商品要件＋任意の視覚的スクリーニング	50

モードを黙って切り替えないでください。Beta では、リクエストごとにバッチを1つだけ使用できます。 既存の検索タスクでは、モードとフィルターを維持してください。続行する前に {baseDir}/references/pro-pagination.md をお読みください。

検索ワークフロー

1. ユーザーの必須条件を事前確認します。検索では、クリエイターのプラットフォーム、 地域／言語、フォロワー数／パフォーマンスの範囲、クリエイターの性別、連絡先の有無を指定できます。 オーディエンスの属性には別途 audience 分析が必要です。TikTok Shop のフルフィルメント率など、 対応していない指標は未検証のままにしてください。対応していない必須条件を キーワードに置き換えて、検証済みと主張しないでください。
2. 文脈からプラットフォーム、国、希望するモードを推定します。プラットフォームが重要で、 指定がない場合は一度だけ確認してください。対象国はすべて1つの --regions リストに指定します。 ユーザーが指定していないフィルターは、しきい値を勝手に設定せず省略してください。消費者の ターゲット年齢／性別は、クリエイターのフィルターではなく、Beta の --product／--audience に指定します。
3. デフォルトでは search-v2 を1回実行します。CLI は有料リクエストの前に、 モード固有の無料の準備処理と見積もりを取得します。parse-v2 はプランの表示／編集に任意で使用できますが、 ユーザーの確認に必須の手順ではありません。ユーザーの既存の承認は、明示された範囲と予算内の 必要な手順すべてに適用されます。
4. 返された taskId と idempotencyKey を保持します。search-v2 はデフォルトで読み取り可能な 結果が得られるまで待機します。--no-wait を指定するとすぐに戻ります。タイムアウトは検索失敗を意味しません。 task --task-id <id> で無料で再開してください。送信結果が不確かな場合は、保存済みのローカルジャーナルから search-v2 --idempotency-key <original-key> で復旧します。ポーリングがタイムアウトしたからといって、 代わりの有料検索を開始しないでください。
5. 読み取り可能な結果から要求された件数を提示し、kolId／URL で重複を除き、 返されたフィールドを使って対応可能な必須条件を確認します。指標が欠落している場合、 screening=unverified の場合、または対応していない要件は未検証のままにします。 条件を一部しか満たさない候補は、その旨を正直に説明してください。連絡先があるからといって、 公開メールアドレスまたは利用可能なメールアドレスがあるとは限りません。必要な場合は、 実際に値が入力されたメールアドレスの数を数えてください。

RESULT_READY は結果を読み取れる状態であることを示しますが、処理／精算の完了を意味するものではありません。 settlement.pending=true の COMPLETED は、返金の照合がまだ完了していません。 不明なステージ件数はゼロではなく null です。失敗または未完了のタスクをリコールゼロと表現したり、 不明な判定を却下とみなしたりしないでください。

さらに結果を読み込み、続行する

• task --task-id <id> --offset 50 --limit 50 を使うと、保存済みの次のページを無料で読み込めます。 別の有料バッチをリクエストする前に、既存タスクの nextOffset まで結果を取得してください。
• 承認済みの目標件数に別のバッチが必要な場合は、COMPLETED を待ってから、 新しい冪等性キーを使って search-next --task-id <latest-id> を実行します。モード、 プラットフォーム、フィルターは引き継がれます。返された子タスクから順番に続行してください。 古い親タスクを起点に分岐したり、並行して続行したりしないでください。
• ユーザーが要求した件数に達したら停止します。バッチの目標件数は保証されません。 不足があっても、モードを自動的に変更したり、フィルターを緩めたり、無関係な検索を実行したりせず、 その旨を説明してください。

予算管理

CLI が確保するのは、表示される行数ではなくサーバー見積もり額です。タスクポイント 1 点は、生のクォータ 10 に相当します。共有のローリング CLI 検索予算は、デフォルトで 2 時間あたり生のクォータ 50（5 ポイント）です。確定した返金は、タスクの読み取り時に反映されます。詳細は {baseDir}/references/quota-heuristics.md を参照してください。

デフォルトでは 1 回のバッチを使用してください。ユーザーがより大きなプランを承認している場合は、見積もられたバッチ費用を合算し、その承認の範囲内で続行してください。各段階で繰り返し許可を求める必要はありません。プランがユーザーの承認した範囲や予算を超える場合、または CLI が終了コード 8 を返した場合は、追加費用を説明し、--confirm-spend の前に承認を得てください。明示された承認はターンをまたいで有効です。承認を勝手に想定してはいけません。

異なるニッチを検索する場合は、国やフィルターの設定を共通にして、焦点を絞った文を使い、結果を統合して重複を除去してください。検索ごとに個別のバッチ見積もりが必要です。表示件数を減らしても、価格は下がりません。統合したプランは、ユーザーが承認した予算内に収めてください。estimatedTotal は候補全体を示すものではありません。

レガシーとの互換性

search ／ parse は、従来の V1 名、オプション、動作を維持しています。V2 の検索コントラクトとは共有されず、タスクの継続にも対応していません。more-words も V1 ユーティリティです。V2 が 404 を返した場合や、モード固有のリクエストが失敗した場合に、これらを黙って使用してはいけません。バックエンドとバージョンの不一致を報告してください。既存の profile、video、emails、similar、audience コマンドは、引き続き既存のエンドポイントを使用します。

類似クリエイターの検索

ユーザーが特定のチャンネルに似たクリエイターを探している場合は、easykol similar --url <profile-url> を使用してください。これは非同期で、約 30 秒かかります。検索中であることをユーザーに伝えてください。

任意のフィルター：--regions、--languages、--min-subscribers、--max-subscribers、 --min-avg-views、--max-avg-views。--dedup-days（デフォルトは 3）は、最近確認済みのクリエイターを除外します。無効にするには 0 を設定してください。

結果は search の結果と同じ形式で提示してください。

---

3. クリエイターの評価

クリエイターにアプローチする価値があるかどうか、ユーザーが判断できるよう支援してください。数字を大量に並べるのではなく、まず概要を伝えてください。

プロフィール

easykol kol --url <profile-url> を実行して、クリエイターの現在のプロフィールを取得します。 ニックネーム、フォロワー数、平均パフォーマンス、地域、言語、登録されている場合はメールアドレスが含まれます。

ユーザーがクリエイターの URL を貼り付けた場合や、「このクリエイターについて何が分かりますか？」と尋ねた場合は、まずこれを実行してください。

オーディエンス分析

easykol audience --url <profile-url> を実行して、次の情報を取得します。

• 属性：年齢分布（18 歳未満／18～25 歳／25～45 歳／45 歳以上）と男女比
• 地域：T1／T2／T3 の発展レベルを含む、オーディエンスの上位国
• 偽フォロワー：偽アカウントの疑いがある割合、偽アカウント数、サンプル総数

結果は 30 日間キャッシュされます。キャッシュに結果があれば、コマンドはすぐに返ります。新しい分析は非同期で、最大 2 分かかります。時間がかかる場合は、分析を取得中であることをユーザーに伝えてください。

結果をユーザー向けに解釈し、オーディエンスが T1 市場に集中しているか、男女比がキャンペーンの要件に合っているかを説明してください。また、suspectedFakeRate が高い場合は注意を促してください（20% を超える場合は注意が必要で、40% を超える場合は重大な懸念事項です）。

結果に含まれていない正確な年齢層を断定するために、オーディエンス分析を使ってはいけません。標準の区分には 18–25 と 25–45 が含まれますが、これだけでは 25–40 ≥ 60% であることは確認できません。API がそのフィルターを明示的にサポートしていない限り、オーディエンス分析はクリエイターごとの検証手順であり、検索フィルターではありません。

4. メールの取得

重要な違い：easykol kol は、プラットフォームのプロフィールに公開されているクリエイターのメールアドレスをすでに返します。単一のクリエイターのメールアドレスや連絡先についてユーザーから尋ねられた場合、easykol emails は実行しないでください。kol で対応できます。

クリエイターの URL リストから連絡先メールアドレスを一括抽出したいとユーザーが明示的に求めている場合、または連絡先を Excel ファイルにエクスポートしたい場合は、easykol emails を使います。これは非同期で実行されます（約60秒）。すべてのアドレスが公開されている、有効である、または取得可能であることを証明するものではありません。処理の完了後、取得できなかった結果とカバレッジを報告してください。

easykol emails --tt-urls <url1,url2,...>
easykol emails --yt-urls <url1,url2,...>
easykol emails --ins-urls <url1,url2,...>

複数のプラットフォームが混在するバッチでは、フラグを組み合わせられます。URL 5件ごとにクォータを1消費します（端数は切り上げ）。

このコマンドは Excel ファイルの downloadUrl を返します。ファイルの準備ができたことをユーザーに伝え、URL を共有してください。

---

5. 動画の分析

easykol video --url <video-url> を実行すると、動画のメタデータを取得できます。取得される項目は、タイトル、視聴回数、高評価数、コメント数、シェア数、指定された場合の Instagram のリポスト数、公開日、投稿者名、投稿者のフォロワー数です。shareCount はシェア指標（Instagram の紙飛行機アイコンによるアクション）で、repostCount は Instagram 独自の両矢印のリポスト指標です。Instagram の場合、両方のフィールドは v3 の投稿詳細レスポンスから取得されます。v5 の値は使用されません。どちらのフィールドも、null は v3 エンドポイントからその指標が提供されなかったことを意味します（測定されたゼロではありません）。これらのフィールドを組み合わせたり、相互に置き換えたりしないでください。

対応対象：YouTube 動画、TikTok 投稿、Instagram リール／投稿。

ユーザーが動画のリンクを共有して簡単な統計情報を求めている場合や、アプローチ前にクリエイターの最近のコンテンツを確認したい場合に便利です。

---

エラー処理

すべてのエラーでは、CLI のレスポンスを使用してください。

• action.url — ユーザーが移動する先（チャージ、認証）
• action.hint — 次に行う操作

Exit code	Meaning	What to do
2	認証されていません	easykol auth --key-stdin --email <email> を実行します
3	クォータを使い切りました	停止し、ユーザーに伝え、action.url があれば共有します
4	プランに含まれていない機能です	説明し、アップグレードを提案します
5	ネットワークエラーです	1回再試行してから報告します
6	パラメーターが正しくありません	easykol schema <cmd> を再確認し、フラグを修正して再試行します
7	レート制限です	間隔を空けてから再試行します
8	検索セッションの予算です	停止してユーザーに確認し、承認された場合に限り --confirm-spend を付けて再試行します

非同期コマンド（similar、emails、audience）がタイムアウトした場合（終了コード 1 で「timed out」と表示）、タスクが予想より長くかかっていることをユーザーに伝え、--timeout 300 を付けて再試行するよう提案してください。

原因が不明な場合は、最初の診断として easykol doctor を実行してください。

参考資料

• {baseDir}/references/pro-pagination.md — Pro の単一ページ取得、タスクの継続、CLI／API の境界
• {baseDir}/references/search-filters.md — search／parse／more-words のフラグに関する完全なリファレンス
• {baseDir}/references/platform-support.md — プラットフォームおよびコマンドごとのデータ取得可否
• {baseDir}/references/quota-heuristics.md — コマンドごとの課金の詳細
• {baseDir}/references/async-tasks.md — 非同期コマンド（similar／emails／audience）の仕組み
• {baseDir}/references/error-codes.md — 終了コードと出力エンベロープ