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 个技能全部是「审查/最佳实践」定位：

一个有意思的生态位观察：总榜第 1 的 find-skills（3.0M）同样来自 vercel-labs——Vercel 既 owns 技能分发的 CLI 入口，又 owns 头部内容技能，这在整个生态里是独一份的卡位。

评测对比表

以下评分基于本次实际抓取的仓库 README 与 SKILL.md 原文，实战效果以 skills.sh 安装量为主要佐证：

深度拆解：vercel-react-best-practices 的 SKILL.md

第一段：Frontmatter，三句话 description 与一个「过分」的名字

先看原文：

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 个类别按影响力排序的表：

这张表是整个技能的灵魂，它做了三件事：

其一，给每条规则一个可引用的 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 等移动端专项。

什么时候该用「规则库型」范式

把本期主角放回设计模式的坐标系里，四种主流范式各有适用场景：

规则库型的三个成立条件：知识可以拆成独立条目；条目之间有可比较的重要性排序；使用方式以「检查/应用」为主而非「执行流程」为主。如果你的领域知识是「遇到 X 就做 Y」的映射（性能规则、无障碍检查、文案禁词都是），规则库型是上下文成本最低的选择。反过来，如果知识之间有强时序依赖（先做 A 才能做 B），硬拆成规则条目反而会丢失流程语义，那是工作流型的地盘。

flowchart TD
    A[用户请求: 写/审/重构 React 代码] --> B{description 常驻匹配}
    B -- 命中 --> C[加载 SKILL.md 索引层<br/>约2000 token]
    C --> D[查8类优先级表<br/>CRITICAL 规则优先]
    D --> E[按前缀锁定子集<br/>async- / bundle- / rerender-]
    E --> F{需要细节?}
    F -- 查一条 --> G[读 rules/async-parallel.md<br/>why + 错例 + 正例]
    F -- 读全部 --> H[读编译版 AGENTS.md]
    G --> I[带规则 ID 输出审查/重构]
    H --> I
    B -- 不命中 --> J[技能不触发<br/>零常驻成本]

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 自动构建

安装命令

# 整仓库安装（安装器会让你挑选技能和目标 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 — 本文全部安装量与排名数据（2026-08-29 抓取的总榜）
2. vercel-labs/agent-skills — 仓库 README：8 个技能的定位、规则规模、安装命令与发布机制
3. react-best-practices SKILL.md 原文 — 逐段拆解的原始文本：frontmatter、优先级表、70 条规则清单
4. 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 等场景全覆盖。