Front-End-Checklist 的 animated-content 技能实战：将大型动画 GIF 替换为 WebM/MP4 视频

本篇指南围绕 Front-End-Checklist 仓库中的 animated-content Agent 技能展开，讲清一条性能规则的完整落地路径：如何检查页面中的大型动画 GIF、如何转换为 WebM/MP4 视频并正确配置 <video> 属性、以及该技能文件是如何由规则源文件自动生成的。读完后你既能掌握「GIF 换视频」这一具体优化方案的实操细节（含完整代码示例与验证方法），也能理解该项目「一条规则 → 一个可安装技能」的生成机制。

这个技能在项目中是什么

animated-content 是 Front-End-Checklist 面向 AI Agent 的可安装技能（skill），对应 performance 分类下的「Convert animated GIFs to video」规则。它在仓库中的组成非常精简：

• 技能主文件 SKILL.md：包含元数据、快速参考，以及 Check / Fix / Explain / Code Review 四段式指令；
• 完整规则参考 references/rule.md：由规则 MDX 正文转换而来，包含代码示例、最佳实践、工具链与验证清单；
• 规则源文件 animated-content.mdx：SKILL.md 与 references/rule.md 的单一事实来源（single source of truth）。

技能元数据（见 SKILL.md 的 frontmatter）为：category: performance、priority: medium、difficulty: intermediate、estimatedTime: "10"（约 10 分钟可完成一次整改），description 以 “Use when auditing slow page loads, heavy assets, or rendering delays related to Convert animated GIFs to video” 开头，用于让 Agent 按意图匹配该技能。

规则背景：为什么大型 GIF 要换成视频

规则原文给出的问题陈述是：大型动画 GIF 会显著增加页面体积，并消耗过多 CPU/内存，从而导致页面加载变慢、滚动性能下降。相比现代视频格式，GIF 的效率极低——文档指出将其转换为 MP4 或 WebM 后，文件体积通常可以减少 80% 以上。

具体代价体现在四个方面（见 references/rule.md 的 “Why It Matters”）：

• 页面体积（Page Weight）：GIF 未采用现代视频式压缩，很容易达到数 MB 级别，拖慢页面加载；
• CPU 占用：浏览器解码和渲染大型 GIF 消耗的 CPU/GPU 资源，明显多于经过优化的视频；
• 电池寿命：在移动设备上，GIF 的高资源消耗会显著加快耗电；
• 用户体验：大体积资源会推迟页面加载完成，并在滚动时造成卡顿。

因此该规则的 Quick Reference（快速参考）给出三条结论：

1. 动画内容优先用 <video> 替代大型 GIF；
2. GIF 文件体积显著大于 MP4/WebM；
3. 视频格式提供更好的可控性与性能表现。

技能的四步工作流：Check、Fix、Explain、Code Review

SKILL.md 的主体就是四段面向 Agent 的指令，这也是 Front-End-Checklist 所有规则技能的统一结构（由生成脚本统一生成，见后文机制一节）。以本技能为例：

Check（检查）：查找可能被更高效的视频格式（MP4 或 WebM）替代的大型动画 GIF。实际排查时可以结合 DevTools Network 面板按类型/体积排序静态资源，筛出 .gif 中体积异常大的文件。

Fix（修复）：将动画 GIF 转换为 MP4 或 WebM，并使用 <video> 标签配合 autoplay、loop、muted、playsinline 四个属性来复现 GIF 的行为（自动播放、循环、静音、内联播放）。

Explain（解释）：向使用者说明视频格式为何比 GIF 更适合动画内容、以及它如何改善性能——对应的就是上节的四点代价分析。

Code Review（代码审查）：审查影响该规则的路由、资源与加载行为，标出具体文件、请求或渲染步骤中引入的多余网络/CPU/布局开销，并描述用于确认问题的测量方法。

四段指令的共同前提是 animated-content.mdx frontmatter 中 aiContext 字段的约束：在 DevTools、Lighthouse 或线上数据中先确认真实瓶颈，再推荐变更——即先测量、后优化，避免凭直觉改动。

代码示例：GIF 写法与视频写法的对比

规则参考文档给出了两组可直接对照的 HTML 示例。

传统 GIF（低效写法）：

<img src="animation.gif" alt="Description of animation">

优化后的视频写法（推荐）：

<video
  autoplay
  loop
  muted
  playsinline
  poster="animation-frame.jpg"
>
  <source src="animation.webm" type="video/webm">
  <source src="animation.mp4" type="video/mp4">
  Your browser does not support the video tag.
</video>

这段示例里有几个值得展开的细节：

• 双 source 回退链：<source> 的顺序是 WebM 在前、MP4 在后。浏览器按顺序选取第一个能解码的格式，因此现代浏览器走体积更小的 WebM，不支持 WebM 的环境回退到兼容性更好的 MP4。这与最佳实践中「WebM 给现代浏览器、MP4 作为回退」的要求一致。
• 四个属性缺一不可：autoplay 对应 GIF 的自动播放，loop 对应循环，muted 是浏览器允许自动播放的前提（几乎所有主流浏览器都禁止有声自动播放），playsinline 避免 iOS 等环境强制全屏播放。
• poster 属性：在视频资源尚未加载完成时先展示一帧静态画面，改善感知加载体验。
• 降级文案：标签内的纯文本在浏览器完全不支持 <video> 时呈现。

最佳实践与反模式

文档以 ✅/❌ 的形式给出了六条实践约束，全部继承如下：

• ✅ 使用现代格式：WebM 供现代浏览器，MP4 作为回退；
• ✅ 添加 poster 图：视频加载期间展示静态帧；
• ✅ 默认静音：自动播放的视频必须加 muted，以保证跨浏览器可用；
• ✅ 懒加载：首屏以下的视频使用 loading="lazy" 或 Intersection Observer 延迟加载；
• ❌ 避免用 GIF 做大型动画：尺寸超过几百像素、或时长超过一秒的动画不要用 GIF；
• ❌ 不要忘记可访问性：动画必须提供替代文本或描述。

文档还有一条更高层的建议：在决定一个动画是否还需要以 GIF 形式存在时，优先考虑以生产环境实测行为为准的性能方法论——最大的收益通常来自直接去掉沉重的动画资源，而不是仅仅把它缓存得更好。

转换工具链

文档 “Tools & Validation” 一节列出的工具（此处仅列名称，详见 references/rule.md）：

• FFmpeg：命令行转换工具，是 GIF → WebM/MP4 的主力；
• Cloudinary / Imgix 一类的自动化媒体优化服务：适合不想在本地维护转换流程的团队；
• Lighthouse：可识别大型 GIF 并建议视频替代方案，用于验证阶段。

以 FFmpeg 为例，一个典型的 WebM 转换命令形态（供实操参考，具体参数需按源文件帧率与质量需求调整）：

ffmpeg -i animation.gif -c:v libvpx-vp9 -b:v 0 -crf 30 -an animation.webm
ffmpeg -i animation.gif -c:v libx264 -pix_fmt yuv420p -an animation.mp4

转换后建议直接对比产物体积，确认体积降幅符合规则中「80% 以上」的预期量级，再进入替换环节。

验证清单：自动化检查 + 手动检查

规则的 Verification 一节把验收拆成两类，这也是该技能 Code Review 指令中「描述测量方法」要求的具体落点。

自动化检查：

• 用 Lighthouse、PageSpeed Insights 或 DevTools 测量受影响的页面或流程，确认目标指标（如总体积、TBT、LCP 等）确实改善；
• 检查网络瀑布流或性能时间线，确认预期的资源/执行变化真实生效（例如确认页面请求中不再出现原来的 .gif，转而请求 .webm/.mp4）。

手动检查：

• 在限流的移动端模拟档位下验证变更，而不只是本地桌面环境；
• 如果该规则映射到某个预算或 Web Vitals 阈值，确认页面现在稳定处于阈值之内。

机制深挖：SKILL.md 与 references/rule.md 是如何生成的

skills/ 目录下的技能文件不是手写的，而是由 scripts/generate/generate-skills.ts 从规则 MDX 的 frontmatter 与正文自动生成。理解这个机制，能解释为什么技能文件结构高度一致、以及改动规则后如何同步技能。

从源码结构看，生成流程分三步（generate-skills.ts 的 main()）：

1. 遍历规则源目录：脚本读取 packages/content/rules/en/{分类}/{slug}.mdx，本技能对应 performance/animated-content.mdx；
2. 生成 SKILL.md：buildSkillMd（L88-L160）按固定模板拼装 frontmatter（name、description、category、priority、difficulty、estimatedTime、source、url），随后依次输出标题、whyItMatters、由 tldr 数组生成的 “Quick Reference” 列表，以及 prompts 中的 check/fix/explain/codeReview 四个字段对应的四段指令。这正好对应我们在 SKILL.md 中看到的结构；
3. 生成 references/rule.md：buildReferencesMd（L165-L186）在头部拼上 Priority/Difficulty/Time 元信息后，把 MDX 正文交给 stripMdxToMarkdown（L67-L83）剥离 import/export 与 JSX 组件标签，输出纯 Markdown 正文——这就是 references/rule.md 里代码示例、最佳实践、工具与验证清单的由来。

此外源码中还有几个与 Agent 消费直接相关的设计约束：

• description 必须以 “Use when” 开头：buildSkillMd 会检查 aiContext/description 是否以 “Use when” 起始，否则自动补前缀（L89-L95），这是为了让 Agent 按意图匹配技能；description 不足 50 字符时还会自动拼接标题与分类补齐。
• 扁平目录结构：技能输出为 skills/{slug}/（目录名即技能名）；当不同分类出现同名 slug 时自动加分类前缀（L563-L574）。animated-content 无重名，故目录名就是 animated-content。
• 增量再生成：脚本支持传入具体 .mdx 文件路径做增量更新（lefthook 钩子会把暂存的规则文件作为参数传入），不传参数则全量重建，同时始终会刷新一个汇总全局技能 frontend-checklist-global。

也就是说，维护规则只需改 animated-content.mdx，运行 pnpm generate:skills（全量）或带路径参数（增量，如 pnpm generate:skills packages/content/rules/en/performance/animated-content.mdx）即可同步出 SKILL.md 与 references/rule.md。技能安装方式（见脚本头部注释）为：

npx skills add frontendchecklist/skills
npx skills add frontendchecklist/skills --skill animated-content

规则元数据与关联规则

从 animated-content.mdx 的 frontmatter 可以看到这条规则的完整画像：

• 分类路径：performance，子分类 metrics；优先级 medium，难度 intermediate，预计耗时 10 分钟；
• tldr 三条快速参考（即 SKILL.md 的 Quick Reference 来源）；
• prompts 四段式指令（check/fix/explain/codeReview，即 SKILL.md 的四个 H2 小节）；
• sources 声明了 web.dev Learn Performance（reference，primary）与 Chrome Developers 的 Lighthouse overview（implementation，primary）两条权威依据，resources 指向 PageSpeed Insights 工具；
• relatedRules 列出同属 performance/metrics 区域、常被一起审查的关联规则：browser-caching、font-loading、javascript-minification、dom-size。做页面体积与渲染性能整改时，可顺带对照这几条规则，形成完整的性能审查闭环。

小结

animated-content 技能浓缩了 Front-End-Checklist 的一条性能规则：定位大型动画 GIF → 转换为 WebM（首选）/MP4（回退）→ 用 autoplay、loop、muted、playsinline 与 poster 复现 GIF 行为 → 在限流移动端档位下用 Lighthouse/DevTools 验证指标改善。技能文件本身由规则 MDX 经 generate-skills.ts 自动派生，因此规则源文件是唯一维护入口；而 Check/Fix/Explain/Code Review 的四段结构则保证了人类开发者与 AI Agent 都能以同一套「先测量、后变更、可验证」的流程消费这条规则。