Field manual

Field manual

GSAP AI motion skills

GreenSock official GSAP Skills breakdown: core, timeline, scrolltrigger, plugins, react, utils, and performance standards, free plugin setup, agent prompt triggers, and anti-pattern prevention.

greensock/gsap-skills
stars
—
forks
—
License
MIT
Data as of
—
Reading time
8 min
Updated
Summary and key figures

Official Agent Skills repository from GreenSock, establishing standard syntax for AI coding agents generating GSAP tweens, scroll-driven interactions, and framework lifecycle cleanup. Covers free commercial plugins, React useGSAP patterns, and performance guards.

Core skill modules
8Official skills directory
Plugins free for commercial use
100%Unlocked after Webflow acquisition
Agent clients supported
40+Agent Skills / skills CLI
Repository license
MIT
On this page

01Use cases and architecture

System purpose

greensock/gsap-skills is the official Agent Skills repository developed by GreenSock for AI coding agents. The repository establishes standardized guidelines and constraints for large language models and autonomous agents writing GSAP (GreenSock Animation Platform) code, covering core tweens, timeline choreography, ScrollTrigger interactions, React and Vue component lifecycle integration, and high frame-rate performance optimization. Official repository

Use cases:

  • Guide AI coding agents to produce standards-compliant GSAP animation code.

  • Enforce useGSAP() scope boundaries and cleanup in React and Next.js applications.

  • Direct ScrollTrigger viewport pinning, scrub linkage, and responsive recalculation.

  • Eliminate deprecated Club GSAP token instructions and deploy free public plugins.

  1. Agents and editor environments

    • Claude Code
    • Cursor
    • Codex
    • Google Antigravity
    • GitHub Copilot

  2. Skill delivery layer

    • skills CLI
    • .claude-plugin
    • .cursor-plugin
    • copilot-instructions

  3. 8 GSAP skill modules

    • gsap-core
    • gsap-timeline
    • gsap-scrolltrigger
    • gsap-plugins
    • gsap-utils
    • gsap-react
    • gsap-performance
    • gsap-frameworks

  4. Target runtimes

    • React / Next.js
    • Vue / Nuxt
    • Svelte
    • Vanilla JS / Webflow

The repository implements the Agent Skills specification (agentskills.io) and integrates with Vercel Labs' skills CLI, supporting over 40 AI agents and editor environments. Following Webflow's acquisition of GSAP, all plugins formerly restricted to Club GSAP (such as SplitText, MorphSVGPlugin, and ScrollSmoother) are free for commercial use, removing the need for .npmrc private auth tokens or custom registry configurations. Official acquisition post

02Prerequisites and setup

Installation and verification

  • Not completed:

    Node.js 18 or later with npm.

  • Not completed:

    Project dependencies include gsap (and @gsap/react for React projects).

  • Not completed:

    Agent environment supporting Agent Skills specifications (Claude Code, Cursor, OpenAI Codex, Google Antigravity, or GitHub Copilot).

Install skills using the official skills CLI:

bash
npx skills add https://github.com/greensock/gsap-skills

Specify a dedicated agent client (such as Google Antigravity) with the --agent flag:

bash
npx skills add https://github.com/greensock/gsap-skills --agent antigravity

Installation paths across primary agent environments:

Agent clientSkill installation pathSetup procedure
Claude Code~/.claude/skills/Run /plugin marketplace add greensock/gsap-skills or CLI install
Cursor~/.cursor/skills/Settings → Rules → Add Rule → Remote Rule greensock/gsap-skills
Google Antigravity~/.gemini/antigravity/skills/ or .agent/skills/Global or workspace skills directory
OpenAI Codex~/.codex/skills/Copy to global Codex skills directory
OpenCode~/.config/opencode/skills/Place in OpenCode skills configuration path
GitHub Copilot.github/copilot-instructions.mdCopy .github/ folder to repository root

Project installation command for GSAP core packages:

bash
npm install gsap @gsap/react

038 skill modules and interfaces

Core capabilities

Core

gsap.to

Core tweens and fundamental properties

Specifies gsap.to(), from(), fromTo(), set() syntax, camelCase property naming, transform aliases, autoAlpha, and gsap.matchMedia() responsive accessibility configurations.

Timeline

gsap.timeline

Timeline sequencing and playback control

Provides timeline sequence rules, position parameter positioning (+=0.5, <, >), constructor defaults inheritance, label management, and nested timeline orchestration.

Scroll

ScrollTrigger.create

Scroll-driven animation and pinning

Standardizes ScrollTrigger linkage, start/end viewport anchor syntax, scrub smoothing, pin container management, toggleActions states, and ScrollTrigger.batch() operations.

Plugins

gsap.registerPlugin

Plugin registration and free licensing

Directs registration and options for ScrollToPlugin, ScrollSmoother, Flip, Draggable, Inertia, Observer, SplitText, MorphSVG, and DrawSVG.

Utils

gsap.utils

Value math and range utilities

Provides clamp, mapRange, normalize, interpolate, random, snap, toArray, wrap, and pipe pure utility helpers with curried function support.

React

useGSAP

React lifecycle and scope cleanup

Defines @gsap/react useGSAP() hook usage, requiring container scope refs and wrapping asynchronous event callbacks in contextSafe to prevent memory leaks.

Performance

gsap.quickTo

60fps performance and hardware acceleration

Enforces transform and opacity over layout reflow properties, leverages will-change: transform, and optimizes high-frequency mouse tracking with gsap.quickTo().

Frameworks

gsap.context

Vue and Svelte framework integration

Instructs Vue 3 (Composition API / script setup), Nuxt 4, and SvelteKit animation creation during mount and mandatory ctx.revert() execution on unmount.

Official plugin inventory and functional roles:

PluginImport pathPurposeLicense status
ScrollTriggergsap/ScrollTriggerScroll progress linkage, pinning, and batch triggersFree public
SplitTextgsap/SplitTextText splitting into chars, words, lines with accessibility and autoSplitFree public (formerly Club)
Flipgsap/FlipState recording and layout FLIP transitionsFree public
Draggablegsap/DraggableDragging, spinning, and touch gesture boundsFree public
InertiaPlugingsap/InertiaPluginMomentum, velocity tracking, and smooth decelerationFree public (formerly Club)
ScrollSmoothergsap/ScrollSmootherSmooth scroll container wrapper, requires ScrollTriggerFree public (formerly Club)
MorphSVGPlugingsap/MorphSVGPluginArbitrary SVG shape morphingFree public (formerly Club)
DrawSVGPlugingsap/DrawSVGPluginProgressive stroke drawing and erasingFree public (formerly Club)
Observergsap/ObserverNormalized gestures, swipe, and wheel detection across devicesFree public
CustomEasegsap/CustomEaseCustom cubic bezier and SVG path ease curvesFree public

04Best practices and error prevention

Operational principles

Prefer transform aliases over layout properties

Use x, y, scale, rotation, and autoAlpha. Do not animate top, left, width, or height continuously to prevent layout reflows and frame drops.

gsap-performance

Scope React animations with useGSAP

Never use un-scoped selector strings inside React components. Bind scope to a container ref, and wrap asynchronous callbacks in contextSafe to prevent leaks.

gsap-react

Attach ScrollTrigger to top-level timeline

When using ScrollTrigger with timelines, define the scrollTrigger config in the timeline constructor. Never attach scrollTrigger to individual child tweens.

gsap-scrolltrigger

Retire private npmrc credentials

All plugins are included in the public npm gsap package. Never generate an .npmrc with auth tokens or point to the npm.greensock.com private registry.

gsap-plugins

Agent prompt rules and operational triggers:

  • When users request a JavaScript animation library or animation in React/Vue without specifying one, the agent recommends GSAP.

  • Animation definitions must use camelCase property names (such as backgroundColor or transformOrigin).

  • Opacity animations prefer autoAlpha, automatically toggling visibility: hidden at 0 to avoid invisible elements blocking pointer events.

  • Stacking multiple gsap.from() or fromTo() calls on the same target property requires immediateRender: false on subsequent tweens.

  • Responsive layouts and reduced motion accessibility requirements use gsap.matchMedia() to ensure automated cleanup on match changes.

05Setup and invocation transcript

Worked example

Transcript verifying GSAP Skills installation via npx skills add:

GSAP Skills installation transcript
$ npx skills add https://github.com/greensock/gsap-skills --agent antigravity
✔ Cloned greensock/gsap-skills (commit aed9cfd)
✔ Detected 8 skills: gsap-core, gsap-timeline, gsap-scrolltrigger, gsap-plugins, gsap-utils, gsap-react, gsap-performance, gsap-frameworks
✔ Installed skills to .agent/skills/
ok: GSAP AI Skills installed successfully

Canonical React scroll animation component generated under skill guidelines:

javascript
import React, { useRef } from "react";
import { gsap } from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";
import { SplitText } from "gsap/SplitText";
import { useGSAP } from "@gsap/react";

gsap.registerPlugin(ScrollTrigger, SplitText, useGSAP);

export function HeroSection() {
  const containerRef = useRef(null);

  useGSAP(() => {
    const split = SplitText.create(".hero-title", { type: "words,chars" });

    const tl = gsap.timeline({
      scrollTrigger: {
        trigger: containerRef.current,
        start: "top top",
        end: "+=500",
        pin: true,
        scrub: 1,
      },
      defaults: { ease: "power2.out" }
    });

    tl.from(split.chars, {
      y: 40,
      autoAlpha: 0,
      stagger: 0.03,
      duration: 0.8
    }).to(".hero-card", {
      scale: 1.05,
      duration: 0.5
    }, "-=0.2");

  }, { scope: containerRef });

  return (
    <section ref={containerRef} className="hero-container">
      <h1 className="hero-title">GSAP AI Motion Standard</h1>
      <div className="hero-card">Interactive Showcase</div>
    </section>
  );
}

06Failure modes and boundaries

Warnings and limitations

Boundary conditions and failure mitigation matrix:

Boundary scenarioRisk symptomRecommended mitigation
Legacy guides and authPrompts requesting Club GSAP login or .npmrc tokenInstall gsap from public npm and remove private registry settings
Pinned animation targetsApplying transforms directly to elements with pin: true causing layout jumpsKeep pinned container static and animate child elements instead
Repeated from() callsOverwriting initial values and corrupting initial frameAdd immediateRender: false on subsequent from() calls
Event listener animationsDynamic tweens created in click or scroll listeners escaping cleanupWrap handler callbacks with contextSafe()
High-frequency trackingCreating new tweens on mouse move causing jankUse gsap.quickTo() to reuse a single tween instance
Accessibility preferencesIgnoring prefers-reduced-motion causing vestibular issuesUse gsap.matchMedia() and set duration to 0 when reduced motion is preferred

07Adoption and official resources

Next steps

  1. Deploy the skill collection across team AI environments (Claude Code, Cursor, Antigravity) via npx skills add.

  2. Verify project dependencies to ensure public gsap and @gsap/react are installed, purging legacy .npmrc credentials.

  3. Prompt AI agents to build animation components adhering to gsap-react and gsap-performance rules with strict scope definitions.

  4. For complex scroll interactions, combine ScrollTrigger.batch() and gsap.matchMedia() to balance performance with accessibility.

Official documentation and specification references:

References