gsap-skills：给你的 AI 编程助手装上 GSAP 官方"驾照"

一句话核心结论：AI 写的 GSAP 代码经常是错的——GreenSock 官方出手了。gsap-skills 是一套官方技能文件，装到 Claude Code / Cursor 里，AI 生成的动画代码正确率从猜的变成可靠的。

---

一、What — gsap-skills 是什么

1.1 一句话定义

gsap-skills 是 GreenSock 官方维护的一套 AI Agent 技能文件。它不是 GSAP 库本身，而是教 AI 编程助手如何正确使用 GSAP 的结构化指南。

gsap-skills ≠ GSAP 动画库
gsap-skills = AI 的"GSAP 使用说明书"

1.2 解决的问题

你用 Claude Code 或 Cursor 写 GSAP 动画时，有没有遇到过：

❌ gsap.to('.box', { left: 100 })        // AI 用了 left 而不是 x（性能差）
❌ 忘记 registerPlugin(ScrollTrigger)     // AI 不知道要先注册
❌ new TimelineMax()                      // AI 用了 GSAP v2 的旧 API
❌ 在 React useEffect 里创建动画但不清理   // 内存泄漏
❌ 把 Flip.getState() 和 gsap.to() 的顺序写反

AI 模型的训练数据里 GSAP 的版本是混乱的——v2、v3、付费版、免费版混在一起。gsap-skills 给 AI 装了"最新版官方指南"。

1.3 包含的 8 个技能

技能文件	覆盖内容
gsap-core	核心 API：to()/from()/fromTo()、缓动、stagger、transform 别名
gsap-timeline	时间线编排：位置参数、标签、嵌套、播放控制
gsap-scrolltrigger	滚动驱动动画：start/end、scrub、pin、refresh、清理
gsap-plugins	插件全家桶：ScrollTo、Flip、Draggable、SplitText、ScrambleText、DrawSVG、MorphSVG 等
gsap-utils	工具函数：clamp、mapRange、random、snap、toArray、interpolate 等
gsap-react	React 最佳实践：useGSAP hook、gsap.context()、ref 模式、SSR
gsap-frameworks	Vue / Svelte 等框架的生命周期和选择器作用域
gsap-performance	性能指南：transform vs layout、will-change、批量更新、ScrollTrigger 优化

1.4 类比锚点

类比	说明
TypeScript 类型定义	.d.ts 让 IDE 知道 API → gsap-skills 让 AI Agent 知道正确用法
ESLint 规则	ESLint 告诉你不该写什么 → gsap-skills 告诉你该写什么
官方 SDK 文档	给人看的文档 → gsap-skills 是给 AI 看的"文档"
驾照考试	没驾照也能开车但容易出事 → 有 gsap-skills 的 AI 像持证上路

---

二、Why — 为什么需要 gsap-skills

2.1 背景：GSAP 已全面免费

Webflow 收购 GreenSock 后，所有插件全部免费——SplitText、MorphSVG、DrawSVG、Flip、ScrollSmoother 这些曾经收费的插件现在都从 gsap npm 包直接安装，无需会员、无需 token、商业可用。

这意味着更多开发者会开始用 GSAP，更多 AI Agent 会遇到 GSAP 相关问题——gsap-skills 的重要性也水涨船高。

2.2 痛点

不用 gsap-skills 时	用了 gsap-skills 时
AI 凭"记忆"写代码，经常用 v2 旧 API	AI 按官方指南生成 v3 最新 API
忘记 registerPlugin()	始终先注册再使用
React 里不清理动画 → 内存泄漏	自动用 gsap.context() 包裹并清理
Transform 用 left/top 而不是 x/y	始终用高性能 transform 别名
ScrollTrigger 忘记 refresh()	知道什么时候该 refresh
AI "幻觉"出不存在的方法名	方法名和 API 签名 100% 准确

2.3 设计哲学

gsap-skills 的设计原则很聪明：

1. 不是 README，是指令集——每个 skill 文件告诉 AI “遇到什么场景该怎么做”，不是罗列 API
2. 声明"不要做什么"比"要做什么"更重要——DONT use 'left' for positional animations 这类禁止规则是 AI 最需要的
3. 代码示例优先——每个规则都配有正确/错误对比示例
4. 框架感知——React 有专门的 useGSAP hook 指导，不跟 Vue 混在一起

---

三、How — 怎么用

3.1 安装（30 秒）

# 方式一：CLI 自动检测你的 Agent（推荐）
npx skills add https://github.com/greensock/gsap-skills

# 方式二：Claude Code 插件市场
/plugin marketplace add greensock/gsap-skills

# 方式三：手动复制
git clone https://github.com/greensock/gsap-skills.git
cp -r gsap-skills/skills/ ~/.claude/skills/

3.2 安装后 AI 行为变化

不用 skills，你问 AI： “帮我做一个卡片列表，滚入时逐个淡入上移”

AI 可能输出：

// ❌ 没有注册插件、用了 left、没有清理
gsap.to('.card', { left: 0, opacity: 1, duration: 0.5, delay: 0.1 })

用了 skills，AI 输出：

import { gsap } from 'gsap'
import { ScrollTrigger } from 'gsap/ScrollTrigger'
gsap.registerPlugin(ScrollTrigger)  // ✅ 先注册

// ✅ 用 x 而不是 left（触发 composite 层，不重排）
// ✅ 用 autoAlpha 而不是 opacity（自动处理 visibility）
// ✅ stagger 替代手动 delay 循环
// ✅ scrollTrigger 集成
gsap.from('.card', {
  x: 60,
  autoAlpha: 0,
  duration: 0.5,
  stagger: 0.1,
  scrollTrigger: {
    trigger: '.card-list',
    start: 'top 80%',
    toggleActions: 'play none none reverse',
  },
})

3.3 实战：用 AI + gsap-skills 做一个产品特性展示页

你跟 AI 说：

“做一个三列的特性卡片区，滚入时卡片从下方依次淡入，带弹性效果。用 React + GSAP。不要用 CSS animation。”

安装 gsap-skills 后的 AI 会输出：

import { useRef } from 'react'
import { gsap } from 'gsap'
import { ScrollTrigger } from 'gsap/ScrollTrigger'
import { useGSAP } from '@gsap/react'

gsap.registerPlugin(ScrollTrigger, useGSAP)

const features = [
  { title: '实时操控', desc: '10ms 响应延迟' },
  { title: '5G 远程', desc: '跨省操控无压力' },
  { title: 'AI 识别', desc: 'YOLO 实时检测' },
]

export function FeatureCards() {
  const containerRef = useRef(null)

  useGSAP(() => {
    gsap.from('.feature-card', {
      y: 80,
      autoAlpha: 0,
      duration: 0.6,
      stagger: 0.12,
      ease: 'back.out(1.7)',
      scrollTrigger: {
        trigger: containerRef.current,
        start: 'top 75%',
        toggleActions: 'play none none none',
      },
    })
  }, { scope: containerRef })

  return (
    <div ref={containerRef} className="grid grid-cols-3 gap-6">
      {features.map((f) => (
        <div key={f.title} className="feature-card rounded-xl bg-white p-6 shadow-lg">
          <h3 className="text-xl font-bold">{f.title}</h3>
          <p className="text-gray-500">{f.desc}</p>
        </div>
      ))}
    </div>
  )
}

3.4 常用的 ask AI 方式

你想做的	怎么跟 AI 说
元素淡入	“用 GSAP from 做入场动画，autoAlpha + y”
多步骤编排	“用 timeline，B 在 A 结束前 0.2s 开始”
滚动触发	“加 ScrollTrigger，元素进入视口时触发”
列表交错	“用 stagger，间隔 0.1s”
SVG 路径动画	“用 DrawSVG 插件画路径”
页面切换过渡	“用 Flip 插件做 layout transition”
React 中使用	“用 useGSAP hook，不是 useEffect”

---

四、When / Which — 什么场景用它，跟什么对比

4.1 场景矩阵

场景	不加 gsap-skills	加 gsap-skills
简单 gsap.to()	⚠️ 可能用错 transform 属性	✅ 自动用 x/y/autoAlpha
timeline 编排	⚠️ 可能不知道位置参数 '>' '+='	✅ 知道所有位置参数语法
ScrollTrigger	❌ 很大概率忘记 registerPlugin、refresh	✅ 完整的注册+配置+清理
React 项目	❌ useEffect 里写动画但不清理	✅ useGSAP + gsap.context()
复杂插件（Flip、DrawSVG）	❌ API 用法高度不确定	✅ 标准范例 + 禁止事项
性能敏感场景	❌ 用 width/left 触发重排	✅ 只用 transform + opacity

4.2 同类对比

方案	是什么	和 gsap-skills 的区别
GSAP 官方文档	给人看的 API 文档	给 AI 看的指令，带"禁止规则"
GSAP Cheatsheet	速查表	skills 是行为和场景导向
type definitions	@types/gsap	类型只告诉"参数叫什么"，不告诉"为什么不能那样做"
Cursor Rules	用户自定义规则	gsap-skills 是官方维护的，持续更新
.cursorrules 文件	通用项目规则	专注于 GSAP 这一个领域，更精确

4.3 要不要装？

你的情况	建议
偶尔写几个简单 GSAP 动画	⚠️ 不用也行，但装了更省心
项目中大量使用 GSAP	✅ 必装，正确率提升显著
用 React + GSAP	✅ 必须装，useGSAP 模式一般人不知道
用 ScrollTrigger 做复杂交互动效	✅ 必须装，API 细节太多
团队多人协作写动画	✅ 装到项目级 skill，保证产出一致性

---

五、Where — 后续怎么学

5.1 进阶路线

第 1 步   安装 gsap-skills → 用 AI 写几个基础动画试试效果
第 2 步   对比 AI 生成代码和官方文档 → 理解 AI 为什么那样写
第 3 步   学 timeline + ScrollTrigger → 让 AI 做复杂编排
第 4 步   在 React 项目中正确使用 → useGSAP + context
第 5 步   探索插件（Flip、DrawSVG、SplitText） → 打开新世界
第 6 步   看 AI 的"禁止规则"列表 → 反向理解性能陷阱

5.2 资源推荐

资源	链接	说明
gsap-skills 仓库	github.com/greensock/gsap-skills	官方仓库，star 9K+
GSAP 官方文档	gsap.com/docs	每个 API 有 CodePen 示例
GSAP 官方论坛	gsap.com/community	问题 24h 内必回
GSAP React 指南	gsap-skills 中的 gsap-react skill	React 最佳实践
Codrops GSAP 教程	tympanus.net/codrops	高质量实战项目

5.3 一句话收尾

GSAP v3 全部免费了，gsap-skills 让 AI 帮你写对的代码。装一个 skill 文件，AI 的 GSAP 编码水平从"猜"变成"确定性"。