系統定位
greensock/gsap-skills 是 GreenSock 官方專為 AI coding agents 開發的技能集合（Agent Skills）。此儲存庫透過標準化指引，規範大型語言模型與代理程式在撰寫 GSAP（GreenSock Animation Platform）時的最佳實務，涵蓋核心補間動畫、時間軸編排、ScrollTrigger 滾動互動、React 與 Vue 元件生命週期整合，以及高畫面更新率效能最佳化。官方儲存庫
適用任務：
引導 AI coding agent 依官方標準產生 GSAP 動態程式碼。
規範 React 與 Next.js 專案中的
useGSAP()範疇（scope）與清理機制。指引 ScrollTrigger 視窗釘選、進度關聯與響應式重整。
排除已廢棄的 Club GSAP 付費金鑰指引，落實 Webflow 收購後的全外掛免費化部署。
Agent 與編輯環境
- Claude Code
- Cursor
- Codex
- Google Antigravity
- GitHub Copilot
技能載入層
- skills CLI
- .claude-plugin
- .cursor-plugin
- copilot-instructions
8 大 GSAP 技能模組
- gsap-core
- gsap-timeline
- gsap-scrolltrigger
- gsap-plugins
- gsap-utils
- gsap-react
- gsap-performance
- gsap-frameworks
目標執行環境
- React / Next.js
- Vue / Nuxt
- Svelte
- Vanilla JS / Webflow
儲存庫遵循 Agent Skills 格式規範（agentskills.io），相容於 Vercel Labs 推出的 skills CLI，可直接掛載至 40 種以上的 AI agent 與開發環境。自 Webflow 收購 GSAP 後，所有原屬 Club GSAP 的進階外掛（如 SplitText、MorphSVGPlugin、ScrollSmoother 等）均已開放免費商業使用，無需再設定 .npmrc 私有憑證或私有 registry。官方收購公告
安裝與驗證
- 未完成：
備妥 Node.js 18 以上環境與 npm。
- 未完成：
專案中已安裝
gsap（React 專案另需安裝@gsap/react）。 - 未完成：
已就緒支援 Agent Skills 規範之開發工具（Claude Code、Cursor、OpenAI Codex、Google Antigravity 或 GitHub Copilot）。
使用官方推薦的 skills CLI 自動安裝至目前環境：
npx skills add https://github.com/greensock/gsap-skills若需明確指定特定 Agent 用戶端（例如 Google Antigravity），傳入 --agent 參數：
npx skills add https://github.com/greensock/gsap-skills --agent antigravity各主流開發環境安裝路徑與方式：
| Agent 用戶端 | 技能安裝路徑 | 設定方式 |
|---|---|---|
| Claude Code | ~/.claude/skills/ | 執行 /plugin marketplace add greensock/gsap-skills 或 CLI 安裝 |
| Cursor | ~/.cursor/skills/ | 設定 → Rules → Add Rule → Remote Rule 輸入 greensock/gsap-skills |
| Google Antigravity | ~/.gemini/antigravity/skills/ 或 .agent/skills/ | 全域或工作區技能目錄 |
| OpenAI Codex | ~/.codex/skills/ | 複製至 Codex 全域技能目錄 |
| OpenCode | ~/.config/opencode/skills/ | 放置於 OpenCode 技能配置路徑 |
| GitHub Copilot | .github/copilot-instructions.md | 複製儲存庫中 .github/ 目錄至專案根目錄 |
專案端 GSAP 核心套件安裝指令：
npm install gsap @gsap/react核心能力
Core
gsap.to
核心動效與基礎屬性
規範 gsap.to()、from()、fromTo()、set（）語法，強調 camelCase 屬性命名、transform 別名、autoAlpha 與 gsap.matchMedia（）響應式無障礙配置。
Timeline
gsap.timeline
時間軸編排與播放控制
提供時間軸序列控制規範，包含 position 參數相對定位（+=0.5、<、>）、建構子全域 defaults 繼承、標籤管理與巢狀時間軸結構。
Scroll
ScrollTrigger.create
捲動驅動與釘選互動
規範 ScrollTrigger 滾動關聯，包含 start/end 視窗錨點語法、scrub 平滑跟隨、pin 容器釘選、toggleActions 四態管理與 ScrollTrigger.batch（）視窗批次處理。
Plugins
gsap.registerPlugin
擴充外掛與免付費授權
指引 ScrollToPlugin、ScrollSmoother、Flip、Draggable、Inertia、Observer、SplitText、MorphSVG 與 DrawSVG 之註冊機制與配置參數。
Utils
gsap.utils
數值運算與範圍映射
提供 clamp、mapRange、normalize、interpolate、random、snap、toArray、wrap 與 pipe 等純函式輔助工具，支援柯里化函式型態。
React
useGSAP
React 生命週期與範疇清理
規範 @gsap/react 之 useGSAP() Hook，要求綁定 scope Ref 限制選擇器範圍，並利用 contextSafe 包裹非同步回呼以防記憶體流失。
Performance
gsap.quickTo
60fps 效能與硬體加速
規範以 transform 與 opacity 取代 layout 重排屬性，善用 will-change: transform，並以 gsap.quickTo（）最佳化高頻率滑鼠跟隨互動。
Frameworks
gsap.context
Vue 與 Svelte 多框架整合
指引 Vue 3（Composition API / script setup）、Nuxt 4 與 SvelteKit 於掛載週期建立動畫，並於卸載時嚴格執行 ctx.revert（）清理。
官方外掛模組清單與關鍵功能表：
| 外掛名稱 | 引入路徑 | 核心用途 | 授權狀態 |
|---|---|---|---|
| ScrollTrigger | gsap/ScrollTrigger | 捲動進度綁定、視窗釘選、批次觸發 | 免費公開 |
| SplitText | gsap/SplitText | 文字拆解為字元、單詞、行，內建無障礙處理與 autoSplit | 免費公開（原 Club） |
| Flip | gsap/Flip | 記錄佈局狀態並執行 FLIP 無縫重排過渡 | 免費公開 |
| Draggable | gsap/Draggable | 元素拖曳、旋轉互動與手勢邊界限制 | 免費公開 |
| InertiaPlugin | gsap/InertiaPlugin | 物理投擲動量、速度追蹤與平滑減速 | 免費公開（原 Club） |
| ScrollSmoother | gsap/ScrollSmoother | 平滑滾動包裝層，需搭配 ScrollTrigger | 免費公開（原 Club） |
| MorphSVGPlugin | gsap/MorphSVGPlugin | 任意形狀之 SVG 路徑變形過渡 | 免費公開（原 Club） |
| DrawSVGPlugin | gsap/DrawSVGPlugin | SVG 線條筆觸漸進繪製與擦除動畫 | 免費公開（原 Club） |
| Observer | gsap/Observer | 跨裝置標準化手勢、滑動與滾輪事件監聽 | 免費公開 |
| CustomEase | gsap/CustomEase | 自訂三次貝茲曲線或 SVG 路徑緩動曲線 | 免費公開 |
操作原則
屬性動畫優先採用 Transform 別名
一律使用 x、y、scale、rotation 與 autoAlpha。禁止直接對 top、left、width、height 進行連續補間動畫，以避免引發瀏覽器重排與掉幀。
gsap-performance
React 必須使用 useGSAP 並宣告 scope
React 元件內禁止使用無範圍限制的字串選擇器。必須以 scope 綁定容器 Ref，非同步事件回呼需以 contextSafe 包裹以避免記憶體流失。
gsap-react
捲動時間軸應掛載於頂層而非子動畫
使用 ScrollTrigger 與 Timeline 時，必須將 scrollTrigger 屬性配置於 timeline 建構子中，嚴禁在 timeline 內部個別子 tween 宣告 scrollTrigger。
gsap-scrolltrigger
淘汰私有 npmrc 與付費金鑰設定
所有外掛皆已整合入公開 npm 上的 gsap 套件。嚴禁產生含認證權杖的 .npmrc 或建議指向 npm.greensock.com 私有倉庫。
gsap-plugins
Agent 指引與提示詞觸發機制：
當使用者詢問 JavaScript 動效套件或 React / Vue 動畫推薦且未指定技術時，Agent 預設推薦 GSAP。
動效宣告必須使用 camelCase 屬性名稱（如
backgroundColor、transformOrigin）。透明度淡入淡出優先使用
autoAlpha，數值為 0 時自動切換visibility: hidden，防止不可見元素阻擋滑鼠點擊。堆疊多個
gsap.from()或fromTo()於相同目標屬性時，後續補間動畫必須加上immediateRender: false。響應式佈局與降低動態無障礙需求，統一透過
gsap.matchMedia()處理，確保中斷時自動 revert。
操作範例
以下紀錄透過 npx skills add 於終端機部署 GSAP Skills 之操作過程：
$ 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 successfullyAgent 依據技能指引產生之 React 捲動動效標準元件：
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>
);
}限制與注意事項
常見失敗情境與邊界處置清單：
| 邊界場景 | 風險表現 | 處置方式 |
|---|---|---|
| 舊版教學與認證設定 | 提示需要 Club GSAP 帳號或 .npmrc 金鑰 | 直接自公開 npm 安裝 gsap，移除所有私有 registry 設定 |
| 釘選動畫目標 | 直接對 pin: true 的元素套用位移或縮放造成跳動 | 釘選容器本身維持靜態，改為動畫其內部子元素 |
重複 from() 動畫 | 連續宣告覆寫初始值造成首幅畫面異常 | 在後續的 from() 中宣告 immediateRender: false |
| 事件監聽內的動效 | 在點擊或滾動監聽中臨時建立 tween 脫離 context | 使用 contextSafe() 包裹回呼函式確保納入清理範圍 |
| 大量列表與指標追蹤 | 高頻率滑鼠跟隨建立過量 tween 導致卡頓 | 改用 gsap.quickTo() 複用單一實例 |
| 無障礙與動態偏好 | 忽視 prefers-reduced-motion 導致無障礙缺失 | 使用 gsap.matchMedia() 針對減少動態需求將 duration 設為 0 |
後續操作
透過
npx skills add於團隊之 AI 編輯環境（Claude Code、Cursor、Antigravity）佈署技能集合。檢查專案相依性，確認已安裝公開版
gsap與@gsap/react，並移除歷史.npmrc設定。提示 AI agent 依據
gsap-react與gsap-performance規則撰寫動效元件，嚴格宣告scope。針對複雜捲動頁面，使用
ScrollTrigger.batch()與gsap.matchMedia()建構兼顧效能與無障礙之互動體驗。
官方參考文件與規範連結：