Content & Media Creation · iart-ai/explainer-video-skills

wrapped-video

Name: wrapped-video
Author: iart-ai/explainer-video-skills

This skill should be used when the user asks to "make a Spotify Wrapped style video", "build a year in review / year-in-review video", "create a personalized data video", "generate a recap video", "build a wrapped video generator", "turn a data table into shareable videos", or "make per-user stat videos". Covers the data row → one shareable video pattern, the Wrapped scene grammar (big-number reveals, top-X lists, superlatives), animated data counters, vertical 9:16 framing, and batch-rendering many personalized videos from one template.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit

Author iart-aiGitHub iart-ai/explainer-video-skills ↗Stars 26License MIT（仓库根 LICENSE：MIT License / Copyright (c) 2026 iart.ai；.claude-plugin/plugin.json 声明 "license": "MIT"，GitHub API license.spdx_id = MIT）Commit 3e2d411b72

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 entire methodology is built on "one template × one data table → one video per row": first define a typed schema for a single row of records, making the entire video a pure function of that record. Any scene that cannot be populated with a single row of data should not appear in Wrapped.

skills/wrapped-video/SKILL.md

Define a typed schema for one record. The whole video is a pure function of it.

This turns "batch personalization" from an editing problem into a data contract problem—subsequent concurrency, naming, and deduplication are all built on "row as input".

The second non-negotiable principle is "design for screenshots": each scene must be readable within 2 seconds and look stunning even when frozen into a still frame, because what actually gets shared is that very still frame.

skills/wrapped-video/SKILL.md

2. **Built to be screenshotted.** Each scene must read in under 2 seconds and look good frozen

Treat the shared asset (still frame) as the design target, rather than treating the video as the target and the screenshot as an afterthought.

Scene grammar is fixed to 5–7 short scene types (Intro / Big-number / Top-X / Superlative / Comparison / Time-heatmap / Outro), each lasting about 2.5–4s; each year only the data and color palette change, while the grammar remains constant.

skills/wrapped-video/SKILL.md

A Wrapped is a fixed sequence of short scene *types*, each ~2.5–4s.

A fixed grammar is the prerequisite for "one template powering millions of personalized videos"—what is reused is not the visuals, but the slots.

Narrative is structured with "ascending impact": arrange statistics in ascending order of emotional weight (magnitude, rarity, prestige), with the hero metric serving as the grand finale and holding the longest screen time; never reveal the biggest number first, or there will be nowhere left to climb.

skills/wrapped-video/SKILL.md

**Sequence stats for rising impact — smallest first, biggest last.**

This elevates "sorting" into narrative design rather than an editing detail; the paired requirement is that the climax frame is the largest and longest-lasting.

The protagonist must be the viewer themselves: display their name within the first two seconds, use a per-user accent color, and write all copy in the second person; if a frame reads identically for two different users, that frame is failing its job.

skills/wrapped-video/SKILL.md

If a frame would read identically for two different users, it isn't pulling its weight.

This is an actionable acceptance criterion (the same frame must differ across different rows), not an empty slogan about "needing personalization".

The signature animation is the big-number counter: it must be driven by useCurrentFrame + spring (setState/setInterval are strictly forbidden—they flicker during frame-by-frame renderer snapshots), formatted to locale, and styled with tabular-nums to prevent width jitter during number rolling.

skills/wrapped-video/SKILL.md

Drive it from `useCurrentFrame()` (never `setState`/`setInterval` — that flickers on render), ease it with a spring, and format with `toLocaleString()`.

Shares the same frame-driven discipline with explainer-video / map-animation from the same pack.

The vertical safe zone is quantified down to the pixel: render at 1080×1920, and critical content (names, numbers, lists, CTAs) must fall within the center 80% of vertical height, avoiding the top 12% and bottom 18% (platform UI overlay zones).

skills/wrapped-video/SKILL.md

Render **1080×1920**. Stories/Reels/TikTok crop and overlay UI, so keep all type and key numbers inside the **center 80% height**, clear of the **top 12%** and **bottom 18%**.

Being obscured is not an "aesthetic issue"—it means the numbers meant to be seen disappear, which is why explicit pixel ranges are given.

Batch rendering is where the value of this methodology is realized: bundle once, then iterate through rows with selectComposition + renderMedia passing inputProps, using stable ID naming to guarantee idempotency, while skipping and logging failed schema validations without rendering half-baked outputs.

skills/wrapped-video/SKILL.md

The payoff. Render every data row to its own MP4 with `renderMedia`, passing the row as `inputProps`.

"Pure functions + stable naming" allow reruns to overwrite cleanly and failed rows to be retried independently—the key to scaling to tens of thousands.

2Core Capabilities

01Wrapped scene grammar + frame-level storyboard timeline (7 scene categories, 22s@30fps scene-by-scene frame ranges)

02Row-level data contract: zod schema defining a single record row + Composition registration (schema + defaultProps)

03Big-number counter component (spring-driven + interpolate + toLocaleString, tabular-nums to prevent width jitter)

04Staggered Top-X list entrances (one spring per row, rank 1 first, perfectly identical motion curves)

05Climax scene combining percentile bars with synchronized numerical counting

06Scene composition and transitions: <Series> eliminating manual absolute frame calculations, TransitionSeries + fade/slide

07Batch pipeline: CSV/JSON → schema validation → renderMedia → out/wrapped-<id>.mp4 (bundle once, concurrency limits, idempotent naming, deduplication, Lambda scaling)

08Vertical safe-zone rules + freeze-shareable outro card (most critical elements placed at vertical center ~960px)

09Accompanying deliverables: per-user share still (renderStill exporting outro frame) and README demo GIF

3External Dependencies

Kind	Dependency / Endpoint
cli	npx remotion still / render / compositions（单行验证与正式编码）
cli	npx tsx（运行批量脚本 render-all.ts）
package	@remotion/bundler 与 @remotion/renderer（bundle + 逐行渲染）
package	zod（行级 schema 校验）、p-limit（并发上限）、csv-parse（CSV 解析）、@remotion/transitions（转场）
network	@remotion/google-fonts：批量渲染时把字体内联进 bundle（避免 headless 缺字形/FOUT）
api	可选：Remotion Lambda（AWS 无服务器扇出），面向万级批量
cli	ffmpeg / ffprobe（contact-sheet.sh 与 probe-mp4.sh）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Execute local scripts or commands: npx remotion still / render / compositions (SKILL.md instruction): fetches and executes Remot from npm on demand
网络端点: Declare external network access: Build phase: @remotion/google-fonts fetches and inlines fonts into the bundle (explicitly recommended in reference to avoid headless
本地工作目录: File I/O and artifact output: out/wrapped-<recordId>.mp4 (one video per row, named by stable ID to ensure idempotency), out/wrapped-<recordId>.jpg (

Audit Notes: The evaluation target is the skill directory itself (skills/wrapped-video/: SKILL.md + 3 references/ + 0-byte README.md; contains no scripts, reads no credentials, and performs no disk writes inside the directory). The execution chain and dependency surface trigger the Amber rating: ① The output contract requires `npx remotion still/render` to render an MP4 per row, where npx fetches and runs the Remotion CLI and @remotion/* packages from npm registry, executing rendered project code inside local bundle + headless Chromium (precedent in same author's pack: remotion-video rated Amber for identical reasons); ② The batch pipeline depends on third-party packages like tsx, zod, p-limit, csv-parse, @remotion/bundler/renderer/transitions; ③ The optional scaling path in references uses Remotion Lambda (AWS), which involves cloud credentials and billing once enabled. The skill itself reads no credentials/env, contains no business APIs, performs no telemetry, and does not bypass protections, so it is not Red. Trigger condition: occurs only during actual rendering (or when Lambda is enabled); purely authoring schemas/components or performing dry data validation without rendering will not trigger it.

5Second-Pass Verification

[ok] 外部依赖调用点复核（npx remotion / npx tsx / @remotion/* / zod / Lambda） — SKILL.md Verify loop 确有 `npx remotion still Wrapped out/f-start.png --frame=0 --props='{...one user...}'` 与 `npx tsx render-all.ts`；batch-pipeline 确有 `import { renderMedia, selectComposition } from "@remotion/renderer";`、`p-limit` 与 `renderMediaOnLambda`；remotion-recipes 确有 @remotion/google-fonts 与 @remotion/transitions 用法。全部落地，非推测。
[ok] 是否隐含云端凭据需求 — 本地路径（renderMedia）不需要任何云端凭据；仅可选 Lambda 路径会引入 AWS 配置。SKILL.md/reference 中无 AWS key、无 access token 字面量，也无读取 env 的代码——故按「不读凭据」处理，但在 security.reason 与 verdict.risks 中标注了 Lambda 接入时的凭据/计费含义。
[ok] 帧驱动纪律的内部一致性 — SKILL.md 输出契约与 remotion-recipes 开篇「The one rule that prevents broken renders」一致禁止 setState/setInterval/Date.now()/CSS @keyframes 计时；大数字组件示例也确实只用 useCurrentFrame + spring + interpolate。
[ok] 数据契约与场景语法的耦合 — wrappedSchema 字段（name / year / minutesListened / topArtists / topGenre / percentile / accent）与场景类型表逐项对应（Intro 用 name+year、Big-number 用 minutesListened、Top-X 用 topArtists、Superlative/Comparison 用 percentile+topGenre、per-user accent 贯穿）；未见场景需要而 schema 未提供的字段。
[ok] 安全区数值与 storyboard 的自洽性 — 1080×1920 下 top 12% = 0–230px、bottom 18% = 1575–1920px、center 80% = ~230–1575px，与 scene-grammar 的安全区表一致；垂直中心 ~960px 落在中心区内。数值互相自洽。
[ok] 跨目录 / 跨 skill 引用可解析性 — 正文引用的 `scripts/contact-sheet.sh`、`scripts/probe-mp4.sh` 位于仓库根（单装本 skill 目录会悬空，需装整个 repo）；本 skill 自成闭环，未强依赖兄弟 skill（只需 Remotion 本体）。
[ok] 功能声明 vs 实际能力 — frontmatter 宣称覆盖「数据行 → 一条可分享视频」的范式、场景语法、计数动效、9:16 取景与批量渲染，SKILL.md 与三份 reference 逐项兑现（含 CLI 与 Node 两套批量变体）；未夸大——不声称自动产出数据或自动分发。

6Verdict & Scenarios

Treats the "share still" as the design objective, locking in the share card before back-propagating the ascending curve—giving topic selection and layout deterministic objective functions

Data contracts come first (typed schema + Composition registration + row-by-row validation), making "one video = pure function of one data row" engineerable and reliable

Actionable personalization criteria (the exact same frame must differ across different users) instead of vague "be personalized" slogans

Narrative ordering is codified into explicit rules (low → high, climax is largest and longest), preventing the common structural error of "revealing the biggest number upfront"

Batch execution is the core product value, fully backed by engineering details: bundle once, idempotent naming, deduplication, concurrency limits, thumbnail still generation

Best for: Ideal for productized scenarios requiring "one template, unique metrics per person": Year in Review / personal stats (music streaming, fitness, reading, spending, gaming, sales recaps, learning milestones), especially for teams needing to batch-render thousands of vertical short videos from a single data table where every video must be instantly shareable as a screenshot.

Not for: Not suitable for manually edited videos lacking per-record structured data (the skill strictly requires a data table); not suitable for landscape or long-form narrative videos (anchored to 9:16 short scene grammar); not suitable for explainer videos requiring delicate narrative arcs and voiceover (use explainer-video instead; this skill's scenes are slot-based, voiceover-free, and still-frame friendly).

Install Agent-Ready

① Verified Mirror 2026-09-28

Option A · Direct DownloadDownload wrapped-video.tar.gz

sha256: 16427a3a8db59d32…

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 3e2d411b72.