agentleFS
Venkateshvenki404224Venkateshvenki404224/shipcraft-skills/skills/pr-screenshots/SKILL.md

pr-screenshots

Skill2 starsChanged 2 days agoMITView on GitHub

Attach before/after screenshots to a pull request for any frontend/UI change - cropped to the region of interest, marked with red boxes and arrows, and reviewed by a visual-reviewer agent before the PR goes up. Use whenever raising or updating a PR that touches .vue/.html/.jinja/templates/CSS/Tailwind/theme files, or when asked to "add screenshots to the PR", "show before and after", "crop to ROI", or "review how it looks".

17 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use security-review.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • SentrySkill

    security-review

    Finds exploitable application security vulnerabilities in code changes. Use for Warden security scans, appsec review, OWASP-style checks, authentication or authorization bugs, injection, XSS, SSRF, path traversal, secrets, unsafe crypto, webhook verification, open redirects, or sensitive data exposure.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

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

  • 0

    Common

    Most of the 15 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

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

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

    Use the run skill (or the project's own run instructions) to get the app up, and agent-browser to drive it.

    line 18
  2. Distinctive:

    Use the same crop box for the before and after pair so they line up.

    line 54
  3. Very specific:

    Run the visual-reviewer skill (visual/UX judgement, reads the images), plus a code reviewer for the frontend diff, before the PR body is …

    line 69
  4. Very specific:

    Use the house convention: commit the screenshots into the PR branch under docs/implementation/media/ and link them as blob URLs with ?raw=1:

    line 84
  5. Very specific:

    Only when images must outlive the branch: with a GitHub session in agent-browser, upload into the PR comment box's hidden input[type=file] …

    line 93

“Common” is measured: kept by at least 6 in 10 of the 15 edited versions of this file we could read. “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

PR screenshots

A frontend PR without pictures cannot be reviewed. Reference style: frappe/frappe#35626.

When this applies

The diff touches any of: *.vue, *.html, *.jinja, templates/, themes/, *.css, Tailwind classes, or frontend *.js/*.ts that changes what renders. Pure backend / test / config diffs skip this entirely.

1. Run the app and capture the pair

Use the run skill (or the project's own run instructions) to get the app up, and agent-browser to drive it. Capture the same route, same viewport, same data for both states — only the code differs.

# after (current branch)
agent-browser --session pr open "<url>" && agent-browser --session pr wait 3000 \
  && agent-browser --session pr screenshot <scratchpad>/<view>-after-full.png

# before — temporarily restore the base version of just the changed files
git checkout <base-branch> -- <changed files>
# wait for HMR/rebuild, then re-open the same url
agent-browser --session pr screenshot <scratchpad>/<view>-before-full.png
git checkout <this-branch> -- <changed files>     # ALWAYS restore

Rules:

  • One pair per distinct view the change touches (list page + detail page + mobile width if the change affects narrow layouts).
  • Seed or navigate to real data — an empty state proves nothing.
  • Restore the working tree before doing anything else; verify with git status. This matters most on a shared server checkout, where another session may commit leftovers.
  • A pure-addition change has no "before" — ship a single "after" image instead of faking one.
  • The -full.png captures stay in the scratchpad; only the annotated crops (step 2) ship.
  • Toasts and error pop-ups do not render in a headless capture. Assert the message from the DOM instead, skip that image, and quote the error text in the body. Never fake it.
  • Alpine x-show looks frozen headless (rAF never drains): shim window.requestAnimationFrame = cb => setTimeout(() => cb(performance.now()), 0) before driving the page.

2. Crop and annotate

Crop each capture to the region that changed, scale it 2x, and mark the change with a red rounded box, plus an arrow when the eye needs leading (e.g. "click this → that opens"). An arrow must run through empty space; if it would cross another field or text, use the box alone. Use the same crop box for the before and after pair so they line up.

# needs Pillow; without it: uv run --with pillow python ...
python3 <this skill's folder>/annotate.py <scratchpad>/header-after-full.png \
  docs/implementation/media/header-after.png \
  --crop 900,0,1280,130 --box 1142,18,1178,62 --arrow 1070,118,1142,58

Coordinates are source-screenshot pixels: measure them with getBoundingClientRect() in agent-browser eval rather than guessing. Read the annotated image before using it — a box that misses its target is worse than none.

3. Get the screenshots reviewed

Run the visual-reviewer skill (visual/UX judgement, reads the images), plus a code reviewer for the frontend diff, before the PR body is written. Give the reviewer the image paths, the intent of the change, and the running URL, and tell it explicitly not to launch or modify anything.

Act on REQUEST CHANGES first, then re-capture the "after" images. Do not publish a PR carrying screenshots the reviewer rejected, or one that shows an unrelated bug (a wrong total, a stray error) the PR does not fix — crop it out or drop the image.

4. Publish the images

GitHub's drag-and-drop upload host (github.com/user-attachments/assets/<uuid>) is browser-session-only — there is no API for it and gh cannot use it. Relative repo paths do not render in PR/issue bodies either.

Use the house convention: commit the screenshots into the PR branch under docs/implementation/media/ and link them as blob URLs with ?raw=1:

https://github.com/<owner>/<repo>/blob/<branch>/docs/implementation/media/<name>.png?raw=1

Name files after the change, not the PR number: <view>-before.png / <view>-after.png. The URL dies with the branch after merge; that is accepted.

Only when images must outlive the branch: with a GitHub session in agent-browser, upload into the PR comment box's hidden input[type=file] and use the user-attachments URL it inserts.

5. Put them in the PR body

The intent must be clear at a glance: the problem in user terms, what you can do now, where to see it, then the images. Nothing else — no "Verified:" line, no implementation notes (file names, routes, mechanisms), no test logs, no "Generated with Claude Code" / session-link footer. Those are noise; reasoning belongs in code comments or the review thread.

One image per row, never a side-by-side table. A capture squeezed into half a table column is unreadable.

1. <the problem, in user terms>
2. <what you can do now>

You can visit <route / screen> to see it.

## Before

<img src="<url>/<view>-before.png?raw=1" width="760">

## After

<img src="<url>/<view>-after.png?raw=1" width="760">

Set width to the annotated image's pixel width, capped at 900. The 2x scale then keeps it sharp without rendering as a giant column.

Then verify: curl -sL -o /dev/null -w "%{http_code} %{content_type}" <raw-url> must print 200 image/png for every image (?raw=1 redirects, hence -L), and the body must come back changed when read again — gh pr edit fails silently on repos with Projects (GraphQL scope), so patch with gh api -X PATCH repos/<owner>/<repo>/pulls/<n> -f body="$(cat body.md)" and read the body back.

Checklist before you say it's done

  • before + after captured at the same route/viewport/data
  • working tree restored (git status clean of the temporary checkout)
  • each image cropped to its ROI, change boxed in red, annotated image looked at
  • visual reviewer ran; its blocking findings are fixed and re-captured
  • every image URL returns 200 with content_type: image/png
  • PR body read back: problem / what you can do now / where to see it, images render, no Verified line or footer

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.