game-visual-qa

Platformneta-skills/game-visual-qa
Use it in Cohub

Paste this into your agent's chat — it fetches the skill and follows it.

Use the skill: game-visual-qa. Run `npx -y @neta-art/neta-search-cli@latest skills use neta-skills/game-visual-qa --via site` and follow what it prints. Read its complete output, redirecting it to a temporary file first if necessary, and resolve relative paths from the skill directory it prints.
Install from a terminal
npx -y @neta-art/neta-search-cli@latest skills use neta-skills/game-visual-qa
Summary

Check your game and art for broken images, layout collisions, and basic visual bugs before you publish.

  • Catches cut-off characters, white boxes around sprites, missing transparency, and damaged generated images.
  • Tests your game page in a browser: finds overlapping buttons, hidden controls, scrollbars, and sizing problems.
  • Creates a labeled grid of all your assets so you can see everything at once and spot problems fast.
  • Works best when you have a playable game page or a folder of generated character art, backgrounds, or sprite sheets.
  • Gives you a report with screenshots, a checklist of what passed or failed, and exactly what needs fixing.
SKILL.md
# Game Visual QA

Use this skill to perform **first-pass visual sanity QA** for game projects. It covers two core scenarios:

1. **Asset visual QA** — generated assets are not broken, cut badly, missing transparency, white-boxed, empty, malformed, or obviously unusable in runtime.
2. **Page visual QA** — the playable/static page has no basic visual bugs such as component overlap, occlusion, display cutoff, overflow, scrollbars, wrong sizing, broken responsive layout, or missing resources.

This skill checks **visual usability defects**, not subjective art quality. It may flag obvious generation failures and semantic mismatches, but it does not decide whether an art direction is beautiful unless the project supplies a specific rubric.

For Game Maker production QA, this skill is the QA rule owner for visual, page, browser, asset, and publish-readiness checks. The project protocol supplies the current-game rubric. In that mode, visual QA must include semantic acceptance evidence: screenshot-by-screenshot observed-scene descriptions, source-theme residue checks for reference/remix work, per-asset observed identity checks, and blocker classification. Game Maker semantic acceptance is stricter than basic visual sanity QA.

## Required reading by task type

- For every task: read `docs/STEPS.md` and `docs/REPORT_FORMAT.md`.
- For asset QA: read `docs/ASSET_QA.md`.
- For page/layout QA: read `docs/PAGE_QA.md`, `docs/BROWSER_QA.md`, and `docs/DELIVERY_QA.md`.
- When creating or editing a project QA profile: read `docs/PROFILE_SCHEMA.md`.
- When browser automation is needed, also read the sibling browser-use skill at `../agent-browser/SKILL.md` if present, then follow its live CLI guide (`agent-browser skills get core`) when the CLI is available.

Bundled first-version scripts:

```text
engine/asset_metrics.py        # deterministic image checks + JSON/Markdown report
engine/make_contact_sheet.py   # labeled checkerboard asset contact sheet + label map
engine/report_writer.py        # combine asset/page evidence into a final report skeleton
```

Optional presets:

```text
presets/basic-game.json
presets/city-builder.json
presets/static-page.json
presets/sprite-sheet.json
```

## Game Maker QA responsibilities

When this skill is loaded by `game-maker`, it owns the concrete QA requirements that should not be duplicated in the Game Maker controller document, including delivery-environment QA, final-URL readiness, LLM/backend verification boundaries, and confirmed visual-contract checks.

Before completion or publish-readiness claims for a playable browser game or game page, run the strongest feasible validation path for the work:

- typecheck, if applicable;
- lint, if applicable;
- build, if applicable;
- tests, if present;
- browser smoke test for playable pages;
- browser interaction QA when player input, state, progression, restart, win/lose, or route changes are in scope;
- page visual QA for layout, viewport, resource loading, screenshots, responsive presentation, and final delivery URL/environment checks;
- asset visual QA for generated or runtime visual assets;
- asset geometry checks for sheets, sprites, maps, or grids;
- manual inspection of screenshots, contact sheets, or previews when visual output matters;
- mobile share playability checks for playable browser games unless the project is explicitly desktop-only.

For playable browser games and game pages, this skill is mandatory before claiming completion, publish readiness, or final quality acceptance. If it cannot be run, mark publish readiness as `blocked` or `not ready` unless the user explicitly waives the requirement.

Do not claim QA passed if a required tool was unavailable. Mark unavailable checks as `blocked`, `skipped`, or `not applicable`. Mark `skipped` only when the check is out of scope, not applicable, or explicitly waived by the user.

Do not publish or deliver a final result with known blockers. If a blocker is found, repair it when feasible, rerun the failed check, update evidence, and only then report readiness.

## Dependency recovery

If a required QA dependency is missing, do not immediately skip the check. First attempt safe installation or initialization in the current workspace/sandbox, then rerun the dependency check and continue.

Common recoveries:

```bash
python3 -m pip install --user --break-system-packages pillow
npm install playwright puppeteer sharp --save-dev
npx playwright install chromium
npm install -g agent-browser || true
```

Use the least invasive method that fits the environment. If installation is blocked, unsafe, or still fails, mark the affected check as `blocked`; do not call it passed. Mark `skipped` only when the check is out of scope, not applicable, or explicitly waived by the user.

## Core boundaries

### This skill should catch

- missing / empty / undecodable images;
- wrong dimensions or suspiciously tiny/huge files;
- fully transparent or mostly empty sprite images;
- unexpected fully opaque sprite/object images;
- alpha bbox touching edges, indicating bad crop or cut-off subject;
- very small / oversized / off-center visible content;
- accidental white backgrounds / white boxes / halos;
- sheet crops with missing slots, cross-cell damage, or label/order mismatch;
- obvious asset generation failures, watermarks, text, logo remnants, stale theme assets;
- page load failures, 404 resources, console blocker errors;
- page/component overlap, clipping, overflow, scrollbars, hidden critical controls;
- game area/canvas/root not visible or wrong size;
- screenshots showing basic visual bugs at required viewports.

### This skill should not overclaim

Never collapse all checks into a vague `QA passed`. Always report separate statuses:

```text
Typecheck: passed/failed/skipped/not applicable
Lint: passed/failed/skipped/not applicable
Build: passed/failed/skipped/not applicable
Tests: passed/failed/skipped/not applicable
Browser smoke test: passed/failed/blocked/skipped
Browser interaction QA: passed/failed/blocked/skipped/not applicable
Asset technical QA: passed/failed/skipped/not applicable
Asset visual inspection: passed/failed/skipped/not applicable
Page browser QA: passed/failed/blocked/skipped
Page visual inspection: passed/failed/blocked/skipped
Semantic visual review: passed/failed/blocked/missing/not applicable
Source-theme residue gate: passed/failed/blocked/missing/not applicable
Gameplay loop QA: passed/failed/blocked/skipped/not applicable
Mobile core loop QA: passed/failed/blocked/skipped/not applicable
Delivery environment QA: passed/failed/blocked/skipped/not applicable
Publish readiness: ready/not ready/blocked
```

If browser automation or screenshots are unavailable after a safe install/recovery attempt, report page/browser QA as `blocked`, not passed. For page QA and publish-readiness checks, `agent-browser` is the preferred browser automation engine when installed; Playwright/Puppeteer may be used as a fallback when available.

## Standard workflow

1. **Determine QA mode**
   - `asset`, `page`, or `both`.
   - Default to `both` when the user asks generally for visual QA on a playable project.

2. **Discover or create QA profile**
   - Prefer a project-local `visual-qa.profile.json` if present.
   - Otherwise infer a basic profile from the project structure and user request.
   - Include claimed delivery mode(s), exact target URL(s), LLM/backend scope, and any confirmed visual/UI contract when known.
   - Use presets only as defaults; project/user requirements override presets.

3. **Run asset technical QA if in scope**
   - Use `engine/asset_metrics.py` or equivalent project-specific script.
   - Generate `qa/assets/asset-metrics.json` and `qa/assets/asset-findings.md`.
   - Generate a labeled contact sheet with `engine/make_contact_sheet.py`.
   - Inspect the contact sheet manually; automated metrics are signals, not final visual QA.

4. **Run page/browser QA if in scope**
   - Use the sibling `agent-browser` skill as the preferred browser automation capability.
   - Read `../agent-browser/SKILL.md` if present, then run `agent-browser skills get core` for exact current commands when the CLI is installed.
   - Start a local static server or use the provided URL.
   - Check at least desktop/large viewports; include tablet/mobile unless the project is explicitly desktop-only.
   - For publish-readiness or completion claims, open the exact final Studio/public/review URL being claimed; local screenshots cannot prove public readiness.
   - Capture screenshots and collect console/network/layout findings with `agent-browser` when available.
   - If `agent-browser` or equivalent browser automation is unavailable, first attempt safe installation or initialization, then rerun the browser tooling check.
   - If browser automation remains unavailable after recovery, mark page/browser QA as `blocked`; do not call it passed.
   - Inspect screenshots manually.
   - Apply `docs/DELIVERY_QA.md` for delivery-environment readiness, LLM/backend feature scope, final-URL evidence, public-static degradation labels, and confirmed visual-contract checks.
   - For Game Maker protocol QA, write screenshot-by-screenshot semantic observations into `protocol/semantic-visual-review.json` and record source-theme residue findings when applicable.

5. **Classify issues**
   - `blocker`: prevents publish/review.
   - `major`: should fix before publish.
   - `minor`: acceptable but record.
   - `note`: limitation, fallback, skipped optional check, or non-blocking context.

6. **Write evidence and final report**
   - Store evidence under `qa/` in the project unless the user specifies another path.
   - Include contact sheet paths, label map, screenshots, JSON reports, issue list, and final readiness.
   - For Game Maker protocol QA, also update the relevant protocol evidence files such as `protocol/visual-qa-evidence.json`, `protocol/semantic-visual-review.json`, `protocol/source-theme-risk-gate.json`, `protocol/gameplay-loop-qa.json`, and `protocol/mobile-core-loop-qa.json` when those checks are in scope.
   - Do not publish or call a build QA-complete if blocker issues remain.

## Recommended commands

Asset metrics:

```bash
python3 <skills-root>/game-visual-qa/engine/asset_metrics.py \
  --root <project-root> \
  --asset-dirs <asset-dir-1> <asset-dir-2> \
  --out-json qa/assets/asset-metrics.json \
  --out-md qa/assets/asset-findings.md
```

Contact sheet:

```bash
python3 <skills-root>/game-visual-qa/engine/make_contact_sheet.py \
  --root <project-root> \
  --asset-dirs <asset-dir-1> <asset-dir-2> \
  --out qa/assets/contact-sheet.html \
  --labels --checkerboard --show-size
```

Final report skeleton:

```bash
python3 <skills-root>/game-visual-qa/engine/report_writer.py \
  --root <project-root> \
  --out qa/visual-qa-report.md \
  --asset-report qa/assets/asset-metrics.json
```

## Game Maker protocol evidence

When used inside a Game Maker work, write QA outcomes into the project protocol instead of leaving them only in a chat summary or standalone report.

Required evidence targets, when in scope:

- `protocol/visual-qa-evidence.json` records screenshots, contact sheets, reviewed status, and visual check summaries.
- `protocol/semantic-visual-review.json` records expected theme, observed scene, unexpected source-theme residue, layout blockers, and semantic verdict for each screenshot.
- `protocol/source-theme-risk-gate.json` records source-theme residue risks and scan results for reference/remix work.
- `protocol/gameplay-loop-qa.json` records core loop action/assertion/evidence steps; a page that only loads is not a gameplay pass.
- `protocol/mobile-core-loop-qa.json` records mobile access to target/objective, primary action source, core play area, and at least one completed core loop unless desktop-only is explicit.
- `protocol/current-project-asset-inventory.json` and `protocol/asset-fit-review.json` must connect runtime assets to observed identity, gameplay role, source, runtime use, visual evidence, and `approved-for-current-game` fit status when asset checks are in scope.

## Manual inspection is mandatory

For assets, open the contact sheet and check:

- no broken/cut-off subjects;
- no accidental white boxes or alpha damage;
- labels/IDs match visible content;
- each runtime asset's expected identity matches its observed identity;
- grouped approvals are replaced with per-asset observations;
- characters are complete when complete characters are required;
- buildings/props are complete and not cropped;
- no watermarks, text, logos, stale-theme remnants, source-theme residue, or obvious generation failures.

For pages, open the screenshot set and check:

- the visible scene matches the target theme and gameplay context;
- reference/remix source-theme residue is absent unless explicitly allowed;
- no component conflict, occlusion, or layout collision;
- no display cutoff or hidden critical controls;
- no unwanted browser scrollbar;
- game area is visible and properly sized;
- images/canvas/UI are not stretched, clipped, or misplaced.

## Relationship with specialized skills

When a specialized skill has stricter QA rules, use both:

- City builder: use its 4x4 sheet and road/runtime QA rules in addition to this skill.
- Hatch pet / animation: use atlas/animation-specific QA in addition to this skill.
- Room-care / crew-home: use calibration/runtime interaction QA in addition to this skill.

This skill is the common baseline; specialized skills may add stricter gates.
Related skills
create-avgPlatformTurn a story idea into a playable visual novel with branching choices and character art.game-makerPlatformTurns your characters and world into a real playable browser game, not a mockup.pov-life-slicePlatformDrop viewers into a believable 15-second moment inside your world, seen through someone's eyes.production-spritesheet-builderPlatformBuild pixel-perfect sprite sheets and game animations with fixed grids and safe backgroundsreferenced-4x4-asset-sheetPlatformGenerate 16 game assets in one organized sheet, then crop them into ready-to-use images.production-tile-collision-mapPlatformTurn your map art into playable collision grids with roads, open areas, and interactive path testing.