img-recog

img-recog — 画像認識スキル

画像（スクリーンショット、写真、図、スキャン画像）を確認する必要があるものの、現在のモデルにマルチモーダル（視覚）機能がない場合や、組み込みの read ツールが画像形式に対応していない場合に、このスキルを使用します。

⚠️ セキュリティ：設定ファイル

設定ファイルは2つあり、~/.wmyskills/img-recog/ に保存されています。

ファイル	用途	AI による読み取り
provider.yaml	API のベース URL とキー	いいえ — このファイルは絶対に読み取ったり表示したりしないでください
model.yaml	モデルとプロバイダーの対応付け、および既定値	はい — AI はモデルとプロバイダーの対応付けや既定値を把握するために読み取れます。ただし、生のキーは絶対に表示しないでください

AI は provider.yaml の内容を絶対に読み取ったり表示したりしてはいけません。 このファイルは Python スクリプトによって実行時にのみ読み込まれます。ユーザーからこのファイルの表示や編集を求められた場合は、依頼を断るか、ユーザー自身で直接編集するよう案内してください。

どのモデルとプロバイダーが設定されているかを把握する必要がある場合（ユーザーへの使い方のアドバイスなど）、AI は model.yaml を読み取ってもかまいません。ただし、生の API キーやシークレットは絶対に表示してはいけません。

セットアップ

設定ファイルは、img-recog_PROVIDER_FILE と img-recog_MODEL_FILE の環境変数で定義されたパスから読み込まれます（既定値：~/.wmyskills/img-recog/{provider,model}.yaml）。環境変数が設定されていない場合は、テンプレートを既定のディレクトリにコピーしてください。

cp references/templates/provider.yaml.template ~/.wmyskills/img-recog/provider.yaml
cp references/templates/model.yaml.template ~/.wmyskills/img-recog/model.yaml

パスをカスタマイズするには、~/.wmyskills/.env（または優先される scripts/.env）で img-recog_PROVIDER_FILE / img-recog_MODEL_FILE に希望のパスを設定してください。

コピーした後、プレースホルダーの値を実際のキーに置き換え、プレースホルダーのマーカーを削除してください。スクリプトは base_url と api_key が空でないことを検証します。プレースホルダーを残すとエラーになります。

要件

• Python >= 3.10、scripts/requirements.txt に記載されたパッケージ
• ffmpeg — --compact による画像圧縮を行う場合のみ必要
• Pillow — --metadata で EXIF フィールドを取得する場合のみ必要

実行ルール

プロバイダーの設定、API キー、モデルの利用可否を事前に確認せず、画像認識コマンドを直接実行してください。問題がある場合はスクリプトが明確なエラーを出すため、その時点で確認して修正してください。

使い方

cd <skill-dir>
python scripts/img_recog_cli.py --img <image-source> [--prompt <text>] [--provider <name>] [--model <name>] [--compact <size>] [--metadata] [--json]

引数

引数	必須	説明
--img	はい	ローカルパス、HTTP(S) URL、または Base64 データ URI（data:image/...;base64,...）
--prompt	いいえ	テキストまたは @filepath（既定値："この画像について詳しく説明してください"）
--provider	いいえ	プロバイダーを上書きします（既定値は model.yaml から取得）
--model	いいえ	モデルを上書きします（既定値は model.yaml から取得）。プロバイダーがサポートするモデル名であれば指定でき、model.yaml に記載されている必要はありません
--compact	いいえ	送信前に画像を WebP に変換し、指定サイズを目標に圧縮します（例：500KB、0.5MB、512000B。単位のない数値は KB として扱います）。
--metadata	いいえ	認識と並行して画像のメタデータ（サイズ／幅／高さ／色／デバイス／アプリ／時刻／位置情報）を抽出します。メタデータはモデルには送信されず、エージェントに渡されます（JSON の場合はトップレベルの metadata キー、JSON 以外の場合は [metadata] ブロックを stderr に、取得でき次第出力します）。取得できないフィールドは null になり、取得に失敗した場合は警告を出して処理を続行します
--max-tokens	いいえ	出力トークンの最大数（既定値：4096）。正の整数を指定してください
--json	いいえ	詳細情報を含む JSON を出力します

簡単な使用例

# Describe a local screenshot
python scripts/img_recog_cli.py --img screenshot.png

# Extract text from a photo with specific prompt
python scripts/img_recog_cli.py --img photo.jpg --prompt "Extract all text from this image"

# Fetch and describe an online image
python scripts/img_recog_cli.py --img https://example.com/diagram.png

# Use custom model
python scripts/img_recog_cli.py --provider openai --model gpt-5.6-terra --img chart.png

# Read prompt from file
python scripts/img_recog_cli.py --img graph.png --prompt @prompt.txt

# Structured JSON output
python scripts/img_recog_cli.py --img screenshot.png --json

# Compress a large screenshot to ≤ 500KB before sending
python scripts/img_recog_cli.py --img screenshot.png --compact 500KB

# Recognize + extract metadata
python scripts/img_recog_cli.py --img photo.jpg --metadata

参考ファイル

場所	用途
references/templates/	設定ファイルのテンプレート（~/.wmyskills/img-recog/ にコピー）
references/prompts/	よくあるタスク用のプロンプトテンプレート（--prompt @ と併用）
references/prompts/_system.md	システムプロンプト — スクリプトによって自動的に system メッセージとして読み込まれ、視覚モデルに出力が別の AI によって使用されることを伝えます。ユーザー向けのプロンプトプリセットではないため、--prompt @ と併用しないでください
references/prompts/index.yaml	プロンプトプリセットのインデックス — スキルの読み込み時に最初に確認し、利用可能なプリセットとそれぞれの使用方法を把握してください

プロンプトプリセット

このスキルが読み込まれたら、まず references/prompts/index.yaml を読み込んで、利用可能なプリセット（それぞれに name、lang、use_when があります）を確認してください。

デフォルトでは、説明を求められたとき（画像を「見て」「確認して」「説明して」と頼まれた場合）は describe.txt を使用してください。 画像内のテキストを「読んで」または「抽出して」と頼まれた場合は、extract-text.txt を使用してください。

# Example: describe in English
python scripts/img_recog_cli.py --img photo.jpg --prompt @references/prompts/describe.txt

# Example: extract text in Chinese
python scripts/img_recog_cli.py --img scan.png --prompt @references/prompts/extract-text-zh.txt

注意事項

• スクリプトは Windows のエンコーディングを自動検出し、標準出力を UTF-8 に切り替えます
• タイムアウト：接続 10 秒、読み込み 120 秒
• ローカル画像の場合、ファイルは読み込まれ、メモリ上で Base64 に変換されます。テンポラリファイルは作成されません
• URL 画像の場合、画像はダウンロードされ、API との互換性を最大限に高めるためデータ URI に変換されます
• --compact は ffmpeg を使用して WebP に圧縮します。アニメーション画像（GIF など）と、すでに目標サイズ以内の元画像は再エンコードせずにスキップされます
• --metadata は認識処理と並行してバックグラウンドスレッドで実行され、その後、ffprobe で取得した size（元のバイト数）、width／height／color（pix_fmt）と、Pillow EXIF で取得した device／app／time／location（GPS → 10進度）を報告します。--compact も使用した場合でも、すべてのフィールドは元画像を反映します
• デフォルトの（JSON 以外の）出力は 2 つのブロックで構成されます。[metadata]（--metadata 使用時に標準エラー出力）と [result]（ビジョンモデルの出力、標準出力）です。モデル名とトークン使用量は表示されません
• 設定ファイルのパスは、環境変数 img-recog_PROVIDER_FILE と img-recog_MODEL_FILE（~/.wmyskills/.env または scripts/.env に設定）で上書きできます。デフォルトは ~/.wmyskills/img-recog/ のままです

トラブルシューティング

エラー	考えられる原因
"Authentication failed"	provider.yaml の api_key を確認してください
"Model not found at provider endpoint"	そのプロバイダーにモデル名が存在しません
"Cannot connect to API"	provider.yaml の base_url またはネットワークを確認してください
"Bad request / model may not support image input"	選択したモデルは画像認識に対応していません
"Request timed out"	画像が大きすぎるか、ネットワークが遅い可能性があります
"ffmpeg not found"	ffmpeg をインストールしてください（「要件」を参照）
"Pillow is required for --metadata"	Pillow をインストールしてください（「要件」を参照）

プロンプトプリセットの追加

新しいプロンプトプリセットを追加するには：

1. references/prompts/ にプロンプトファイルを作成します
2. references/prompts/index.yaml に name、lang、use_when フィールドを含むエントリーを追加します
3. この SKILL.md の「プロンプトプリセット」セクションに使用例を追加します