✨ Add Vizzly agent project guidance

Install the packaged Vizzly skill from init and optionally add project AGENTS.md guidance for agents using Vizzly visual context.

Author: Robdel12

README.md

@@ -28,6 +28,13 @@ pnpm install -g @vizzly-testing/cli
 vizzly init
 ```
 
+For agent-friendly repos, install the Vizzly skill and add a short project
+`AGENTS.md` note:
+
+```bash
+vizzly init --agent-guidance
+```
+
 ### Start Local TDD
 
 Start the TDD server, run your tests, and open the dashboard at
@@ -140,6 +147,13 @@ Generate a config file:
 vizzly init
 ```
 
+To teach project agents about Vizzly screenshot memory and the local visual TDD
+loop, add the repo-local skill and AGENTS.md guidance:
+
+```bash
+vizzly init --agent-guidance
+```
+
 Or create `vizzly.config.js` manually:
 
 ```javascript

docs/json-output.md

@@ -737,6 +737,29 @@ vizzly init --json
 }
 ```
 
+With project agent setup:
+
+```bash
+vizzly init --agent-guidance --json
+```
+
+```json
+{
+  "status": "created",
+  "configPath": "/path/to/vizzly.config.js",
+  "plugins": [],
+  "agentSkill": {
+    "status": "installed",
+    "sourcePath": "/path/to/cli/skills/vizzly",
+    "targetPath": "/path/to/project/.agents/skills/vizzly"
+  },
+  "agentGuidance": {
+    "status": "created",
+    "agentsPath": "/path/to/project/AGENTS.md"
+  }
+}
+```
+
 ### `vizzly project link`
 
 ```bash

package.json

@@ -55,6 +55,7 @@
     "bin",
     "dist",
     "docs/assets",
+    "skills",
     "README.md",
     "LICENSE"
   ],

skills/vizzly/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: vizzly
+description: "Use when a repo has Vizzly configured and you need screenshot memory or visual history: before/after UI changes, visual regression review, screenshot history, approved baselines, diffs, dynamic regions, docs/manual images, public screenshots, or Vizzly builds. Teaches agents to use Vizzly CLI/context for local TDD, cloud builds, review state, comments, hotspots, previews, and SDK capture patterns."
+---
+
+# Vizzly
+
+Vizzly is the project's screenshot memory database. It stores approved baselines, current screenshots, diffs, review state, comments, hotspots, previews, and public screenshot URLs.
+
+Use Vizzly when you need to understand what the UI looked like before, what changed, what humans already reviewed, or which screenshots already exist. Browser automation is still useful for interacting with a live app; Vizzly is usually the faster first stop for visual history.
+
+## First Instinct
+
+Before changing UI, check whether Vizzly already has local screenshot context:
+
+```bash
+vizzly context build current --source local --agent
+```
+
+If a task names a screen, component, or screenshot, inspect that screenshot's history before changing thresholds or re-capturing blindly:
+
+```bash
+vizzly context screenshot "<screenshot-name>" --source local --json
+```
+
+When you make or verify UI changes, run the focused user workflow that owns the surface:
+
+```bash
+vizzly tdd run "<test command>" --no-open
+```
+
+Then inspect what changed:
+
+```bash
+vizzly context build current --source local --agent --json
+```
+
+For specific evidence, drill in:
+
+```bash
+vizzly context comparison <comparison-id> --json
+vizzly context screenshot "<screenshot-name>" --json
+vizzly context review-queue --json
+```
+
+If local context is unavailable and the project uses cloud builds, use the build id from CI or CLI output:
+
+```bash
+vizzly context build <build-id> --agent --json --include diffs,comments
+```
+
+## What Vizzly Knows
+
+- **Approved baselines**: expected UI.
+- **Current screenshots**: what the latest run rendered.
+- **Diffs**: where pixels/layout/content changed.
+- **Review state and comments**: human context attached to builds and screenshots.
+- **Hotspots and confirmed regions**: known dynamic areas.
+- **Preview links**: static or deployed UI context for a build.
+- **Public screenshots**: stable URLs for documentation and manuals.
+
+## Acting On Visual Context
+
+- Treat approved baselines as visual truth.
+- Treat diffs as evidence, not as approval instructions.
+- Do not approve or reject visual changes unless the user explicitly asks.
+- Prefer existing E2E or user journeys over narrow screenshot-only specs.
+- For dynamic content, inspect screenshot context before changing thresholds.
+- Prefer deterministic test data, per-screenshot `threshold`, per-screenshot `minClusterSize`, hotspots, or confirmed regions over global tolerance changes.
+- Report visual findings with screenshot names, build/comparison links when available, and the command you ran.
+
+## Capturing Screenshots
+
+Use the existing integration when one is present. For direct JavaScript capture:
+
+```javascript
+import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
+
+let screenshot = await page.screenshot();
+await vizzlyScreenshot('checkout-form', screenshot, {
+  properties: {
+    browser: 'chromium',
+    viewport: 'desktop',
+    state: 'valid-card'
+  },
+  threshold: 2,
+  minClusterSize: 4
+});
+```
+
+Use `properties` to separate variants such as theme, locale, viewport, role, state, component, page, or docs/manual grouping.
+
+## When You Need More Detail
+
+- For SDK examples and capture patterns, read `references/sdks.md`.
+- For CLI/context commands and JSON output, read `references/cli-context.md`.
+- For dynamic content, thresholds, and hotspots, read `references/dynamic-content.md`.
+- For public screenshot URLs and docs/manual images, read `references/public-screenshots.md`.
+- For project setup and CI, read `references/setup-ci.md`.

skills/vizzly/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Vizzly"
+  short_description: "Use Vizzly visual context while changing UI."
+  default_prompt: "Use Vizzly to inspect visual context before and after UI changes."

skills/vizzly/references/cli-context.md

@@ -0,0 +1,42 @@
+# CLI And Context
+
+Use these commands to gather Vizzly evidence before making UI assumptions.
+
+## Local TDD
+
+```bash
+vizzly tdd start
+vizzly tdd run "<test command>" --no-open
+vizzly context build current --source local --agent
+vizzly context build current --source local --agent --json
+```
+
+Local context reads `.vizzly` state and does not require cloud auth.
+
+## Cloud Builds
+
+```bash
+export VIZZLY_TOKEN="project-token"
+vizzly run "<test command>" --wait --json
+vizzly context build <build-id> --agent --json --include diffs,comments
+```
+
+`vizzly run --wait --json` returns a `contextCommand` when a cloud build is created. Prefer that command over constructing URLs by hand.
+
+## Drilldowns
+
+```bash
+vizzly context comparison <comparison-id> --json
+vizzly context screenshot "<screenshot-name>" --json
+vizzly context similar <fingerprint-hash> --json
+vizzly context review-queue --json
+```
+
+Use comparison context for one diff. Use screenshot context for history and recurring dynamic areas. Use review queue context when triaging unresolved visual work.
+
+## Good Agent Behavior
+
+- Use `--json` for automation and summaries.
+- Use `--agent` when building prompt context or asking another agent to continue.
+- Keep human-readable command output in final summaries only when it changes the user's next action.
+- Do not approve/reject unless explicitly asked.

skills/vizzly/references/dynamic-content.md

@@ -0,0 +1,44 @@
+# Dynamic Content
+
+Dynamic content is common: dates, calendars, generated images, avatars, timers, randomized data, responsive text, and API-backed content.
+
+## Order Of Operations
+
+1. Make test data deterministic when the changing content is not what you are testing.
+2. Inspect screenshot context before changing code:
+
+```bash
+vizzly context screenshot "<screenshot-name>" --json
+```
+
+3. Use per-screenshot tolerances for local noise:
+
+```javascript
+await vizzlyScreenshot('plant-calendar', screenshot, {
+  properties: { surface: 'calendar' },
+  threshold: 4,
+  minClusterSize: 12
+});
+```
+
+4. Use hotspots or confirmed regions for recurring valid dynamic regions.
+
+## Avoid
+
+- Raising global project thresholds for one dynamic area.
+- Masking a whole page when a small region changes.
+- Treating every daily diff as product breakage.
+- Ignoring structural changes because a region is known to be dynamic.
+
+## How To Explain Findings
+
+Say whether the diff looks like:
+
+- expected dynamic content
+- deterministic fixture drift
+- real content disappearance
+- layout shift
+- screenshot timing/capture instability
+- baseline mismatch
+
+Then name the screenshot and include the relevant context command or link.

skills/vizzly/references/public-screenshots.md

@@ -0,0 +1,44 @@
+# Public Screenshots
+
+Public screenshots are Vizzly's path for stable image URLs in docs and manuals.
+
+Use this when a user asks for hotlinked UI screenshots, generated manual images, docs that stay current with UI, or CDN-like screenshot URLs.
+
+## Mental Model
+
+Do not use arbitrary build screenshot URLs as stable docs assets. Use Public Properties.
+
+The flow:
+
+1. Capture screenshots with stable metadata.
+2. Configure project Public Properties in Vizzly.
+3. Approve/publish the baseline build.
+4. Use the Public URLs tab to copy the stable URL.
+
+Example capture:
+
+```javascript
+await vizzlyScreenshot('watering-widget', screenshot, {
+  properties: {
+    manual: 'plant-care',
+    component: 'watering-widget',
+    viewport: 'desktop'
+  }
+});
+```
+
+Configure a Public Property like `manual=plant-care`. Vizzly publishes matching approved baseline screenshots and keeps stable URLs for each screenshot/property identity.
+
+## Good Uses
+
+- Product manuals
+- User docs
+- Component catalogs
+- In-app UI examples
+- Screenshots that should update when approved UI changes
+
+## Cautions
+
+- Public screenshots are public. Do not publish private user data, secrets, or internal-only UI.
+- A new unapproved build does not automatically become the public docs image.
+- Use stable names and properties so URLs do not churn.

skills/vizzly/references/sdks.md

@@ -0,0 +1,62 @@
+# SDK Capture Patterns
+
+Vizzly works best when screenshots are attached to real user journeys and stable names.
+
+## JavaScript Client
+
+```javascript
+import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
+
+let screenshot = await page.screenshot();
+await vizzlyScreenshot('settings-profile-edit-mode', screenshot, {
+  properties: {
+    browser: 'chromium',
+    viewport: 'desktop',
+    state: 'edit'
+  },
+  threshold: 2,
+  minClusterSize: 4
+});
+```
+
+`vizzlyScreenshot(name, image, options)` accepts a PNG buffer or file path.
+
+Important options:
+
+- `properties`: metadata used for baseline identity and filtering.
+- `threshold`: per-screenshot CIEDE2000 Delta E tolerance.
+- `minClusterSize`: minimum changed-pixel cluster size.
+- `fullPage`: marks full-page captures.
+
+## Vitest
+
+Use the Vizzly Vitest plugin when present. It keeps the native `toMatchScreenshot` style:
+
+```javascript
+await expect(page.getByRole('heading')).toMatchScreenshot('hero-section.png', {
+  properties: {
+    theme: 'dark',
+    viewport: 'desktop'
+  },
+  threshold: 2,
+  fullPage: true
+});
+```
+
+## Storybook And Static Sites
+
+If the repo uses Vizzly Storybook or static-site clients, prefer those existing flows over adding custom Playwright screenshots. They already know how to crawl stories/pages, name screenshots, and attach viewport metadata.
+
+## Swift
+
+Swift/XCTest projects use `VizzlyXCTest` helpers such as `app.vizzlyScreenshot(name:properties:threshold:minClusterSize:)`. For iOS work, verify against the Swift package docs in the repo before changing examples.
+
+## Naming
+
+Use stable, descriptive screenshot names:
+
+- Good: `checkout-payment-form-valid-card`
+- Good: `settings-profile-edit-mode`
+- Avoid: `screenshot1`, `test`, names with slashes
+
+Use properties for variants instead of stuffing every variant into the name.