GSAP AI Skills: Dạy AI Agent Viết Animation Chuẩn

Nếu bạn đã từng nhờ một AI coding assistant viết GSAP animation và nhận về đoạn code thiếu cleanup, đặt ScrollTrigger sai chỗ, hoặc tệ hơn là hướng dẫn bạn mua Club GSAP membership trong khi tất cả plugin đã miễn phí từ lâu — thì bạn không cô đơn. Đây là vấn đề có hệ thống, không phải lỗi ngẫu nhiên.

AI coding assistant học từ dữ liệu training cũ. GSAP thay đổi khá nhiều sau khi Webflow mua lại GreenSock, và các model lớn vẫn đang nhớ những pattern từ năm 2022, 2023 — thời điểm mà SplitText và MorphSVG vẫn còn sau paywall. Kết quả là mỗi lần bạn hỏi về animation, AI có khả năng cao sẽ tạo ra code không chạy được, hoặc chạy được nhưng leak memory như cái rổ.

GreenSock giải quyết vấn đề này bằng cách tạo ra GSAP AI Skills — một repository chính thức chứa structured knowledge về GSAP, được đóng gói theo Agent Skills specification để tích hợp trực tiếp vào 40+ AI coding agent phổ biến. Đây không phải documentation thêm một lần nữa. Đây là cơ chế để AI thực sự hiểu GSAP đúng cách.

GSAP AI Skills Repository là gì?

Repository greensock/gsap-skills là collection chính thức của GreenSock, được xây dựng theo Agent Skills specification từ agentskills.io — một chuẩn mở cho phép đóng gói domain knowledge vào định dạng mà AI agent có thể đọc, index, và áp dụng khi generate code.

Điểm khác biệt lớn nhất so với việc nhét documentation vào system prompt thủ công: Agent Skills được thiết kế để AI agent tự động load đúng skill phù hợp với yêu cầu của người dùng, thay vì load toàn bộ mọi thứ một lúc. Điều này vừa giữ context window gọn, vừa đảm bảo AI có đủ context chuyên sâu khi cần.

Về độ phủ: repository này tương thích với Claude Code, Cursor, GitHub Copilot, Windsurf, OpenAI Codex, Google Antigravity, và tổng cộng hơn 40 AI coding agent. Cài đặt chỉ cần một lệnh:

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

CLI sẽ tự detect agent đang dùng và cấu hình vào đúng thư mục workspace. Không cần config thủ công. MIT licensed, do team GreenSock maintain.

Tám Specialized Skills, Không Phải Một Monolith

Quyết định kiến trúc quan trọng nhất của repository này là chia nhỏ knowledge thành 8 skill riêng biệt thay vì nhét tất cả vào một file khổng lồ:

• gsap-core: API cơ bản, gsap.to(), gsap.from(), easing, control methods
• gsap-timeline: sequencing, labels, callback, relative positioning
• gsap-scrolltrigger: scroll-based animation, pin, scrub, markers
• gsap-plugins: toàn bộ plugin ecosystem bao gồm Flip, Draggable, SplitText, MorphSVG
• gsap-utils: helper functions, utility methods
• gsap-react: useGSAP hook, gsap.context(), scoped selectors
• gsap-frameworks: Vue 3, Nuxt 4, Svelte integration
• gsap-performance: optimization patterns, will-change, force3D, ticker management

Granular design này có lý do thực tế: khi bạn hỏi “làm scroll animation với parallax effect”, agent chỉ cần load gsap-scrolltrigger thay vì toàn bộ 8 skill. Context window không bị lãng phí vào những thông tin không liên quan. Khi cần cross-reference — ví dụ ScrollTrigger trong một React component — các skill sẽ tự reference lẫn nhau.

GSAP ecosystem có hơn 20 plugin. Trước đây, AI thường chỉ biết 3-4 cái phổ biến nhất và mô tả sai setup cho phần còn lại. Với gsap-plugins skill, toàn bộ ecosystem được document đúng cách, từ Flip (layout animation) đến MorphSVG (shape morphing) đến CustomEase.

Framework-Specific Guidance: React, Vue, Svelte, Nuxt

Đây là phần mà nhiều developer sẽ thấy ngay giá trị. GSAP trong vanilla JS khá straightforward, nhưng khi kết hợp với React hoặc Vue, có vô số cách để viết code đúng về mặt chức năng nhưng sai về mặt memory management.

React

Pattern đúng trong React là dùng useGSAP hook từ @gsap/react, không phải useEffect thuần. Lý do: useGSAP tự động handle cleanup thông qua gsap.context(), đảm bảo tất cả animation được kill khi component unmount.

import { useGSAP } from "@gsap/react";
import { useRef } from "react";
import gsap from "gsap";

function AnimatedBox() {
  const container = useRef(null);

  useGSAP(() => {
    gsap.to(".box", { x: 200, duration: 1 });
  }, { scope: container });

  return (
    <div ref={container}>
      <div className="box"></div>
    </div>
  );
}

AI không dùng GSAP AI Skills thường generate useEffect với selector string global như gsap.to(".box") không có scope — nghĩa là animation có thể target nhầm element ở component khác. gsap-react skill document rõ cả pattern đúng lẫn pattern sai cần tránh.

Vue 3 và Nuxt 4

Vue 3 Composition API cần cleanup trong onUnmounted. Nuxt 4 phức tạp hơn vì có SSR — plugin cần được lazy load để tránh lỗi khi render trên server. gsap-frameworks skill cover cả hai case này với composable pattern cụ thể cho Nuxt 4.

Svelte

Svelte có lifecycle riêng, và GSAP animation cần được cleanup trong onDestroy. Đây là chi tiết mà nhiều tutorial bỏ qua, dẫn đến stale references khi component bị destroy rồi re-create.

Repository còn cung cấp working example projects trong thư mục examples/ — mỗi framework có project riêng chạy được với Vite hoặc Nuxt 4. Không phải pseudo-code, là code thật có thể clone về chạy ngay.

Anti-Pattern Documentation: Tính Năng Quan Trọng Nhất

Nếu phải chọn một điều làm cho GSAP AI Skills khác biệt so với documentation thông thường, đó là các section “Do Not” trong mỗi skill.

Thay vì chỉ document cách làm đúng, mỗi skill explicitly list ra những pattern mà AI model thường sinh ra nhưng sai. Đây là cách tiếp cận thông minh hơn nhiều so với positive examples đơn thuần — vì AI sẽ học cả hai chiều.

Ví dụ cụ thể từ gsap-scrolltrigger skill:

Do Not: Đặt ScrollTrigger trực tiếp trên một child tween bên trong timeline. ScrollTrigger phải được đặt trên timeline, không phải tween con.

Code sai mà AI hay generate:

// SAI - ScrollTrigger trên child tween
const tl = gsap.timeline();
tl.to(".box", {
  x: 200,
  scrollTrigger: { trigger: ".box", start: "top center" } // SAI
});
tl.to(".circle", { y: 100 });

Code đúng:

// ĐÚNG - ScrollTrigger trên timeline
const tl = gsap.timeline({
  scrollTrigger: { trigger: ".box", start: "top center" }
});
tl.to(".box", { x: 200 });
tl.to(".circle", { y: 100 });

Sự khác biệt nhỏ nhưng impact lớn — code sai có thể chạy nhưng timing sẽ lệch hoặc scrub animation không hoạt động đúng. Chỉ developer có kinh nghiệm mới nhận ra ngay, còn người mới sẽ mất hàng giờ debug.

Anti-pattern documentation còn cover những lỗi khác như dùng selector string không có scope trong React, quên ScrollTrigger.refresh() sau khi DOM thay đổi dynamic, và dùng gsap.set() sai thời điểm trong lifecycle.

Trigger-Based Skill Discovery và Multi-Agent Installation

Cơ chế discovery của Agent Skills specification hoạt động qua semantic trigger terms — mỗi skill khai báo danh sách keyword liên quan. Khi bạn nhập prompt vào AI agent, system sẽ match intent với trigger terms và tự load skill phù hợp.

Ví dụ thực tế:

• Prompt “animate text letter by letter” → trigger “text split”, “SplitText” → load gsap-plugins
• Prompt “parallax on scroll” → trigger “scroll animation”, “parallax” → load gsap-scrolltrigger
• Prompt “drag and drop with snap” → trigger “drag interaction”, “Draggable” → load gsap-plugins
• Prompt “animate in React component” → load cả gsap-react lẫn gsap-core

Developer không cần biết tên skill là gì. Describe yêu cầu bằng ngôn ngữ tự nhiên, agent tự lo phần còn lại.

Về installation: npx skills add CLI tự detect agent đang active trong workspace. Nếu dùng Claude Code, skills được cài vào .claude-plugin/. Cursor thì .cursor-plugin/. GitHub Copilot thì .github/copilot-instructions.md kết hợp với path-specific instructions trong .github/instructions/. Không cần đọc hướng dẫn riêng cho từng tool.

Câu Chuyện Licensing: Hậu Webflow Acquisition

Một trong những vấn đề thực tế nhất với AI-generated GSAP code trong 2025-2026 là thông tin licensing cũ. Trước khi Webflow mua lại GreenSock, SplitText, MorphSVG, Flip và nhiều plugin khác nằm sau Club GSAP paywall — bạn cần trả phí membership và dùng private npm registry.

Sau acquisition, toàn bộ plugin được mở miễn phí thông qua package gsap công khai trên npm. Không cần auth token, không cần private registry, không cần Club GSAP membership. Một lệnh đơn giản:

npm install gsap

Thế nhưng nhiều AI model vẫn generate setup instructions kiểu cũ, hướng dẫn developer cấu hình .npmrc với auth token hoặc dùng URL registry riêng. Điều này gây friction không cần thiết — developer mới không biết tại sao setup không chạy, developer cũ thấy bực khi phải giải thích cho AI mỗi lần.

GSAP AI Skills giải quyết bằng cách document rõ ràng trong tất cả relevant skills: licensing đã thay đổi, tất cả plugin hiện tại là free, đây là cách import đúng. AI agent sử dụng skill này sẽ không bao giờ hướng dẫn bạn setup Club GSAP membership nữa.

Mô Hình Này Có Ý Nghĩa Gì Với Open-Source Rộng Hơn?

GSAP AI Skills thực ra là proof-of-concept cho một vấn đề lớn hơn: làm thế nào để open-source project đảm bảo AI coding assistant hiểu đúng library của họ khi model training data luôn bị lag so với hiện tại?

Documentation truyền thống không đủ — AI đọc documentation khi training, không phải real-time. Fine-tuning tốn kém và không scalable. RAG có thể giúp nhưng cần infrastructure riêng. Agent Skills specification cung cấp một con đường thứ ba: đóng gói expert knowledge vào định dạng chuẩn, cho phép developer install trực tiếp vào workflow của họ.

Nếu mô hình này lan rộng — và có lý do để tin là sẽ vậy khi specification được support bởi ngày càng nhiều agent — thì developer advocate và maintainer của các library lớn sẽ cần nghĩ đến việc publish Agent Skills cùng với documentation thông thường.

Kết Luận

GSAP AI Skills không giải quyết vấn đề “AI viết code” theo nghĩa rộng. Nó giải quyết một vấn đề cụ thể, thực tế, và đau đớn: AI coding assistant tạo ra GSAP code sai, và developer phải mất thời gian debug những lỗi mà lẽ ra không nên tồn tại.

Tám skill được thiết kế granular để giữ context window hiệu quả. Anti-pattern sections dạy AI tránh đúng những lỗi nó hay mắc nhất. Framework-specific guidance cover React, Vue, Nuxt, Svelte với lifecycle handling đúng. Licensing information được cập nhật để không ai phải setup Club GSAP membership năm 2026 nữa.

Nếu bạn đang dùng Claude Code, Cursor, Copilot, hay bất kỳ agent nào trong danh sách 40+ được support, việc cài đặt GSAP AI Skills mất chưa đến một phút và trả về lợi ích ngay từ prompt đầu tiên. Với frontend developer làm animation work thường xuyên, đây không phải nice-to-have — đây là upgrade thực sự cho workflow hàng ngày.

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

Chạy lệnh này, rồi thử hỏi AI về ScrollTrigger animation trong React. So sánh kết quả với trước đây. Sự khác biệt sẽ rõ ràng ngay.