GSAP Performance Skill: Smooth 60fps Rules for AI Agents

What is the gsap-performance skill?

gsap-performance is the shortest skill in the official greensock/gsap-skills set. Its SKILL.md applies when an agent optimizes GSAP animation for smooth 60fps, reduces layout and paint cost, or answers a question about jank.

It builds on gsap-core for transforms and autoAlpha, and on gsap-timeline for sequencing. ScrollTrigger tuning is shared with gsap-scrolltrigger.

What changes in your agent's output

• Movement animates x, y, scale, rotation and opacity instead of width, height, top, left, margin or padding.
• will-change: transform appears only on elements that really animate, not on everything just in case.
• Repeated animation of the same kind uses stagger rather than many tweens with manual delays.
• Mouse followers use gsap.quickTo(), which reuses one tween instead of creating a new tween on every mousemove.
• Off-screen or inactive animations are paused or killed, and ScrollTrigger gets refresh() only when layout actually changes.

Why animation jank happens

The skill's core idea is that layout and paint are expensive and compositing is cheap. Transforms and opacity stay on the compositor, so they animate smoothly even when the main thread is busy.

It also reminds the agent that too many simultaneous tweens or ScrollTriggers cost real time, so it should test on low-end devices when creating many.

Who the gsap-performance skill is for

Best for

• Pages where scroll or hover animation drops frames on mid-range phones.
• Agents that animate left and top for movement or add will-change everywhere.
• Review passes that sit next to fixing-motion-performance, which targets the same class of problem more broadly.

Not for

• Learning the GSAP API. Start with gsap-core.
• Replacing profiling. The skill itself says to test on low-end devices when you create many tweens or ScrollTriggers.

How to install GSAP Performance Skill: Smooth 60fps Rules for AI Agents

git clone https://github.com/greensock/gsap-skills.git

1. Clone the repository

   Run git clone https://github.com/greensock/gsap-skills.git. The skill is the skills/gsap-performance folder, which holds one SKILL.md.

2. Copy the skill folder

   Copy skills/gsap-performance into your agent's skills directory. The README lists ~/.claude/skills/ for Claude Code, ~/.cursor/skills/ for Cursor, ~/.config/opencode/skills/ for OpenCode and ~/.codex/skills/ for OpenAI Codex.

3. Install GSAP in the project

   The skill guides the agent's code but does not add the library. Add the gsap package to your project with your package manager. It includes every plugin.

4. Ask for animation work

   Describe the motion you want, such as a staggered card entrance, and name the skill if your agent needs a nudge.

Check that it loaded

Ask the agent to add a cursor-following dot. The result should call gsap.quickTo() for x and y instead of a new gsap.to() inside the mousemove handler.

Read the official instructions on GitHub

Key features

• Transform and opacity firstAnimating x, y, scaleX, scaleY, rotation, skewX and opacity keeps work on the compositor and avoids layout and most paint.
• Layout property banThe skill flags width, height, top, left, margin and padding as properties that trigger layout and can cause jank.
• Careful will-changeAdd will-change: transform in CSS on elements that will animate. The Do Not list rules out setting it or force3D on every element.
• Read and write batchingGSAP batches its own updates. When you mix in direct DOM reads and writes, do all reads first and then all writes to avoid layout thrashing.
• Stagger over manual delaysThe same animation on many elements should use one stagger instead of many tweens with hand-set delays.
• Many-element guidanceFor long lists, consider virtualization or animating only visible items, and reuse timelines instead of creating new ones every frame.
• quickTo for frequent updatesgsap.quickTo('#id', 'x', { duration: 0.4, ease: 'power3' }) returns a setter that reuses one tween for values updated often, such as a cursor follower.
• ScrollTrigger tipsPin only what needs pinning, try a small scrub value such as scrub: 1, and call ScrollTrigger.refresh() only on real layout changes, debounced where possible.
• CleanupPause or kill animations that are off-screen or inactive. Stray tweens and ScrollTriggers keep running and hurt performance and correctness.

Frequently asked questions