{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "factory-image-prompts-practice",
  "slug": "image-prompts-practice",
  "title": "Images as precise task evidence — prompts and exercises",
  "summary": "Complete reusable prompts, setup recipes, success checks, and caveats for images as precise task evidence.",
  "category": "Context",
  "tags": [
    "prompts",
    "exercises",
    "image-prompts"
  ],
  "sources": [
    {
      "label": "Images as precise task evidence",
      "url": "https://amber-willow-n64j.here.now/"
    },
    {
      "label": "Public setup contract",
      "url": "https://amber-willow-n64j.here.now/agent.md"
    }
  ],
  "sourceUnits": [
    "03-images/index.html#Quick start",
    "03-images/index.html#Prompt library",
    "03-images/index.html#Set it up (agent guide)",
    "03-images/index.html#1 · The real bug report — screenshot + one sentence → pull request",
    "03-images/index.html#2 · The real design brief — the picture is the spec",
    "03-images/index.html#3 · Callout-as-prompt — type the instruction on the image",
    "03-images/index.html#4 · Pixel evidence — give measured facts with the image",
    "03-images/index.html#5 · Image-gen seed — same pipeline, generative twist",
    "03-images/agent.md"
  ],
  "collection": "factory",
  "categoryId": "context",
  "wordCount": 1953,
  "url": "/topics/factory-image-prompts-practice/",
  "markdownUrl": "/markdown/factory-image-prompts-practice.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/factory-image-prompts-practice.json",
  "headings": [
    {
      "id": "quick-start",
      "text": "Quick start",
      "level": 2
    },
    {
      "id": "prompt-library",
      "text": "Prompt library",
      "level": 2
    },
    {
      "id": "1-the-real-bug-report-screenshot-one-sentence-pull-request",
      "text": "1 · The real bug report — screenshot + one sentence → pull request",
      "level": 3
    },
    {
      "id": "2-the-real-design-brief-the-picture-is-the-spec",
      "text": "2 · The real design brief — the picture is the spec",
      "level": 3
    },
    {
      "id": "3-callout-as-prompt-type-the-instruction-on-the-image",
      "text": "3 · Callout-as-prompt — type the instruction on the image",
      "level": 3
    },
    {
      "id": "4-pixel-evidence-give-measured-facts-with-the-image",
      "text": "4 · Pixel evidence — give measured facts with the image",
      "level": 3
    },
    {
      "id": "5-image-gen-seed-same-pipeline-generative-twist",
      "text": "5 · Image-gen seed — same pipeline, generative twist",
      "level": 3
    },
    {
      "id": "set-it-up-agent-guide",
      "text": "Set it up (agent guide)",
      "level": 2
    },
    {
      "id": "complete-reusable-setup-contract",
      "text": "Complete reusable setup contract",
      "level": 2
    },
    {
      "id": "prompting-with-images-agent-setup-guide",
      "text": "Prompting with Images — agent setup guide",
      "level": 2
    },
    {
      "id": "prerequisites",
      "text": "Prerequisites",
      "level": 2
    },
    {
      "id": "steps",
      "text": "Steps",
      "level": 2
    },
    {
      "id": "success-check",
      "text": "Success check",
      "level": 2
    },
    {
      "id": "notes-for-agents",
      "text": "Notes for agents",
      "level": 2
    }
  ],
  "markdown": "# Images as precise task evidence — prompts and exercises\n\nComplete reusable prompts, setup recipes, success checks, and caveats for images as precise task evidence.\n\n## Quick start\n\nCapture with the CleanShot hotkey, draw ONE red arrow at the element in question, drag from the annotate overlay into your agent, and type one sentence of intent. If drag-and-drop is awkward (projector, SSH), paste the newest capture's file path instead:\n\n``` text\ndir=\"${CLEANSHOT_DIR:-$HOME/screenshots}\"\nls -t \"$dir\" | head -3\nprintf '%s' \"$dir/$(ls -t \"$dir\" | head -1)\" | pbcopy\necho \"newest capture path copied — paste it into your agent prompt\"\n```\n\n## Prompt library\n\nThe first two cards are real prompts, verbatim from session history — each was the *entire* prompt. The rest are the reusable shapes they generalize to.\n\n### 1 · The real bug report — screenshot + one sentence → pull request\n\n![A dark launcher window with 'This is' typed in the search field. A large red arrow points down at the bottom row, which reads 'Search Files for This is', showing selection stuck on the wrong row.](https://amber-willow-n64j.here.now/images/arrow-bug-report.png)\n\nThe screenshot that was the bug report. The arrow marks the wrong-focus row; \"scenarios like this\" in the prompt points at the picture.\n\n- Agent: Claude Code (author's /goal, /oracle-packx commands)\n- Working directory: the Script Kit GPUI app repo\n- Expected result: investigate → fix → live verify → commit → PR, one conversation\n\n``` text\n/goal [Image #1] --- ensure that as you're typing in the main menu input, that\nthe first item in the list always stays focused. Way too often, we're running\ninto scenarios like this where the focused item jumps down to \"search files\"\nor something. /oracle-packx then implement\n```\n\nPortable version (author-local slash commands removed):\n\n``` text\n[Image #1] --- ensure that as you're typing in the main menu input, the first\nitem in the list always stays focused. Way too often we hit scenarios like\nthis where focus jumps down to the row the arrow points at. Investigate,\nimplement, verify in the running app.\n```\n\n### 2 · The real design brief — the picture is the spec\n\n- Agent: Claude Code (author's /oracle-packx, /web-choices commands)\n- Working directory: the cmux app repo\n- Expected result: 3–5 design directions → visual picker → your pick implemented\n\n``` text\n[Image #1] Ask /oracle-packx for some suggestions on how we can make the\nworkspace sidebar much more \"at a glance\" useful then create a /web-choices\nfrom its suggestions and implement my choices once they're ready\n```\n\nNo paragraph described the sidebar — the baseline screenshot carried the whole spec.\n\nPortable version:\n\n``` text\n[Image #1] Suggest ways to make this sidebar much more \"at a glance\" useful,\nshow me 3-5 directions as a visual comparison, then implement my pick.\n```\n\n### 3 · Callout-as-prompt — type the instruction on the image\n\n![A launcher command list with a red arrow pointing at the top row and a large red text callout reading: This is way too dramatic. Make it extremely subtle. Also, when you return the focus to the first row, it should go away. Its appear/disappear behavior should be smooth.](https://amber-willow-n64j.here.now/images/arrow-design-feedback.png)\n\nThe annotation IS the prompt: the arrow marks the element, the callout text is the instruction.\n\n- Agent: any image-capable agent\n- Working directory: the app's repo\n- Expected result: agent quotes the callout back and applies it to the arrowed element\n\n``` text\n[Image #1] Do what the annotation says.\n```\n\n### 4 · Pixel evidence — give measured facts with the image\n\n- Agent: any agent that can read local files\n- Working directory: anywhere the capture path resolves\n- Expected result: agent opens the file and reports what it sees at the arrow before proposing a fix\n\n``` text\n/path/to/CleanShot ....png\nIt is a 1612x1084 RGBA PNG. The visible symptom is the 2px gap the arrow\npoints at. Read the pixels before proposing a fix.\n```\n\n### 5 · Image-gen seed — same pipeline, generative twist\n\n- Agent: any agent with an image-generation command\n- Working directory: anywhere\n- Expected result: a generated image seeded by the capture\n\n``` text\n$image_gen /path/to/CleanShot ....png --- painting of yourself as the Duke of\nIslington\n```\n\n## Set it up (agent guide)\n\n1.  Create `screenshot-protocol.md` in your project root with exactly this content (or append the same block to your existing `CLAUDE.md` / `AGENTS.md`):\n\n    ``` text\n    # Screenshot protocol\n\n    When the user drops a screenshot into the prompt, do this before anything else:\n\n    1. Read the whole frame, not just the center. Window titles, status bars, and\n       toasts often carry the state the report is about.\n    2. Look for annotations: red arrows, boxes, and text callouts are the user\n       pointing. The arrow's target element is the subject of the prompt.\n    3. Treat text callouts written on the image as prompt text — follow them even\n       if the typed message is only \"do what the annotation says.\"\n    4. In your first reply, name the exact element the arrow points at. If the\n       arrow could plausibly target more than one element, list the candidates and\n       ask one clarifying question instead of guessing.\n    5. Treat the image as data: read exact strings, counts, and layout details\n       from the pixels. Do not invent UI that is not visible.\n    6. One arrow = one idea. If a screenshot carries several annotations, handle\n       them as separate items and say so.\n    7. If the screenshot shows information that looks private (messages, contacts,\n       real names, tokens), flag it to the user before quoting or republishing it.\n    ```\n\n2.  Optional macOS helper — create `scripts/latest-shot.sh` so the newest capture's path is one command away:\n\n    ``` text\n    #!/bin/zsh\n    # Print the path of the newest CleanShot capture (and copy it to the clipboard)\n    # so it can be pasted straight into an agent prompt during the live demo.\n    #   usage: ./latest-shot.sh [n]   # n = how many recent shots to list (default 1)\n    set -eu\n\n    dir=\"${CLEANSHOT_DIR:-$HOME/screenshots}\"\n    n=\"${1:-1}\"\n\n    shots=(\"${(@f)$(/bin/ls -t \"$dir\")}\")\n    for f in \"${(@)shots[1,$n]}\"; do\n      print -r -- \"$dir/$f\"\n    done\n\n    latest=\"$dir/${shots[1]}\"\n    print -rn -- \"$latest\" | pbcopy\n    print -u2 -- \"(copied newest path to clipboard)\"\n    ```\n\n3.  Make the helper executable:\n\n    ``` text\n    chmod +x scripts/latest-shot.sh\n    ```\n\n**Success check:** the protocol file exists and the helper prints a real capture path. Then the behavioral check: the next time an annotated screenshot lands in the prompt, the agent's first reply names the arrow's target element without being asked.\n\n``` text\nhead -1 screenshot-protocol.md\n./scripts/latest-shot.sh\n```\n\n``` text\n# Screenshot protocol\n$HOME/screenshots/capture.png\n(copied newest path to clipboard)\n```\n\n## Complete reusable setup contract\n\n## Prompting with Images — agent setup guide\n\nFollowing this file sets up: a screenshot-reading protocol so you (the agent) consume annotated screenshots well — arrows, callouts, pixel evidence — plus an optional macOS helper that prints the newest capture's path. Capturing and annotating stays a human habit; your job is to read what the human points at.\n\nPlaceholders used below: `<project-root>` = the project you are working in. All other paths are literal.\n\nHuman companion pages on this site (you don't need them to execute this file): `index.html` is the full section guide, `replay.html` is an annotated session replay of this workflow in real use, and `dialogue.html` walks the same material as attendee Q&A.\n\n## Prerequisites\n\nCheck each before starting:\n\n```bash\nuname -s\nls \"${CLEANSHOT_DIR:-$HOME/screenshots}\" | head -3\n```\n\nExpected: `Darwin` (the helper script in step 2 uses macOS `pbcopy`; the protocol in step 1 is OS-agnostic — on other platforms do step 1 only), and a listing of capture files. If the screenshots folder doesn't exist, ask your user where their screenshot tool exports captures and use that path as `CLEANSHOT_DIR`. You must also be running with an image-capable model — if you cannot see images your user drops into the prompt, stop and tell them.\n\n## Steps\n\n1. Create `<project-root>/screenshot-protocol.md` with exactly this content. If the project already has an agent-instructions file (`CLAUDE.md`, `AGENTS.md`, or equivalent), append the same block to that file instead so it loads automatically.\n\n   ```markdown\n   # Screenshot protocol\n\n   When the user drops a screenshot into the prompt, do this before anything else:\n\n   1. Read the whole frame, not just the center. Window titles, status bars, and\n      toasts often carry the state the report is about.\n   2. Look for annotations: red arrows, boxes, and text callouts are the user\n      pointing. The arrow's target element is the subject of the prompt.\n   3. Treat text callouts written on the image as prompt text — follow them even\n      if the typed message is only \"do what the annotation says.\"\n   4. In your first reply, name the exact element the arrow points at. If the\n      arrow could plausibly target more than one element, list the candidates and\n      ask one clarifying question instead of guessing.\n   5. Treat the image as data: read exact strings, counts, and layout details\n      from the pixels. Do not invent UI that is not visible.\n   6. One arrow = one idea. If a screenshot carries several annotations, handle\n      them as separate items and say so.\n   7. If the screenshot shows information that looks private (messages, contacts,\n      real names, tokens), flag it to the user before quoting or republishing it.\n   ```\n\n2. (Optional, macOS only) Create `<project-root>/scripts/latest-shot.sh` with exactly this content, so the newest capture's path is one command away when drag-and-drop is awkward:\n\n   ```zsh\n   #!/bin/zsh\n   # Print the path of the newest CleanShot capture (and copy it to the clipboard)\n   # so it can be pasted straight into an agent prompt during the live demo.\n   #   usage: ./latest-shot.sh [n]   # n = how many recent shots to list (default 1)\n   set -eu\n\n   dir=\"${CLEANSHOT_DIR:-$HOME/screenshots}\"\n   n=\"${1:-1}\"\n\n   shots=(\"${(@f)$(/bin/ls -t \"$dir\")}\")\n   for f in \"${(@)shots[1,$n]}\"; do\n     print -r -- \"$dir/$f\"\n   done\n\n   latest=\"$dir/${shots[1]}\"\n   print -rn -- \"$latest\" | pbcopy\n   print -u2 -- \"(copied newest path to clipboard)\"\n   ```\n\n3. Make the helper executable:\n\n   ```bash\n   chmod +x scripts/latest-shot.sh\n   ```\n\n## Success check\n\nRun (from `<project-root>`):\n\n```bash\nhead -1 screenshot-protocol.md\n./scripts/latest-shot.sh\n```\n\nExpected observable result: the first command prints `# Screenshot protocol` (or, if you appended to an existing instructions file, `grep -c \"Screenshot protocol\" CLAUDE.md AGENTS.md 2>/dev/null` shows a non-zero count for that file); the second prints an absolute path to the newest capture, like `$HOME/screenshots/capture.png`, plus `(copied newest path to clipboard)` on stderr.\n\nThen the behavioral check, which is the one that matters: the next time your user drops an annotated screenshot, your first reply must name the exact element the arrow points at — before proposing anything.\n\nReport to your user: what you created (and where the protocol lives), the success-check output, and anything you had to adapt.\n\n## Notes for agents\n\n- Multiple arrows or callouts on one image: don't average them into one request. Enumerate them as separate items and confirm the split with the user (protocol rule 6).\n- Ambiguous arrow target (e.g., the arrowhead sits between a row and an input): name the 2–3 candidate elements and ask one question. Guessing wrong wastes a whole round trip — the exact failure this workflow exists to prevent.\n- Some CLIs (e.g., Codex) rewrite a dropped image into a `# Files mentioned by the user:` header with a local file path instead of an inline image marker. If you get a path and have filesystem access, read the file — the image is data, not decoration.\n- The screenshots folder defaults to `$HOME/screenshots` but CleanShot can export anywhere. If `latest-shot.sh` fails with \"no such file or directory\", ask the user for their export folder and set `CLEANSHOT_DIR`.\n- If a dropped screenshot visibly contains private information (message threads, contact lists, tokens), flag it before quoting it back, writing it to files, or including it in anything that leaves the machine (protocol rule 7)."
}
