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 最佳实践：useGSAPhook、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 这些曾经收费的插件现在都从gsapnpm 包直接安装，无需会员、无需 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 的设计原则很聪明：
- 不是 README，是指令集——每个 skill 文件告诉 AI “遇到什么场景该怎么做”，不是罗列 API
- 声明"不要做什么"比"要做什么"更重要——
DONT use 'left' for positional animations这类禁止规则是 AI 最需要的 - 代码示例优先——每个规则都配有正确/错误对比示例
- 框架感知——React 有专门的
useGSAPhook 指导，不跟 Vue 混在一起
三、How — 怎么用
3.1 安装（30 秒）
# 方式一：CLI 自动检测你的 Agent（推荐）npx skillsaddhttps://github.com/greensock/gsap-skills# 方式二：Claude Code 插件市场/plugin marketplaceaddgreensock/gsap-skills# 方式三：手动复制gitclone https://github.com/greensock/gsap-skills.gitcp-rgsap-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 编码水平从"猜"变成"确定性"。
