1仕組みと動作原理
プラグインを第一級の主題として扱い、まず「登録」による前提条件を確立した上で、設定面（trigger/start/end/scrub/pin…）ごとに20項目以上のリファレンステーブルを提示します。
skills/gsap-scrolltrigger/SKILL.md
ScrollTrigger is a plugin. After loading the script, register it once:
機能が実現できる理由: ScrollTrigger はコアエンジンの一部ではないため、先に gsap.registerPlugin(ScrollTrigger) を実行しないと tween/timeline に scrollTrigger 設定を適用できません。本スキルではこの手順を冒頭に配置し、モデルが scrollTrigger 設定を直接記述してサイレントに失敗するのを防止します。
start/end の文字列構文を「トリガー点 vs ビューポート点」の座標モデルとして解説し、clamp()・相対値・関数の3つの発展形を提示します。
skills/gsap-scrolltrigger/SKILL.md
**start** / **end**: viewport position vs. trigger position. Format `"triggerPosition viewportPosition"`.
ここで行われていること: "top center" のような短縮構文を推論可能なモデル（要素のどの位置がビューポートのどの位置と重なるか）に落とし込むことで、モデルが用例を暗記するのではなく、有効な組み合わせ（"bottom 80%"、clamp(top bottom)、"+=300"、"max"）を自律生成できるようにします。
batch() により、複数の ScrollTrigger と時間枠を組み合わせた集約コールバックを提供し、IntersectionObserver の手書きバッチ処理を代替して、今回のターンでビューポートに入った全要素を一度に渡します。
skills/gsap-scrolltrigger/SKILL.md
**ScrollTrigger.batch(triggers, vars)** creates one ScrollTrigger per target and **batches** their callbacks
重要な詳細も明記: バッチコールバックのシグネチャは通常の ST コールバックの単一インスタンスではなく2つの引数（targets, scrollTriggers）であること、batchMax はレスポンシブ対応のために関数化可能であること、trigger/scrub/snap などの競合オプションの指定は禁止されていることを記載しています。
scrollerProxy() により、サードパーティ製スムーズスクロールライブラリと共存するための接続方法を提示: カスタム getter/setter で scrollTop/scrollLeft をオーバーライドし、ScrollTrigger.update をスクロールリスナーとして登録します。
skills/gsap-scrolltrigger/SKILL.md
**Critical:** When the third-party scroller updates its position, ScrollTrigger must be notified.
さらに、「スクロールが別スレッドで発生する／transform で変位される」場合にのみ現れる pinType（fixed/transform）や fixedMarkers などのトラブルシューティング用設定も提供しており、これは公式ドキュメントをなぞるだけでは得られない実践的な知見です。
「疑似横スクロール」パターンを4ステップの定石レシピに分解し、ease: "none" を必須制約として明記（設定しない場合、スクロール位置と横方向の位置が同期しなくなります）。
skills/gsap-scrolltrigger/SKILL.md
The container animation must use **ease: "none"**.
定石レシピ: パネルを pin 固定 → 内部の x/xPercent をアニメーション化（ease: "none"） → ST をその tween にバインド（pin + scrub） → 他の要素は containerAnimation でそれを参照。同時に2つの制約（containerAnimation のシーンでは pin と snap は使用不可）も明記しています。
ライフサイクル管理を前置: refresh の自動／手動の境界 + 作成順序／refreshPriority + kill によるクリーンアップを徹底し、SPA 内で古いノードに残存インスタンスが走り続けるのを防止します。
skills/gsap-scrolltrigger/SKILL.md
Create ScrollTriggers in the order they appear on the page (top to bottom, scroll 0 → max).
具体的なルール: リサイズ時は自動 refresh されますが（200ms デバウンス）、動的コンテンツ追加時は自動更新されないため手動 refresh() が必要です。作成順序が pin spacing に影響するため順不同時は refreshPriority を設定し、要素削除時やページ遷移時には kill を実行します。
「scrub と toggleActions は二者択一」であることを排他的仕様として明記し、両方が存在する場合は scrub が優先される旨を明示。問い合わせ調査で最も頻発する混乱を解消します。
skills/gsap-scrolltrigger/SKILL.md
❌ Use **scrub** and **toggleActions** together on the same ScrollTrigger; choose one behavior. If both exist, **scrub** wins.
gsap-performance の「scrub: 1 でスクロール中の負荷を軽減する」という方針と呼応していますが、本スキルでは意味論的な正しさを重視しています。
2コア機能
01基本トリガー: trigger + start/end + toggleActions の4アクション（onEnter/onLeave/onEnterBack/onLeaveBack）
02scrub スクロール連動: ダイレクト追従の true、または「追いつき」を滑らかにする数値（秒）指定
03pin 固定 + pinSpacing スペース確保（「固定された要素自体はアニメーションさせない」制約を含む）
04batch() による一括表示/離脱の集約コールバック（interval / batchMax / 2引数シグネチャ）
05scrollerProxy() によるサードパーティ製スムーズスクロールライブラリ連携（scrollTop/scrollLeft の getter-setter 双方のセマンティクスを含む）
06containerAnimation による疑似横スクロール（ease: "none" の必須制約および pin/snap 使用不可の制約付き）
07snap スナップ配置（数値/配列/"labels"/duration-delay-ease を含むオブジェクト）および toggleClass、markers、refreshPriority、id/getById
08リフレッシュと破棄: refresh()/refreshPriority の順序管理、および getAll()/getById() による kill クリーンアップ
3外部依存関係
| Kind | Dependency / Endpoint |
|---|---|
| package | gsap/ScrollTrigger（插件，须 registerPlugin） |
| network | GSAP 官方 ScrollTrigger 文档 |
| network | batch() 官方文档 |
| network | scrollerProxy() 官方文档 |
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
自動ロード可能
管理者向け
ソースとバージョンの記録
判定根拠（ファイルパスと抜粋）
- SKILL.md: 純粋なプロンプト指示およびルールテキストのみで構成され、スクリプト実行や外部への影響はありません。
監査ノート： 純粋な指示型スキル: ディレクトリ内には SKILL.md（18,390 B）のみが存在し、スクリプトの実行、外部ネットワーク通信、認証情報の読み込み、ファイル書き込みは一切行いません。外部リンク3件はすべて gsap.com の公式ドキュメントです。留意点: 本スキルはエージェントを誘導してユーザーのページ内に多数の ScrollTrigger インスタンスを生成させます（pin や scrollerProxy は DOM やスクロールコンテナの挙動を変更します）。クリーンアップ規約を怠ると要素の固着やスクロールのずれが生じる可能性がありますが、これは機能利用上の境界事項であり、セキュリティリスクではありません。
5二重目の独立検証
- [ok] 目录资产面：仅 SKILL.md — skills/gsap-scrolltrigger/ 下唯一文件 SKILL.md（18,390 B）；无 scripts/、references/、数据文件。
- [ok] external_deps 逐条核实调用点 — registerPlugin(ScrollTrigger) 代码块、三条 gsap.com URL（文档链接、batch()、scrollerProxy()）均在文件内逐字命中，无自造端点。
- [ok] 「ease: none 是硬约束」是否有原文支撑 — 原文两处强调：配方第 2 步「Use **ease: "none"** on that tween」与 Caveats「The container animation must use **ease: "none"**.」，并解释原因是 1:1 映射会被缓动破坏。
- [ok] batch 回调签名描述（两参数）是否属实 — 原文明确「Batched callbacks receive **two** parameters (unlike normal ScrollTrigger callbacks, which receive the instance)」，与 GSAP 官方 batch 行为一致。
- [ok] scrollerProxy getter/setter 双态语义描述 — 原文「called **with** an argument, it is a setter; called **with no** argument → getter」并给出 arguments.length 判定的示例代码，符合官方 API。
- [ok] 安全反例搜索（隐藏脚本/网络/凭证） — 对该文件 token 扫描：curl/wget/fetch(/XMLHttpRequest/exec(/child_process/process.env/.env/API_KEY/secret 全零命中；URL 仅 3 条 gsap.com。
- [ok] 与 gsap-performance / gsap-react 的表述是否冲突 — 三者对 scrub、refresh、React 清理的说法一致（performance 提出去抖 refresh、react 提供 useGSAP 自动清理），无自相矛盾。
- [ok] 元数据与 pin — frontmatter license MIT；本地 HEAD = aed9cfd3277740755f6bfc1155c7aa645403b760；GitHub API stars 15326 / pushed_at 2026-07-29T17:36:08Z（晚于 pin，结论不跨版本）。
6結論
最適な用途： スクロールテリング、パララックス、セクション固定、横スクロールを扱うあらゆる GSAP プロジェクト、特に pin、scrub、batch の活用やサードパーティ製スムーズスクロールライブラリとの共存が求められる複雑なページに最適。チーム内における ScrollTrigger 実装規約のクイックリファレンス原案としても有用。React/Vue/Svelte 環境では gsap-react / gsap-frameworks と併用してライフサイクルを管理します。
不向きな用途： 単純な「要素が画面に入ったらフェードインする」用途には不向き（IntersectionObserver や CSS のほうが軽量であり、本スキルでも batch を IntersectionObserver の代替手段と位置付け必須とはしていません）。GSAP を使用しないスクロール構成（純粋な CSS scroll-driven animations など）には不向き。スキル自体にビジュアルデバッグツールが含まれることを期待する用途には不向き（デバッグ機能は gsap-plugins の GSDevTools に委ねられます）。
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload gsap-scrolltrigger.tar.gz
sha256:
Option B · Copy Guide for Agentd77050ca6e9970e0…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit aed9cfd327.