annotate-screenshots

Original：🇺🇸 English
Translated

Bake hand-drawn boxes, arrows, labels, freeform strokes, and redactions onto a screenshot so a PR reviewer or teammate sees exactly what changed and where to look, instead of reading a caption and hunting for it. Use this whenever a screenshot needs a callout — "point at the new button", "circle the bug", "arrow to the diff", "blur out the API key in this screenshot", "mark up this image before I attach it". Covers both annotating a live page during capture (`uploads screenshot --annotate`, CSS selector targeting) and annotating an image you already have (`uploads annotate`, pixel/freeform coordinates only). For getting the resulting image into a GitHub PR or issue, hand off to the github-screenshots skill — this skill only covers producing the annotated image.

29installs
Sourcebuildinternet/uploads
Added on

NPX Install

npx skill4agent add buildinternet/uploads annotate-screenshots

Tags

Translated version includes tags in frontmatter
screenshot-annotationcli-toolimage-redactiongithub-collaborationcss-selector

SKILL.md Content

View Translation Comparison →

Annotating screenshots

When to annotate

Add annotations when a screenshot needs to draw the reader's eye somewhere specific — a new element, a bug, a diff — rather than leaving them to find it in the caption. A plain before/after pair is often enough; reach for annotation when "look at the top-right corner" is easier to say with an arrow than with words, or when a screenshot contains a secret that must be hidden before it's shared anywhere (uploads.sh URLs are public).
Two commands, same underlying spec format:
CommandInputTargeting
uploads screenshot <url|file.html> --annotate <spec>
captures a live pageCSS selectors (preferred) or pixel coordinates
uploads annotate <image> --spec <spec>
an existing PNG/JPEG filepixel coordinates only — selectors are rejected
Prefer selectors, resolved live, over guessing pixel coordinates. An agent estimating 
x
/
y
/
w
/
h
by eye is unreliable — it's easy to point at the wrong element or clip a box awkwardly. 
uploads screenshot --annotate
resolves a CSS selector against the real DOM at capture time (local backend only in v1 — 
--via remote
rejects selector-bearing specs up front), so use it whenever you're capturing the page yourself. Fall back to pixel coordinates with 
uploads annotate
only when you're marking up an image you already have and there's no live page to query — a screenshot someone else took, a photo, a diagram exported from elsewhere.

The spec format

A spec is a JSON document: 
{ "version": 1, "annotations": [...] }
. 
annotations
is a non-empty array; each entry has a 
type
plus fields for that type. House style (color, stroke weight, sketchy roughness, font) is fixed and not configurable — the one style knob is a per-annotation 
color
override.
Annotation types:
TypeRequired fieldsNotes
box
x, y, w, h
(or 
selector
)		outlines a region
arrow
from, to
points (or 
selector
)
to
= element center when resolved from a selector; 
from
defaults to an offset above-right if omitted
label
text
, plus 
target
or 
at
point (or 
selector
)		a callout bubble with a leader line to 
target
draw
points
(>= 2 
[x, y]
pairs)		freeform stroke, pixel-only, no selector support
redact
x, y, w, h
(or 
selector
), optional 
style: "blur" | "solid"
hides a region (default 
solid
; always 
solid
for secrets)
svg
fragment
(raw SVG; no 
<script
, 
href=
, or 
url()
)		escape hatch, injected verbatim
Rules: a geometric annotation (
box
/
arrow
/
label
/
redact
) takes either pixel geometry or 
selector
, never both — supplying both is rejected as ambiguous. 
draw
and 
svg
never take a selector. Every type accepts an optional 
color
override.

Worked example — selector mode (preferred)

Point at a specific element on a live page, label it, and redact a nearby API key, then capture and annotate in one call:
json
{
  "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" }
  ]
}
bash
uploads screenshot http://localhost:4321/settings --via local \
  --annotate ./callouts.json --out settings.png

Worked example — pixel mode (existing image only)

Annotating a screenshot you already have — no live page to query, so geometry is given directly:
json
{
  "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]
      ]
    }
  ]
}
bash
uploads annotate ./before.png --spec ./callouts.json --out ./before.marked.png
Coordinates are in image pixels, not CSS/viewport pixels — for a capture at 
--viewport 1280x800@2x
the image is 2560x1600, so pixel-mode geometry must be scaled accordingly. This is exactly why selector mode is preferable whenever a live page is available: the resolver handles device-scale conversion for you.
Read a spec from stdin with 
-
:
bash
cat ./callouts.json | uploads annotate ./shot.png --spec -

Redacting secrets

Every uploads.sh object is public once uploaded — see the github-screenshots skill's "Cautions" section. Before capturing or attaching a screenshot that shows an API key, token, password, session cookie, or other secret, add a 
redact
annotation with 
style: "solid"
over it. Always use 
solid
for secrets — blurred text can be recoverable, so reserve 
style: "blur"
for non-sensitive visual cleanup where the surrounding shape should stay legible, never for credentials. Do this at capture time with 
screenshot --annotate
when possible — it's one less chance to forget before the image goes anywhere public.

Workflow: capture, annotate, attach

  1. Capture and annotate together when there's a live page: 
    uploads screenshot <url> --via local --annotate ./spec.json ...
    . This is one call — no separate "capture then annotate" round-trip.
  2. Annotate an existing image with 
    uploads annotate <image> --spec ...
    when there's no live page (an image from elsewhere, or a second annotation pass on something already captured).
  3. Attach the result to a PR or issue — this skill stops at producing the annotated PNG. Hand off to the github-screenshots skill for hosting, embedding, and the managed attachments comment (
    uploads attach
    , 
    uploads put --pr
    , before/after tables, etc.).
Invalid specs fail fast with per-annotation error messages (
annotations[i]: <reason>
); a selector that matches nothing on the page fails the command naming the selector rather than silently skipping it. See 
uploads annotate --help
/ 
uploads screenshot --help
for the full flag reference, including 
--seed
(deterministic sketchy rendering) and 
--format json
.