Design & Motion · greensock/gsap-skills

gsap-timeline

Name: gsap-timeline
Author: greensock/gsap-skills

Official GSAP skill for timelines — gsap.timeline(), position parameter, nesting, playback. Use when sequencing animations, choreographing keyframes, or when the user asks about animation sequencing, timelines, or animation order (in GSAP or when recommending a library that supports timelines).

L1 Basic · Source registration onlyV1 Commit-PinnedDual-pass Audit

Author greensockGitHub greensock/gsap-skills ↗Stars 15326License MIT（仓库根 LICENSE，Copyright (c) 2026 GreenSock；GitHub API spdx_id=MIT；每个 SKILL.md frontmatter 亦写 license: MIT）Commit aed9cfd327

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

The second lightest among the eight skills (4.4 KB, only larger than gsap-performance's 4,139 B). It focuses on a single goal: turning "how to sequence multi-step animations" into enumerable rules—position parameter, defaults, labels, nesting, and playback controls.

skills/gsap-timeline/SKILL.md

Apply when building multi-step animations, coordinating several tweens in sequence or parallel, or when the user asks about timelines, sequencing, or keyframe-style animation in GSAP.

The description directly includes trigger words (sequencing / timeline / keyframes / choreograph / animation order), allowing hosts to trigger it when the user mentions "play in order" or "choreograph"; the body contains no unrelated APIs.

Transforms "where to place on the timeline" from guesswork into four enumerable categories: absolute seconds, relative (+= / -=), labels, and placeholders (< / >).

skills/gsap-timeline/SKILL.md

Third argument (or position property in vars) controls placement:

This is the most error-prone aspect of timelines (defaults to appending, and the default reference point is the end of the most recently added animation). The skill explicitly specifies "<" = aligns with the start of the previous animation, and "<0.2" = 0.2s after the previous start, preventing the model from guessing.

Uses defaults to push common duration/ease down to the timeline constructor, fundamentally preventing redundant parameters across individual child tweens.

skills/gsap-timeline/SKILL.md

Pass defaults into the timeline so all child tweens inherit:

In the example, both child tweens in tl.to(".a", { x: 100 }).to(".b", { y: 50 }) inherit 0.5s / power2.out; this corresponds to "do not forget to pass defaults" in the Do Not section.

Uses labels to make choreography readable and seekable: addLabel + play("outro") + tweenFromTo turns "chapter jumping" into a one-liner.

skills/gsap-timeline/SKILL.md

Add and use labels for readable, maintainable sequencing:

The semantics of tweenFromTo (pauses the original timeline and returns a new Tween scrubbing the playhead from intro to outro) are also clearly explained to prevent mistaking it for the animation itself.

Master/child nested timeline composition serves as the primary reuse pattern (child timelines can be sequenced independently and then added to the master timeline via add).

skills/gsap-timeline/SKILL.md

Timelines can contain other timelines.

Paired with Do Not: never place animations with ScrollTrigger inside a timeline—ScrollTrigger can only be attached to top-level tweens/timelines, forming a strict cross-skill boundary (consistent with gsap-scrolltrigger).

Explicitly clarifies two semantic misunderstandings: the default reference point of the position parameter, and that timeline duration is determined by its children rather than constructor parameters.

skills/gsap-timeline/SKILL.md

❌ Forget that **duration** on the timeline constructor is not the same as tween duration; timeline “duration” is determined by its children.

The former pitfall is "assuming +=0.5 is relative to the entire timeline", and the latter is "assuming timeline({duration:1}) will compress the whole timeline". Both are listed with ❌ marks.

2Core Capabilities

01Sequential and parallel choreography: appends by default, using position parameters to place tweens at absolute times or relative anchors

02Four forms of position parameter: seconds / += -= / labels / < > placeholders (including relative offsets)

03defaults inheritance: centralize common parameters such as duration/ease in the timeline constructor

04Labels and jumping: addLabel / play("label") / tweenFromTo(intro, outro)

05Nesting and reuse: sequence child timelines independently and add them to the master timeline

06Full timeline playback control: play/pause/reverse/restart/time/progress/kill

3External Dependencies

Kind	Dependency / Endpoint
package	gsap（npm 公共包，timeline 属核心 API）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Can be auto-loaded

For Administrators

Evidence & Triggers (File Paths & Excerpts)

SKILL.md: Pure prompt instructions and rule text; no script execution or external side effects

Audit Notes: Pure instruction-based skill: contains only SKILL.md (4,394 B) within the directory, with no scripts, no network requests, no credential access, and no file writes; this file contains no external links (zero hits across the repository URL scan), and the only dependency is the gsap package already installed in the user's project. The only consideration is at the instruction level: it anchors the agent's multi-step animation authoring to the timeline + position parameter paradigm (an advantage for GSAP projects, but not applicable if the project intentionally relies on CSS/keyframes for orchestration).

5Second-Pass Verification

[ok] 目录资产面：仅 SKILL.md、无脚本/引用 — skills/gsap-timeline/ 下唯一文件 SKILL.md（4,394 B）；无 scripts/、references/、模板。
[ok] 外部依赖清单：只有 gsap 包，无网络端点 — 该 SKILL.md 的 URL 正则扫描结果为空（0 条），确认无文档外链；包依赖证据取自 README 的 npm 安装说明。
[ok] 位置参数语义描述是否与 GSAP 实际行为一致 — 「+0.5s after last end」「< same start as previous」「<0.2 = 0.2s after previous start」与 GSAP position parameter 官方语义一致，无编造。
[ok] tweenFromTo 描述是否准确 — 正文写明它会暂停 timeline 并返回一个把 playhead 从 intro 拖到 outro 的新 Tween（no ease），与官方 API 行为一致。
[ok] 与 gsap-scrolltrigger 的边界是否自相矛盾 — 本文件 Do Not「Nest animations that contain a ScrollTrigger」与 gsap-scrolltrigger「Do Not 把 ScrollTrigger 放在 timeline 子 tween 上」方向一致，互为印证。
[ok] 安全反例搜索 — token 扫描：curl/wget/fetch(/exec(/child_process/process.env/.env/API_KEY 零命中；文件内无代码可执行单元（仅代码块中的示例）。
[ok] 元数据（license/stars/commit） — frontmatter license: MIT；仓库 MIT；本地 HEAD = pin aed9cfd…；GitHub API stars 15326 / pushed_at 2026-07-29T17:36:08Z。
[ok] 与 examples 的呼应 — examples/vanilla/main.js 用 position parameter（"+=0.2"、"-=0.1"）按本 skill 规则编排 tl.to 链，可作可运行参照。

6Verdict & Scenarios

Addresses specific problems with minimal footprint: 4,394 B covers all common timeline features with low retrieval and loading costs, ideal as a permanently resident base skill.

Contains an actionable mental model: the four forms of the position parameter plus an explicit explanation of "defaults to referencing the end of the most recent animation" eliminate the most common timing bugs directly.

defaults and labels keep choreography maintainable: centralized common parameters, plus named and seekable chapters.

Clear cross-skill boundaries: explicitly enforces that ScrollTrigger can only be attached at the top level, avoiding semantic conflicts with gsap-scrolltrigger.

Zero external links and zero dependencies: no web fetching, no installations, and no interaction with external systems other than the already installed gsap.

Best for: Suitable for any project using GSAP for multi-step/multi-element choreography: entrance sequences, keyframe-style animations, and presentations requiring rewind or seek capabilities; ideal for combined use with gsap-core and gsap-scrolltrigger (the former handles syntax, the latter handles scroll binding).

Not for: Not suitable for simple single-step animations (use to()/from() from gsap-core directly without a timeline); not suitable for projects not using GSAP; not suitable for scenarios expecting runtime validation or visual debugging tools from the skill (debugging capabilities reside in the GSDevTools section of gsap-plugins).

Install Agent-Ready

① Verified Mirror 2026-09-15

Option A · Direct DownloadDownload gsap-timeline.tar.gz

sha256: b2100e5b57129ab4…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit aed9cfd327.