Gist

Visual Proof of Work

markdown · October 27, 2026

An agent skill for capturing before-and-after screenshots and adding visual comparisons to GitHub pull requests.

View on GitHub

# Visual proof of work

Capture before/after screenshots, keep them organized, and attach comparison tables to GitHub PRs.

## Install

```bash
npx skills add https://gist.github.com/def5bb7e3026836477fcc7c8587244f8.git -g -a codex -y
```

`-g`: all projects · `-a codex`: Codex · `-y`: skip prompts. Omit flags for interactive setup.

## Use

```text
Use $visual-proof-of-work for this UI change.
```

Publishing screenshots requires authenticated GitHub CLI 2.99+ (`--attach`).
---
name: visual-proof-of-work
description: Capture and organize real before-and-after screenshots during visual development, then publish comparison tables in a GitHub PR using gh --attach. Use for UI changes on web, mobile, desktop, or other rendered interfaces, or when asked for visual proof of work.
---

# Visual proof of work

Give reviewers visible evidence of what changed. Capture the baseline before editing, preserve the final result after verification, and put matched screenshots directly in the PR description. This workflow supplements the project's checks; screenshots alone do not prove behavior or accessibility.

## Start with evidence

Before changing visible code, identify the affected screens and representative states. Choose the smallest useful set: the changed view, important error or empty states, and relevant themes, platforms, or viewport sizes. Follow the project's required coverage; avoid an exhaustive screenshot matrix for a small change.

Use the environment's supported browser, simulator, emulator, or desktop tooling and its interaction instructions. Capture the running product, not a generated mockup. Navigate using discovered elements. Wait for loading, animations, fonts, and layout to settle before capturing.

Record enough context to repeat each capture: source revision (and whether dirty), build, platform/device or browser, viewport, theme, locale, text scale, test fixture, navigation steps, and expected state. Use non-sensitive test content. Inspect images for tokens, personal information, notifications, and debug overlays before publishing; prefer recapturing with clean fixtures to obscuring the interface.

If implementation already started, obtain the baseline from the actual pre-change revision in a separate checkout when practical. Never reset a dirty checkout or overwrite the user's edits to recover it. If a baseline cannot be reproduced, label it unavailable and show an after-only image with the limitation. Never present a reconstruction or final screenshot as “before.” New screens can compare the previous entry point or flow when meaningful; otherwise mark them as new.

## Keep artifacts organized

Prefer the project's existing artifact location. Otherwise use a durable local directory outside the checkout, such as:

```text
~/.local/share/visual-proof/<repo>/<task>/<run>/
  captures.md
  before/
    ios-dark-chat-notice.png
    web-light-settings.png
  after/
    ios-dark-chat-notice.png
    web-light-settings.png
  pr-body.md
```

Use a task slug and unique run identifier. Matching before/after filenames identify one scenario; include platform, theme, and state when they distinguish captures. Keep original screenshots intact. If a close-up helps, retain the full capture and use the same crop for both sides, explicitly labeled as a detail.

In `captures.md`, keep a compact scenario list with the capture context, file paths, revisions, observed results, and any missing coverage. Later add the target PR URL and uploaded asset URLs. Do not store credentials. Do not commit binary evidence or change `.gitignore` unless the project or user requests it. Retain artifacts until the PR is updated and uploads are verified; do not delete the only baseline between turns.

## Capture the completed change

After implementation and appropriate checks, repeat the same scenarios with matching dimensions, theme, locale, fixture, zoom, scroll position, and keyboard state. If one of these is intentionally changed, explain it in the caption.

Inspect every pair yourself. Check that the intended change is visible, text is readable, and nearby layout has not regressed. Fix observed issues and recapture the final state. Keep intermediate attempts out of the PR. For motion or interaction that still images cannot establish, add a short real recording alongside the screenshots; describe what was exercised and avoid implying that a static capture verifies it.

Do not claim a platform or state was checked when it was not. If tooling or a build blocks capture, record the exact gap and continue independent work without inventing evidence.

## Publish a reviewer-friendly table

When creating or updating the PR is within the user's task, upload with GitHub CLI. If only drafting was requested, prepare the body and command locally and leave publishing pending. Do not create a PR solely because this skill was selected.

Check `gh --version`, `gh pr edit --help`, repository, account, and target PR. `--attach` was introduced in **gh 2.99.0**; verify that the chosen executable supports it. If the installed CLI is older, use an available compatible binary or download an official release for the host architecture into a task-local tools directory. Do not silently replace the user's system CLI or switch their global account. Never print authentication tokens.

Read the latest PR description immediately before editing. Save it locally and preserve the reviewer's existing text and tables. Add or update one `## Visual proof` section; group comparisons by platform or scenario when helpful. If the body changes while preparing the edit, reconcile against the latest version before writing. Do not append duplicate evidence sections on reruns.

Use Markdown image references with the exact local paths passed to `--attach`. The CLI replaces those references with uploaded URLs, preserving their positions inside the table. Plain `--attach` without matching references appends attachments instead.

Example body section (paths are illustrative; use the actual absolute capture paths):

```markdown
## Visual proof

### iOS · dark appearance

| Scenario | Before | After |
|---|---|---|
| Chat notice | ![Chat notice before](/absolute/proof/before/ios-dark-chat-notice.png) | ![Chat notice after](/absolute/proof/after/ios-dark-chat-notice.png) |

Verified on iPhone simulator, matching viewport and test fixture. The notice now uses the glass pill surface and keeps its dismiss action.
```

Write the complete preserved description plus the section to a UTF-8 body file. Then run:

```bash
gh pr edit 222 --repo OWNER/REPO \
  --body-file /absolute/proof/pr-body.md \
  --attach /absolute/proof/before/ios-dark-chat-notice.png \
  --attach /absolute/proof/after/ios-dark-chat-notice.png
```

For an already-authorized new PR, use the same `--body-file` and repeated `--attach` flags with `gh pr create` and the correct base/head. Quote paths containing spaces. Use a body file rather than embedding Markdown in a shell argument. Each command supports up to 50 attached files on GitHub.com and GitHub Enterprise Cloud. Keep ordinary evidence sets substantially smaller. Put videos outside comparison table cells so their players remain usable.

A failed command may still have uploaded some files and updated the body. Read the PR before retrying. Preserve successful asset URLs and attach only the missing local files. Stop and report an actionable authentication or upload failure instead of looping or creating duplicate comments. Never use a public throwaway issue as an upload staging area.

## Verify and hand off

Read back the PR description with `gh pr view <number> --repo OWNER/REPO --json body`. Confirm that every expected image reference became a GitHub asset URL, no local paths remain in the published evidence, existing content survived, and every row maps to the correct scenario. Inspect the rendered table with available browser tooling when practical. Register the PR with the host application's PR-linking tool when required.

Update `captures.md` with the asset URLs and verification result. Report the PR link, captured coverage, and any material gaps briefly. When evidence is only prepared locally, link the artifact directory/body file and state that it has not been uploaded.

## Sources

- [skills.sh documentation](https://skills.sh/docs) and [creating skills](https://github.com/vercel-labs/skills/blob/main/docs/creating-skills.md): portable skill format and discovery.
- [GitHub CLI 2.99.0 release](https://github.com/cli/cli/releases/tag/v2.99.0): repeated `--attach` uploads and local-path rewriting.
- [gh pr edit manual](https://cli.github.com/manual/gh_pr_edit): attachment flags, body files, and partial-upload behavior. Consult the selected executable's help for its installed capabilities.