ShortFormアイデアエンジンは何をしますか？

競合の異常値動画を、ランク付けされブランドに適合したショートフォームアイデアと完成したスクリプトに変換する、調査からスクリプトまでのパイプライン。

使用するタイミング

ユーザーがショートフォーム動画のアイデアパイプラインを求めている場合にこのスキルを使用します。具体的には、ニッチな分野で何が成功しているかを発見し、その理由を理解し、リミックスされたアイデアを生成し、撮影準備が整ったスクリプトを受け取ることを目的とします。

以下の場合には使用しないでください:

ユーザーが解読を希望する単一の既知の動画がある場合: 代わりに video-decoder スキルにルーティングしてください。
ユーザーがすでにアイデアを持っていてスクリプト化を希望する場合: 代わりに script-writer スキルにルーティングしてください。

依存関係

これは自己完結型のプラグインです。すべてのサブスキルとGeminiヘルパースクリプトをバンドルしています。共有スキル環境は必要ありません。必須の外部要件は3つのAPIキーです（次のセクションを参照）。

依存関係	このスキルでの役割
`virlo` スキル（バンドル済み）	ステージ1のキーワードモード: Instagram、TikTok、YouTube全体でニッチなキーワードによる異常値ショートフォーム動画を発見
`scrape` スキル（バンドル済み）	ステージ1のハンドルモード、ステージ2、ステージ4のCDN URL解決: ScrapeCreators APIを介して最近の投稿、トランスクリプト、カバーフレーム、ダイレクトメディアURLを取得
`video-decoder` スキル	ステージ3および4: 各異常値動画を、入力されたデコードレコード（ビジュアルフック、書き言葉のフック、話し言葉のフック、根源、VV、IT、フォーマット）にデコード
`script-writer` スキル	ステージ7: 承認された各アイデアに対して撮影準備完了のスクリプトを1つ作成
`brand-profiler` スキル（バンドル済み）	ステージ0: ブランドプロファイルが存在しない場合に新規作成。`voice_tone` を含むすべてのスキーマフィールドを収集
`scripts/gemini-video-analyze.js`（バンドル済み）	ステージ4の深層パス: OpenRouter Geminiを介して視覚分析（ペーシング、カットリズム、ビジュアルスタイル、リテンションデバイス、テキストオン画面のケイデンス）を実行

APIキーとグレースフルデグラデーション

必要なキー: VIRLO_API_KEY、SCRAPECREATORS_API_KEY、OPENROUTER_API_KEY。\n 支出前にステージ0でそれらをロードします:

source .env

デグラデーションルール:

不足しているキー	影響
`VIRLO_API_KEY`	キーワードモードが無効になります。ハンドルモードは引き続き機能します。これをステージ0で明確に報告してください。
`OPENROUTER_API_KEY`	ステージ4（深層パス）が完全にスキップされます。すべてのデコードは `shallow` のままです。浅いデコードから派生したアイデアは、ランク付けテーブルで「shallow-decoded」とフラグ付けされます。
`SCRAPECREATORS_API_KEY`	エンジンを実行できません。ScrapeCreatorsはすべてのモードでトランスクリプトとカバーフレームに必要です。ステージ0で停止し、ユーザーに明確に伝えてください。

パイプライン

ステージ0: インプット

ユーザーに以下を尋ねてください:

モード: キーワードモード（ニッチなキーワードで動画を発見）またはハンドルモード（特定の競合ハンドルを分析）。
ブランドプロファイルパス: references/brand-profile-template.md に従って入力されたブランドプロファイルへのパス。存在しない場合は、バンドルされている brand-profiler スキルにチェーンして対話的に、または既存のブランドドキュメントからすべてのスキーマフィールド（voice_tone、audience、positioning、content_pillars、anti_topics、forbidden_constructions、proof_credibility、format_preferences、on_camera_talent）を収集して構築することを提案してください。
実行スラッグ: このセッションの短い小文字のラベル（例: ai-tools-keyword または techcreator-handles）。実行フォルダの命名に使用されます。
実行ベースパス: 実行フォルダを作成する場所。デフォルトのベースは現在の作業ディレクトリからの相対パス ./shortform-runs/ で、./shortform-runs/YYYY-MM-DD-<slug>/ を生成します。セッションが独自のリサーチエリアまたは出力エリアを持つ構造化プロジェクト内で実行されている場合は、代わりにそこに実行フォルダを配置するかどうかをユーザーに尋ねてください。ファイルを書き込む前に、解決されたベースパスをユーザーに確認してください。

3つのAPIキーすべてを確認してください。クレジットを使用する前に、どのモードが利用可能かを報告してください。確認されたベースパス（例: <base>/YYYY-MM-DD-<slug>/）に実行フォルダを作成し、モード、クエリまたはハンドルリスト、使用されたブランドプロファイルファイル名、実行ベースパス、利用可能なキー、およびオーバーライドを記載した 00-intake.md を書き込んでください。

ステージ1: 発見

キーワードモード。 virlo スキルを呼び出して、ニッチなキーワードの異常値ショートフォーム動画を発見します。video-decoder/references/decode-framework.md で定義されている3つの競合リングすべてにわたって発見を実行します:

直接リング: ニッチなキーワードをそのまま。
間接リング: オーディエンスに近いキーワードフレーズ（同じオーディエンス、異なるトピックアングル）。
隣接リング: フォーマットに近いキーワードフレーズ（同じフォーマットまたは制作スタイル、異なるトピック）。

virlo スキルを一度に1つのリングずつ呼び出し、そのリングのリングラベルとキーワードフレーズを渡します。複数のリングに対して同時にviriloを呼び出さないでください。virlo スキルはすべてのオービットメカニクスを所有します。まず、リングキーワードをカバーする既存のコメットをチェックし、利用可能な場合はその蓄積されたデータを（無料で）再利用し、一致するコメットがないリングに対してのみ新しいオービット（コスト: $0.50）を起動します。オーケストレーターの責任はシーケンスです。リングのviriloがランク付けされた異常値リストを返すのを待ってから、次のリングに対してviriloを呼び出します。

viriloがリングの結果を返した後、動画ごとの異常値の大きさを計算します。Viriloの結果にはクリエイターレベルの異常値比率が含まれますが、オーケストレーターはステージ4とステージ6のランク付けルーブリックのために動画ごとの比率を必要とします。リング結果に表示される各ユニーククリエイターについて、scrape スキルを呼び出して、そのクリエイターの該当プラットフォーム上の最近の投稿（およそ過去20件）を取得します。返された投稿を使用して、そのクリエイターのベースライン中央値視聴回数を計算します。次に、各動画の異常値比率を video_views / creator_median_views として計算します。各リングおよび各ベースライン取得の生JSONレスポンスを raw/ に保存します。

ハンドルモード。 scrape スキルを呼び出して、該当プラットフォーム上の各ハンドルの最近の投稿（およそ過去20件）を取得します。各ハンドルについて、返された投稿全体の中央値視聴回数を計算します。そのクリエイター自身の中央値の2倍以上の投稿のみを保持します（異常値しきい値）。生JSONを raw/ に保存します。

ハンドルが2倍のしきい値を超える投稿をゼロ件生成した場合（低分散クリエイター）、そのクリエイターの直近の最高パフォーマンスの投稿を1つ含めてください。00-intake.md に、そのハンドルには明確な異常値がなく、フォールバックとしてトップ投稿が含まれていることを記載してください。

両方のモードで、ステージ1の出力は、ソースURL、プラットフォーム、クリエイターハンドル、視聴回数を含む、重複排除された異常値動画のリストです。

ステージ2: レシート

各異常値動画について、scrape スキルを呼び出して以下を収集します:

トランスクリプト: YouTubeの場合、scrape スキルを呼び出して動画URLからトランスクリプトを取得します。TikTokとInstagramの場合、ステージ1ですでに取得した投稿ペイロードからトランスクリプトテキストを抽出してみてください。投稿ペイロードに動画のトランスクリプトが含まれていない場合は、動画をステージ3に渡す前に、フォールバックとしてその動画URLに対して scrape スキルのトランスクリプト関数を呼び出します。
カバーフレーム: 投稿ペイロードで返されたサムネイルURL。YouTubeの場合、カバーフレームを https://img.youtube.com/vi/[VIDEO_ID]/hqdefault.jpg として導出します。

すべての生レスポンスを、ソースとタイムスタンプで名前を付けて raw/ に保存します（例: scrapecreators-transcript-[video_id]-[timestamp].json）。下流で使用されるすべての視聴回数とエンゲージメント数値は、raw/ 内のファイルにトレース可能である必要があります。

ステージ3: デコード

すべての異常値に対して video-decoder スキルを実行します。渡すもの: トランスクリプトテキスト（利用可能な場合）、カバーフレームURL（利用可能な場合）、クリエイターハンドル、プラットフォーム、異常値の大きさ（ステージ1で計算された比率）、競合リング割り当て（video-decoder/references/decode-framework.md のリング定義を使用して、ブランドに対する各動画のリングを分類）。

video-decoder スキルは、動画ごとに入力された1つのデコードレコードを返します。これには、ビジュアルフック（カバーフレームと表示されるテキストオン画面から導出）、書き言葉のフック、話し言葉のフックが含まれます。各レコードを 01-decodes/[video_id].md に書き込みます。この時点で、すべてのデコードには decode_depth: shallow が設定されています。

トランスクリプトがないだけでは、動画をスキップする理由にはなりません。最も高い異常値を持つ動画の多くは、テキストオーバーレイまたはPOVスタイルの動画で、音声コンテンツがありません。動画にカバーフレームまたはキャプションがある場合は、spoken_hook: n/a で浅くデコードします。デコードするものが本当に何もない場合にのみ動画をスキップします。トランスクリプトがない、カバーフレームがない、キャプションがない、そして他の意味のあるシグナルもない（例: 取得失敗で何も取得できない）場合です。スキップされた動画はすべて、動画URLと正確な理由とともに 00-intake.md に decode-failed として記録します。残りの動画の処理を続行します。

ステージ4: 深層パス

異常値の大きさでランク付けされた上位5〜8の異常値を選択します（最も高い比率から順）。

いずれかの動画に対してGeminiヘルパーを呼び出す前に、scrape スキルを使用してその動画のダイレクトCDNメディアURLを解決します。ソーシャルページURL（TikTokやInstagramのページURLなど）はGeminiによって拒否されます。CDNメディアURLをヘルパーに渡し、ソーシャルページURLは決して渡さないでください。解決方法はプラットフォームによって異なります。プラットフォームごとのアプローチについては、scrape/references/reading-scrape.md の「動画のダイレクトメディアURLの解決」を参照してください（TikTokはビデオ情報ルックアップが必要です。InstagramメディアURLはすでに取得済みの投稿ペイロードにあります。YouTube視聴URLは直接通過します）。CDN URLは期限切れになるため、実行内で迅速に解決して使用してください。

選択された各動画について、Geminiヘルパーを呼び出し、stdoutを1つのコマンドで生ファイルに直接リダイレクトします。

ヘルパーパスは、このSKILL.mdを含むディレクトリ（インストールされたプラグイン内の shortform-idea-engine スキルディレクトリ）からの絶対パスとして解決する必要があります。そのディレクトリを実行時に特定し、その中の scripts/gemini-video-analyze.js への絶対パスを構築します。出力リダイレクトのターゲットは、ステージ0で確認された実行ベースパスの下の実行フォルダです。これら2つのパスは独立して解決されます。ヘルパーパスはスキルディレクトリから、出力パスは実行ベースパスから解決されます。

OPENROUTER_API_KEY=<key> node <skill-dir>/scripts/gemini-video-analyze.js <cdnMediaUrl> "Analyze this short-form video for: pacing (average cut frequency, notable slow or fast segments), cut rhythm (pattern of cuts: cut-on-beat, reaction cuts, b-roll intercuts), visual style (color grading, background, camera movement, on-screen graphic density), text-on-screen cadence (how often captions or callouts appear relative to spoken content), and retention devices (specific hooks, pattern interrupts, cliffhangers, or loops used mid-video). Return structured notes for each dimension." > <run-base>/YYYY-MM-DD-<slug>/raw/gemini-<video_id>-<timestamp>.json

ここで、<skill-dir> は shortform-idea-engine スキルディレクトリ（このSKILL.mdを含むディレクトリ）への絶対パスであり、<run-base>/YYYY-MM-DD-<slug>/ はステージ0で確認された実行フォルダです。

リダイレクトにより、生のGeminiレスポンスが実行フォルダ内の raw/gemini-<video_id>-<timestamp>.json に保存され、ステージ8のトレーサビリティを満たすことができます。

これらの動画のそれぞれに対して video-decoder スキルを再実行し、オプションの深層分析入力としてGeminiブロックを渡します。再実行により、decode_depth: deep と deep_notes が入力された更新されたデコードレコードが返されます。既存の 01-decodes/[video_id].md を深いレコードで上書きします。

OPENROUTER_API_KEY が設定されていない場合は、ステージ4を完全にスキップします。すべてのデコードは shallow のままであり、「shallow-decoded」フラグがステージ6でアイデアごとに記録されます。

ステージ5: アイデア創出

01-decodes/ のすべてのデコードレコードから、すべてのバイラルベクター、インタレストトピック、フォーマットをプールします。10〜15のリミックスアイデアを生成します。各アイデアは以下を満たす必要があります:

どのバイラルベクターを借用するか名前を付ける（デコードレコードからのそのままのラベル）。
どのインタレストトピックを借用または適応するか名前を付ける。
どのフォーマットを使用するか名前を付ける。
ブランドアングルを述べる：借用したVV、IT、フォーマットがこの特定のブランドに適合するようにどのようにリミックスされるか（ブランドプロファイルの content_pillars、audience、proof_credibility フィールドを使用してアングルを固定する）。
借用した各要素のソース系列を記録する：creator_handle、source_url、video_id を、その要素が抽出されたデコードレコードから取得する。要素が複数のデコードレコードに出現する場合は、すべてをリストする。この系列は、ランキングを経てスクリプトまでアイデアとともに移動する。

ここではリングによる抽出シグナルの重みが適用されます（video-decoder/references/decode-framework.md から）: VVは4つのリングすべてから有効です。ITは間接競合他社からのシグナルが最も強いです。フォーマットは隣接競合他社からのシグナルが最も強いです。それに応じてリミックスの重み付けを行いますが、リングのみに基づいて機械的にアイデアを除外しないでください。

プール内に存在しないVV、IT、またはフォーマットの組み合わせを作り出すことなく、10の異なるアイデアをサポートするにはデコードプールが小さすぎる場合は、プールがサポートする数の本物のアイデアのみを生成します。02-ideas.md の上部に不足数と実際の数を記載してください。デコードされなかった抽出可能なものを決して発明しないでください。

ステージ6: ランク付け

references/ranking-rubric.md を使用してすべてのアイデアをスコアリングします:

各アイデアをブランドプロファイルの anti_topics リストと照合します。一致した場合は即座に失格となります（DQ: anti-topic）。失格となったアイデアをランク付けテーブルから削除します。各失格アイデアを、ランク付けテーブルの下、02-ideas.md の下部にある明確にラベル付けされた「失格（アンチトピック）」セクションに追加し、アイデアとトリガーとなった特定のアンチトピックをリストします。
残ったアイデアを2つの軸でスコアリングします: viral_potential（5つのサブ要素の平均: VVの強さ、異常値の大きさ、フォーマットの再現性、トピックの新しさ、フックの強さ）および brand_fit（4つのサブ要素の平均: ボイスの一致、オーディエンスの一致、コンテンツピラーの一致、信頼できる信頼性）。両方のスコアは1〜10のスケールを使用します。
combined = viral_potential * (brand_fit / 10) を計算します。小数点第1位に丸めます。
combined で降順に並べ替えます。2つのアイデアが同点の場合、viral_potential が高い方が最初にランクされます。
ランク付けテーブルを 02-ideas.md に次の列順で書き込みます: # | idea | root | borrowed VV/IT/Format | source video | viral | brand fit | combined | one-line rationale。source video セルは、アイデアのトレース元となるプライマリソース動画を @creator_handle / video_id として表示します。アイデアが複数のソースから要素を借用する場合は、プライマリとして1つを選択し（VVソースが最も重要）、「+ N more」を追加します。
各アイデアについて、viral_potential と brand_fit の内訳（各サブ要素のスコア）をテーブルの下に別のセクションとして書き込みますが、one-line rationale にサブスコアの要約を含めます。
各「shallow-decoded」アイデアを 02-ideas.md でフラグ付けします。

ステージ7: スクリプト作成

ランク付けテーブルから、実行の範囲内でトップNのアイデアを選択します。デフォルトでは上位3つ。各アイデアについて、script-writer スキルを呼び出します。次のパラメータを渡します:

アイデアの説明（02-ideas.md のランク付けテーブルの idea 列の内容）
シードバイラルベクター（borrowed VV/IT/Format 列からのVV）
シードフォーマットテンプレート（borrowed VV/IT/Format 列からのフォーマット）
ブランドの voice_tone（brand_profile.md から）
ブランドの forbidden_constructions リスト（brand_profile.md から）
ブランドの on_camera_talent（brand_profile.md から）
アイデアの source video URL

script-writer スキルが返す完成したスクリプトを 03-scripts/[idea-number]-[idea-slug].md に書き込みます。各スクリプトの上部に、それがどのランク付けアイデアに由来するかを示すメタデータフロントマター（テーブルの # 列番号）を含めます。

ステージ8: ラップアップ

references/post-run-summary.md テンプレートに入力します。実行フォルダのルートに 99-summary.md として書き込みます。概要には以下を含めます:

処理された動画の総数（ステージ1、ステージ3、ステージ4の間のドロップオフを含む、各ステージで）
生成されたアイデアの数と失格となった数
使用されたブランドプロファイル
00-intake.md からのモードと実行スラッグ
消費されたクレジットの見積もり（もし既知であれば）

使い方

一般的なユーザーフローは以下の通りです:

インプット (ステージ0)：モード（キーワードまたはハンドル）、クエリ/ハンドル、ブランドプロファイル、実行スラッグを選択します。APIキーがチェックされ、フォルダ構造が作成されます。
発見 (ステージ1)：キーワード（直接/間接/隣接リングを経由）またはハンドルの異常値動画を検出します。動画ごとの異常値比率を計算するためにクリエイターのベースラインも計算します。
レシート (ステージ2)：各異常値動画のトランスクリプトとサムネイルを取得します。
デコード (ステージ3)：各動画を解読し、ビジュアルフック、書き言葉のフック、話し言葉のフック、VV、IT、フォーマットを抽出します。
深層パス (ステージ4、オプション)：上位の異常値をGeminiによる視覚分析で分析し、デコードを強化します。
アイデア創出 (ステージ5)：デコードされた要素をリミックスして、ブランドに適合したアイデアを作成します。
ランク付け (ステージ6)：バイラル可能性とブランド適合度に基づいてアイデアをスコアリングし、ランク付けします。
スクリプト作成 (ステージ7)：トップアイデアの撮影準備完了のスクリプトを作成します。
ラップアップ (ステージ8)：実行の概要を生成します。

ファイル構造

実行後、ファイル構造は次のようになります:

<run-base>/YYYY-MM-DD-<slug>/
├── 00-intake.md
├── 01-decodes/
│   ├── [video_id_1].md
│   ├── [video_id_2].md
│   └── ...
├── 02-ideas.md
├── 03-scripts/
│   ├── 1-[idea-slug-1].md
│   ├── 2-[idea-slug-2].md
│   └── 3-[idea-slug-3].md
├── 99-summary.md
├── raw/
│   ├── virlo-response-[ring]-[timestamp].json
│   ├── scrapecreators-posts-[handle]-[timestamp].json
│   ├── scrapecreators-transcript-[video_id]-[timestamp].json
│   ├── gemini-[video_id]-[timestamp].json
│   └── ...
└── brand_profile.md (もし作成された場合)

参考文献

references/brand-profile-template.md: ブランドプロファイルのスキーマ定義。
references/ranking-rubric.md: アイデアのランク付けに使用されるスコアリング基準。
references/post-run-summary.md: 実行概要テンプレート。

ShortFormアイデアエンジン