skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
voidmatcha/ui-clone-skills61 installs

visual-debug

Diagnose why an existing implementation differs from reference evidence using AE/SSIM, pixel, section, computed-style, and transition diffs. Use for post-implementation mismatch or repair guidance; not baseline capture or full clone generation.

How do I install this agent skill?

npx skills add https://github.com/voidmatcha/ui-clone-skills --skill visual-debug
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    This skill is a visual debugging and verification suite for UI engineering tasks. It provides a comprehensive set of scripts to compare an implementation against a reference using pixel-level diffs, structural DOM analysis, and runtime behavior checks. The skill uses standard system tools (ImageMagick, ffmpeg) and a browser automation CLI (agent-browser). All external resources point to the author's official GitHub repository, and the skill follows safe practices by prompting the user for installation rather than executing remote code automatically.

  • Socketwarn

    2 alerts: gptAnomaly

  • Snykpass

    Risk: LOW · No issues

What does this agent skill do?

Visual Debug

Diagnose an existing implementation against captured reference evidence with structural, AE, DSSIM, runtime, and transition checks.

Boundary and return contract

  • Use this skill when reference and implementation evidence already exist. Route missing baseline evidence to ui-capture; route implementation, regeneration, and full clone orchestration to ui-reverse-engineering or the active caller.
  • Diagnose and return the failing artifact, selector or region, likely root cause, recommended fix, and exact verification command. The caller owns source edits unless it explicitly delegated repair.
  • Read brief/WORKER_BRIEF.md or evidence-pack.json first when present, then only the summaries and named drill-down artifacts needed for the failing hotspot.
  • If repair was delegated to you, read ../ui-reverse-engineering/iteration-discipline.md before the repair loop. Attempt history and stop conditions survive delegation and compaction. Report checker defects with a reproducer unless shared-tool repair is already authorized; never edit an installed cache.
  • Matching text, heights, fired events, or a successful build does not prove appearance or trajectory parity. Compare background and foreground, media fit, and intermediate motion states.

Required invariants

Do not read ref/impl images for routine comparison. Start with summaries and AE/SSIM tools. For a failing position, run auto-diagnose.sh; read a diff image only if automated diagnosis finds nothing. Phase E is the required exception and must run in a delegated context.

Pin the reference during iteration. Dynamic sites otherwise compare against a moving target: after the first complete reference capture, use frozen reference crops (RECATCH_REF=0) until evidence is genuinely stale. After any implementation edit, produce fresh implementation evidence before judging the fix.

When evidence contains window.scrollTo, scrollYProgress, setTimeout, velocity, a guard ref around scroll-stop logic, or ScrollTrigger pin/scrub, require scroll state-machine proof of initial → active/expanded → settled/returned; a single endpoint frame is insufficient.

Do not weaken thresholds or mask unexplained regions to clear a failure. Classify each failure as implementation, reference/capture, checker, or unknown before editing.

Close every browser session you opened on success, failure, or interruption:

agent-browser --session <session-name> close

Never use close --all; other agents may own sessions.

Start once per session

Check required tools. If anything is missing, stop and surface the bootstrap command; do not execute a remote installer automatically.

miss=""
for c in agent-browser ffmpeg dssim; do command -v "$c" >/dev/null 2>&1 || miss+=" $c"; done
{ command -v magick >/dev/null 2>&1 || command -v convert >/dev/null 2>&1; } || miss+=" imagemagick"
if [ -n "$miss" ]; then
  printf 'Missing system deps:%s\nBootstrap:\n  tmp=$(mktemp) && curl -LsSf -o "$tmp" https://raw.githubusercontent.com/voidmatcha/ui-clone-skills/main/install.sh && bash "$tmp" && rm -f "$tmp"\n' "$miss"
  exit 1
fi

Resolve scripts from the active plugin or checkout:

SCRIPTS_DIR="${VISUAL_DEBUG_SCRIPTS_DIR:-}"
if [ -z "$SCRIPTS_DIR" ]; then
  for root in "${PLUGIN_ROOT:-}" "${CODEX_PLUGIN_ROOT:-}" "${CLAUDE_PLUGIN_ROOT:-}" "${UI_CLONE_ROOT:-}" "$PWD" "$PWD/.." "$PWD/../.." "${INSTALL_DIR:-$HOME/.local/share/ui-clone-skills}"; do
    [ -n "$root" ] && [ -f "$root/skills/visual-debug/scripts/ae-compare.sh" ] && SCRIPTS_DIR=$(cd "$root/skills/visual-debug/scripts" && pwd) && break
  done
fi
[ -n "$SCRIPTS_DIR" ] || { echo "Set VISUAL_DEBUG_SCRIPTS_DIR or PLUGIN_ROOT" >&2; exit 1; }

Run the scripts as bash "$SCRIPTS_DIR/<script>.sh" .... On hosts without a Skill event (Codex), the first such call is what tells the plugin hooks that this session owns the diagnosis.

Pipe large browser JSON to files; do not print it into the model context. Every agent-browser command needs --session <name>, and every JS eval must be an IIFE.

Choose the route

  1. Read the smallest existing summary first: sections/result.txt, pipeline-state.json, _summary.json, pixel-perfect-diff.json, or the failing gate artifact.
  2. Run cheap structural checks before pixels: implementation chrome scan, stray-absolute-check.sh, relevant transition/spec coverage, reveal/breakpoint checks, then a narrow computed-diff.sh.
  3. Use section-compare.sh for routed post-generation verification and batch-scroll.sh plus batch-compare.sh for a standalone broad sweep. The section command requires the fourth ref-dir argument because the gate reads its sections/result.txt.
  4. Diagnose only failing rows with auto-diagnose.sh. Escalate unresolved failures in order to tree-diff.sh, layout-tree-diff.sh, hover-tree-diff.sh, or keyframes-diff.sh according to the symptom.
  5. Re-run the affected check and its dependency closure. Use scoped or standard verification during iteration; canonical closeout still requires the caller's full comprehensive verification.

Read tool-routing.md only when you need exact commands, ONLY_IF_CHANGED, masking rules, or tool selection. Read common-selectors.md only for domain selector sets. Read verification.md only for standalone full capture/verification mechanics. Read comparison-fix.md only when entering the repair loop or dispatching Phase E. Do not load all references up front.

Three-axis completion

Every position requires all three axes:

AxisToolPass condition
PixelAEAE per image ≤ 500
PerceptualDSSIM / frame SSIMSSIM per frame ≥ 0.995
Semanticdelegated Phase E reviewPASS, or explicit approval of a known difference

Computed-style comparison passes with 0 mismatches. AE=500 permits antialiasing variance; dynamic content may use AE=2000 only through the documented dynamic route. These thresholds are contracts and may change only with explicit user approval and recorded rationale.

Phase E is mandatory for full verification and reviews every ref/impl position after AE and DSSIM. Delegate it to the host-native visual-debug-reviewer (a Codex native subagent where available); otherwise use a generic delegated worker with the same contract. Do not retry a rejected role name. Only the verdict table returns to the coordinator. A bounded diagnostic Phase E may inspect representative existing pairs early, but its noncanonical artifact cannot replace final all-position review. See comparison-fix.md.

Return PASS only when all three axes agree and every required row is measured. FAIL, INCOMPLETE, UNMEASURED, stale evidence, or missing artifacts remain incomplete. Then resume the caller's pipeline for implementation and canonical closeout.

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/voidmatcha/ui-clone-skills/visual-debug">View visual-debug on skillZs</a>