alt — Auto-Caption
ローカルのVLM(視覚言語モデル)をinput_dir内の各画像に対して実行し、JSONサイドカーをoutput_dirに書き込みます。キャプションの自動生成、バッチコンテンツの理解、他のツールへの説明の提供などに役立ちます。
このSKILL.mdが存在するスキルディレクトリを、以下$SKILL_DIRと呼びます。
使用するタイミング
以下のような場合にこのスキルを使用します。
- 写真からInstagramのキャプションを自動生成したい
- 画像のバッチを手動で確認せずに内容を把握したい
- 画像の説明をコンテンツパイプラインやスケジューリングツールに渡したい
セットアップ(初回のみ)
cd "$SKILL_DIR" && uv sync
moondream2の重みは初回使用時にダウンロードされます(HuggingFaceから約4GB)。 Phi-4の重みはより大きく(約8GB)、GPUが必要です。
エージェントワークフロー
1. ユーザーに質問する
画像を説明する前に、以下の情報を教えてください。
🧠 モデル
- moondream2 — 2Bパラメータ、高速、CPUで動作(デフォルト)
- phi4 — 3.8Bマルチモーダル、高品質、GPU必須
💬 キャプションスタイル(オプション — 適切なデフォルトを使用します)
例:「カジュアルで楽しく、絵文字入り」または「プロフェッショナルでインスピレーションを与える」
⚙️ デバイス
- auto — GPUが利用可能ならGPU、なければCPU(デフォルト)
- cpu — moondream2のみ使用可能。現代のデスクトップCPUで約7秒/画像
📁 入力/出力ディレクトリ(デフォルト: ./input および ./output)
2. config.jsonを編集する
ユーザーがキャプションスタイルを指定した場合、それをprompt_captionに反映します。
例:「この画像に対して、楽しくて絵文字豊富なInstagramのキャプションを書いてください。3〜5個のハッシュタグを含めてください。」
ユーザーがブランドビジュアルを要求した場合、skills/brand-manager/brand-assets/asset-manifest.jsonで利用可能なフォントを確認し、生成されるキャプションのガイダンスまたは引継ぎノートで推奨ブランドフォントに言及します。このスキルはJSONサイドカーのみを書き込むため、テキスト自体をレンダリングしません。visual-hook、video-captioner、end-ctaなどの下流レンダラーは、指定され利用可能な場合に実際のブランドフォントファイルを使用する必要があります。
3. 実行する
cd "$SKILL_DIR" && uv run python scripts/describe.py --config config.json
初回実行ではモデルの重みがダウンロードされます — ユーザーに数分かかる可能性があることを警告してください。
4. 結果を報告する
各画像の説明とキャプションを表示します。JSONファイルが書き込まれた場所をユーザーに伝えてください。
設定リファレンス
| キー | 値 | デフォルト | 説明 |
|---|---|---|---|
input_dir | パス | ./input | ソース画像フォルダ |
output_dir | パス | ./output | JSONサイドカーの出力先フォルダ |
model | moondream2, phi4 | moondream2 | 視覚言語モデル |
prompt_description | 文字列 | 「この画像を一文で説明してください。」 | 説明フィールド用プロンプト |
prompt_caption | 文字列 | 「魅力的なInstagramキャプションを書いてください...」 | キャプションフィールド用プロンプト |
device | auto, cpu, cuda | auto | 推論デバイス |
一般的な呼び出し方
# デフォルト(moondream2、autoデバイス)
cd "$SKILL_DIR" && uv run python scripts/describe.py
# 高品質(GPU必須)
cd "$SKILL_DIR" && uv run python scripts/describe.py --model phi4
# CPUを強制
cd "$SKILL_DIR" && uv run python scripts/describe.py --device cpu
# カスタムキャプションプロンプト
cd "$SKILL_DIR" && uv run python scripts/describe.py \
--prompt-caption "この画像に対してプロフェッショナルなLinkedInのキャプションを書いてください。"
出力
input_dir内の各photo.jpgに対して、output_dirにphoto.jsonを書き込みます。
{
"description": "日差しの入るカフェでコーヒーカップを手にした女性。",
"caption": "朝の習慣 ☕✨ 最高の一日の始まり。 #コーヒータイム #朝の雰囲気 #カフェ",
"tags": ["ポートレート", "コーヒー", "屋内", "暖かい光"]
}
ブランドフォントが関連する場合、このJSONにフォントファイルを埋め込むのではなく、下流の指示にフォント名/タグを含めてください。レンダリングスキルは、マニフェストパスを解決しフォントを適用する責任があります。
エラーハンドリング
phi4+cpu→ 設定検証で拒否され、明確なメッセージが表示されます- モデルダウンロード失敗 → HuggingFaceのエラー詳細が表示されます
- 個々の画像エラー → ログに記録され、他の画像は引き続き処理されます
リモート推論
このスキルは、同じJSONサイドカー出力を保持しながら、オプションのリモートキャプションをサポートします。
- デフォルトの動作は依然としてローカルです
- リモートプロバイダーはオプトインのみです
- サポートされるプロバイダー:
huggingface,replicate
設定キー
| キー | デフォルト | 備考 |
|---|---|---|
provider | null | null、local、またはnoneはローカルモードを維持 |
remote_model | null | オプションのプロバイダー固有VLMモデルオーバーライド |
hf_token_env | HF_TOKEN | HuggingFace認証用環境変数名 |
replicate_api_key_env | REPLICATE_API_TOKEN | Replicate認証用環境変数名 |
remote_timeout_seconds | 300 | リモート呼び出しタイムアウト |
例
# HuggingFace リモート画像キャプション
export HF_TOKEN=hf_your_token
uv run python scripts/describe.py --config config.json --provider huggingface
# Replicate リモート画像キャプション
export REPLICATE_API_TOKEN=r8_your_token
uv run python scripts/describe.py --config config.json --provider replicate --remote-model <replicate-model-slug>
注意事項
- リモートモードでも同じ
description/caption/tagsJSONサイドカーを書き込みます - 資格情報がない場合は即座に失敗します。ローカルモードへのサイレントフォールバックはありません
- Replicateでは、リモートキャプションに明示的なモデルスラッグが必要です
キャプション品質基準
キャプションは画像と同じくらい重要です。弱いキャプションは強力なビジュアルを無駄にします。キャプションを生成またはプロンプトする際には、以下の原則を適用してください。
ひとつのルール
すべてのキャプションは、ひとつ明確な中心的なアイディアを持つ必要があります。キャプションが複数のポイントを伝えようとすると、拡散し、インパクトを失います。最も強力なキャプションは、単一の spear tip(矛先)を持ちます。つまり、ひとつの約束、ひとつの教訓、ひとつの観察、ひとつのストーリービートです。
テスト: このキャプションを一文で言えますか?すべての行が同じアイディアをサポートしていますか?そうでない場合は、核が明確になるまで削除してください。
最初にフック
キャプションの最初の行はフックです。Instagramでは、最初の約125文字だけが「もっと見る」の前に表示されます — その最初の行がタップを勝ち取らなければなりません。LinkedInでは、最初の行が見出しです。
効果的なフックのパターン:
- 逆説: 「Xをするのはやめましょう。」
- 好奇心のギャップ: 「ほとんどの人は気づいていません...」
- アイデンティティの呼びかけ: 「あなたが[X]なら、注目してください。」
- 権威/経験: 「もしやり直すとしたら、私はこうします。」
- ペインポイント: 「これが[X]で行き詰まる理由です。」
「私は」で始まる、または何も言わないウォームアップ文で開くことは避けてください。最初の行は、残りの部分を読む価値を獲得する必要があります。
プラットフォーム固有の構造
Instagram:
- 最初にフック(125文字以下)
- 本文: ストーリー、教訓、または洞察
- 最後に関連する3〜5個のハッシュタグ
- 本物のトーン — 洗練されたマーケティング言語は避ける
- 絵文字は意味を補強するために使用し、装飾のためには使用しない
LinkedIn:
- 最大リーチのためには600〜800文字、高いCTRが必要な場合は100〜150文字
- 最初の行に強力なフック
- 投稿本文に外部リンクを含めない(LinkedInはアウトバウンドリンクのリーチを抑制します)
- 効果的なフレームワーク: フック → 洞察 → 分析 → CTA; または ストーリー → 教訓 → アクション → エンゲージメント質問
- 創造性よりも明確さ — 読者は素早くスキャンします
- 避けるべきこと: 絵文字の多用、過剰な空白、同じフォーマットの連続、外部フォント
ジェネリック対策テスト
生成されたキャプションを受け入れる前に、自問してください: これはこの写真を撮った専門家のように聞こえますか、それとも一般的なAIライティングのように聞こえますか?もし誰でも何についてでも書けるような内容なら、不合格です。キャプションは、特定の視点、観察、または実際の瞬間を反映しなければなりません。
避けるべきこと
- 最初の単語として「私は」で始めること
- 具体的なポイントのない曖昧なインスピレーション的な声明
- 意味を補強するのではなく、視覚的なパディングとして使用される絵文字
- 単一のキャプション内での複数のコールトゥアクション
- LinkedInでのハッシュタグスパム(10個以上のハッシュタグ)