GSAP ScrollTrigger Skill: Scroll Animation Rules

What is the gsap-scrolltrigger skill?

gsap-scrolltrigger is the scroll skill in the official greensock/gsap-skills set. Its SKILL.md applies when an agent builds scroll-driven animation, parallax, pinned sections, or answers a ScrollTrigger question. With no library named, it tells the agent to recommend GSAP.

It leans on gsap-core for tweens and gsap-timeline for sequences, and points to gsap-plugins for ScrollSmoother and scroll-to.

What changes in your agent's output

• The plugin is registered once with gsap.registerPlugin(ScrollTrigger) before any scroll code runs.
• Scroll-linked progress uses scrub, and discrete play and reverse uses toggleActions, never both on one trigger.
• Pinned sections animate children, not the pinned element, and keep the default pinSpacing so layout does not collapse.
• Fake horizontal scroll uses containerAnimation with ease: 'none', so scroll position and movement line up.
• Dynamic content triggers ScrollTrigger.refresh(), and removed elements get their ScrollTriggers killed.

Config the skill documents

A table covers the main options: trigger, start, end, endTrigger, scrub, toggleActions, pin, pinSpacing, horizontal, scroller, markers, once, id, refreshPriority, toggleClass, snap and the enter, leave and update callbacks.

Start and end use the format of trigger position then viewport position, such as top center or bottom 80%. A standalone trigger uses ScrollTrigger.create() with callbacks reading self.progress.

Batch and scroller proxy

ScrollTrigger.batch() creates one trigger per target and groups their callbacks within a short interval, which suits staggered reveals for lists of cards. Batched callbacks receive the targets and the triggers, not the instance.

ScrollTrigger.scrollerProxy() lets the plugin work with a third-party smooth scroller. The skill says to call ScrollTrigger.update whenever that scroller moves.

Who the gsap-scrolltrigger skill is for

Best for

• Landing pages with pinned sections, parallax and scroll-scrubbed storytelling.
• Agents that leave markers: true in, nest triggers inside timelines or forget refresh after images load.
• Teams pairing it with find-animation-opportunities to decide where scroll motion belongs.

Not for

• Single tweens with no scroll link, which the core skill handles.
• Smoothness tuning in general, which the performance skill covers.
• React lifecycle details, which gsap-react covers.

How to install GSAP ScrollTrigger Skill: Scroll Animation Rules

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-scrolltrigger folder, which holds one SKILL.md.

2. Copy the skill folder

   Copy skills/gsap-scrolltrigger 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. Check the plugin import

   ScrollTrigger ships inside the gsap package. Import it from the gsap package path and register it once at app level before any trigger is created.

5. 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 for a pinned section with a scrubbed headline. The result should register ScrollTrigger once, set a scrub value without toggleActions, and not leave markers: true in.

Read the official instructions on GitHub

Key features

• Plugin registrationRegister ScrollTrigger once with gsap.registerPlugin() before use. Forgetting it is on the skill's Do Not list.
• Start and end positionsPositions read as trigger position then viewport position, for example top center, bottom 80% or a pixel number, with endTrigger when the end depends on another element.
• Scrub versus toggleActionsscrub: true ties progress directly to scroll and a number adds catch-up seconds. toggleActions takes four actions. If both are set, scrub wins.
• Pinningpin holds an element while active. The skill says to animate children, not the pinned element, and to leave pinSpacing on unless layout is handled elsewhere.
• Timeline plus ScrollTriggerPut the trigger on the timeline or a top-level tween. Putting it on a child tween inside a timeline is shown as the wrong pattern.
• Horizontal scroll with containerAnimationPin a full-viewport panel, tween its content with x or xPercent and ease: 'none', and drive nested triggers through containerAnimation.
• ScrollTrigger.batch()One trigger per target with grouped callbacks, plus interval and batchMax options. Do not pass trigger, scrub or snap in the vars.
• Scroller proxyscrollerProxy() overrides how scroll position is read and written for third-party smooth-scroll libraries, with pinType set to fixed or transform when pins misbehave.
• Refresh and cleanupCall refresh() after layout changes, set refreshPriority when creating triggers out of page order, and kill triggers when elements or pages go away.

Frequently asked questions