sprite-anim
Skill2 starsChanged 4 months agoMITView on GitHub
Process and verify sprite/animation work for web UIs — normalize a set of animation frames to a uniform character size (area-scale + baseline-align) and verify CSS/JS animations in a real browser via the Chrome DevTools Protocol. Use when a task touches sprite frames, sprite-sheet alignment, or a decorative/UI animation whose on-screen motion must be confirmed (drift, jump, stall, fade). Distilled from animated-character-sprite work, 2026-06-12.
In this repository11 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- designSkill
- diagramSkill
- evidence-ledgerSkill
- market-scanSkill
- motionSkill
- prototypeSkill
- reframeSkill
- retroSkill
- review-motionSkill
- speechSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 58
Don't burn effort on a clamped outlier the frame selector never renders — check which frames the code actually uses first.
- Very specific: line 89
If the feature is gated on app state (e.g.
- Distinctive: line 102
If a new sprite/animation surprise appears, add a lesson and (on the second occurrence) fold the fix back into the scripts here — don't let …
≈ “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.
Files
/sprite-anim — sprite frames & browser-verified animation
Two capabilities that recur together when polishing a sprite-driven UI animation: (A) make a set of frames look like one consistent character, and (B) prove the animation actually behaves on screen — not just in the code. Both ship as runnable scripts beside this file; the gotchas that make them non-obvious live in two lessons.
The cardinal rule for both: a code read is not evidence about pixels. Re-measure the output, and verify motion in a real browser. The session that produced this skill burned an iteration dismissing real drift as a "measurement artifact" — don't.
A — Normalize sprite frames to a uniform character size
When: frames of the same character render at visibly different sizes or bob vertically as the animation cycles (sitting frame bigger than running frame; feet at different heights).
Two choices, each with a wrong-looking default:
- Size by silhouette AREA, not bbox height/width. Area is pose-robust — a crouched
or stretched pose holds the same "amount of character" as a tall one. Scale each frame
by
sqrt(medianArea / frameArea). Height-normalizing inflates low/wide poses into giants. Clamp the factor (default[0.70, 1.45]) so a folded pose (curled sleeper = little area) doesn't blow up, and re-clamp to the canvas. - Align the bbox BOTTOM to a baseline, not center. Centering puts feet at different
heights → the character bobs frame-to-frame. Seat every bbox bottom on one baseline.
Pick the baseline to match the render's
transform-origin(e.g.50% 85%→ feet near bottom → baseline low on the canvas).
Run:
python3 .claude/skills/sprite-anim/normalize_frames.py SRC_DIR DST_DIR \
[--clamp LO HI] [--baseline auto|N] [--align-x center|N] [--pad N]Canvas size is preserved per frame, so the render's object-fit math is untouched. Write
to a scratch DST first, verify, then copy into the repo's frames dir (in a worktree, per
the code-changes-go-to-worktree rule).
Verify two ways (do both):
- Re-measure: opaque-pixel area of the outputs should cluster (spread ≈ 1.1×, σ ≈ a
few %). The script prints
target linear+baseline y; a quick re-measure loop confirms the cluster. - Montage at the ACTUAL render size — a faithful no-server preview of the in-app look:
magick montage DST/*.png -tile 4x -geometry 88x88+3+3 -background '#888' \ -font /System/Library/Fonts/Helvetica.ttc -label '%f' /tmp/preview.png-geometry WxHmust mirror the in-app rendered box (it mirrorsobject-fit: contain). The-fontflag is required on macOS or montage errors "unable to read font".-append/+appendoperators go AFTER the input filenames, not before. - Don't burn effort on a clamped outlier the frame selector never renders — check which frames the code actually uses first.
B — Verify a CSS/JS animation in a real browser (CDP)
When: an animation's on-screen behavior must be confirmed — does it drift to a corner, jump, snap back, stall, or fade correctly? A code read cannot answer this.
Run: edit the CONFIG block (url, setup, trigger, probe, assertions) in
.claude/skills/sprite-anim/verify-anim.mjs, then node verify-anim.mjs. It launches
headless Chrome, samples the element's transform + getBoundingClientRect + opacity
across the whole animation window, screenshots chosen frames, and prints a verdict. No
Playwright, no test framework.
Gotchas baked into the harness — and two binding lessons:
- Trust
getBoundingClientRect, not the matrix.DOMMatrix(getComputedStyle(el).transform).m41reflects only thetransformproperty — NOT the separate CSSscale/translate/rotateproperties. When the rect and the matrix disagree, the rect is the truth and the gap is real motion, not noise. (Note also: the individualscaleproperty multiplies atransform: translate()offset per spec composition order → a "shrink in place" drifts toward 0,0. Shrink viatransform: translate() scale()in one property, or split parent/child, or just fade.) - Verify on the main-checkout dev server, not a worktree. A bundler's out-of-tree
file-access allowlist can block a worktree's symlinked
node_modules→ blank page. Edit in the worktree, run your framework's codegen + type-check, merge to the working branch, then verify HMR on the single main-checkout dev server. - Navigate + sleep BEFORE touching
localStorage— the blank initial document throws aSecurityError. The harness does this; keep it if you adapt the flow. - If the feature is gated on app state (e.g. an animated character that only mounts
when
app.ready:true), the seeded mock must satisfy the gate or the element never mounts.
Lessons this skill is built on
| Rule this skill encodes | What it locks in |
| Normalize frames by area + baseline | area for size, baseline for vertical, render-size montage to verify |
CSS scale multiplies translate | trust getBoundingClientRect over the matrix when they disagree |
If a new sprite/animation surprise appears, add a lesson and (on the second occurrence) fold the fix back into the scripts here — don't let this skill calcify.
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
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.

