compare-screenshots

name	compare-screenshots
description	Create a Diffy visual diff from two existing screenshot set IDs with diff:create. Use when the user asks to compare screenshots, compare two uploaded screenshot sets, create a diff from screenshot IDs, or get a diff ID for before/after screenshots.
allowed-tools	Bash, Read, Write

compare-screenshots

Create a diff from two screenshot set IDs and return a DIFF_ID. Do not upload screenshots or do detailed diff result analysis in this skill.

Preflight

1. Resolve the CLI:
   • Prefer diffy from PATH.
   • Else, if ./vendor/bin/diffy exists in the current repo, use that.
   • Else, ask the user to install it and stop until it is available. Suggested install (pick a bin directory the user can write to — /usr/local/bin may need sudo; Homebrew on Apple Silicon uses /opt/homebrew/bin): wget -O /usr/local/bin/diffy https://github.com/diffywebsite/diffy-cli/releases/latest/download/diffy.phar && chmod a+x /usr/local/bin/diffy
2. Check authentication: ~/.diffy-cli/diffy-cli.yaml must exist. If it does not, run diffy auth:login <API_KEY> after the user provides the key (key from https://app.diffy.website/#/keys).

Required:

• PROJECT_ID
• first screenshot ID
• second screenshot ID

If screenshot IDs are missing, inspect recent screenshot sets:

diffy screenshot:list <PROJECT_ID> --limit=10

This prints a PHP var_export dump, not JSON. Read each set's ID from its 'id' => <number> line rather than trying to parse the output as JSON.

Ask only for the missing ID(s). Treat the first ID as the baseline/before screenshot and the second ID as the after/current screenshot unless the user says otherwise.

Compare

Use --wait by default unless the user explicitly asks to start the diff asynchronously.

diffy diff:create <PROJECT_ID> <SCREENSHOT_ID_BEFORE> <SCREENSHOT_ID_AFTER> --wait --name="<diff-name>"

The command prints the DIFF_ID.

Naming:

• If the user provides a name, use it exactly.
• Otherwise use a concise generated name, for example Uploaded screenshots 2026-07-06.

Wait behavior:

• --wait polls until Diffy completes or fails.
• --max-wait=<seconds> can be added when the user needs a custom timeout.
• If the command returns before completion, use get-diff-info later to check status and results.

Output

Write metadata to .diffy-skills/diffs/last-diff.json:

{
  "projectId": 12345,
  "beforeScreenshotId": 111,
  "afterScreenshotId": 222,
  "diffId": 333,
  "name": "Uploaded screenshots 2026-07-06",
  "createdAt": "2026-07-06T12:00:00Z"
}

Return:

• diff ID
• project ID
• before screenshot ID
• after screenshot ID
• whether the command waited

Stop there. Tell the user to use get-diff-info for the detailed changed-page report.

This skill writes metadata under .diffy-skills/; offer to add .diffy-skills/ to the repo's .gitignore if it is not already ignored.