从 API 文档到 Skill.md:组件库正在换一种方式活着,每个组件都是一份AI-Skill

一个你可能没注意到的变化

ThreeUI 做了一件很新奇的事。

ThreeUI 它是一个 3D 特效组件库——文字动画、按钮、背景、场景，全部用 WebGL/Canvas 2D 实现。页面结构跟普通组件库差不多：演示、代码、用法。

官网是：https://threeui.com/browse

但是你看下一下它的每个组件下面，多了一个东西：Skill.md。

不是文档。不是 README。不是 Storybook 的另一种形态。

而是一份写给 AI Agent 读的"技能卡"。

AI 读完这份 Skill.md，就知道这个组件是什么、Props 怎么传、什么场景该用、什么场景不该用、怎么和其他组件组合、有什么坑。然后直接在你项目里组装。不需要人读文档。不需要人指导。人只审核结果。

这不是组件库的小改版。这是AI当下组件库的物种变异。

web/h5端的基础设施框架需要去迎合并适应当下的AI时代下的新需求。

我们经历过的三个时代

远的我们不去考虑，就简单看看从现在到过去五年的变化，前端用组件的方式变了三次：

2020-2023：人读文档，人写代码。

你打开 Ant Design 官网，看 API 表格，记住 Props，在项目里 import 使用等等。这些文档的读者是人，一直是人。

2024-2025：AI 辅助人写代码。

Claude、Cursor 、Codex等等AI 工具的出现。你发现 AI 写注释，AI 代码补全等等。但组件还是你要去装 npm 包、你还是需要去读文档、你决定怎么用。AI 还是初级辅助阶段，还无法去自主智能的读取网页文档等等。

2026：AI 直接消费组件。

AI 读 Skill.md，理解组件能力，直接在你项目里组装代码。有时候直接一个页面地址即可，或者一个名称就可以了，人已经不再去读文档了——人只审核结果。人不需要关心过程是什么。只需要 AI 做的东西满足我的需求即可。

ThreeUI 的 Skill.md，就是第三个时代的产物。这个东西我之前在其他的组件库中并没有发现。

简单的例子：Circle Buttons

ThreeUI 有一个组件叫 circle-buttons。三个圆形图标按钮——Play、Plus、Mail。

我用这个例子，把我们之前的组件库传统文档和 Skill.md 放在一起，你自己看区别。

之前的组件文档长这样（我假设的）：

## CircleButtons### Props| Prop | Type | Default | Description ||------|------|---------|-------------|| variant | 'play' \| 'plus' \| 'mail' | 'play' | 按钮变体 || mode | 'dark' \| 'light' | 'dark' | 主题模式 || size | number | 64 | 按钮直径(px) || onClick | () => void | - | 点击回调 |### 用法```tsximport { CircleButtons } from '@threeui/circle-buttons';<CircleButtons variant="mail" mode="dark" />```

这是给开发人员看的。当然 AI 也能读，但它不知道：

•什么时候该用这个组件，什么时候不该用

•这个组件和 Rectangle Buttons 什么关系

•移动端会不会有问题

•有没有性能坑

•怎么和其他组件配合

•等等其他

ThreeUI 的实际 Skill.md 长这样：

---name: add-circle-buttonsdescription: "Build Circle Buttons from its verified authored source using DOM + CSS,including the complete renderer, interactions, and required assets. Use when Codexneeds to implement, port, or adapt this effect without requiring the ThreeUI packageor reconstructing the visual from an approximation."---# Build Circle Buttons## DescriptionThree compact circular icon controls using the exact Dark Glass, Launch, and Dot Bordermaterial systems.Recreate the authored behavior from the verified source, not from screenshots or theabbreviated orchestration sample in this skill. The implementation may live directlyin the target project and does not require `@designcodeio/threeui`.## Technologies- React and TypeScript- Semantic button elements- Scoped layered CSS- Inline SVG icons- Light and dark palette controls- Reduced-motion fallback## Verified source material-`src/shaders/circle-buttons/CircleButtons.tsx`-`src/shaders/circle-buttons/circle-buttons.css`Source revision: `SHA-256 2e85693f7ada`## Implementation steps1. Open every verified source file listed above and identify the renderer, host   lifecycle, styles, and assets before editing.2. Use CircleButtons as the public entry point and select play, plus, or mail   with the variant prop.3. Keep every variant circular, icon-only, and compact at its responsive 56–72px   default; provide ariaLabel when the surrounding action needs a more specific   accessible name.4. Map each treatment directly to its Rectangle Buttons source: Dark Glass for Play,   Launch for Plus, and Dot Border for Mail, including the original material tokens   and motion timing.5. Keep hover, keyboard focus, pressed, disabled, and reduced-motion behavior intact   when adapting the control to another layout.6. Use mode and palette controls at the component boundary rather than rewriting the   internal highlight and shadow layers.7. Give the local component a sized, overflow-controlled parent and verify desktop,   mobile, reduced-motion, and context-loss behavior.Asset handling: This effect has no required external assets.## Local component exampleImport the copied local component rather than a package entrypoint:```tsximport { CircleButtons } from "./effects/circle-buttons/CircleButtons";import "./effects/circle-buttons/styles.css";export function Scene() {  return <div className="effect-frame"><CircleButtons /></div>;}```## Core renderer patternThis excerpt documents orchestration only. Copy the exact shader, geometry, pass,and interaction code from the verified source files.```tsx<CircleButtons variant="mail" mode="dark" ariaLabel="Open inbox" />```## Behavior contract- Runtime: DOM + CSS- Passes: 1 layered DOM/CSS circle composition- Interaction: Source-faithful hover and press behavior, focus-visible ring,  reduced-motion fallback, and adaptive light/dark palette- Assets: Inline SVG icons; no external runtime assets-**renderer** (host): Semantic button + scoped layered CSS-**variants** (fixed): Play + Plus + Mail-**materials** (fixed): Dark Glass + Launch + Dot Border-**size** (responsive): 56–72px diameter-**theme** (adaptive): Dark (default) | Light-**interaction** (adaptive): Hover | Focus | Press | Disabled | Reduced motion-**assets** (embedded): Three inline SVG icons## Verification1. Compare the rendered composition, animation timing, pointer behavior, and state   transitions with the source implementation.2. Exercise resize, high-DPI, mobile/coarse-pointer, reduced-motion, tab visibility,   and WebGL context-loss paths where applicable.3. Confirm every animation frame, observer, listener, geometry, buffer, texture,   framebuffer, material, and renderer is released on teardown.4. Check the browser console and confirm the effect renders at native-or-better   backing resolution.## Guardrails- Do not substitute a visually similar package, demo, shader, or runtime.- Do not approximate, reconstruct, or simplify the authored GLSL, render passes,  geometry, interaction state, or assets.- Keep exact source and asset hashes under regression tests when the source project  provides them.- Adapt only the surrounding host boundary needed by the target project; keep  renderer behavior intact.

如果大家英文看不懂的，大家去翻译一下再看，但是我们看这份文档的结构就非常清楚了。相关文案描述看不懂不重要的。

你看到什么区别了吗？

传统文档很简单直白的，告诉你"这个组件有什么 Props"，因为就是一个按钮所有就没有然后了。

但是 Skill.md 告诉你：

前者是基本的字典而已。后者是一个组件库使用开发教练员。

前者让人记住。后者让 AI 做对。

AI 编程中很重要的就是做对。人可以不关心这个是什么，但是AI 你不能错。

这不是简单的文档升级，这是“物种变异”

当下我可以激进一点：如果当前你在开发组件库还在写传统 API 文档，你已经过时了。

不是你的文档不够好。是文档的读者或者说使用对象变了。

之前简单讲过的2020-2023 年，文档的读者是人。你要写得清楚、有示例、有截图。有时候文档写的太差，你在使用的时候是否也骂过街呢？

2026 年，文档的第一读者是 AI Agent。你要写得结构化、有约束、有验证。

AI 不需要"好看"的文档。AI 需要"能用"的技能卡。 好不好看不重要，能用且是正确的才是重要的。

从 ThreeUI 写的 Skill.md 做了几件我认为还算是颠覆性的事：

1. 组件的分发方式变了

以前：npm install @threeui/circle-buttons → 读文档 → 写代码。

现在：AI 读 Skill.md → 直接把组件源码复制到你项目 → 你审核。

shadcn/ui 已经验证了这条路——它不是 npm 包，是"可复制的代码"。ThreeUI 的 Skill.md 把这条路推得更远：连"复制"都不需要你自己动手。

AI 直接做，AI 搞定一切。

2. 组件的竞争力变了

以前比谁组件多、API 全、文档好看。

以后比谁的 Skill.md 写得清楚——AI 能不能正确理解和使用。

文档写得不好的组件库，AI 用不对，就等于不存在。 在当下 AI 时代在，文档，Skill.md 一错再错是件很可怕的事情。

3. 前端的工作变了

以前：你记住组件 API，在项目里调用， 版本升级再看下文档更新调用方式。

现在：你定义需求，AI 选组件、组装、调试。你只需要审核结果，中间过程不需要你参与， AI 搞定一切。

你不再需要"记住"50 + 个组件的 Props。

你需要的是判断力——知道什么场景用什么组件、怎么组合、AI 组装的结果对不对。

只需要你的判断力即可。

4. 组件的"正确完整性"

ThreeUI 的 Skill.md 里有 Verification 和 Guardrails 两个章节。

这不是给开发者看的建议。这是给 AI 看的约束条件。

AI 做完之后，按 Verification 清单自检。AI 做的过程中，按 Guardrails 约束自己不犯错。

组件的"正确完整性"不再是"符合 API 文档"，而是"符合 Skill.md 的行为契约"。适应AI的发展为核心要素

给我带来的思考是什么

我说说我的一些判断，原则上是我不讨好，我不中立。大致如下观点：

1. 组件库作为"npm 包"的时代正在结束

不是今天结束，但方向已经明确。

shadcn/ui 证明了"代码即组件"模式可行。 ThreeUI 证明了"Skill.md 即分发"模式可行。 下一步是 AI 直接消费 Skill.md，人完全不碰代码。

畅想一下未来：估计几年后，大部分前端不会 npm install 组件库。AI 会把组件源码直接组装到你的项目里。

如果是这样的话，那么这意味着：

•组件库的版本管理、发布流程、CI/CD 会大幅简化

•组件的"文档"会变成"技能卡"

•组件的"API"会变成"行为契约"

•组建库AI会自行搭建

•等等等

那么我想前端开发工程师应该已经死光了。

2. "写 Skill.md"会成为组件库作者的核心能力

不是写 README。不是写 Storybook。是写 Skill.md。

谁先把组件库的文档从"给人看"改成"给 AI 看"，谁就能吃到 AI 时代的红利。

AI 时代下的适者生存，AI 时代下的丛林法则。

大部分组件库团队还在卷 API 设计、卷 Storybook 插件、卷 Monorepo 工具链。但是有些人他们不知道，他们的文档格式已经过时了。

3. 对大部分前端来说，"自行搭建组件库"不值得学了

这是我认为的观点，组件库已经失去意义了，现在更坚定了。

我们之前热门的Monorepo、Changesets、Storybook、文档站——等等这些工程化的能力没有消失，但它们的价值在下降，他们变成了AI 的燃料，燃烧着。

因为组件的分发方式变了，搭建组件库的意义也变了。

你不需要学"怎么搭一个组件库"。你需要学"怎么让 AI 正确使用组件库"。

前者是工程能力，后者是设计思维 +  AI 使用能力 + AI 协作能力。

4. "Design System 思维"更值钱了

Skill.md 不是随便写的。它需要：

•理解组件的场景和边界

•定义组件的行为契约

•写出 AI 能理解的约束条件

•设计验证清单

•等等

这是 Design System 思维的高级形态。

以前 Design System 是给人用的——颜色、字体、间距、组件规范等等其他东西。 现在 Design System 是给 AI 用的——场景、约束、契约、验证等等。

能写好 Skill.md 的人，本质上是能定义"AI 该怎么用组件"的人。这个能力现在很重要，也会变得极其稀缺。

差不多的功能要求，一个好的Skill.md得出的结果比100不怎好的Skill.md还要重要。

你写的内容与你的思想高度决定你使用 AI 能力的高度。

你需要静下心来好好思考，好好想想什么才是你的核心价值，你的天赋是什么？

5. 这不是前端的专属问题

虽然 ThreeUI 只是一个组件库。但是这个趋势是通用的：

•MCP（Model Context Protocol）：给 AI 定义"工具"的协议

•Cursor Rules / CLAUDE.md：给 AI 定义"项目规范"的文件

•Skill.md：给 AI 定义"组件能力"的卡片

•等等其他

它们本质是同一件事：把软件工程知识翻译成 AI 能消费的东西。

以前，知识存在于人的脑子里、文档里、Stack Overflow 、知乎等等的回答里。

现在，知识必须存在于 AI 能直接读取的结构化文件里，所有文档， 不仅仅是 .md 文档。

你写不清楚，AI 就用不对。用不对，你的工具/库/框架就是垃圾

思维方式的转变对谁有影响？

如果你是组件库作者

1.给每个组件写一份 Skill.md，包含：场景、依赖、实现步骤、行为契约、验证清单、护栏等等。

2.放在仓库根目录，让 AI Agent 能直接读到

3.测试：用 Claude / Cursor / GPT 读你的 Skill.md，看它能不能正确组装你的组件

4.如果 AI 用错了，迭代 Skill.md 直到 AI 用对

5.等等其他

如果你是业务开发

1.学会用 AI 读第三方 Skill.md 来快速组装页面

2.把你的判断力花在"选什么组件、怎么组合"上，而不是"怎么写代码"上

3.不要花时间去学组件库的工程搭建——除非你明确要做这个方向

4.等等其他

不要再去想代码怎么写，而且想怎么让AI去给你写正确的代码。 你会不会写代码这个事情已经不重要了。

简单总结一下

其实本质上来说组件库还没有死绝。它只是换了一种存在形式。跟随时代的发展进行不断的变化与发展。

从"人用的工具"变成"AI 用的技能"。 从"npm 包"变成"可复制的代码片段"。 从"API 文档"变成"Skill.md"。

2026 年的前端，不需要记住 500 个组件的 API。2026 年的前端，需要知道怎么让 AI 正确使用这 500 个组件。

这不是技术降级。这是AI 开发工程师的核心工作，是能力重心的转移。

而转移的方向，已经不可逆。

过去的编程已经死了，我们需要拥抱未来的AI 开发方式。跟随AI时代的发展，我们需要去改变，去迎合，去融入这个AI时代。

工具还是重要的，只是方式与历史已经截然不同。