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:

Command	Input	Targeting
`uploads screenshot <url\|file.html> --annotate <spec>`	captures a live page	CSS selectors (preferred) or pixel coordinates
`uploads annotate <image> --spec <spec>`	an existing PNG/JPEG file	pixel coordinates only — selectors are rejected

Prefer selectors, resolved live, over guessing pixel coordinates. An agent estimating

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:

Type	Required fields	Notes
`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

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.
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).
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

annotate-screenshots

NPX Install

Tags

SKILL.md Content

Annotating screenshots

When to annotate

The spec format

Worked example — selector mode (preferred)

Worked example — pixel mode (existing image only)

Redacting secrets

Workflow: capture, annotate, attach