Merge pull request #47 from DiffyWebsite/diffy-skills

add claude skills

Author: gregurcom

.claude-plugin/marketplace.json

@@ -0,0 +1,24 @@
+{
+  "name": "diffy",
+  "owner": {
+    "name": "Diffy",
+    "email": "support@diffy.website"
+  },
+  "metadata": {
+    "description": "Diffy visual-regression skills for Claude Code."
+  },
+  "plugins": [
+    {
+      "name": "diffy",
+      "source": "./plugins/diffy",
+      "description": "Create Diffy projects, capture/upload screenshots, and run visual diffs.",
+      "version": "1.0.0",
+      "author": {
+        "name": "Diffy"
+      },
+      "homepage": "https://diffy.website/",
+      "category": "testing",
+      "tags": ["visual-regression", "screenshots", "diffy", "testing", "ui"]
+    }
+  ]
+}

plugins/README.md

@@ -0,0 +1,29 @@
+# Claude Code plugins for diffy-cli
+
+This directory holds Claude Code plugins distributed through the marketplace defined at
+[`../.claude-plugin/marketplace.json`](../.claude-plugin/marketplace.json).
+
+## `diffy`
+
+Visual-regression skills built on the `diffy` CLI — create projects, capture/upload screenshots, and run
+visual diffs. See [`diffy/README.md`](diffy/README.md).
+
+## Install (once this repo is pushed)
+
+```shell
+/plugin marketplace add diffywebsite/diffy-cli
+/plugin install diffy@diffy
+```
+
+Then the skills are available namespaced, e.g. `/diffy:visual-diff`. Claude also invokes them
+automatically based on your request.
+
+## Local development / testing (no install)
+
+```bash
+# from the repo root
+claude --plugin-dir ./plugins/diffy
+claude plugin validate ./plugins/diffy   # run before publishing / submitting
+```
+
+Use `/reload-plugins` inside a session to pick up edits without restarting.

plugins/diffy/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "diffy",
+  "description": "Diffy visual-regression skills: create projects, capture/upload screenshots, and run visual diffs via the diffy CLI.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Diffy",
+    "email": "support@diffy.website"
+  },
+  "homepage": "https://diffy.website/",
+  "license": "MIT"
+}

plugins/diffy/README.md

@@ -0,0 +1,47 @@
+# diffy plugin
+
+Claude Code skills for [Diffy](https://diffy.website/) visual-regression testing, built on the `diffy` CLI.
+Claude invokes these automatically based on what you ask; you can also call them explicitly with their
+namespaced names (`/diffy:<skill>`).
+
+## Skills
+
+| Skill | What it does |
+|---|---|
+| `/diffy:create-project` | Create a new Diffy project from a base URL, pages, and breakpoints. |
+| `/diffy:update-project-settings` | Edit an existing project's pages, environments, breakpoints, masks, login, schedule, etc. |
+| `/diffy:upload-screenshot` | Capture a running app with Playwright and upload it as a Diffy screenshot set. |
+| `/diffy:compare-screenshots` | Create a diff from two existing screenshot set IDs. |
+| `/diffy:get-diff-info` | Fetch and summarize a diff: % changed, per-page/per-breakpoint table, report link, JUnit. |
+| `/diffy:visual-diff` | End-to-end before/after regression: baseline your UI, edit, then compare — pages/breakpoints read from the project. |
+
+`visual-diff` is the one-shot orchestrator (baseline → edit → compare). The other five are granular
+building blocks you can compose yourself.
+
+## Prerequisites
+
+- **`diffy` CLI** on `PATH` (or `./vendor/bin/diffy` in the repo). Install the phar:
+  ```bash
+  wget -O /usr/local/bin/diffy https://github.com/diffywebsite/diffy-cli/releases/latest/download/diffy.phar && chmod a+x /usr/local/bin/diffy
+  ```
+  Pick a bin directory you can write to — `/usr/local/bin` may need `sudo`; Homebrew on Apple Silicon uses
+  `/opt/homebrew/bin`.
+- **Authentication:** `diffy auth:login <API_KEY>` (get a key at https://app.diffy.website/#/keys). Stored
+  in `~/.diffy-cli/diffy-cli.yaml`.
+- **Playwright** (only for `upload-screenshot` and `visual-diff`):
+  `npm i -D playwright && npx playwright install chromium`.
+
+## Working files & .gitignore
+
+These skills write intermediate files (configs, PNGs, upload payloads, diff JSON) under `.diffy-skills/`
+(granular skills) and `.diffy-visual/` (`visual-diff`). Add both to your project's `.gitignore`:
+
+```gitignore
+.diffy-skills/
+.diffy-visual/
+```
+
+## Notes
+
+Diffy is a cloud service — these skills need an account, API key, and project; they do not do a purely
+local pixel diff.

plugins/diffy/skills/compare-screenshots/SKILL.md

@@ -0,0 +1,88 @@
+---
+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:
+
+```bash
+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.
+
+```bash
+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`:
+
+```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.

plugins/diffy/skills/create-project/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: create-project
+description: >-
+  Create a Diffy project with the diffy CLI from user-provided project details. Use when the user asks to
+  create a Diffy project, set up a new project in Diffy, or turn a base URL, pages, and breakpoints into a
+  new Diffy project. Requires the user to provide base_url and returns the created project ID.
+allowed-tools: Bash, Read, Write
+---
+
+# create-project
+
+Create Diffy projects only. Do not update existing project settings, upload screenshots, create diffs, or
+summarize diff results in this skill.
+
+Always generate a fresh JSON config from the user's input. Do not use the repo's example JSON or YAML files
+as the project creation input.
+
+## 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).
+
+## Inputs
+
+Required:
+- `base_url`: the production/base URL for the new project, for example `https://www.example.com`. This is
+  written to the config as the `production` field (same field name `update-project-settings` uses).
+
+If `base_url` is missing, ask the user for it before creating the config. Do not infer it from examples.
+
+Optional:
+- `name`: default to the hostname from `base_url` if omitted.
+- `pages` or `urls`: default to only the homepage path `/` if omitted.
+- `breakpoints`: default to `[640, 1024, 1200]` if omitted.
+- `staging`: default to an empty string if omitted.
+- `development`: default to an empty string if omitted.
+- `schedule`: omit by default (no monitoring schedule). The create endpoint expects a schedule *string*
+  such as `"mon:false, tue:false, wed:false, thu:false, fri:false, sat:false, sun:false"`, so only add this
+  field when the user asks for a schedule.
+
+Create a JSON config in `.diffy-skills/project-create/<safe-name>.json`. Do not overwrite an existing
+config unless the user asked for that exact file to be replaced.
+
+Generated JSON shape:
+
+```json
+{
+  "name": "Project name",
+  "breakpoints": [640, 1024, 1200],
+  "production": "https://www.example.com",
+  "staging": "https://staging.example.com",
+  "development": "",
+  "urls": [
+    "https://www.example.com/",
+    "https://www.example.com/about"
+  ]
+}
+```
+
+Rules:
+- Keep `urls` absolute by resolving each page path against `base_url`.
+- Do not create from example/sample config files.
+- This skill creates one project per run unless the user explicitly provides several `base_url` values.
+
+## Create
+
+Run:
+
+```bash
+diffy project:create <generated-config.json>
+```
+
+The command prints created IDs in this form:
+
+```text
+[12345] created.
+```
+
+Parse and report the numeric project ID(s). Then verify each project:
+
+```bash
+diffy project:get <PROJECT_ID>
+```
+
+Return a concise result with:
+- project ID
+- project name
+- production/base URL
+- pages count
+- breakpoints
+- config file path used
+
+If creation fails, show the exact CLI error and the config path. Do not retry by changing project settings;
+that belongs to `update-project-settings`.
+
+This skill writes its generated config under `.diffy-skills/`; offer to add `.diffy-skills/` to the repo's
+`.gitignore` if it is not already ignored.