shot-annotate: スクショに赤枠と注釈を入れる

画像を貼っただけでは、見る人はどこを見ればいいのか分からない。 説明を口で補うか、キャプションを読ませることになる。どちらも相手の負担が増える。

赤枠で場所を示し、短い注釈を書く。ここまでやって1枚が完成する。 指摘（これが問題）にも、修正指示（ここをこう直す）にも使う。

使い方

スクリプトはこの SKILL.md と同じディレクトリの scripts/ にある。 npx skills add で入れた場合は .claude/skills/shot-annotate/scripts/annotate-shot.py。

python3 .claude/skills/shot-annotate/scripts/annotate-shot.py \
  --in before-article.png --out annotated-article.png --px \
  --box     112,166,740,100 --arrow 470,140,566,164 --label 296,110,"タイトルを変更" \
  --box     112,282,420,200 --arrow 700,382,548,382 --label 716,370,"画像を入れる" \
  --ellipse 106,500,280,48  --label 410,506,"トル" \
  --line    118,641,842,641 --line 118,677,478,677

指定	意味
--box x,y,w,h	枠
--ellipse x,y,w,h	丸。1語や見出しを囲む
--arrow x1,y1,x2,y2	矢印（x1,y1 から x2,y2 へ）
--line x1,y1,x2,y2	線。斜めに引いて「ここは消す」を示す
--label x,y,text	注釈の文字。\n で改行
--color red|green|blue	以降の色。既定は red。OK を示すときだけ green
--px	座標を実寸ピクセルで読む（既定は画像に対する %）
--scale	線の太さと文字の倍率
--font	フォントファイルのパス。自動で見つからないときだけ

--box --ellipse --arrow --line --label --color は何度でも書ける。書いた順に描かれる。

線の太さと文字の大きさは画像の幅から決まる（幅2880pxで線8px・文字44px）。 画像の大きさが違っても見た目が揃うので、案件をまたいでも同じ絵になる。

必要なもの

python3 と Pillow だけ。

pip install pillow

日本語フォントは macOS（ヒラギノ）・Windows（游ゴシック / メイリオ）・ Linux（Noto Sans CJK）を自動で探す。見つからないときは警告を出して既定のフォントに落ちるので、 --font /path/to/font.ttf を渡す。

座標の決め方

1. 画像を半分の大きさにして開く

   python3 -c "from PIL import Image; Image.open('原本.png').resize((1440,810)).save('/tmp/half.png')"
   

2. 半分の画像で位置を読み、2倍して実寸にする

3. 枠を描いたら、その部分だけ切り出して確かめる

   python3 -c "from PIL import Image; Image.open('出力.png').crop((900,240,2100,480)).save('/tmp/c.png')"
   

文字が枠を突き抜けたり、枠が文字の途中を切ることが多い。必ず目で見る。

書き方の規律

• 原本は別ディレクトリに退避してから上書きする。位置を直すたびに撮り直すのは無駄で、 注釈の重ねがけで線が太る
• 何を伝える画像かで、入れてよい数が変わる
  • 指摘（これが問題だと示す）… 枠1つ、注釈1つ。複数入れると、どれが本題か伝わらない
  • 修正指示（ここをこう直してほしい）… 直す箇所のぶんだけ入れてよい。 ただし1画面に収まる数まで。多いなら画像を分ける
• 注釈は画像の中で完結させる。キャプションや本文と同じ文を書かない
• 「無い」ものを示すときは、有るべき場所を枠で囲って「◯◯がない」と書く
• 評価語（ひどい・危険・致命的）を書かない。事実だけを書く。見た人が自分で判断する
• 色は赤と緑だけ。緑は「こちらは正しい」を並べて見せるときにしか使わない

画面に写らないものを図にする

設定ファイルの中身・APIのレスポンス・ログのように、画面に出ないものがある。 そのまま丸ごと貼ると、読む人が追えない。

問題になっている行だけを HTML で組み、ブラウザで撮ってから同じ書式で注釈を足す。

<div class="code">timeout = 300</div>

• 値は必ず実物から取る。作った値を図にしない
• 行は2〜4行まで。文脈が要る行だけコメントで補う
• 文字は26px以上。縮小して表示される場所に置くなら、その縮尺で読めるか確かめる

貼り先が固定の縦横比で切り抜く作りなら、その比で作る。 横長で作ると左右が切れる（例: aspect-video + object-cover の枠なら 1230x692）。

撮る側の注意

• 上から1000pxのスクショで「無い」を判定しない。枠の外にあるだけのことがある。 「〜が無い」は DOM で数えてから書き、画像は説明のために添える
• ページは直る。撮影日を必ず控える