What is the fixing-motion-performance skill?
The fixing-motion-performance skill is a SKILL.md from the ibelick/ui-skills repo. It tells your coding agent to animate transform and opacity by default, batch layout reads before writes, avoid scroll-event animation and keep blur small. Run it on a file and it reports each violation with a concrete fix.
fixing-motion-performance is an agent skill from the ibelick/ui-skills repo. Its SKILL.md gives a coding agent a ranked rule set for animation work, aimed at stutter, jank and layout thrashing in CSS, WAAPI, Motion, requestAnimationFrame and GSAP code.
The rules start from how the browser renders a frame. Composite work (transform, opacity) is cheap, paint work (color, borders, gradients, masks, images, filters) costs more and layout work (size, position, flow, grid, flex) costs the most.
What changes in your agent's output
transformandopacitybecome the default for movement, instead ofwidth,leftortop- Layout reads are batched before writes, and measurement happens once
- Scroll-linked motion uses scroll or view timelines or
IntersectionObserver, not scroll events will-changeappears briefly and on purpose, not across a whole stylesheet- Blur animation stays at 8px or less and runs once, never on a loop
Run /fixing-motion-performance to apply the rules to all UI animation work in the conversation, or /fixing-motion-performance <file> to review one file. Fixes stay inside your existing animation library.
Who it is for
Best for
- Animations that stutter or transitions that jank
- Scroll-linked effects and reveal-on-scroll sections
- Components that animate layout, filters, masks, gradients or CSS variables
- Reviewing AI-generated animation code before it ships
Not for
- Swapping animation libraries. The skill forbids migrating or partially rewriting an API unless you ask
- Profiling a live page. It reviews code, and it tells the agent to validate layer behavior with tooling when performance matters
- Deciding what to animate. It governs how, not whether
Use it with UiChemy
UiChemy Composer writes real HTML, CSS and JS inside Elementor or Gutenberg, so any animation it produces is ordinary code this skill can review. Run it on the CSS and scripts before you publish. Pair it with the fixing-accessibility skill and the Impeccable polish skill before launch.
How to install Fixing Motion Performance
git clone https://github.com/ibelick/ui-skills.gitClone the repo
Run the command above. The skill lives in
skills/fixing-motion-performanceand is oneSKILL.mdfile.Copy the folder
Copy
skills/fixing-motion-performanceinto your agent's skills directory. For Claude Code that is~/.claude/skills/for every project or.claude/skills/inside one project.Apply it
Type
/fixing-motion-performanceto apply the rules to the session, or/fixing-motion-performance src/components/Hero.tsxto review a single file.
Check that it loaded
Start a new session and type /fixing-motion-performance with a file path. The agent should return violations with the quoted line, a one-sentence reason and a code-level fix.
Key features
- Never patternsThe critical list bans interleaving layout reads and writes in one frame, continuously animating layout on large surfaces, driving animation from
scrollTop,scrollYor scroll events, andrequestAnimationFrameloops with no stop condition. - Choose the mechanismDefault to
transformandopacity, use JS-driven animation only where interaction requires it, and accept paint or layout animation only on small, isolated surfaces. Downgrading the technique beats removing motion. - Measure once, then animateMeasure once, batch all DOM reads before writes and never read layout repeatedly during an animation. FLIP-style transitions are preferred for layout-like effects.
- Scroll-linked motionPrefer Scroll or View Timelines when available and use
IntersectionObserverfor visibility and pausing. Never poll scroll position, and pause animations that are off-screen. - Paint limitsPaint-triggering animation is allowed only on small, isolated elements, never on large containers. Do not animate CSS variables that drive transform, opacity or position, and scope animated variables locally without inheritance.
- Layer promotionCompositor motion needs layer promotion and the skill says never to assume it. Use
will-changetemporarily and surgically, avoid many or large promoted layers and validate with tooling. - Blur and filtersKeep blur animation to 8px or less and use it only for short, one-time effects. Never animate blur continuously or on large surfaces, and try opacity and translate first.
- View transitionsUse view transitions only for navigation-level changes. Avoid them for interaction-heavy UI and wherever interruption or cancellation is required, and treat size changes as potentially layout-triggering.
- Rendering glossaryThe skill defines composite, paint and layout work so the agent can name the cost of each property it touches. Any non-default choice needs a stated constraint, such as surface size, duration or interaction need.
- Tool boundariesRules apply inside the existing animation system. The agent does not migrate or rewrite libraries unless asked and never mixes old and new API styles within one component.
Frequently asked questions
What is the fixing-motion-performance skill?
It is a SKILL.md from the ibelick/ui-skills repo that teaches a coding agent to audit and fix animation performance. It covers layout thrashing, compositor properties, scroll-linked motion, paint cost, layer promotion, blur effects and view transitions, and it applies those rules inside whatever animation library your project already uses.
How do I install the fixing-motion-performance skill?
Clone the ibelick/ui-skills repo with git, then copy the skills/fixing-motion-performance folder into your agent's skills directory. In Claude Code that is ~/.claude/skills/ for all projects or .claude/skills/ inside one project. The folder contains one SKILL.md, so nothing else needs installing.
Which properties does fixing-motion-performance tell the agent to animate?
Transform and opacity are the default, because they run as composite work. Paint properties such as color, borders, gradients, masks and filters, and layout properties such as size and position, are acceptable only on small, isolated surfaces. The skill prefers downgrading a technique to removing motion entirely.
How does fixing-motion-performance handle scroll animations?
It bans driving animation from scrollTop, scrollY or scroll events and tells the agent not to poll scroll position. Instead it prefers Scroll or View Timelines where available, and IntersectionObserver for visibility and pausing. Animations should pause or stop when they are off-screen.
How much blur does the skill allow in animations?
Blur animation stays at 8px or less and is meant for short, one-time effects. The skill says never to animate blur continuously and never to animate it on large surfaces. It tells the agent to reach for opacity and translate before blur.
Will fixing-motion-performance rewrite my animation library?
No. The skill says not to migrate or rewrite animation libraries unless you explicitly request it. Its rules apply within the existing stack, whether that is CSS, WAAPI, Motion, requestAnimationFrame or GSAP, and it never partially migrates APIs or mixes styles within the same component.
Is the fixing-motion-performance skill free to use?
Yes. The ibelick/ui-skills repo is published under the MIT license, so you can use, copy and adapt the skill in your own projects. The skill is a plain text SKILL.md file, and installing it means copying one folder from the repository into your agent's skills directory.
Which other skills are in the same repo?
The ibelick/ui-skills repo also holds baseline-ui, create-design-md, fixing-accessibility, fixing-metadata and improve-ui. Pair fixing-motion-performance with fixing-accessibility, which asks for prefers-reduced-motion support, or with fixing-metadata for page titles and social cards. Each skill is a separate folder under skills/, so you can install only the ones you need.