# 64万安装的React性能Skill拆解：Vercel官方「规则库型」SKILL.md设计全解 ## 概述 本期做单个 Skill 的深度拆解，对象是 skills.sh 总榜第 9 名的 `vercel-react-best-practices`（647.0K 安装），来自 Vercel 官方技能仓库 vercel-labs/agent-skills。选它的理由有三：一，它是榜单头部唯一一个「规则库型」Skill——和 grill-me 的访谈式、tdd 的工作流式、rigorpilot 的编排式完全不同，70 条规则靠 ID 前缀和优先级表组织，是另一种值得学的 SKILL.md 范式；二，它的渐进式披露做得很干净，主文件常驻上下文极小，细节全在按需加载的 `rules/` 目录；三，同一个仓库里还有 7 个同范式兄弟技能，其中 `web-design-guidelines`（557.7K，总榜 37 名）也进了头部，整个仓库是一套完整的「企业规则库」样本。本文逐段拆它的 SKILL.md，并顺手指出一处官方文档自相矛盾的细节。 ## 仓库快照：一个仓库，八个技能，两个进头部 vercel-labs/agent-skills 是 Vercel 官方维护的 Agent 技能集合，MIT 协议，README 自述「Skills follow the Agent Skills format」。8 个技能全部是「审查/最佳实践」定位： | 技能 | 定位 | 规模 | skills.sh 排名/安装量 | |---|---|---|---| | vercel-react-best-practices | React/Next.js 性能优化规则 | 70 条规则、8 类 | #9 / 647.0K | | web-design-guidelines | Web 界面审查（可访问性/UX） | 100+ 条规则、11 类 | #37 / 557.7K | | writing-guidelines | 文档与文案写作规范 | 80+ 条规则 | 榜内 | | react-native-guidelines | React Native/Expo 最佳实践 | 16 条规则、7 节 | 榜内 | | vercel-optimize | Vercel 项目成本/性能审计 | 指标驱动 | 榜内 | | vercel-deploy-claimable | 一键部署到 Vercel | 自动识别 40+ 框架 | 榜内 | | composition-patterns | React 组合模式 | 4 类模式 | 榜内 | | react-view-transitions | View Transition API | 组件+CSS 配方 | 榜内 | 一个有意思的生态位观察：总榜第 1 的 `find-skills`（3.0M）同样来自 vercel-labs——Vercel 既 owns 技能分发的 CLI 入口，又 owns 头部内容技能，这在整个生态里是独一份的卡位。 ## 评测对比表 以下评分基于本次实际抓取的仓库 README 与 SKILL.md 原文，实战效果以 skills.sh 安装量为主要佐证： | 技能 | 功能完整度(25%) | 设计质量(25%) | 实战效果(20%) | 上手难度(15%) | 社区活跃度(15%) | 加权总分 | |---|---|---|---|---|---|---| | vercel-react-best-practices | ★★★★★ | ★★★★★ | ★★★★★ | ★★★★★ | ★★★★ | **4.80** | | web-design-guidelines | ★★★★★ | ★★★★☆ | ★★★★★ | ★★★★★ | ★★★★ | **4.65** | | writing-guidelines | ★★★★ | ★★★★★ | ★★★★ | ★★★★ | ★★★★ | **4.20** | | vercel-optimize | ★★★★ | ★★★★ | ★★★★ | ★★★ | ★★★★ | **3.95** | | vercel-deploy-claimable | ★★★★ | ★★★★ | ★★★★ | ★★★★★ | ★★★ | **3.90** | | composition-patterns | ★★★★ | ★★★★ | ★★★ | ★★★★★ | ★★★ | **3.80** | ## 深度拆解：vercel-react-best-practices 的 SKILL.md ### 第一段：Frontmatter，三句话 description 与一个「过分」的名字 先看原文： ```yaml name: vercel-react-best-practices description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements. license: MIT metadata: author: vercel version: "1.0.0" ``` description 是标准的三段式，值得逐句抄： 1. **是什么**：「React and Next.js performance optimization guidelines from Vercel Engineering.」——一句话定性，顺带用 Vercel Engineering 做权威背书； 2. **何时用**：「should be used when writing, reviewing, or refactoring...」——用动词枚举圈定任务类型（写/审/重构）； 3. **触发词**：「Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization...」——把用户请求里最可能出现的名词短语直接铺进去。 这三句分别对应技能路由的三个问题：你是谁、什么场景选你、用户说了什么词该想到你。很多 Skill 的 description 只写了第一句，等于把路由决策全丢给了模型自由发挥。 名字本身也是个设计点：目录名是 `react-best-practices`，但 frontmatter 的 name 是 `vercel-react-best-practices`——目录名与技能名不一致。原因不难猜：「react-best-practices」这种通用名在 2300+ 技能的市场里必然撞车，加上厂商前缀才能保证全局唯一和搜索直达。给 Skill 起名时用「厂商前缀 + 通用名」，是官方仓库示范的命名纪律。 ### 第二段：优先级表，规则 ID 是全部设计的锚点 SKILL.md 正文第一个实质内容，是一张把 8 个类别按影响力排序的表： | Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Eliminating Waterfalls | CRITICAL | `async-` | | 2 | Bundle Size Optimization | CRITICAL | `bundle-` | | 3 | Server-Side Performance | HIGH | `server-` | | 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` | | 5 | Re-render Optimization | MEDIUM | `rerender-` | | 6 | Rendering Performance | MEDIUM | `rendering-` | | 7 | JavaScript Performance | LOW-MEDIUM | `js-` | | 8 | Advanced Patterns | LOW | `advanced-` | 这张表是整个技能的灵魂，它做了三件事： **其一，给每条规则一个可引用的 ID。** 后文 70 条规则全部是 `async-parallel`、`bundle-barrel-imports` 这样的「前缀 + 短横线名词」格式。有了 ID，Agent 输出审查报告时可以写「违反 `rerender-no-inline-components`」，用户拿 ID 就能反查规则文件——规则从「一段提示词」升级成了「可索引的知识条目」。这也是多技能协作的基础：另一个技能想引用 React 性能规则时，指个 ID 就够。 **其二，前缀即分类。** Agent 在具体任务里只需要扫一遍前缀就能锁定相关子集：做数据获取看 `async-`/`server-`，调包体积看 `bundle-`，处理卡顿看 `rerender-`。不需要每次都把 70 条全部过一遍。 **其三，优先级即降级策略。** SKILL.md 开头明确写了规则「prioritized by impact to guide automated refactoring and code generation」——这句话是写给 Agent 而非人看的：上下文预算紧张或改动范围受限时，先执行 CRITICAL 级的水梯消除和包体优化。人类写的规范文档很少敢做这种「哪些规则可以牺牲」的排序，而 Agent 场景里这才是关键信息。 ### 第三段：Quick Reference，70 条规则每条只占一行 优先级表之后是 8 个小节，每节用一行一条的格式列规则： ``` - `async-parallel` - Use Promise.all() for independent operations - `bundle-barrel-imports` - Import directly, avoid barrel files - `rerender-no-inline-components` - Don't define components inside components ``` 我按 SKILL.md 实际列出的条目数了一遍：async 6 条、bundle 6 条、server 10 条、client 4 条、rerender 15 条、rendering 11 条、js 14 条、advanced 4 条，合计恰好 70 条，与正文自称的「70 rules across 8 categories」吻合。注意这个信息密度控制：每条规则只给「ID + 一句祈使句」，不解释、不举例。整个 Quick Reference 部分大约只有 2000 token，却覆盖了完整规则面——SKILL.md 是常驻上下文，它的每一行都要在每次会话里付租金，这里的克制就是成本设计。 规则内容本身也反映官方工程的最新偏好：`bundle-analyzable-paths`（偏好静态可分析的导入路径）、`server-after-nonblocking`（用 after() 做非阻塞操作）、`rendering-activity`（用 Activity 组件做显隐）、`advanced-effect-event-deps`（useEffectEvent 的依赖处理）——这些是博客文章还没写烂的新模式，规则库先行。 ### 第四段：渐进式披露，rules/ 目录与 AGENTS.md 兜底 「How to Use」一节只有寥寥数行，但结构上是关键一跳： ``` Read individual rule files for detailed explanations and code examples: rules/async-parallel.md rules/bundle-barrel-imports.md ``` 每个规则文件内部固定四件套：为什么重要（why）、错误示例及解释、正确示例及解释、补充上下文与参考。SKILL.md 明示了路径格式，Agent 就能对任何 ID 机械地拼出文件路径去按需读取——不需要每次会话加载全部 70 个示例。这是 Agent Skills 官方推崇的渐进式披露（progressive disclosure）在规则库场景的标准落地：**常驻层放索引，细节层放磁盘，用路径约定连接两者**。 末尾还有一条兜底：「For the complete guide with all rules expanded: `AGENTS.md`」——需要完整展开版时读编译产物。三层结构（SKILL.md 索引 → rules/*.md 单条 → AGENTS.md 全量）分别对应「扫一眼」「查一条」「读全部」三种粒度的需求。 ### 第五段：一处官方文档的自身矛盾 有个值得玩味的细节：仓库 README 里 react-best-practices 一节写的是「Contains 40+ rules across 8 categories」，而 SKILL.md 正文写的是「Contains 70 rules across 8 categories」，且实际条目数就是 70。也就是说 README 的「40+」是旧数字没跟上——这发生在 Vercel 官方仓库里，说明一个普遍问题：**一个技能有 README、SKILL.md、rules/、AGENTS.md 四个界面，同步成本是真实存在的**。对技能作者的启示是：凡是会随版本增长的数字（规则数、类别数），要么只在一处声明，要么用构建脚本从规则文件数量自动生成，手写两遍迟早打架。 ### 第六段：发布工程，immutable release 与 discovery index 这个仓库还有一个多数技能仓库没有的机制。README 写明：技能在 main 分支上的每次变更，都会发布一个 immutable 的 GitHub Release，附上 Agent Skills discovery index 和每个技能单独的 artifact，并提供了本地复现命令： ``` npm ci --ignore-scripts node scripts/build-discovery-index.mjs https://example.com/skills ``` 这是把技能当软件包发版的思路：每个版本不可变、可追溯、可被聚合站索引。skills.sh 这类目录站能够稳定收录和计数，前提正是上游有这样的规范化发布。个人开发者写 Skill 用不到这套，但企业内部建技能库时，「技能变更走 Release、索引自动生成」是值得直接抄的工程化模板。 ### 第七段：同仓库其余 7 个技能速览 - **web-design-guidelines**（#37，557.7K）：100+ 条规则、11 个类别，覆盖可访问性、焦点态、表单、动画（prefers-reduced-motion）、排版（弯引号、tabular-nums）、暗色模式、touch-action、i18n 等。触发词设计同样直白——「Review my UI」「Check accessibility」这种用户原话直接写进 Use when。与 react-best-practices 是同一套「ID + 优先级 + 分类」骨架，只是换了领域。 - **writing-guidelines**：80+ 条规则审查文档文案，最有味道的是它的禁词表——禁用 `easy`/`simple`/`quick` 形容用户任务，禁止用 em dash 做标点，要求弯引号而非直引号。这是把 Vercel 写作手册整个规则化成 Agent 可执行清单的产物。 - **vercel-optimize**：唯一一个「先采集指标再行动」的技能——先拉 Vercel 的成本/性能/缓存指标，再只下钻指标指向的路由和文件。指标驱动而非全库扫描，这个顺序设计避免了 Agent 在大项目里漫无目的地翻代码。 - **vercel-deploy-claimable**：面向 claude.ai 和 Claude Desktop 的部署技能，从 package.json 自动识别 40+ 框架，部署后返回 preview URL 和 claim URL（用户可把部署认领到自己账号）。是「把产品操作写成 Skill」的分发样本。 - **composition-patterns**：4 类组合模式（复合组件、状态提升、内部组合、避免 prop drilling），解决布尔 prop 泛滥。规则最少、最偏设计理念的一个。 - **react-view-transitions / react-native-guidelines**：前者是 View Transition API 的配方集（含 Next.js 的 transitionTypes 集成），后者 16 条规则 7 节，FlashList、Reanimated、expo-image 等移动端专项。 ## 什么时候该用「规则库型」范式 把本期主角放回设计模式的坐标系里，四种主流范式各有适用场景： | 范式 | 代表 | SKILL.md 主体 | 适用场景 | |---|---|---|---| | 规则库型 | vercel-react-best-practices | ID 索引 + 优先级表 | 领域知识多而稳定，任务是「审/改」 | | 工作流型 | tdd | 阶段闸门 + 循环 | 过程纪律重于知识 | | 访谈型 | grilling | 提问策略 + 终止条件 | 需求模糊，对齐成本高 | | 编排型 | rigorpilot 入口技能 | 路由到子技能 + 证据包 | 多阶段长流程，要审计 | 规则库型的三个成立条件：知识可以拆成独立条目；条目之间有可比较的重要性排序；使用方式以「检查/应用」为主而非「执行流程」为主。如果你的领域知识是「遇到 X 就做 Y」的映射（性能规则、无障碍检查、文案禁词都是），规则库型是上下文成本最低的选择。反过来，如果知识之间有强时序依赖（先做 A 才能做 B），硬拆成规则条目反而会丢失流程语义，那是工作流型的地盘。 ```mermaid flowchart TD A[用户请求: 写/审/重构 React 代码] --> B{description 常驻匹配} B -- 命中 --> C[加载 SKILL.md 索引层
约2000 token] C --> D[查8类优先级表
CRITICAL 规则优先] D --> E[按前缀锁定子集
async- / bundle- / rerender-] E --> F{需要细节?} F -- 查一条 --> G[读 rules/async-parallel.md
why + 错例 + 正例] F -- 读全部 --> H[读编译版 AGENTS.md] G --> I[带规则 ID 输出审查/重构] H --> I B -- 不命中 --> J[技能不触发
零常驻成本] ``` ```mermaid mindmap root((vercel-labs/agent-skills)) React主战场 react-best-practices 70条规则 composition-patterns view-transitions 跨栈审查 web-design-guidelines 100+条 writing-guidelines 80+条 react-native-guidelines 产品自举 vercel-optimize 指标驱动 deploy-claimable 认领制部署 发布工程 immutable release discovery index 自动构建 ``` ## 安装命令 ```bash # 整仓库安装（安装器会让你挑选技能和目标 Agent） npx skills add vercel-labs/agent-skills # 或锁定最新版 npx skills@latest add vercel-labs/agent-skills ``` 装好后无需配置，Agent 在写/审/重构 React 代码时会自动触发；也可以显式说「Review this React component for performance issues」来唤起。 ## 推荐排行榜 - **设计质量第一**：vercel-react-best-practices——规则 ID + 优先级表 + 三层渐进披露，规则库型的教科书 - **覆盖面第一**：web-design-guidelines——100+ 条规则把可访问性和 UX 审查一网打尽 - **最被低估**：writing-guidelines——禁词表和排版规则让所有 AI 生成文档立刻变体面 - **产品团队最该学**：vercel-optimize——「先指标后下钻」的审计顺序设计 - **企业技能库模板**：本仓库整体的 immutable release + discovery index 发布机制 ## 参考来源 1. [skills.sh — The Agent Skills Directory](https://skills.sh) — 本文全部安装量与排名数据（2026-08-29 抓取的总榜） 2. [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) — 仓库 README：8 个技能的定位、规则规模、安装命令与发布机制 3. [react-best-practices SKILL.md 原文](https://raw.githubusercontent.com/vercel-labs/agent-skills/main/skills/react-best-practices/SKILL.md) — 逐段拆解的原始文本：frontmatter、优先级表、70 条规则清单 4. [mattpocock/skills](https://github.com/mattpocock/skills) — 工作流型/访谈型范式的对照样本（tdd、grilling 等） > [!tip] 51学通信知识星球 > **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 > **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 > **当前规模**：5200 篇主题 / 990 个回答，198 元/年。 > **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 > **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。