Web Technique to Skill

将Web技术转化为可复用技能

Start from working code, not from prose. Reach for

article-prompts-to-skills

when the source is an article or a prompt pack that describes behavior. Reach for this when you built the thing, it works, and the knowledge is currently trapped in one file.

Extract one mechanism per skill. A page that turned out well usually holds several; package them separately or each one gets diluted.

Treat this as the living quality contract for every web-technique skill. On every creation or revision, audit this skill too. If the work exposes a missing fidelity rule, failure mode, packaging constraint, or verification step, update this contract in the same scoped change instead of solving it only inside one child skill.

从可运行的代码入手，而非文字描述。如果源内容是描述行为的文章或提示包，请使用

article-prompts-to-skills

流程；当你已经完成开发、效果可用，但相关知识仍局限在单个文件中时，使用本流程。

每个技能仅提取一个核心机制。一个效果出色的页面通常包含多个机制，请分别打包，否则每个机制都会被弱化。

将本指南视为所有Web技术技能的动态质量契约。在创建或修订任何技能时，都需对照本指南进行审核。如果开发过程发现了缺失的保真规则、故障模式、打包约束或验证步骤，请在同一范围内更新本契约，而非仅在单个子技能中解决问题。

Name the mechanism in one sentence

用一句话定义核心机制

Write the sentence before you write anything else: the one thing that, if removed, makes the effect stop working. If you cannot write it, you have a look, not a mechanism, and there is no skill here yet.

The sentence decides everything downstream. For a leaf fall it is "the tumble crosses edge-on, and that instant of near-disappearance is what the eye reads as a leaf" — so the sprite artwork, the palette, and the night scene are all staging, and the tumble is the skill.

Test it: change the subject, the palette, and the layout in your head. If the sentence still holds, it is the mechanism. If it stops making sense, you named the staging.

在撰写任何内容前先写下这句话：移除后会导致效果失效的那个核心逻辑。如果你无法写出这句话，说明你只有视觉效果，没有核心机制，目前还不能称之为技能。

这句话将决定后续所有内容。以树叶飘落效果为例，核心机制是“树叶翻滚至边缘视角的瞬间近乎消失，这正是人眼识别为树叶飘落的关键”——因此精灵图、调色板、夜景场景都属于场景配置，而翻滚逻辑才是技能核心。

验证方法：在脑海中替换主题、调色板和布局。如果这句话仍然成立，那它就是核心机制；如果逻辑不再通顺，说明你命名的是场景配置。

Name the demo and disclose the stack

命名演示并披露技术栈

Use the concrete technique name for the visible

h1

and browser

<title>

: Wisps, Cursor Ripples, Liquid Metal Border, or Scroll-scrubbed Word Reveal. Do not hide the subject behind an abstract mechanism claim. “Draw at any speed” describes behaviour, but it does not tell anyone what the demo is.

Put the verified implementation path directly above or below that title. Name, in order:

The runtime or framework: Vanilla JavaScript, React, Vue
The renderer or browser API: Canvas 2D, WebGL, DOM/CSS, SVG
The technique layer when present: GLSL shaders, Three.js, GSAP, ScrollTrigger

Write Vanilla JavaScript · Canvas 2D or Three.js · WebGL · GLSL, not “interactive experiment” or “motion study.” Never guess from the look. Verify imports, renderer construction, and context creation in the source.

getContext('2d')

is Canvas 2D, not a shader;

WebGLRenderer

plus

ShaderMaterial

is Three.js, WebGL, and GLSL. When the visual could be mistaken for a more complex stack, state the absence plainly: No WebGL, shaders, or Three.js.

Separate the effect stack from the interface stack when they differ. Write Vanilla JavaScript + Canvas 2D effect; CSS interface instead of listing CSS beside Canvas 2D as if both render the particles. Readers should know which technology creates the technique and which technology only lays out its controls.

If an approved reference headline must remain for layout fidelity, keep it and put the technique name plus stack in the browser title and the reference's existing kicker, control panel, or secondary label. The implementation must still be obvious on the first screen.

使用具体的技术名称作为可见的

h1

标题和浏览器

<title>

：Wisps、Cursor Ripples、Liquid Metal Border或Scroll-scrubbed Word Reveal。不要用抽象的机制描述掩盖主题。“支持任意速度绘制”描述了行为，但无法让人知道演示的具体内容。

在标题的上方或下方直接标注已验证的实现路径，按顺序列出：

运行时或框架：Vanilla JavaScript、React、Vue
渲染器或浏览器API：Canvas 2D、WebGL、DOM/CSS、SVG
相关技术层（如有）：GLSL shaders、Three.js、GSAP、ScrollTrigger

请写Vanilla JavaScript · Canvas 2D或Three.js · WebGL · GLSL，而非“交互实验”或“动效研究”。绝不要仅凭视觉猜测，务必在源码中验证导入内容、渲染器构造和上下文创建。

getContext('2d')

对应Canvas 2D，而非着色器；

WebGLRenderer

搭配

ShaderMaterial

对应Three.js、WebGL和GLSL。当视觉效果可能被误认为是更复杂的技术栈实现时，需明确声明未使用的技术：未使用WebGL、着色器或Three.js。

当效果技术栈与界面技术栈不同时，请分开说明。例如写Vanilla JavaScript + Canvas 2D实现效果；CSS实现界面，而非将CSS与Canvas 2D并列，让读者误以为两者都用于渲染粒子。读者需要清楚了解哪些技术用于实现核心技能，哪些仅用于布局控件。

如果为了布局保真度必须保留已获认可的参考标题，请保留该标题，并将技术名称和技术栈添加到浏览器标题以及参考内容现有的副标题、控制面板或次要标签中。实现信息必须在首屏即可清晰识别。

Split mechanism from staging

分离核心机制与场景配置

Sort every part of the source into three piles and keep only the first:

pile	goes where	examples
mechanism	the skill	the maths, the state model, the ordering constraint, the budget
staging	the demo only	palette, copy, imagery, page layout, brand
incidental	nowhere	selector names, a font choice, a one-off asset path

Strip project selectors and incidental asset paths from the reusable mechanism in the skill body. Keep the approved reference staging in the demo: the same owned brand, palette, type treatment, composition, asset placement, atmosphere, and motion hierarchy. Isolate the technique by narrowing what the demo teaches and controls, not by inventing a different visual world.

将源码的每个部分分为三类，仅保留第一类：

分类	去向	示例
核心机制	技能主体	数学逻辑、状态模型、排序约束、性能预算
场景配置	仅用于演示	调色板、文案、图片、页面布局、品牌元素
无关内容	弃用	选择器名称、字体选择、一次性资源路径

从技能主体的可复用机制中移除项目专属选择器和无关资源路径。在演示中保留已获认可的参考场景配置：相同的专属品牌、调色板、字体样式、构图、资源位置、氛围和动效层级。通过缩小演示的教学和控制范围来隔离核心技术，而非创造一个完全不同的视觉环境。

Anchor every rule to the failure it prevents

每条规则都锚定其预防的故障

State the wrong result, not the right adjective. A rule with a named failure is testable; a rule without one is decoration.

Weak: "vary the particle rotation for a natural feel."
Strong: "drive rotation from the tumble angle, ninety degrees out of phase. An independent sine reads as a wobble or as an easing bug."

If you cannot name what goes wrong, you probably never tested the alternative, and the rule may not be real. Cut it or go and find out.

说明错误结果，而非正确的形容词。带有明确故障描述的规则是可测试的；没有故障描述的规则只是装饰。

弱规则：“调整粒子旋转以实现自然效果。”
强规则：“根据翻滚角度驱动旋转，相位差90度。若使用独立正弦函数，会呈现出抖动或缓动错误的效果。”

如果你无法说明会出现什么问题，可能从未测试过替代方案，这条规则可能并不成立。要么删除它，要么去验证清楚。

Carry numbers, not adjectives

使用具体数值，而非形容词

Ship the constants you actually landed on. "Subtle" is unusable;

0.3–0.5

is a starting point someone can adjust.

Include ranges per layer or state, timing and easing, size and spacing, budgets (

dt

clamp, DPR cap, instance counts), and any formula that trades one quantity against another. Where a value was tuned by measurement rather than taste, say what was measured.

Prefer a small table over prose when three or more parameters vary together.

交付你实际确定的常量值。“微妙的”毫无用处；

0.3–0.5

是他人可以调整的起点。

包含各层或各状态的范围、时间与缓动参数、尺寸与间距、性能预算（

dt

限制、DPR上限、实例数量），以及任何用于权衡不同量化指标的公式。如果某个值是通过测量而非主观偏好确定的，请说明测量对象。

当三个或更多参数联动时，优先使用小型表格而非文字描述。

Keep the expensive gotchas

记录耗时踩过的坑

The rules worth most are the ones that cost hours and cannot be re-derived by reading the code. They are usually one of:

Colour space — a value that looks right in the editor and wrong on screen because something decodes or tone-maps between the two.
Layout timing — code that measures once and is correct only if layout already happened; the fix is an observer, not a longer timeout.
Stacking and compositing — an element that cannot rise above another because of a context created three ancestors up.
Ordering — two correct operations that are wrong in one order.
Platform quirks — a property that silently no-ops on one engine.

Write these as their own rule with the symptom first, so the reader recognises the bug they are currently staring at.

最有价值的规则是那些花费数小时才发现、无法通过阅读代码直接推导出来的经验。通常包括以下几类：

色彩空间——在编辑器中显示正常，但在屏幕上显示异常，因为两者之间存在解码或色调映射差异。
布局时机——仅在布局完成后才正确的一次性测量代码；解决方案是使用观察者，而非更长的超时时间。
堆叠与合成——由于三层祖先元素创建的上下文，某个元素无法显示在另一个元素上方。
执行顺序——两个单独正确的操作，按错误顺序执行时会出错。
平台特性——在某个引擎上静默失效的属性。

将这些内容作为独立规则，先描述症状，让读者能够识别他们当前遇到的问题。

Declare the boundary in the opening lines

在开篇明确技能边界

Name the nearest existing skill and say when to reach for it instead. Search

agent-skills/*/*/SKILL.md

before you start; if a skill already covers the mechanism, extend it rather than adding a near-duplicate.

Two skills that both "add particles" with no stated boundary means neither gets picked correctly.

列出最相近的现有技能，并说明何时应使用该技能替代当前技能。开始前请搜索

agent-skills/*/*/SKILL.md

；如果已有技能覆盖该核心机制，请扩展该技能，而非添加一个近似重复的技能。

如果两个技能都“添加粒子”但未明确边界，用户将无法正确选择使用哪一个。

Fold in accessibility and lifecycle

融入无障碍与生命周期管理

For web-design skills these are part of the mechanism, not an appendix:

Under
```
prefers-reduced-motion: reduce
```
, render a designed still frame. Do not hide the effect; the composition was built with it in. Keep controls live so they still do something.
Pause on
```
document.hidden
```
and when the section leaves the viewport. Reset the time base on resume so the first frame does not integrate the whole pause.
Clamp
```
dt
```
to about 1/30 s. Cap device pixel ratio at 2.
Size from a
```
ResizeObserver
```
, and guard any build step against a zero viewport.
Keep controls as real form elements, keyboard reachable, with visible focus and a live region for changes.

对于Web设计技能而言，这些内容是核心机制的一部分，而非附录：

当
```
prefers-reduced-motion: reduce
```
时，渲染经过设计的静态帧。不要隐藏效果，因为构图是围绕该效果构建的。保持控件可用，确保用户仍能进行操作。
当
```
document.hidden
```
或元素移出视口时暂停效果。恢复时重置时间基准，避免第一帧整合整个暂停时段的时长。
将
```
dt
```
限制在约1/30秒。将设备像素比上限设为2。
通过
```
ResizeObserver
```
调整尺寸，并防止构建步骤出现零视口的情况。
控件使用真实的表单元素，支持键盘访问，具有可见的焦点状态，并为变更提供实时区域提示。

State the cost honestly

如实说明性能成本

Say what is actually expensive, and measure before claiming it. Profile rather than guess: the part that looks heavy often is not. Name the real bottleneck, the cheap lever, and the thing that does not matter.

Report the lever that buys the most for the least — for a recycled particle field, tightening the spawn band beats raising the count, because on-screen density goes as count ÷ area.

明确说明真正消耗性能的部分，并在宣称前进行测量。通过性能分析而非猜测：看起来繁重的部分往往并非瓶颈。指出真正的瓶颈、低成本的优化手段，以及无关紧要的因素。

报告性价比最高的优化手段——对于循环利用的粒子场，收紧生成范围比增加粒子数量更有效，因为屏幕密度与粒子数量÷面积成正比。

Record where the design came from

记录设计来源

Write one line in

SKILL.md

naming the source: what the project was, and what the mechanism was doing in it. A reader decides whether the skill applies to them by understanding the context it survived — "extracted from a dark WebGL Kyoto night scene where it had to stay legible over type" tells them more than any amount of description.

The demo should look like that source — see Direct the demo below. What stays behind is only what you do not own: a client's name and brand, licensed fonts, purchased or third-party imagery. Substitute those and reproduce everything else.

在

SKILL.md

中用一行文字说明来源：项目是什么，该机制在项目中的作用。读者会通过了解该技能所经历的上下文来判断是否适用——“提取自深色WebGL京都夜景场景，需在文字上方保持清晰可见”比任何描述都更有价值。

演示应与来源一致——参见下方的演示设计要求。仅保留非专属内容：客户名称和品牌、授权字体、付费或第三方图片。替换这些内容，其余部分完全复现。

Direct the demo

演示设计要求

The demo is the only evidence most readers will ever see. They will not read the source project, and they will judge the technique by this one file. A mechanism that shipped on a considered page, demonstrated by something that looks like a test harness, reads as unfinished — and nobody reaches for a skill that looks unfinished.

So the demo inherits the craft bar of the source, not the craft bar of a code sample.

Treat the approved reference as an acceptance target, not inspiration. Reproduce the same first frame, layout geometry, palette, type treatment, asset scale, atmosphere, and motion hierarchy around the isolated mechanism. Do a layer-by-layer inventory before coding. Someone opening the demo should identify the source immediately, before reading its name.
Use the reference's own assets, by porting the code that makes them. If the source generates its sky, its moon, its textures, its silhouettes, bring those functions across unchanged. A hand-rolled CSS approximation of a procedurally generated moon is a flat disc next to one with real maria and a crater field, and the gap is obvious the moment they sit side by side. Porting a generator costs nothing at rest, keeps the demo one self-contained file, and makes the staging genuinely the same rather than merely similar.
Owned reference assets cross with the technique when they are necessary for fidelity. Copy the smallest local set the demo needs and record their provenance. Exact owned staging outranks a one-file preference; a portable local bundle is better than a self-contained approximation that no longer matches. What must not cross is anything you do not own: a client's brand, licensed fonts, purchased imagery, or third-party media.
Show the mechanism on the first screen — before any scroll, before any interaction. If it takes a click to see the point, the framing is wrong.
Verify the whole state path when the mechanism spans time or scroll. The opening frame must establish the world and expose its conductor, but it cannot prove a multi-scene journey by itself. Compare every authored key state plus the forward, reverse, fast-skip, and reload-at-depth paths; a perfect hero does not excuse a broken third chapter.
Preserve layout-defining reference copy. If changing the headline or body would change the approved composition, keep it exactly and put the technique name, verified stack, and mechanism argument into the browser title plus the reference's existing secondary panel, controls, microcopy, or accessible description. Do not trade visual fidelity for an explanatory headline, but never leave the implementation unidentified.
Keep a family. Two techniques pulled from the same reference should produce two demos that look like siblings. A library of demos that share a reference reads as a body of work; a library where each one invents its own world reads as scraps.

A worked example of the copy rule, for a Canvas 2D trail that emits per unit of distance:

Vanilla JavaScript · Canvas 2D

Wisps

Distance-emitted Canvas 2D particles keep the same spacing at any hand speed; CSS styles the interface only. Switch emission to a timer and the same gesture breaks apart — a fast pass leaves scattered dots, while a resting hand piles them on one spot. No WebGL, shaders, or Three.js.

The title names the effect. The kicker identifies the stack. The body states the mechanism, the failure, and any likely implementation ambiguity. The control named in the body is on screen, so the reader can check the claim.

One idea per screen. A demo proving three things proves none of them.
Controls expose states that matter, as real form elements, and prove the system is parameterised rather than baked. Skip controls that only restate what is already visible.

演示是大多数读者唯一会看到的证据。他们不会阅读源项目，只会通过这个文件判断技术的价值。如果一个在精心设计的页面上运行的机制，其演示看起来像测试工具，会给人一种未完成的印象——没人会使用看起来未完成的技能。

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

将已获认可的参考作为验收目标，而非灵感。围绕隔离的核心机制，完全复现相同的首帧、布局几何、调色板、字体样式、资源比例、氛围和动效层级。编码前进行逐层盘点。打开演示的人应能立即识别出源项目，无需阅读名称。
使用参考项目自身的资源，通过移植生成资源的代码实现。如果源项目生成天空、月亮、纹理、剪影，请完整移植这些函数。手动用CSS模拟的 procedural生成月亮，与带有真实月海和陨石坑的月亮相比，只是一个扁平圆盘，两者的差距一目了然。移植生成器在静态时没有成本，能让演示保持为单个独立文件，并确保场景配置与源项目完全一致，而非仅仅相似。
当专属参考资源对保真度至关重要时，随技术一起迁移。复制演示所需的最小本地资源集，并记录其来源。精确的专属场景配置优于单文件偏好；可移植的本地包优于不再匹配源项目的独立近似实现。不得迁移非专属内容：客户品牌、授权字体、付费图片或第三方媒体。
在首屏展示核心机制——无需滚动或交互。如果需要点击才能看到核心效果，说明框架设计有误。
当机制涉及时间或滚动时，验证完整的状态路径。首帧必须构建场景并展示控制器，但无法单独证明多场景流程的有效性。比较所有预设关键状态，以及正向、反向、快进和深度重载路径；完美的首屏效果无法掩盖第三章节的故障。
保留定义布局的参考文案。如果修改标题或正文会改变已获认可的构图，请完全保留原文，并将技术名称、已验证的技术栈和机制说明添加到浏览器标题以及参考内容现有的次级面板、控件、微文案或无障碍描述中。不要为了解释性标题而牺牲视觉保真度，但永远不要让实现信息模糊不清。
保持风格统一。从同一参考项目中提取的两个技术，其演示应看起来像“姊妹篇”。共享同一参考的演示库会给人一种体系化成果的感觉；每个演示都创造独立视觉世界的库则显得杂乱无章。

以下是Canvas 2D距离触发轨迹效果的文案规则示例：

Vanilla JavaScript · Canvas 2D

Wisps

基于距离触发的Canvas 2D粒子在任意手势速度下保持相同间距；仅使用CSS样式化界面。切换为基于时间触发后，同一手势会出现效果断裂——快速滑动会留下零散的点，而静止手势会在同一位置堆积大量粒子。未使用WebGL、着色器或Three.js。

标题命名效果，副标题说明技术栈，正文阐述核心机制、故障情况和可能的实现歧义。正文中提到的控件需在屏幕上可见，以便读者验证说法。

一屏一个核心概念。一个演示同时证明三个概念，相当于一个都没证明。
控件展示关键状态，使用真实表单元素，证明系统是参数化的而非硬编码的。跳过仅重复可见内容的控件。

Quality floor

质量底线

Every one of these, every time:

A deliberate type scale with a considered largest and smallest step — never browser defaults
Spacing on one consistent rhythm
A restrained palette with one accent that carries meaning
Every interactive control styled, including its focus state
A concrete technique title plus the verified runtime, renderer, and major technique libraries on the first screen
Real, specific copy from a plausible project — never "Card title" or "Demo section"
One self-contained file when the exact reference permits it; otherwise a minimal local bundle of owned assets with no remote runtime dependency
390px through 1440px, semantic HTML, visible focus, and a clean console at both ends

If the demo would embarrass you next to the page you extracted it from, it is not finished.

每次都必须满足以下所有要求：

采用精心设计的字体比例，明确最大和最小步长——绝不要使用浏览器默认值
遵循统一的间距节奏
使用克制的调色板，其中一个强调色具有明确含义
所有交互控件都经过样式设计，包括焦点状态
首屏显示具体的技术标题，以及已验证的运行时、渲染器和主要技术库
使用来自真实项目的具体文案——绝不要使用“卡片标题”或“演示章节”
当精确参考允许时，使用单个独立文件；否则使用最小的本地专属资源包，无远程运行时依赖
支持390px至1440px的视口尺寸，使用语义化HTML，焦点可见，两端尺寸下控制台均无报错

如果演示放在源项目页面旁边会让你感到尴尬，说明它还未完成。

Verify in a browser, then report

在浏览器中验证并记录

Do not claim visual or interaction behavior from reading the file. Drive it:

Load the demo at 1440×900 and 390×844.
Confirm the visible title names the technique and the stack disclosure matches the source imports, renderer, and context creation.
Exercise the primary interaction and confirm the state actually changes.
For scroll, timeline, or multi-state techniques, traverse every authored state forward and backward, fast-skip across seams, and reload at a nonzero state.
Tab through and confirm focus is visible and ordered.
Run the reduced-motion path and confirm a composed frame renders and animation stops.
Confirm the console is clean at both sizes.
Capture the preview at the repository's shared dimensions.
Compare the demo and source side by side at the source viewport. For multi-state techniques, compare every representative key state. Fix structural drift in hierarchy, crop, scale, alignment, and atmosphere before polishing the isolated effect.

Expect this pass to find something. When it does, fix the demo and re-run rather than softening the rule.

不要仅通过阅读文件就宣称视觉或交互行为符合要求。实际运行并验证：

在1440×900和390×844分辨率下加载演示。
确认可见标题命名了技术，且技术栈披露与源码导入、渲染器和上下文创建一致。
执行主要交互操作，确认状态确实发生变化。
对于滚动、时间轴或多状态技术，正向和反向遍历所有预设状态，快速跳过过渡阶段，并在非零状态下重新加载。
通过Tab键遍历，确认焦点可见且顺序正确。
运行减少动效路径，确认渲染了经过设计的静态帧且动画停止。
确认两种尺寸下控制台均无报错。
按照仓库的统一尺寸捕获预览图。
在源项目视口尺寸下将演示与源项目并排对比。对于多状态技术，比较所有代表性关键状态。在优化隔离效果前，修复层级、裁剪、缩放、对齐和氛围方面的结构性偏差。

预计此步骤会发现问题。如果发现问题，请修复演示并重新验证，而非放宽规则。

Package and commit

打包并提交

text

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

Write

SKILL.md

in imperative form with only

name

and

description

in frontmatter, and put every trigger phrase in the description. Give

demo/PROMPT.md

three headings: Minimal prompt, Recreate the demo, Remix prompt, where the remix changes subject, palette, and composition while preserving the mechanism and the budgets.

Stage only the new folder and the gallery rows it needs. Review

git diff --cached --stat

before committing, and leave pre-existing dirty files alone.