1仕組みと動作原理
gsap.utils を「登録不要の純粋関数ツールボックス」と位置づけ、アニメーションワークフロー内での挿入ポイント（関数ベースの値、ScrollTrigger / Observer コールバック）を説明する。
skills/gsap-utils/SKILL.md
**gsap.utils** provides pure helpers; no need to register.
主張する機能を実現できる理由：utils は副作用やネットワーク通信を持たない純粋な計算 API です。このスキルの真価は各関数の入力→出力セマンティクスを明確に示す点にあり、スクロール位置のマッピング、ランダム化、グリッド吸着などの場面でモデルが独自の計算処理を自作するのを防ぎます。
「値を省略すると再利用可能な関数を返す」という呼び出しパラダイムを統一し、唯一の例外である random() に true を渡すケースを明記する。
skills/gsap-utils/SKILL.md
If you omit that argument, the util returns a **function** that accepts the value later.
これは utils の設計における一貫性によるものです。clamp、mapRange、normalize、interpolate、snap、wrap、wrapYoyo はいずれも関数型スタイルをサポートします。random はシグネチャの違い（snapIncrement パラメータが存在する）から末尾引数に true を渡して関数を返します。この例外を明確にすることで、モデルの誤用を防ぎます。
各関数に仕様として「具体的な入力 → 出力コメント」（検証可能なマイクロテストに相当）を提供し、モデルが例を通じてセマンティクスを一致させられるようにする。
skills/gsap-utils/SKILL.md
gsap.utils.clamp(0, 100, 150); // 100
例えば normalize(0, 100, 50) // 0.5、snap(10, 23) // 20、interpolate("#ff0000", "#0000ff", 0.5) // mid color などです。こうした確定的コメントにより、モデルが文章定義を読むよりも確実に値の推移を自己検証できます。
distribute() を表形式の構成（base、amount、each、from、grid、axis、ease）に分解し、GSAP 内部の stagger 分布エンジンとして解説する。
skills/gsap-utils/SKILL.md
**Returns a function** that assigns a value to each target based on its position in the array (or in a grid).
使用方法は2通りあります。tween のプロパティ値として直接渡し（GSAP が (index, target, targets) ごとに各ターゲットへ呼び出す）、または手動で特定インデックスの値を取得します。grid + axis と組み合わせることで2次元リップル効果を構築できます。
selector(scope) をコンポーネント内「セレクターサンドボックス」の公式プリミティブとして提示し、gsap-react や gsap-frameworks のスコーピング規律と連携させる。
skills/gsap-utils/SKILL.md
Returns a scoped selector function that finds elements only within the given element (or ref).
DOM 要素または ref（内部で .current を処理）を受け付けるため、React や Vue では containerRef をそのまま渡すことができ、グローバルセレクターによる意図しない他ノードへの影響を防止します。
単位と色の解析を独立したセクションとし、getUnit / unitize / splitColor で「数値以外」の入力を処理し、mapRange や normalize は単位変換を行わないことを明確にする。
skills/gsap-utils/SKILL.md
❌ Assume **mapRange** / **normalize** handle units; they work on numbers.
splitColor は rgb、rgba、hsl、hsla、hex、カラーネームに対応し、第2引数に true を渡すと HSL を返します。これによりチャンネルごとの色補間やグラデーション生成が可能になります。
2コア機能
01範囲マッピングと正規化：clamp / mapRange / normalize / interpolate（数値、色、オブジェクト）
02ランダムと吸着：random（snapIncrement や配列サンプリングを含む）/ snap（数値または配列）/ shuffle
03tween 内での文字列形式ランダム：x: "random(-100, 100, 5)"（GSAP がターゲットごとに評価）
04distribute()：インデックス、グリッド、イージングに応じた値の分布（高度な stagger の内部エンジン、手動呼び出し可能）
05単位と色：getUnit / unitize / splitColor（HSL 出力を含む）
06コレクションとスコープ：selector(scope) / toArray(value, scope) による混合入力の真の配列化
07関数合成とループ・剰余：pipe(...fns)（パイプライン）、wrap / wrapYoyo（ループ／往復）
3外部依存関係
| Kind | Dependency / Endpoint |
|---|---|
| package | gsap（utils 为内核自带命名空间，无需注册） |
| network | distribute() 官方文档 |
| network | random() 官方文档 |
| network | splitColor() 官方文档 与 HelperFunctions 列表页 |
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
自動ロード可能
管理者向け
ソースとバージョンの記録
判定根拠（ファイルパスと抜粋）
- SKILL.md: スクリプト実行や外部影響を伴わない純粋なプロンプト指示およびルールテキスト
監査ノート： 純粋な指示型スキル：ディレクトリ内には SKILL.md（12,093 B）のみが含まれ、スクリプト実行、外部ネットワーク通信、認証情報読み取り、ファイル書き込みは一切ありません。外部リンクは 4 つの gsap.com 公式ドキュメントのみです。全編が数学・コレクション・単位変換の関数解説で構成されており、このリポジトリ内で最も権限外動作を引き起こす可能性が低いスキルです。唯一の注意点は、関数型呼び出しで返されたクロージャを誤用（戻り値をスカラー値として比較するなど）するとアニメーションが無言で停止する点ですが、これは機能の利用境界の問題であり、セキュリティ上のリスクではありません。
5二重目の独立検証
- [ok] 目录资产面：仅 SKILL.md — skills/gsap-utils/ 下唯一文件 SKILL.md（12,093 B）；无 scripts/、references/、数据文件。
- [ok] external_deps 逐条核实 — gsap 包依赖证据取自 README 安装段；三条 gsap.com 链接（distribute、random()、HelperFunctions）+ splitColor 链接在内文中逐字命中。
- [ok] 函数签名与示例输出是否与官方语义一致 — 抽查 clamp(0,100,150)=100、mapRange(0,100,0,500,50)=250、normalize(0,100,50)=0.5、snap(10,23)=20、wrap(0,360,370)=10、wrapYoyo(0,100,150)=50，均与 GSAP 官方 API 语义吻合，无编造。
- [ok] 「random 是唯一例外」的说法是否可复核 — 原文明确「This is the only util that uses `true` for the function form instead of omitting the value.」并给出 random(-200,500,10,true) 示例，叙述自洽。
- [ok] 安全反例搜索 — token 扫描：curl/wget/fetch(/XMLHttpRequest/exec(/child_process/process.env/.env/API_KEY/secret 零命中；无混淆代码（该文件只有短代码块）。
- [ok] 与 gsap-react / gsap-frameworks 的 scoping 叙述是否一致 — 本文件「Use **gsap.utils.selector(scope)** in components so selectors are scoped to a container or ref.」与 gsap-react 的「always pass scope」、gsap-frameworks 的「Do not use global selectors」同向。
- [ok] 元数据与 pin — frontmatter license: MIT；本地 HEAD = aed9cfd3277740755f6bfc1155c7aa645403b760；GitHub API stars 15326、pushed_at 2026-07-29T17:36:08Z。
- [ok] 无夸大检查 — description 只声明「Official GSAP skill for gsap.utils …」，文件内容即函数清单与示例，无越界承诺（不宣称性能优化或自动重构）。
6結論
最適な用途： 「スクロール進行度→数値マッピング」「ランダム／吸着」「グリッド分散の時差アニメーション」「スコープ付きセレクター」「カラーチャンネル補間」を必要とするあらゆる GSAP プロジェクトに最適。ScrollTrigger コールバックや複雑な stagger を記述する際の最も実用的な補助スキルです。
不向きな用途： アニメーション全般のチュートリアルとしての利用には不向き（tween や timeline の解説は含まれず、gsap-core / gsap-timeline の基礎が必要）。GSAP を使用しないプロジェクトには不向き（関数はすべて gsap.utils 名前空間に存在）。実行時型チェックやパフォーマンス診断を求める用途には不向き。
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload gsap-utils.tar.gz
sha256:
Option B · Copy Guide for Agent55bd8167106fd1d2…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit aed9cfd327.