Skip to content

README.md

Latest commit

 

History

History
94 lines (71 loc) · 3.69 KB

README.md

File metadata and controls

94 lines (71 loc) · 3.69 KB
Raw

Visual-Driven Review

An Agent Skill for browser-based UI review that treats deliberate visual inspection as required test evidence. It combines visual discovery with functional, responsive, accessibility, adversarial, console, and network checks through a configured Playwright MCP server.

The skill reports findings and evidence. It does not modify application code or install browser tooling.

Requirements

  • An Agent Skills-compatible client
  • A configured Playwright MCP server
  • Direct screenshot image content or a runtime image viewer that can inspect MCP-produced screenshot artifacts
  • A reachable target application and any required test authentication

The skill defaults to an isolated playwright-headless server. It uses an extension-backed Playwright server only when a review explicitly requires the current browser's login state, cookies, or installed extensions.

Install

Clone the repository into your Agent Skills directory:

git clone https://github.com/joisun-skills/visual-driven-review.git \
  ~/.agents/skills/visual-driven-review

Or add it to a Git-managed skills collection as a submodule:

git submodule add \
  https://github.com/joisun-skills/visual-driven-review.git \
  path/to/skills/visual-driven-review

When cloning a parent repository that uses the skill as a submodule:

git clone --recurse-submodules <parent-repository-url>

For an existing clone:

git submodule update --init --recursive

Use

Ask the Agent to audit, inspect, validate, or explore a web UI in a real browser. The workflow covers broad visual audits, responsive and regression reviews, accessibility observations, adversarial UI states, smoke checks, and end-to-end UI flows. When the request does not already specify viewport sizes, the skill asks whether to review PC, Mobile, both, or custom dimensions through Claude Code's AskUserQuestion or Codex's RequestUserInput before browser coverage begins. It separately confirms whether responsive testing is required; declining it keeps multiple viewport checks independent and prevents a responsive verdict. The skill never assumes responsive authorization or a full multi-device matrix.

Run artifacts are written beneath the reviewed project's .vdr-log/YYYY-MM-DD-<task-slug>/ directory, for example .vdr-log/2026-07-23-dayjs-targeted-spot-check/. The date is resolved once per run and the task slug is lowercase ASCII kebab-case; viewport sizes, worker IDs, generic task counters, and random hashes belong in neither the run ID nor the run root. The skill ensures the project's root .gitignore contains the standalone entry /.vdr-log/ before creating artifacts.

See SKILL.md for the complete workflow and references/ for the evidence, observation, Playwright MCP, and reporting guides.

Safety Boundaries

  • Select one Playwright MCP server for a review and do not switch mid-flow.
  • Keep navigation, actions, authentication, data mutation, and destructive operations inside the user-authorized scope.
  • Inspect every material screenshot at its captured resolution.
  • Pair functional conclusions with deterministic evidence.
  • Do not claim complete visual coverage when evidence is missing or skipped.
  • Do not modify application code as part of the review workflow.

License and Attribution

Released under the MIT License.

This curated work derives testing ideas from Browserbase's MIT-licensed skills/ui-test. The Playwright MCP workflow follows Microsoft's official playwright-mcp.