---
name: screenshot-craft
description: Capture and annotate clean screenshots for docs and blog posts: banner-free capture discipline, viewport and full-page strategy, annotation and reticle recipes, format and compression choices, and a pre-publish quality checklist. Use when an agent needs publication-quality screen captures, annotated walkthroughs, or redacted screenshots.
metadata: { "includeInPrompt": true }
---

# Screenshot Craft

## Purpose
Turn raw screen grabs into publication-quality screenshots: no browser chrome, no OS banners, no stray notifications, crisp at retina density, annotated only where the reader needs guidance, compressed for the web without losing legible text.

## Workflow
1. **Stage the screen.** Close unrelated windows and tabs, dismiss notifications, enable do-not-disturb, pick one window size for the whole set, use demo data (demo.user@example.com, RFC1918 IPs), and light theme unless the doc is about dark mode.
2. **Pick the capture type.** Viewport for states, element for a control, full page for a whole flow. Read references/capture-recipes.md first: it covers the four failure modes that break full-page captures (repeated sticky headers, grey lazy images, inner scroll regions, seam lines at 400% zoom).
3. **Capture at 2x density.** `deviceScaleFactor: 2` in the automation tool, or DPR 2+ in the device toolbar. Verify text is sharp at 100% zoom before annotating anything.
4. **Annotate with restraint.** One annotation per idea: numbered markers for steps, arrows for "look here", reticles for "exactly this pixel", opaque blocks for redaction. Blur is not a security guarantee; it leaves pixels recoverable, so use a flattened opaque block. Keep a small palette: one color for actions, one for warnings, and never let color be the only instruction. Use bin/annotate.py for repeatable markup from a JSON spec.
5. **Choose format, then compress.** PNG for UI captures where text must stay crisp, WebP for web delivery. Resize first, pick format second; dimensions matter more than the last few quality points. Numbers live in references/format-guide.md.
6. **Run the pre-publish checklist** from Output Contract. A failed check means fix and re-capture, never ship.

## Output Contract
A published screenshot set meets all of these:
- Expected width and height, no browser chrome unless the doc is about the chrome
- Text sharp at 100% zoom, no pixelation
- Annotations legible at the final display size; marker numbers match the written steps
- Redacted regions are opaque, flattened, and inspected at full zoom
- Filenames describe the task without exposing a customer or account name
- Sizes fit the target: web images resized then compressed; docs images around 500 KB max as a sane default
- Each image sits beside the instruction it illustrates, and the action is also written in text

## Operating Rules
1. Capture enough of the interface for the reader to find the control, no more. A crowded screenshot means split the step.
2. The image illustrates; the text instructs. Always write the action out too.
3. Redact with opaque flattened blocks when the image leaves your machine. Never trust blur for real secrets.
4. One consistent window size, 100% zoom, and one annotation style across the whole set.
5. Numbers mean what the references say: codec "quality 80" is not a shared visual standard, and JPEG can outsize PNG on text-heavy captures. Do not claim format sizes you have not measured.