agentleFS
IHanfoxIIHanfoxI/webapp-docs-kit/skills/visual-check/SKILL.md

visual-check

Skill0 starsChanged 34 days agoMITView on GitHub

Visually verifies UI changes in a web app. Takes Playwright screenshots of the affected screens, looks at them, and reports JavaScript errors, console errors, failed HTTP responses, blank pages and unexpected redirects. Use when asked for "/visual-check", after finishing a change to anything the user sees (views, styles, components, messages), or to see how a screen looks. Does not produce manuals or videos.

2 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions2 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 2

    1. sergenes/mini_agent★ 29same name
    2. eriknomitch/workmelt★ 4same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository2 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If $V/node_modules does not exist, run cd $V && npm install and node node_modules/playwright-core/cli.js install chromium.

    line 19
  2. Very specific:

    Look for docs/webapp-docs.json in the project.

    line 21
  3. Very specific:

    If the change depends on state (an open panel, an applied filter, a dialog), reproduce it with --click and --type.

    line 41
  4. Distinctive:

    If something is wrong, fix it, redeploy and take the screenshot again.

    line 66

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Visual check

A UI change is not done until someone looks at the screen. A successful build, a deploy and an HTTP 200 prove nothing about what the user will see. A collapsed panel, an icon that fails to load, a half-transparent dialog or personal data left unblurred only show up in the screenshot.

$V is this skill's scripts/ folder. The user-manual and video-tutorial skills of webapp-docs-kit reuse these scripts.

Before you start

  1. If $V/node_modules does not exist, run cd $V && npm install and node node_modules/playwright-core/cli.js install chromium.
  2. Look for docs/webapp-docs.json in the project. If it is missing, create it following references/configuration.md. Take the base URL from the project's README.md, CLAUDE.md/AGENTS.md or run scripts. Ask the user which environment to use if it is not obvious: local, dev or staging. Never use production.
  3. The change must be running in that environment. If it is not, follow the project's own instructions to build and start or deploy it.

Screens behind sign-in or other preconditions

This kit does not sign in, handle credentials or assume user roles. If a screen you need is behind a login, a paywall, a feature flag, a specific role or any other precondition (check.js reports a redirect, or the screenshot shows a sign-in page), stop and ask the user how they want to handle it. It is their decision. Never ask for, type or store passwords, tokens or cookies yourself, and never work around access controls.

Steps

  1. Pick what to check. Take the views touched by the change (git diff). If the change depends on state (an open panel, an applied filter, a dialog), reproduce it with --click and --type.
  2. Screenshot from the project root:

    node $V/check.js <path> [options]
    OptionPurpose
    --click "SEL1|SEL2"Open panels, tabs, dropdowns and dialogs, in order
    --type "SEL|text"Type into filters and search boxes
    --wait MS|SELSlow screens or animated dialogs
    --fullFull page
    --mobilePhone viewport (390×844), when the view must be responsive
    --exists SEL / --text SELCheck an element without looking at the image. Useful to tune selectors
    --htmlSave the rendered HTML to look for selectors
    --redact SELBlur more personal data on top of the config's redact list
    --mock FILEScreens that need fake API data

    The screenshot is saved in ~/.cache/webapp-docs-kit/screenshots/<app>/, outside the repository.

  3. Open the image with your file-reading tool. Do not skip this step. Check that the change looks as requested and that nothing around it broke: alignment, clipped text, overlaps, icons, colors and empty states.
  4. Read the problems: section of the output. Report JavaScript errors, console errors, HTTP responses ≥ 400, blank pages and redirects. A new error on a screen that looks fine is still a defect.
  5. If something is wrong, fix it, redeploy and take the screenshot again. Compare it with the previous one.

Rules

  • Read-only. --click and --type are for filtering, navigating and opening panels. check.js refuses to click Save, Delete, Submit, Send, Sign and similar buttons. Use --allow-change only when the user explicitly authorizes that specific case, and only in a test environment.
  • --text prints unblurred data to the terminal. Do not copy it into documents or commits.
  • Known pitfalls (prefixed ids, animated dialogs, charts that render late, JSF/PrimeFaces, SPAs) are in references/capture-pitfalls.md.

Report

For each screen checked, give the path, whether it looks right or what is wrong, the problems detected, and the screenshot path. Do not say "verified" unless you opened the image.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.