GSAP Skills 新手教程

1这是什么

一句话：gsap-skills 是一个纯 Markdown 的「提示词包」，把 GSAP 官方认可的写法、陷阱和清理纪律整理成 8 份 Agent 可加载的技能文件。它不参与运行，只影响 AI 写代码时脑子里装了什么。

它明确不做什么

反向界定比正向描述更能消除误解。以下四件事它不负责：

2为什么需要它

GSAP 的 API 本身不难记。真正让人踩坑的，是几条反直觉的规矩，而它们散落在官方文档的 "Do Not" 段落里，AI 凭记忆生成时最容易被忽略。

在它出现之前，想让 Cursor 正确写 GSAP，通常只有三条歪路：

这个项目的核心洞察：把「必须遵守」和「绝对不能做」从长篇文档里提出来，转成短小、带触发词、可被 Agent 按需加载的独立技能。下面这几条是典型代表 —— 它们全部来自技能正文，而不是 README：

3核心流程

整条链路只有三步。关键认知：技能不是被「调用」的，是被「命中」的 —— Cursor 读你的自然语言，按每个技能 description 里的触发词自动决定加载哪一份。

4安装

Cursor 用户有三条路可走。推荐第一条 —— 它同时管好了后续更新。

路径 A：npx skills（推荐）

官方推荐的通用安装器，能自动识别你机器上装了哪些 Agent。全局装（跨项目长期可用）：

npx skills add https://github.com/greensock/gsap-skills -a cursor -g

只装到当前项目（跟着仓库走，可提交给团队）：

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

不指定 -a 时，CLI 会自动探测已安装的宿主。想装到特定宿主就显式声明，比如 -a cursor -a claude-code。

路径 B：Cursor 里的 Remote Rule

不碰命令行的话，打开 Cursor 设置：Settings → Rules → Add Rule → Remote Rule (GitHub)，填 greensock/gsap-skills 即可。这条路装进去的是规则（Rules），不是你手动管理的技能目录，更新由 Cursor 托管。

路径 C：手动 clone 后拷贝

完全掌控、离线可用，但要自己负责更新：

git clone https://github.com/greensock/gsap-skills.git /tmp/gsap-skills
mkdir -p ~/.cursor/skills
cp -R /tmp/gsap-skills/skills/gsap-* ~/.cursor/skills/

各宿主的技能目录对照

同一份技能，换个目录就是给别的 Agent 用。下面是官方列出的主要宿主：

5环境自检

装完先别急着提问，花 20 秒确认落盘正确。这一步能挡掉绝大多数「装了没反应」。

# 1. 技能目录是否存在，应该看到 8 个 gsap-* 目录
ls -1 ~/.cursor/skills/

# 2. 每个目录下是否都有 SKILL.md（这才是 Agent 真正读的文件）
ls ~/.cursor/skills/gsap-core/

# 3. 看一眼索引文件，确认技能和触发词都在
cat ~/.cursor/skills/llms.txt 2>/dev/null || echo "llms.txt 未随拷贝带过来（不影响使用）"

理想输出：8 个目录 gsap-core、gsap-timeline、gsap-scrolltrigger、gsap-plugins、gsap-utils、gsap-react、gsap-performance、gsap-frameworks，且每个里面都有 SKILL.md。

依赖清单

6第一次实战

从零到一个「Agent 按规范写出 ScrollTrigger」的完整闭环。命令可直接照抄。

# ① 装上技能（全局，一次到位）
npx skills add https://github.com/greensock/gsap-skills -a cursor -g

# ② 确认落盘
ls -1 ~/.cursor/skills/

# ③ 准备一个最小练手项目
mkdir -p ~/gsap-demo && cd ~/gsap-demo
npm init -y
npm install gsap

建一个 index.html 当靶子。注意下面这段是故意留白的 —— 我们要让 Cursor 来补动画，才能验证技能是否生效：

<!DOCTYPE html>
<html>
<head>
  <style>
    .card { width: 120px; height: 80px; background: #4d8bff; margin: 16px 0; border-radius: 10px; }
    .section { min-height: 150vh; }
  </style>
</head>
<body>
  <h1>GSAP 练手</h1>
  <div class="card">A</div>
  <div class="card">B</div>
  <div class="card">C</div>
  <section class="section"><div class="card">滚动我</div></section>
</body>
</html>

然后在项目目录里起 Cursor CLI，直接提问（用大白话，不用提 GSAP，更不用提技能名）：

cd ~/gsap-demo
cursor-agent

如果技能生效，Cursor 会自己去读 gsap-core（弹出/依次 → tween 与 stagger）和 gsap-scrolltrigger（滚动触发），产出的代码应该长这样：

// 1. 注册插件（每次应用一次即可）
gsap.registerPlugin(ScrollTrigger);

// 2. 依次弹出 —— 用 timeline 串，而不是堆 delay
const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.from(".card", { y: 40, autoAlpha: 0, stagger: 0.15 });

// 3. 滚动触发 —— 注意挂在 timeline 构造器上，不是挂在子 tween 上
const tl2 = gsap.timeline({
  scrollTrigger: {
    trigger: ".section",
    start: "top center",
    end: "bottom center",
    scrub: true
  }
});
tl2.to(".section .card", { rotation: 360 });

7产物结构：8 个技能各管什么

技能按「你问什么」切分，不按「GSAP 有什么」切分。这是它能被精准命中的原因。

仓库结构

gsap-skills/
  README.md
  AGENTS.md              # 给「编辑本仓库的 Agent」看的规则
  .claude-plugin/        # Claude Code 插件配置
  .cursor-plugin/        # Cursor 插件配置（plugin.json / marketplace.json）
  .github/               # Copilot 用的 instructions（含 react / scrolltrigger 分路径版）
  assets/                # logo 与图标
  skills/
    llms.txt             # 技能索引：名字 + 摘要 + 触发词
    gsap-core/           SKILL.md
    gsap-timeline/       SKILL.md
    gsap-scrolltrigger/  SKILL.md
    gsap-plugins/        SKILL.md
    gsap-utils/          SKILL.md
    gsap-react/          SKILL.md
    gsap-performance/    SKILL.md
    gsap-frameworks/     SKILL.md
  examples/              # 可直接跑的参考实现
    vanilla/  react/  vue/  nuxt/

8怎么用：触发词是关键

技能不是靠你点名调用的，是靠 description 里的触发词被自动命中的。所以用对的问法，效果差别很大。

9进阶用法

跑通基础之后，这四件事能让技能包的价值再上一层。

验证示例工程

git clone https://github.com/greensock/gsap-skills.git
cd gsap-skills/examples/react
npm install
npm run dev      # 打开后对着 useGSAP 的写法检查你的产出

# vanilla 示例注意：它用 ESM 从 CDN 加载，必须起本地服务器
npx serve examples/vanilla

10不止于此

名字叫 GSAP Skills，但它的适用范围远大于「给网页加个动画」。凡是时间和运动有关的前端活儿，都在射程内。

11体积、成本与性能

技能包全部内容不到 100 KB，而且是按需加载的 —— 只有命中的那 1~2 份会进上下文。

八份合计约 92.6 KB（含 llms.txt 索引约 95.7 KB）。按英文技术文档常见的 1 token ≈ 4 字符估算，全部塞进上下文约 2.3 万 token —— 但实际不会这样发生：Agent 先读 llms.txt 索引（3 KB）决定加载谁，正常一问只吃 5~20 KB。

值得单独说的：技能本身教的就是性能

gsap-performance 这份技能的内容，恰好是「怎么让动画不卡」。它要求的几条硬规矩：

12FAQ 与踩坑

下面每条都是可执行的解法，不是泛泛的提醒。

npm install gsap   # 就这一条，SplitText、MorphSVG 全都在里面

# 只装 core 和 timeline（-s 可多次传，'*' 表示全部）
npx skills add https://github.com/greensock/gsap-skills -a cursor -g -s gsap-core -s gsap-timeline

# 先看有哪些再决定
npx skills add https://github.com/greensock/gsap-skills -l

13许可与版权

两块版权要分开看：技能包本身和GSAP 库，但结论都很宽松。

14参考链接

按「用得上」排序，前两条是必备。