agentleFS
eriknomitcheriknomitch/workmelt/.claude/skills/visual-check/SKILL.md

visual-check

Skill4 starsChanged 4 months agoMITView on GitHub

Verify a Workmelt change by looking at the rendered picture — captures, screenshots, image diffs, baselines, the goal/visibility/cost gate, and the browser playtests. Use this skill whenever the work calls for a capture or a screenshot, whenever a change touches shading, post-processing, materials, lighting, layout or the HUD and someone needs to see whether the frame is right, whenever `tools/capture.mjs` / `imagediff.mjs` / `goal.mjs` / `visibility.mjs` / `cost.mjs` / `profile.mjs` are involved, and whenever performance or quality-tier work needs measuring. Also use it before reporting fps or a perf number, and before claiming a visual check passed.

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. IHanfoxI/webapp-docs-kit★ 0same 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 repository5 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:

    Always pass an explicit --out= under the scratchpad directory rather than letting the tool pick a path, so you know what to read back.

    line 53
  2. Very specific:

    Keep one dev server up and share it: start npm run dev once and pass OW_PORT=5273, because every harness attaches to whatever is already …

    line 71
  3. Very specific:

    Then send it to the user with SendUserFile: when the image is the point of the work — a before/after, a layout change, a bug you are …

    line 88
  4. Distinctive:

    Run the one that covers your change, not the set — or, now that each is seconds, the set in parallel against one server.

    line 156

≈ “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

Look at the picture

The engine's cheap coverage is the Node-only self-tests; this skill is for the part they cannot reach — whether the frame is actually right. Two rules govern everything below, and both are about honesty rather than technique:

  1. A command exiting 0 is not a visual check. The picture is. If a .png was written and nobody read it, no check happened.
  2. A skipped render reported as a pass is much worse than a skipped render. Say plainly that you skipped it and why.

First: should you render at all?

Usually not. The seventeen Node-only self-tests (see AGENTS.md) carry most of the real coverage and run in ~10 s combined. Run those plus npm run build and stop there unless the change is genuinely a function of the image — shading, post-processing, materials, lighting, layout, or a HUD/menu surface.

Collision is the sharpest example of the inverse: it is authored separately from the mesh, so an invisible wall is invisible in a capture too. The frame is correct and the thing that is wrong is the thing that is not drawn. node src/world/collision.selftest.mjs catches it; no screenshot can.

Detect the environment before reaching for a browser

Claude Code on the web runs in a container with no GPU: ls /dev/dri is empty, $DISPLAY is unset, CLAUDE_CODE_REMOTE=true. WebGL2 still works, but only through ANGLE's SwiftShader backend, rasterising every pixel on 4 shared CPU cores. tools/lib/harness.mjs's resolveGpuMode() already detects this and returns 'swiftshader'.

This matters because node tools/capture.mjs at its defaults does not work there — it renders for 25 minutes and still fails. Read references/gpuless-sandbox.md before capturing, scoping the goal gate, or quoting any timing in that environment. On real hardware the defaults are fine.

Capture

Always pass an explicit --out= under the scratchpad directory rather than letting the tool pick a path, so you know what to read back. The tools perform no shell expansion of a variable you did not export — write the real absolute path.

# real GPU — defaults are calibrated for this
node tools/capture.mjs --shot=hero --out=<scratchpad>/after.png

# GPU-less container — the smoke-test recipe (~40 s)
OW_PORT=5273 node tools/capture.mjs --shot=hero \
  --w=640 --h=360 --settle=8 --timeout=600000 \
  --query="prewarm=0&q=performance" --out=<scratchpad>/after.png

tools/capture.mjs frames the boot map from its spawn 0; --query="map=<id>" shoots another. npm run shot is the same command.

Keep one dev server up and share it: start npm run dev once and pass OW_PORT=5273, because every harness attaches to whatever is already listening instead of paying the Vite-plus-shader-warmup boot again. strictPort is on. Note that tools/cost.mjs and tools/visibility.mjs default to their own ports (5331 and 5321) and boot extra servers unless you pass --port=5273, and tools/goal.mjs shells out to both without forwarding a port at all.

Then actually look at it

Read the exact path you just wrote. A Read on an image renders it inline in the transcript, which is the only way the render gets looked at rather than assumed. Paying for a frame and never reading it is worse than skipping the capture, because it reads as a visual check that never happened.

This applies to anything that writes a .png — tools/capture.mjs, tools/imagediff.mjs, a page.screenshot inside a playtest, a one-off script.

Then send it to the user with SendUserFile when the image is the point of the work — a before/after, a layout change, a bug you are demonstrating. Read puts the frame in front of you; only SendUserFile puts it in front of them. Pass display: "render" so it opens inline rather than as a download card, batch related frames into one call, and caption it with what to look at.

Two frames captured at the same --w/--h/--settle are a fair before/after. Frames captured at different settings are not, and must not be presented as one. The same goes for comparing against a tools/baseline.mjs baseline — preserve deterministic output so baselines and tools/imagediff.mjs stay meaningful.

The goal gate

Quality-tier and performance work is gated by node tools/goal.mjs, which scores the open goals in goals/. tools/lib/selftest.mjs (npm run test:metrics) covers the measurement primitives behind it.

It is expensive — npm run goal sweeps five tiers over three shots plus targets, twice over (visibility.mjs then cost.mjs). Scope it:

  • npm run goal:quick over npm run goal.
  • --tiers= and --shots= narrowed to the tier you actually changed.
  • node tools/goal.mjs --score-only re-scores the last measurement for free rather than re-measuring.

Never report fps you did not measure

Frame rate is not measurable on a GPU-less machine, at any resolution or duration. Do not report fps there, and do not let a SwiftShader wall-clock number stand in for one. costIndex ratios and cpuSimMs from tools/cost.mjs are the honest signals; swMsPerFrame is corroboration only.

Real fps comes from tools/profile.mjs on real hardware, fed back via tools/goal.mjs --ingest. Leave the H* criteria UNVERIFIED and say so instead of guessing.

Browser playtests

These drive DOM and engine state rather than judging pixels, so they boot with ?draw=0: the engine, input and HUD run, nothing is drawn, nothing compiles. Measured in the GPU-less container against a shared dev server:

drawingdraw=0
playtest:ads89 s14 s
playtest:grenade75 s, 5 checks failed18 s
playtest:graphics177 s22 s
playtest:lobby279 s30 s

The grenade failures are the reason the waits are on the engine's clock now (waitFrames / waitGameTime in tools/lib/harness.mjs): at 2 fps the engine clamps each step to 0.1 s, so a 3.6 s wall-clock sleep was ~0.7 s of fuse.

Passing a screenshot path to any of them turns drawing back on, since that picture is worth looking at; so does OW_DRAW=1.

  • npm run playtest:ads — pause menu and ADS binds.
  • npm run playtest:graphics — advanced graphics menu, including a reload that carries overrides back into config.q.
  • npm run playtest:grenade — G / H equipment binds: cook, arc preview, throw, detonation, HUD pips, the stun's screen flash.
  • npm run playtest:lobby — the whole join flow in two real browsers against a real relay.
  • npm run playtest:lobby-ui — the lobby SURFACE alone: map cards, garrison chips, keyboard shortcuts, ?mp=0. Rides ?renderGame=false, so no engine boots and it finishes in ~2 s even here.

Run the one that covers your change, not the set — or, now that each is seconds, the set in parallel against one server.

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.