AutoShorts — デイリーバイラルクリップパイプライン

パイプラインツールは ~/Documents/skill-autoshorts/ に配置されます。このスキルは毎日 INPUT_FOLDER から1つの長い動画を選択し、実行可能なすべてのショートフォーム動画を抽出し（Gemini 3 Flash が判定）、ユーザーに承認を得るために表示し、承認されたものを Upload-Post 経由で公開します。

セットアップ（まだ設定されていない場合のみ）

1. Python 環境

cd ~/Documents/skill-autoshorts && python3 -m venv venv && source venv/bin/activate && pip install -r requirements.txt

2. FFmpeg

必須のシステムバイナリです。ffmpeg -version で確認してください。ない場合は brew install ffmpeg でインストールしてください。

3. .env

ファイルは ~/Documents/skill-autoshorts/.env に配置します。必須キー：

UPLOAD_POST_API_KEY=...
UPLOAD_POST_PROFILE=...
GEMINI_API_KEY=...
INPUT_FOLDER=/abs/path/to/long/videos
OUTPUT_FOLDER=/abs/path/to/clip/output
WHISPER_MODEL=medium
TIMEZONE=Europe/Madrid

必須キーが不足している場合は、続行する前にユーザーに尋ねてください。

4. Upload-Post アカウント

• https://upload-post.com でサインアップ → ダッシュボード https://app.upload-post.com にアクセス
• ダッシュボードで OAuth 経由で TikTok、Instagram（Facebook ページにリンクされたビジネス/クリエイターアカウント）、YouTube を接続
• Manage Users でプロフィールを作成 — その名前が UPLOAD_POST_PROFILE です（ソーシャルハンドルではありません）
• Settings で API キーを生成
• 確認: curl -H "Authorization: Apikey $UPLOAD_POST_API_KEY" https://api.upload-post.com/api/uploadposts/me

オーケストレーションモデル

このスキルは openclaw ハーネスによって毎日実行され、ハーネスはメッセージングブリッジ（Telegram、WhatsApp、または openclaw が設定されているチャネル）も処理します。スキル自体は Telegram やメッセンジャーと直接通信しません — パイプラインを実行して候補をテキスト + 絶対ファイルパスとして表示するだけです。openclaw がご自分の出力をユーザーの電話に転送し、ユーザーの返信をキャプチャして、会話に戻します。

具体的には：ステップ 5 で候補テーブルを印字してどの ID を公開するかを尋ねます。openclaw がそのテーブルとクリップファイルをユーザーの選択したチャネル経由で配信します。ユーザーが電話で返信します（例："1, 3, 5"）。openclaw がその返信を再度注入します。ステップ 6-8 を続行します。ワークフロー内の他の「ユーザーに尋ねる」ポイント（メタデータレビュー、ドライラン確認など）でも同じパターンです。

スキルが openclaw の外で実行される場合（例：ユーザーが Claude Code で /autoshorts を直接実行）、同じプロンプトが機能します — ターミナルにのみ表示されます。

デイリーワークフロー

このスキルは デイリー無限ループ として実行されることを想定しています。実行ごとに1つの動画を選択し、パイプラインを通します。ピック セマンティクスは サイクルごとのラウンドロビン です：各動画はサイクルごとに最大1回ピックされます。INPUT_FOLDER 内のすべての動画が現在のサイクルで処理されると、新しいサイクルが自動的に開始され、同じ動画が再度利用可能になります — すでにクリップされたソースから新しいクリップを生成します。state/processed.json のステートファイルは、cycle_started_at、動画ごとの last_processed_at、および動画ごとの cycles_count を追跡します。サイクル内では、次のピックは最新の未処理-このサイクル（mtime DESC）なので、新しい素材は常にキューにジャンプします。

ステップ 0 — プリフライト（すべての実行で実行、スキップしないこと）

作業を開始する前に、環境が準備できていることを確認し、不足しているものについてユーザーに尋ねてください：

1. venv — ~/Documents/skill-autoshorts/venv/bin/python は存在しますか？存在しない場合は、セットアップセクションのステップ 1 を実行してください。（尋ねずに実行できます — 機械的です。）
2. PATH 内の ffmpeg — 不足している場合、ユーザーに brew install ffmpeg を実行してもらうよう依頼してください（自分でインストールしないでください；システム全体のインストールは確認に値します）
3. .env ファイル — すべての必須キーが設定され、空でないことを確認してください：
   • GEMINI_API_KEY → 不足している場合、尋ねてください："Falta la API key de Gemini. Pégamela (la generas en https://aistudio.google.com/apikey)."
   • UPLOAD_POST_API_KEY と UPLOAD_POST_PROFILE → 不足している場合、尋ねてください："Necesito la API key de Upload-Post y el nombre del profile (Manage Users en https://app.upload-post.com)."
   • INPUT_FOLDER と OUTPUT_FOLDER → 不足している場合、デフォルトを ~/Documents/skill-autoshorts/input と ~/Documents/skill-autoshorts/output にして .env に書き込んでください
   • WHISPER_MODEL → デフォルト medium。TIMEZONE → デフォルト Europe/Madrid
4. Upload-Post プラットフォームヘルス — GET /api/uploadposts/users を呼び出し、設定されたプロフィールの各プラットフォームについて reauth_required を読みます。プラットフォームが再認証を必要とする場合、ユーザーが再認証（https://app.upload-post.com）するか、後で --platforms からそれを削除するかのいずれかを行う必要があることをユーザーが知るように表示してください。

ユーザーが会話で API キーを提供する場合、すぐに .env に書き込んで、絶対に返さず、キーが会話ログに含まれていることを警告し、テスト後にそれをローテーションすべき ことを伝えてください。

入力動画フォーマット: INPUT_FOLDER 内の動画は既に 9:16 垂直で投稿準備完了状態（一般的に 1080×1920）であることが想定されています。ユーザーが焼き込みサブタイトルを使用している場合、それらは既にソース動画に含まれているべきです。スキルは再フォーマット、クロップ、スケール、またはサブタイトルの焼き込みは行いません — 選択されたセグメントをカットしてフック テキストをオーバーレイするだけです。動画がランドスケープまたは任意の非 9:16 比率で到着する場合、ユーザーに表示して処理前に確認を得てください — パイプラインをそのまま実行するとTikTok互換でない出力が生成されます。

動画が INPUT_FOLDER にどのように到着するか はハーネスの仕事であり、スキルの仕事ではありません。標準的なフロー：ユーザーが動画を openclaw/Hermes/チャット内のエージェント（Telegram/WhatsApp など）に転送し、ハーネスがダウンロードして INPUT_FOLDER に保存します。スキル自体は既にそこにあるファイルのみで動作します。ユーザーが INPUT_FOLDER 内でない動画パス（例：/autoshorts /Users/foo/Downloads/podcast.mp4）を渡す場合、最初にコピーしてください（cp を使用、移動しないでください — 元のファイルはそのままです）。そうしないと pick はそれを見つけられません。

ステップ 1 — 動画をピック

python autoshorts.py pick

処理する次の動画を JSON で返します。出力フィールド：

• path、name、size_mb、mtime、duration_s — ファイルメタデータ
• previous_cycles_completed — この動画が既に処理されたサイクル数（0 は初回）
• remaining_in_cycle — 現在のサイクルで未処理のままの他の動画の数
• cycle_started_at — 現在のサイクル開始のタイムスタンプ
• new_cycle_started — このピックが新しいサイクルを開いたものである場合 true（前のサイクルですべての動画が処理されて、ループがラップアラウンド）

new_cycle_started が true の場合、簡潔にユーザーに言及してください（"新しいサイクルを開始 — この動画は N 回以前にクリップされていますが、新しいモーメントを狙っています"）。エラーではありません — 予期されたラップアラウンドです。Gemini はプロンプトが非決定的で HOT.md の優先度が進化するため、別のモーメントを選ぶ可能性があります。

パイプラインは新しい動画が不足しても強制停止しません。唯一の強制停止ケースは INPUT_FOLDER が空の場合です — それを表示して、ユーザーに何かをドロップするよう依頼してください。

ユーザーが明示的にサイクル順序の外で「動画 X を今再処理してください」と言う場合、最初に state/processed.json からそのエントリを削除し、ピックを実行してください。他の手段でサイクルロジックをバイパスしないでください。

ステップ 2 — トランスクライブ

python autoshorts.py transcribe "<VIDEO_PATH>"

文セグメントと単語ごとのタイムスタンプを含む output/<video_slug>/transcript.json に書き込みます。Whisper は言語を自動検出します。デフォルトモデルは medium です。

ステップ 3 — Gemini 3 Flash で分析

python autoshorts.py analyze "<VIDEO_PATH>"

動画を Gemini Files API にアップロードし、gemini-3-flash-preview に EVERY 実行可能なショートフォーム モーメント（各 20～60 秒）をリクエストします。タイムスタンプはトランスクリプトの単語の境界にスナップされます。出力：output/<video_slug>/clips.json。このファイルを読んで候補リストを取得します。

ステップ 4 — すべての候補をカットしてフックオーバーレイを追加

clips.json の各クリップについて、2つのコマンドを実行します：

python autoshorts.py extract "<VIDEO_PATH>" \
    --start <START> --end <END> \
    --output "output/<slug>/clip_<ID>.mp4"

python autoshorts.py hook "output/<slug>/clip_<ID>.mp4" \
    --text "<HOOK_TEXT>" --duration 3 \
    --output "output/<slug>/clip_<ID>_final.mp4"

フックは TikTok/Instagram スタイルでレンダリングされます：テキストの各行が背後に独自の黒いピル（78% 不透明、角丸）を取得し、その上に白い Impact テキスト + 黒いストロークが付きます。ピルは任意の背景でフックを読みやすく保ちます — 純白、純黒、ビジーなスクリーンシェア — 基本的なフレームを検査する必要なしに。フレームの上部に位置し、最初の 3 秒間。フック テキストは clips.json から取得します（Gemini が動画の言語で記述）。

すべての候補を事前にカットしてフックします — ユーザーはメタデータではなく、実際の最終ファイルを視覚的にレビューします。

ステップ 4.5 — フックのビジュアル QA（自分でこれを実行、Gemini 呼び出しなし）

あなたはマルチモーダルです。それを使ってください。 候補をユーザーに表示する前に、フック オーバーレイが各クリップで実際にクリーンにレンダリングされることを確認してください。

すべての clip_<ID>_final.mp4 について：

python autoshorts.py preview output/<slug>/clip_<ID>_final.mp4

これにより t=1.0s（フックの途中）でシングルフレームが抽出され、クリップの隣に preview_clip_<ID>_final.png が保存されます。Read ツールで開きます — Claude/openclaw は両方ともPNGを直接表示します。Gemini 呼び出しは不要です；スキルを実行しているエージェント自体がマルチモーダルレビューアーです。

各プレビューについて、以下を評価してください：

1. フック テキストは完全に表示されていますか？左右または上のエッジでクリップされた文字はありますか？
2. ピル背景は安全領域を超えて拡張していますか（任意のエッジから 5% 以上）？
3. フックはスピーカーの顔または他の重要なコンテンツをカバーしていますか？
4. アクセント記号・特殊文字（á é í ó ú ñ ¿ ¡）は正しくレンダリングされていますか？
5. フックは焼き込みサブタイトルと重なっていますか？（下部のサブタイトルは予想されていますが、上部に存在するフック自体と衝突する場合のみフラグを立ててください。）
6. レンダリング不具合：文字化け、ピル欠落、透明度の問題？

ステップ 5 テーブルに "QA" 列を追加 して、以下のいずれかを入力してください：

• ✅ — クリーン
• ⚠️ <issue> — 特定の問題をフラグ（例：⚠️ último carácter recortado、⚠️ pill desbordado a la derecha）

フラグが立ったクリップを黙って削除しないでください — 警告を表示してユーザーに決定させてください。QA パスは助言的です：「⚠️」はヒントであり、拒否ではありません。複数のクリップが同じ方法で失敗する場合（例：フックが一貫してオーバーフロー）、それはユーザーが今後フック スタイルを短縮することを提案する信号です。

ステップ 5 — ユーザーに提示

マークダウン テーブルを表示してください：

ID	Duration	Hook	Score	QA	Reason	File
1	38s	"..."	9	✅	...	output/<slug>/clip_1_final.mp4
2	27s	"..."	7	⚠️ acento "ó" recortado	...	output/<slug>/clip_2_final.mp4
…	…	…	…	…	…	…

常に表にテーブルを含めてください — openclaw はそれらを使用してメッセージをユーザーのメッセンジャー（Telegram/WhatsApp など）に転送するときに実際のクリップ動画を添付します。絶対パスがなければ、ユーザーはメタデータのみを表示して、クリップを視覚的にレビューできません。その後、尋ねてください：

どのクリップ ID を公開しますか？（例：1, 3, 5、または none。）

ユーザーの返信を待ってください（openclaw 経由でユーザーの電話から到着します）。

ユーザーが none と返信した場合（すべての候補を拒否）、ステップ 8 をスキップして mark-processed に --clips-published 0 で実行してください。これにより動画が消費されるため、明日の実行は次の動画をピックします — そうしないと、同じ拒否された候補が再び表示されます。ユーザーが後で同じ動画を再試行したい場合、state/processed.json からそのエントリを手動で削除できます。

ステップ 6 — 承認されたクリップのプラットフォームメタデータを生成

承認された ID ごとに、プラットフォーム固有のコピーを生成してください。これはあなたの仕事です。Claude として — 直接記述し、ツールを呼び出さないでください。動画の言語に合わせてください。

• TikTok (tiktok_title、最大 90 文字）：キャッチーなフック、1～2 の絵文字、最後にハッシュタグミックス。スウィート スポット～70～85 文字。
• Instagram Reels (instagram_title、最大 2200 文字）：ロングフォーム ストーリーテリング — 最初の行はフック、次に 2-4 の短い段落（\n\n を使用）、CTA（"Guarda esto"、"Etiqueta a alguien…"、"Comenta X para…"）、次に大小をミックスしたハッシュタグ 20-30（大/中/ニッチ）。スウィート スポット 500～800 文字合計。
• YouTube Shorts (youtube_title、最大 100 文字ですが ~40-60 文字に保ち モバイルで切り詰められないようにしてください）：キーワード付き SEO フレンドリー。説明は検索可能性に焦点を当て、ハッシュタグ 3-5 個以下。
• 独自のオーバーライドがないプラットフォーム用の一般的な title と description。

長さ契約（公開前に確認）： YouTube タイトルは最も制約されています — 最も短く最も直接的に記述してください。TikTok と Instagram は呼吸ができます — TikTok は tiktok_title で～85 文字、Instagram キャプションはデザイン上ロングフォームです。

生成されたコピーをユーザーに表示し、公開前に確認してください。

ステップ 7 — 公開をスケジュール

承認された各クリップを TIMEZONE（デフォルト Europe/Madrid）の明日の 10:00 から開始して 1 日に 1 クリップをスケジュール。次の各クリップ += 1 日。

公開前に、接続されたプラットフォームと再認証ステータスを確認してください：

curl -s -H "Authorization: Apikey $UPLOAD_POST_API_KEY" \
    https://api.upload-post.com/api/uploadposts/users | python -m json.tool

プラットフォームが "reauth_required": true を表示する場合、ユーザーに警告してください — そのプラットフォームのアップロードは失敗します。--platforms からそのプラットフォームを削除するか、一時停止してユーザーが https://app.upload-post.com で再認証できるようにしてください。

承認された各クリップについて：

python autoshorts.py publish "output/<slug>/clip_<ID>_final.mp4" \
    --platforms tiktok,instagram,youtube \
    --title "<GENERAL>" \
    --description "<DESCRIPTION>" \
    --tiktok-title "<TIKTOK_TITLE>" \
    --instagram-title "<INSTAGRAM_CAPTION>" \
    --youtube-title "<YOUTUBE_TITLE>" \
    --schedule "<ISO_DATE>" \
    --timezone "Europe/Madrid" \
    --tiktok-mode draft \
    --clip-id <ID> \
    --hook-text "<HOOK_TEXT>" \
    --viral-score <GEMINI_SCORE> \
    --reason "<GEMINI_REASON>" \
    --video-source "<SOURCE_VIDEO_FILENAME>"

--clip-id、--hook-text、--viral-score、--reason、--video-source フラグは実務上オプションではありません — これらはラーニングループに供給します。これらなしでは、learn はエンゲージメント メトリクスを無視された値にどのフック パターンが機能したかに相関させることはできません。値は clips.json（Gemini 出力）とソース動画ファイル名から直接取得します。

TikTok モード：--tiktok-mode draft（デフォルト）は post_mode=MEDIA_UPLOAD で TikTok インボックスに送信し、ユーザーがアプリ内で公開前に編集を終了できるようにします。ユーザーが明示的に即座公開を望む場合にのみ --tiktok-mode direct（DIRECT_POST）を使用してください。

常に最初に --dry-run で実行 し、ユーザーに正確なリクエストペイロードを表示します。明示的な「ゴー」の後にのみ実際の公開を実行してください。

ステップ 8 — 動画を処理済みとしてマーク

python autoshorts.py mark-processed "<VIDEO_PATH>" \
    --clips-generated <N_CANDIDATES> \
    --clips-published <N_APPROVED>

これにより動画のハッシュが state/processed.json に追加されるため、明日の pick はスキップします。--clips-published 0 でも実行してください — 拒否された動画も消費されます。mark-processed を実行しない唯一の時間は、パイプラインが途中で停止した場合（例：Gemini がクリップを生成する前にエラーが発生した）です。その場合は、ユーザーが明日同じ動画を再試行するようにしてください。

ステップ 8.5 — 反省（オプション、高速、定性的）

公開後、クイック reflect を実行して、ユーザーがクリップを承認した理由をキャプチャできます（エンゲージメント メトリクスは不要 — 承認対拒否信号だけ）：

python autoshorts.py reflect --window-days 30

これは最近の候補（learnings/candidate-history.jsonl）を承認（learnings/post-history.jsonl）と比較し、Gemini に定性的パターンを抽出するよう依頼します（"具体的な数字を含むフックを承認、質問形式のフックを拒否"）。出力は learnings/runs/reflect-YYYY-MM-DD-HHMM.md に出力されます。

これらの観察は HOT.md に自動的に昇格することはありません。これらはユーザーがレビューしてキュレートするメモです。時々 reflect を実行してください — 毎日は過剰で、週 1 回は問題ありません。

ステップ 9 — 最終サマリー

印字してください：

#	File	Duration	Hook	Schedule	Platforms

… とソース動画名、生成された候補数対公開数。

ウィークリー ラーニング ループ（learn）

このスキルは 時間とともにより賢くなります。過去のクリップからのエンゲージメント データ（ビュー、いいね、コメント、シェア、保存 — Upload-Post アナリティクスから取得）は、将来の実行のためのクリップ選択プロンプトにフィードバックされます。

カデンス

learn を 毎週 実行してください、毎日ではなく。エンゲージメント メトリクスは成熟するまでに時間がかかります。毎日 learn はノイズを追うでしょう。

python autoshorts.py learn

デフォルト：7 日間の浸漬（これより若いクリップは除外）、90 日間の最大年齢（古いものは古い）、複合スコア = 0.6·ビュー + 0.4·エンゲージメント率、上位/下位 20% を勝者/敗者として。

これが何をするか

1. learnings/post-history.jsonl を読み込みます（公開したすべてのクリップ、そのフック + Gemini スコア + Gemini 理由 + ソース動画を含む）
2. ソーク ウィンドウ内の各クリップについて、GET /api/uploadposts/post-analytics/{request_id} を呼び出します — 公開時に取得したのと同じ request_id
3. クリップごとに複合スコアを計算し、上位 20%（勝者）と下位 20%（敗者）をピック
4. 勝者 + 敗者 + 既存の learnings/HOT.md を Gemini Flash に送信し、更新された HOT.md（≤80 行）を生成するメタ プロンプトを実行し、新しい証拠でサポートされるパターンをリストアップ
5. 新しい HOT.md を書き込み（前のものを HOT.YYYYMMDD-HHMMSS.md.bak としてバックアップ）
6. 完全な監査を learnings/runs/learn-YYYY-MM-DD.md に書き込んで、ユーザーがどのクリップが勝者/敗者と呼ばれたか、およびラーニングがどのように変わったかを確認できるようにします。

HOT.md がどのようにフィードバックするか

cmd_analyze は自動的に learnings/HOT.md（存在してかつ空でない場合）を読み込み、それを Gemini プロンプトの前に「PRIOR LEARNINGS — クリップを選択してフックを記述するときに適用」として追加します