mcpField
A
annotate-screenshots

annotate-screenshots

github.com/buildinternetクリエイティブ・メディア1959 回インストール今日更新
リポジトリ

annotate-screenshots について

annotate-screenshots は、撮影時または既存画像に注釈を加えるスキルです。CSS セレクターやピクセル座標で対象を指定でき、機密領域のマスキングにも対応します。

主な機能

  1. 01CSS セレクターで撮影中の画面に注釈
  2. 02ピクセル座標で既存画像に注釈
  3. 03枠、矢印、ラベル、フリーハンド線の追加
  4. 04機密領域の塗りつぶしやぼかし
  5. 05注釈付き PNG の生成

活用シーン

  1. 01ページ上の新要素や不具合の強調
  2. 02スクリーンショット内の差分の指摘
  3. 03画像共有前の秘密情報の隠蔽

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/buildinternet/uploads --skill annotate-screenshots

インストール後、Claude Code で/annotate-screenshotsを入力して読み込まれたか確認します。

詳細

スクリーンショットへの注釈

注釈を付けるタイミング

スクリーンショットに写っている新しい要素、バグ、差分など、読者に特定の箇所へ注目してもらう必要がある場合は注釈を付けてください。キャプションを読んで探してもらうのではなく、注釈で示します。単純な変更前・変更後の画像を並べるだけで十分なこともよくあります。「右上を見てください」と言葉で説明するより矢印で示すほうが簡単な場合や、共有する前に隠さなければならない秘密情報がスクリーンショットに含まれている場合は、注釈を付けてください（uploads.sh の URL は公開されています）。

2 つのコマンドで、同じ基盤の仕様フォーマットを使用します。

コマンド入力対象の指定
uploads screenshot <url|file.html> --annotate <spec>ライブページをキャプチャしますCSS セレクター（推奨）またはピクセル座標
uploads annotate <image> --spec <spec>既存の PNG/JPEG ファイルピクセル座標のみ — セレクターは拒否されます

ピクセル座標を推測するより、実際のページ上で解決されるセレクターを優先してください。 エージェントが目視で x／y／w／h を推定しても信頼性は低く、誤った要素を指したり、ボックスが不自然に切れたりしやすいためです。uploads screenshot --annotate はキャプチャ時に実際の DOM に対して CSS セレクターを解決します（v1 ではローカルバックエンドのみ対応 — --via remote はセレクターを含む仕様を事前に拒否します）。そのため、自分でページをキャプチャする場合は必ずこれを使用してください。すでに手元にある画像に注釈を付ける場合で、照会できるライブページがないときに限り、uploads annotate を使ってピクセル座標を指定してください。たとえば、他の人が撮影したスクリーンショット、写真、別の場所からエクスポートした図などが該当します。

仕様フォーマット

仕様は JSON ドキュメントです：{ "version": 1, "annotations": [...] }。 annotations は空でない配列で、各エントリには type と、そのタイプに対応するフィールドが含まれます。スタイルガイド（色、線の太さ、手描き風の粗さ、フォント）は固定で、変更できません。スタイルを調整する唯一の方法は、注釈ごとに color を上書きすることです。

注釈の種類：

種類必須フィールド備考
boxx, y, w, h（または selector）領域を囲みます
arrowfrom, to の点（または selector）セレクターから解決する場合、to は要素の中心です。from を省略すると、右上寄りの位置がデフォルトになります
labeltext と、target または at の点（または selector）target まで引き出し線が伸びる吹き出しです
drawpoints（2 組以上の [x, y] ペア）自由に描画する線です。ピクセル座標のみ対応し、セレクターは使用できません
redactx, y, w, h（または selector）、任意の style: "blur" | "solid"領域を隠します（デフォルトは solid。秘密情報には常に solid を使用します）
svgfragment（生の SVG。<script、href=、url() は不可）エスケープハッチ。加工せずに挿入されます

ルール：幾何学的な注釈（box／arrow／label／redact）には、ピクセル座標または selector のどちらか一方だけを指定します。両方を指定することはできず、曖昧な指定として拒否されます。draw と svg にはセレクターを指定できません。すべての種類で color を任意で上書きできます。

使用例 — セレクターモード（推奨）

表示中のページで特定の要素を指定してラベルを付け、近くの API キーをマスクしてから、1 回の呼び出しでキャプチャして注釈を付けます。

{
  "version": 1,
  "annotations": [
    { "type": "box", "selector": "#save-button" },
    { "type": "label", "text": "New: bulk save", "selector": "#save-button" },
    { "type": "redact", "selector": "[data-testid=api-key]", "style": "solid" }
  ]
}

uploads screenshot http://localhost:4321/settings --via local \
  --annotate ./callouts.json --out settings.png
使用例 — ピクセルモード（既存の画像のみ）

すでにあるスクリーンショットに注釈を付けます。参照できる表示中のページがないため、ジオメトリを直接指定します。

{
  "version": 1,
  "annotations": [
    { "type": "box", "x": 120, "y": 84, "w": 220, "h": 48, "color": "#2563eb" },
    { "type": "arrow", "from": [520, 60], "to": [360, 108] },
    {
      "type": "draw",
      "points": [
        [40, 400],
        [80, 380],
        [120, 420],
        [160, 390]
      ]
    }
  ]
}

uploads annotate ./before.png --spec ./callouts.json --out ./before.marked.png

座標の単位は画像ピクセルであり、CSS／ビューポートのピクセルではありません。--viewport 1280x800@2x でキャプチャした場合、画像は 2560x1600 になるため、ピクセルモードのジオメトリもそれに応じて拡大する必要があります。表示中のページを利用できる場合は、セレクターモードが望ましい理由はまさにここにあります。リゾルバーがデバイススケールの変換を処理してくれます。

- を使って標準入力から仕様を読み込みます。

cat ./callouts.json | uploads annotate ./shot.png --spec -

シークレットのマスキング

uploads.sh のオブジェクトは、アップロードするとすべて公開されます。github-screenshots スキルの「注意事項」セクションを参照してください。API キー、トークン、パスワード、セッション Cookie、その他のシークレットが写ったスクリーンショットをキャプチャまたは添付する前に、その上に style: "solid" の redact 注釈を追加してください。シークレットには必ず solid を使ってください。ぼかしたテキストは復元できる可能性があるため、周囲の形状を読み取れる状態にしておきたい、機密ではない見た目の調整に限って style: "blur" を使い、認証情報には使用しないでください。可能であれば、キャプチャ時に screenshot --annotate を使ってください。画像が公開される前に忘れる可能性を減らせます。

ワークフロー：キャプチャ、注釈付け、添付

  1. 表示中のページがある場合は、キャプチャと注釈付けを同時に行います。 uploads screenshot <url> --via local --annotate ./spec.json ... を実行します。これは 1 回の呼び出しで完了するため、「キャプチャしてから注釈を付ける」という別々のやり取りは不要です。
  2. 表示中のページがない場合は、既存の画像に注釈を付けます。別の場所から取得した画像や、すでにキャプチャした画像に 2 回目の注釈を付ける場合は、uploads annotate <image> --spec ... を使います。
  3. 結果を PR または issue に添付します。このスキルでは、注釈付き PNG の作成までを行います。ホスティング、埋め込み、添付コメントの管理（uploads attach、uploads put --pr、変更前／変更後の表など）には、github-screenshots スキルを使います。

無効な仕様は、注釈ごとのエラーメッセージ（annotations[i]: <reason>）を表示してすぐに失敗します。ページ上で一致する要素がないセレクターを指定した場合も、黙ってスキップせず、該当のセレクターを示してコマンドが失敗します。--seed（スケッチ風の描画を決定的にする）や --format json を含むすべてのフラグについては、uploads annotate --help／uploads screenshot --help を参照してください。

コメント

Markdown 対応