web-technique-to-skill

将 Web 技巧转化为 Skill

从可运行的代码入手，而不是从文字描述入手。如果来源是描述行为的文章或提示词包，请使用 article-prompts-to-skills。如果你已经构建了某个作品，它能正常运行，而相关知识目前只存在于一个文件中，请使用这个方法。

每个 skill 提取一种机制。一个效果出色的页面通常包含多种机制；应将它们分别打包，否则每种机制都会被稀释。

将此文档视为每个 Web 技巧 skill 持续生效的质量契约。每次创建或修订时，也要审核此 skill。如果工作中发现缺失的保真度规则、故障模式、打包约束或验证步骤，应在同一范围的变更中更新此契约，而不是只在某个子 skill 中解决。

用一句话命名机制

在写其他内容之前，先写出这句话：如果去掉什么，效果就不再起作用？ 如果你写不出来，那你描述的只是外观，而不是机制，这里还没有可用的 skill。

这句话决定后续的一切。以落叶飘落为例：“翻滚经过侧面朝向镜头的瞬间，而那一刻近乎消失的状态，正是让眼睛将其识别为叶片的关键”——因此，精灵图、调色板和夜景都只是衬托，翻滚才是 skill。

测试一下：在脑海中更换主体、调色板和布局。如果这句话仍然成立，它说的就是机制。如果不再说得通，你命名的就是衬托元素。

为演示命名并说明技术栈

为可见的 h1 和浏览器 <title> 使用具体的技巧名称：Wisps、Cursor Ripples、Liquid Metal Border 或 Scroll-scrubbed Word Reveal。不要用抽象的机制描述掩盖主题。“以任意速度绘制”描述的是行为，却没有告诉任何人这个演示是什么。

将经过验证的实现路径放在标题的正上方或正下方，并按顺序注明：

1. 运行时或框架：Vanilla JavaScript、React、Vue
2. 渲染器或浏览器 API：Canvas 2D、WebGL、DOM/CSS、SVG
3. 存在时的技巧层：GLSL shaders、Three.js、GSAP、ScrollTrigger

写成 Vanilla JavaScript · Canvas 2D 或 Three.js · WebGL · GLSL，不要写“交互式实验”或“动态研究”。绝不要根据外观猜测。检查源代码中的导入、渲染器构造和上下文创建，以确认技术栈。getContext('2d') 是 Canvas 2D，不是 shader；WebGLRenderer 加上 ShaderMaterial 则表示 Three.js、WebGL 和 GLSL。如果视觉效果可能被误认为使用了更复杂的技术栈，请明确说明其不包含这些技术：不使用 WebGL、shaders 或 Three.js。

如果效果栈和界面栈不同，应将二者区分开来。写成 Vanilla JavaScript + Canvas 2D 效果；CSS 界面，而不是将 CSS 与 Canvas 2D 并列，仿佛两者都在渲染粒子。读者应当清楚，哪种技术实现了该技巧，哪种技术仅用于布局控制项。

如果为了符合布局要求，必须保留经批准的参考标题，就保留它，并将技巧名称和技术栈写入浏览器标题，以及参考页面已有的引导语、控制面板或次级标签中。首次呈现的屏幕仍必须让实现方式一目了然。

将机制与衬托分开

将源内容的每个部分归入以下三类，只保留第一类：

类别	放在哪里	示例
机制	skill	数学、状态模型、顺序约束、预算
衬托	仅用于演示	调色板、文案、图像、页面布局、品牌
偶然细节	不保留	选择器名称、字体选择、一次性资源路径

从 skill 正文中移除项目专属选择器和偶然的资源路径，让机制可复用。在演示中保留经批准的参考呈现：相同的自有品牌、调色板、字体处理、构图、资源放置、氛围和动态层级。通过缩小演示所讲解和控制的范围来突出技巧，而不是另造一种视觉风格。

将每条规则都锚定到它要避免的故障

说明错误结果，而不是正确的形容词。明确指出故障的规则可以测试；没有明确故障的规则只是装饰。

• 弱：「调整粒子的旋转角度，营造自然的感觉。」
• 强：「让旋转由翻滚角度驱动，并与其相差 90 度。独立的正弦曲线会看起来像晃动，也可能像缓动故障。」

如果你说不出会出什么问题，那你可能从未测试过另一种做法，这条规则或许并不成立。删掉它，或者去查明真相。

写具体数字，不用形容词

写出最终实际采用的常量。「微妙」无法使用；0.3–0.5 则是可供调整的起点。

按层或状态说明取值范围、时序和缓动、大小和间距、预算（dt 上限、DPR 上限、实例数量），以及任何用于权衡不同数值的公式。如果某个值是通过测量而非凭感觉调出的，请说明测量了什么。

三个或更多参数会一起变化时，优先用简短表格，而不是文字说明。

保留代价高昂的陷阱

最有价值的规则，往往是那些要花数小时才能发现、无法仅靠阅读代码重新推导出来的规则。通常包括：

• 色彩空间——某个值在编辑器里看起来正确，在屏幕上却不对，因为两者之间发生了解码或色调映射。
• 布局时序——代码只测量一次，只有布局已完成时才正确；解决办法是使用观察器，而不是延长超时时间。
• 堆叠与合成——某个元素无法显示在另一个元素之上，因为上面三层祖先元素创建了堆叠上下文。
• 顺序——两个操作单独都正确，顺序一换就会出错。
• 平台怪癖——某个属性在一种引擎中会静默失效。

把这些分别写成独立规则，并先写出症状，让读者能认出眼前的故障。

在开头几行说明适用边界

指出最接近的现有 skill，并说明何时应改用它。开始前先搜索 agent-skills/*/*/SKILL.md；如果某个 skill 已涵盖相关机制，就扩展它，而不是另加一个近似重复的 skill。

两个 skill 都声称能「添加粒子」，却没有说明适用边界，就意味着两者都无法被正确选用。

将无障碍支持与生命周期纳入其中

对于网页设计 skill，这些属于机制本身，而不是附录：

• 在 prefers-reduced-motion: reduce 下，渲染一帧精心设计的静止画面。不要隐藏效果；构图本就包含了它。保持控件可用，让它们仍能发挥作用。
• 在 document.hidden 时以及区块离开视口时暂停。恢复时重置时间基准，避免第一帧将整个暂停时段都纳入计算。
• 将 dt 限制在约 1/30 秒。将设备像素比上限设为 2。
• 使用 ResizeObserver 确定尺寸，并在视口为零时为构建步骤设置保护。
• 控件应使用真正的表单元素，支持键盘访问，显示清晰的焦点状态，并提供用于播报变更的实时区域。

如实说明开销

说明实际开销所在，并在下结论前进行测量。通过分析性能，而不是靠猜：看起来最耗资源的部分往往并非如此。指出真正的瓶颈、低成本的优化手段，以及无关紧要的因素。

说明收益最高、成本最低的优化手段——对于循环复用的粒子场，缩窄生成带比增加数量更有效，因为屏幕密度等于数量 ÷ 面积。

记录设计的来源

在 SKILL.md 中用一行说明来源：项目是什么，其中的机制负责什么。读者需要了解它经受考验的背景，才能判断这项 skill 是否适用于自己——「从一处深色 WebGL 京都夜景中提炼而来，必须确保文字上方的内容清晰可读」比再多描述都更有帮助。

演示应还原这种来源——见下文的指导演示。应保留的仅有你无权使用的内容：客户名称和品牌、授权字体、购买或第三方图像。替换这些内容，并复现其余所有内容。

展示演示

**对大多数读者来说，演示是他们唯一会看到的证据。**他们不会阅读源项目，而是会根据这一个文件来评判这项技术。如果某个机制已应用在精心设计的页面上，却通过看起来像测试框架的东西来演示，那它就会显得尚未完成——没人会使用看起来尚未完成的技能。

因此，演示应遵循源项目的工艺标准，而非代码示例的标准。

• **把获批的参考作品当作验收目标，而不是灵感来源。**围绕独立呈现的机制，复现相同的首屏画面、布局几何、配色、字体处理、素材比例、氛围和动效层级。编码前，逐层清点。打开演示的人应该立刻认出源作品，而不必先读它的名称。
• **通过移植生成素材的代码，使用参考作品自身的素材。**如果源作品会生成天空、月亮、纹理和剪影，就原样移植这些函数。用手写 CSS 近似程序生成的月亮，得到的只会是一个扁平圆盘；而真正带有月海和陨石坑的月亮与它并排时，差异一目了然。移植生成器不会增加运行时开销，能让演示保持为单个自包含文件，也能让场景真正一致，而不仅仅是相似。
• **为保证还原度所必需的自有参考素材，应随技术一并移植。**复制演示所需的最小本地素材集，并记录其来源。精确还原自有场景优先于单文件偏好；可移植的本地素材包，胜过不再匹配的自包含近似版本。不得移植任何不属于你的内容：客户品牌、授权字体、购买的图片或第三方媒体。
• 在首屏展示该机制——无需滚动，也无需交互。如果必须点击才能看到重点，说明呈现方式不对。
• **当机制涉及时间或滚动时，验证完整的状态路径。**开场画面必须建立场景并展示其控制元素，但仅凭它无法证明跨场景旅程。对比每个设计好的关键状态，以及正向、反向、快速跳过和深度位置重新加载时的路径；英雄区再完美，也不能掩盖第三章的故障。
• **保留决定布局的参考文案。**如果更改标题或正文会改变获批的构图，就原样保留，并将技术名称、已验证的技术栈和机制说明放入浏览器标题，以及参考作品现有的辅助面板、控件、微文案或无障碍描述中。不要为了说明性标题牺牲视觉还原度，但也绝不能让实现内容无法辨认。
• **保持系列感。**从同一参考作品中提取的两种技术，应该生成看起来像同一系列的两个演示。共享参考作品的演示库会给人一组完整作品的感觉；各自凭空创造世界的演示库看起来则像零散片段。

以下是文案规则的示例，适用于按单位距离发射粒子的 Canvas 2D 轨迹：

Vanilla JavaScript · Canvas 2D

幽光

按距离发射的 Canvas 2D 粒子，无论手速如何，间距都保持一致；CSS 仅用于设置界面样式。将发射方式切换为定时器后，同样的手势就会散开——快速划过会留下零散的点，而手停住时则会在同一处堆积。无需 WebGL、着色器或 Three.js。

标题点明效果。引导语标明技术栈。正文说明机制、失败情形和任何可能引起实现歧义的地方。正文提到的控件会显示在屏幕上，读者可以据此核验说法。

• **每个屏幕只讲一个要点。**证明三件事的演示，往往一件也证明不了。
• 控件应以真实表单元素呈现重要状态，并证明系统支持参数配置，而非预先写死。跳过那些只是重复呈现已有内容的控件。

质量底线

每次都必须满足以下各项：

• 采用经过斟酌的字体比例，明确最大和最小字号层级——绝不使用浏览器默认值
• 间距遵循统一节奏
• 配色克制，只有一种强调色，并且承载明确含义
• 为所有交互控件设置样式，包括焦点状态
• 首屏展示具体的技术名称，以及经过验证的运行时、渲染器和主要技术库
• 使用来自合理项目的真实、具体文案——绝不出现“卡片标题”或“演示区块”
• 只要精确参考允许，就使用一个独立文件；否则，使用最精简的本地自有资源包，且不依赖远程运行时
• 适配 390px 至 1440px，使用语义化 HTML，焦点清晰可见，并确保两种尺寸下控制台干净无报错

如果演示放在提取它的页面旁边会让你觉得难堪，那它就还没完成。

在浏览器中验证，然后汇报

不要只读文件就声称视觉或交互行为符合预期。实际运行它：

1. 在 1440×900 和 390×844 尺寸下加载演示。
2. 确认可见标题标明技术名称，且技术栈说明与源代码导入、渲染器和上下文创建方式一致。
3. 操作主要交互，确认状态确实发生变化。
4. 对于滚动、时间线或多状态技术，向前和向后遍历所有编写好的状态，快速跳过状态间的衔接处，并在非零状态下重新加载。
5. 使用 Tab 键遍历页面，确认焦点可见且顺序合理。
6. 运行减少动态效果模式，确认复合画面能够渲染且动画停止。
7. 确认两种尺寸下控制台均无报错。
8. 按照仓库的共享尺寸截取预览图。
9. 在源页面的视口尺寸下并排比较演示和源页面。对于多状态技术，比较每个有代表性的关键状态。在润饰单独效果之前，先修复层级、裁剪、缩放、对齐和氛围方面的结构偏差。

预计这轮检查会发现问题。发现后，修复演示并重新运行，不要放宽要求。

打包并提交

agent-skills/<category>/<skill-name>/
  SKILL.md
  agents/openai.yaml
  demo/
    index.html
    PROMPT.md
    preview.jpg
    reference.*        # optional owned staging required for exact fidelity

以祈使句形式编写 SKILL.md，frontmatter 中只包含 name 和 description，并将所有触发短语写入描述。为 demo/PROMPT.md 设置三个标题：最简提示词、重现演示、混搭提示词；其中混搭提示词要在保留实现机制和预算的同时，更换主题、配色和构图。

只暂存新文件夹及其所需的画廊条目。提交前检查 git diff --cached --stat，并保留预先存在的脏文件不变。

验证

• 更换主体、调色板和布局后，机制描述依然成立
• 可见标题直接点明技术，而不是使用抽象的机制描述
• 首屏说明已验证的运行时、渲染器或浏览器 API，以及主要技术库
• 演示中包含暂存内容，而不是技能正文
• 每条规则都说明它能防止的问题
• 常量使用真实数值，而不是形容词
• 代价高昂的注意事项从症状入手描述
• 开头几行说明了与最相近的现有技能之间的界限
• 来源信息用一行背景说明点明源项目
• 演示能让人一眼认出是参考作品——调色板、字体、构图和氛围都一致
• 已在源视口下并排比较源文件和演示；没有残留结构偏差
• 已移植参考作品自带的生成器；若无法实际隔离精确代码，则已打包最小的自有参考资源
• 没有带入任何非自有内容；演示以单个文件交付，或仅附带有充分理由的最小自有资源包
• 同一参考作品的演示看起来像同系列作品
• 演示自身的文案说明了机制，并点明它能防止的问题
• 演示在首屏就展示机制，无需滚动或交互
• 已验证滚动、时间轴或多状态机制的每个关键状态、反向过程、快速跳过情况，以及深度滚动后重新加载的表现
• 将演示放在其源页面旁边展示也不会令人尴尬
• 字号层级、间距节奏和调色板都经过精心设计，而非使用默认值
• 减少动态效果时呈现的是经过设计的静态画面，而非隐藏元素
• 成本声明基于实际测量，而非假设
• 已在浏览器中以两个断点测试演示，且控制台无错误
• 仅暂存新的技能文件夹