# 1.2KB 撬动 59 万安装：web-design-guidelines 逐行拆解，顺便看懂 Vercel 仓库里的四种 Skill 写法 ## 概述 本期是 Skills 生态深度拆解（第2轮），主角是总榜第 37 名的 **web-design-guidelines**（vercel-labs/agent-skills，591.4K 安装，skills.sh 2026-08-31 快照）。选它的理由很直接：它是整个头部生态里**最小**的热门 Skill——SKILL.md 只有 1231 字节，正文不含一条具体规则，却能在一次运行中审查你代码里的 100+ 条 Web 界面规范。它的答案是“运行时拉取活文档”：Skill 本体只是一根指针，规则永远从源头现取。本期把这个 Skill 拆到每一行，再顺着同一个仓库讲透 Vercel 放在里面的另外四种 SKILL.md 写法（索引+规则库型、脚本驱动型、Token 载体型、模板生成型），读完你基本能把市面上 Skill 的文件组织方式看全。 ## 评测对比表 本期评测对象为 vercel-labs/agent-skills 仓库内的五个 Skill（安装量标注为 skills.sh 总榜可见数据，未见榜单条目的以"—"标示）： | Skill | 写法类型 | 安装量 | 功能完整度(25%) | 设计质量(25%) | 实战效果(20%) | 上手难度(15%) | 社区活跃度(15%) | 加权总分 | |---|---|---|---|---|---|---|---| | web-design-guidelines | 指针型 | 591.4K | ★★★★☆ | ★★★★★ | ★★★★☆ | ★★★★★ | ★★★★☆ | **4.40** | | vercel-react-best-practices | 索引+规则库型 | 675.7K | ★★★★★ | ★★★★★ | ★★★★★ | ★★★★☆ | ★★★★★ | **4.75** | | deploy-to-vercel | 脚本驱动型 | — | ★★★★☆ | ★★★★☆ | ★★★★☆ | ★★★★☆ | ★★★☆☆ | **4.05** | | composition-patterns | 模板生成型 | — | ★★★★☆ | ★★★★☆ | ★★★☆☆ | ★★★★☆ | ★★★☆☆ | **3.75** | | react-native-skills | 模板生成型 | — | ★★★★☆ | ★★★★☆ | ★★★☆☆ | ★★★★☆ | ★★★☆☆ | **3.80** | | vercel-cli-with-tokens | Token 载体型 | — | ★★★☆☆ | ★★★☆☆ | ★★★☆☆ | ★★★☆☆ | ★★☆☆☆ | **3.20** | > 评分为基于公开安装量、仓库文件结构与 SKILL.md 设计质量的编辑部综合评定，实战效果维度含社区使用佐证，非实验室实测。deploy-to-vercel 等未进总榜展示位的条目无公开安装数。 ## 生态位置：Vercel 是 Skills 世界的“基建+内容”双料玩家 先定位。skills.sh 是 Vercel 出品的 Agent Skills 目录站，一份榜单同时面向 20 个 agent 客户端：Claude Code、Cursor、Codex、GitHub Copilot、Windsurf、Gemini、Cline、AMP、Antigravity、OpenClaw、Droid、Goose、Kilo、Kiro CLI、Nous Research、OpenCode、Roo、Trae、VS Code、Zed。而 Vercel 自己在总榜上有三个仓库同时作战： - **vercel-labs/skills**：find-skills，3.2M 安装，总榜第 1，整个生态的“入口”； - **vercel-labs/agent-browser**：agent-browser，754.4K，总榜第 7； - **vercel-labs/agent-skills**：内容仓库，vercel-react-best-practices 675.7K 位列总榜第 12，web-design-guidelines 591.4K 位列第 37。 web-design-guidelines 是这个内容仓库里体积最小的一个，却在安装量上压过绝大多数家族成员。“最小”与“最热门”并存，正是它值得逐行拆的原因。 ## 主拆解：web-design-guidelines 逐段精读 ### 第一段：frontmatter，教科书级的触发词设计 ``` --- name: web-design-guidelines description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices". metadata: author: vercel version: "1.0.0" argument-hint: --- ``` description 分两截，第一截说它做什么（Review UI code for Web Interface Guidelines compliance），第二截才是精髓——**五个引号内的用户原话**：`"review my UI"`、`"check accessibility"`、`"audit design"`、`"review UX"`、`"check my site against best practices"`。 注意它的写法：不是罗列功能特性，而是罗列**用户会脱口而出的话**。Skill 的触发依赖 agent 对 description 与当前任务的语义匹配，所以“预测用户输入”比“描述自身能力”命中率高得多。五个短语还刻意覆盖了三个动词簇（review / audit / check）和三个对象簇（UI / accessibility / design / UX / site），交叉覆盖日常表达的全部变体。你能数出来的漏网说法大概只剩"check my CSS"这类，那会被别的 skill 接走。 `argument-hint` 留空——它支持直接传文件或 glob 参数（正文有交代），但没写提示文案。这是全 Skill 少数可以挑剔的地方：传参入口存在却不可发现。 ### 第二段：How It Works，四步走完的极简流程 ``` 1. Fetch the latest guidelines from the source URL below 2. Read the specified files (or prompt user for files/pattern) 3. Check against all rules in the fetched guidelines 4. Output findings in the terse `file:line` format ``` 四步里没有一步含知识本身：取规则、读代码、比对、按格式输出。所有重活都被推给两个外部存在——远端规则文档，和 agent 自己的阅读理解能力。这是“Skill 只写流程、不写知识”路线的极端样本。 ### 第三段：Guidelines Source，整个 Skill 的灵魂 ``` Fetch fresh guidelines before each review: https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions. ``` 三次抓取正文，真正决定这个 Skill 价值的只有这一段。它的设计含义有三层： **第一层，内容与分发解耦。** 规则不在 SKILL.md 里，而在另一个仓库（vercel-labs/web-interface-guidelines）的 `command.md`。Vercel 工程团队随时更新那份文档，59 万个安装了此 Skill 的本地副本**一行都不用动**。传统 Skill 的死穴——规则过时、版本漂移、用户不升级——在这里不存在，因为根本没有可过时的本地副本。 **第二层，token 经济学近乎最优。** SKILL.md 全文 1.2KB，作为触发判断的成本常驻几乎可以忽略；只有真正触发时才花一次 WebFetch 拉入完整规则集（README 口径为 100+ 条规则，覆盖可访问性、焦点状态、表单、动画、排版、图片、性能、导航、暗色模式、触控、国际化等 11 类）。对比“把全部规则写死在 SKILL.md”的做法，这个方案让 99% 不触发的会话不为它付一个多余 token。这正是渐进式披露（progressive disclosure）的极限形态：把“披露”推迟到运行时。 **第三层，连输出协议都外置。** `file:line` 格式的具体要求写在远端文档里（"the fetched content contains … output format instructions"），本地不维护一份格式说明。好处是改格式不用发版；代价是输出的确定性完全押在远端文档的措辞上。 ### 第三段的风险清单：你把信任交给了谁 这套设计不是免费午餐，逐条列清楚： 1. **供应链信任扩大。** 安装时你信任的是 vercel-labs/agent-skills，运行时你额外信任 vercel-labs/web-interface-guidelines 的 main 分支内容。远端文档被改动，所有安装者的审查行为随之改变——这是指针型 Skill 的固有面。 2. **离线不可用。** 无网络时四步流程第一步即失败，Skill 空转。 3. **审查基线漂移。** 企业合规场景通常要求“固定版本的评审标准”，而这里每次都拉 main——上周和本周的审查结论可能因规则更新而不同。要可复现，得自己 fork 那份文档。 4. **单点 URL。** 没有 fallback 源，raw.githubusercontent.com 不可达或路径变更，Skill 即失效。 与此前拆过的工具型 Skill 那种“能力内置、永不过期”不同，web-design-guidelines 是**内容型 Skill 的不过期方案**——不靠把能力做全，靠把内容搬走。两条路线解决同一个老化问题，方向恰好相反。 ### 逐文件盘点：这个 Skill 一共就三样东西 对照仓库树，web-design-guidelines 目录下只有：`SKILL.md`（1231 字节）和一个 946 字节的 `web-design-guidelines.zip`（分发用打包）。没有 scripts/、没有 references/、没有规则副本。**一个 Skill 的全部交付物是一个 Markdown 指针**——这刷新了“Skill 可以有多小”的下限，也给想写第一个 Skill 的人一个重要参照：SKILL.md 本身就是完整的、可上线的 Skill，其他一切都是增强项。 ## 同仓库逐文件：另外四种 SKILL.md 写法 vercel-labs/agent-skills 的 skills/ 目录下并存五个目录，恰好构成一份“SKILL.md 写法博物馆”。 ### 写法一：索引 + 规则库型（react-best-practices，总榜第12） 与指针型相对的另一极。`SKILL.md` 6850 字节，角色是**索引页**：开头一段场景触发描述（writing / reviewing / refactoring React 代码时使用），中间一张 8 类优先级表（Eliminating Waterfalls 和 Bundle Size 为 CRITICAL，Server-Side 为 HIGH，往下递减到 advanced-），然后是 70 条规则的名称速览，最后指路：细读 `rules/*.md`，全量编译版看 `AGENTS.md`。 仓库树证实了它的工程化程度：`rules/` 下恰好 70 个规则文件（async- 6 个、bundle- 6 个、server- 10 个、client- 4 个、rerender- 15 个、rendering- 11 个、js- 14 个、advanced- 4 个），每个文件四段式——为什么重要、错误示例、正确示例、延伸参考。`AGENTS.md` 编译版重达 98KB。更硬核的是仓库里有一条 CI 流水线（`.github/workflows/react-best-practices-ci.yml`）加一个构建包：`build.ts`、`parser.ts`、`validate.ts`、`extract-tests.ts`、60KB 的 `test-cases.json`——**规则本身是被测试覆盖的**，从源数据生成 AGENTS.md 与规则文件。另一个细节：README 还写着"40+ rules"，SKILL.md 已是"70 rules"，主文档跑在 README 前面，说明迭代活跃但外围文案滞后。 适用判断也写得很清楚：它管性能，不管美观；管 React/Next.js，不管原生端。 ### 写法二：脚本驱动型（deploy-to-vercel） `SKILL.md` 11786 字节 + `resources/deploy.sh`（8841 字节）+ `resources/deploy-codex.sh`（8855 字节）。SKILL.md 负责编排与决策（识别框架、组织上传），真正的部署逻辑在 shell 脚本里。deploy-codex.sh 与 deploy.sh 体积几乎一致——是给非 Claude 系 agent 的平行实现，同一能力按 agent 方言各发一份。仓库根目录还躺着 `deploy-to-vercel.zip` 和 `Archive.zip`，说明该 Skill 走的是“打包分发”路线。配套的 vercel-deploy-claimable 面向 claude.ai 与 Claude Desktop：打包 tarball、自动识别 40+ 框架、返回 preview URL 和 claim URL。这一型的启示：**当能力涉及确定性操作（打包、上传、重试），把它写成脚本比写成提示词可靠得多**，SKILL.md 退居指挥层。 ### 写法三：Token 载体型（vercel-cli-with-tokens） 单个 8838 字节的 SKILL.md，无脚本无规则库。内容是把带凭证调用 Vercel CLI 的流程写成操作指南。它没有独立的可执行资产，纯靠提示词驱动 agent 操作。适合“流程复杂但每步都是通用工具调用”的场景，也是六者中评分最低的写法——没有外部资产意味着没有工程护栏，全凭 prompt 质量。 ### 写法四：模板生成型（composition-patterns 与 react-native-skills） 两个目录结构完全同构：SKILL.md（2886 / 4439 字节）做索引 + `rules/_template.md` + `rules/_sections.md` + 一组规则文件 + 大体积编译版 AGENTS.md（22.6KB / 73.8KB）。决定性的证据是：**两个 Skill 的 `rules/_template.md` 在 git 树中 sha 完全相同**（`1e9e7070…`）——同一份模板生成多个 Skill。rules 目录就是一条内容生产线：模板定格式，章节清单定结构，源数据填充规则。想批量生产家族式 Skill 的团队，直接抄这个结构即可。 ## web-design-guidelines 运行时工作流 ```mermaid flowchart TD A[用户: review my UI / check accessibility] --> B{agent 匹配 description
五个触发短语} B -->|命中| C[读取 SKILL.md 1.2KB] B -->|未命中| X[不加载, 零 token 成本] C --> D{用户是否指定
文件或 glob?} D -->|是| E[读取指定文件] D -->|否| F[反问用户要审哪些文件] E --> G[WebFetch 拉取远端 command.md
web-interface-guidelines 仓库 main 分支] F --> G G --> H[逐文件比对 100+ 条规则
a11y/表单/动画/排版/性能/暗色模式/i18n] H --> I[按远端文档规定的
file:line 极简格式输出] G -.->|网络失败/URL 变更| J[Skill 空转, 无本地回退] ``` ## 适用与不适用场景 **适用：** - 提交前/PR 评审时的 UI 体检，口头一句 "review my UI" 即触发； - 接手老项目先跑一遍可访问性与 UX 基线审查； - 与 react-best-practices 组合使用：一个管性能、一个管界面规范，互补不重叠。 **不适用：** - 离线或严格内网环境（第一步就断）； - 需要固定审查基线的合规审计（main 分支随时漂移，要可复现请 fork 远端文档并改 URL）； - 原生移动端界面审查（应走同仓库的 react-native-skills）。 ## 安装与使用 ```bash # 安装整个仓库（README 官方命令） npx add-skill vercel-labs/agent-skills # 或用 skills.sh 标准命令 npx skills add vercel-labs/agent-skills ``` 装好后无需配置，对话中直接说： ``` review my UI check accessibility in src/components audit design of this page ``` ## 分维度排行榜 | 维度 | 第一名 | 一句话理由 | |---|---|---| | 体积最小 | web-design-guidelines | 1231 字节含全部逻辑 | | Token 效率 | web-design-guidelines | 不触发零成本，触发才拉规则 | | 工程严谨度 | react-best-practices | CI + 60KB 测试用例 + 生成管线 | | 自动化程度 | deploy-to-vercel | SKILL.md 编排，真活在 shell 脚本里 | | 可复用性 | composition-patterns | _template.md 被多 Skill 共享 | | 上手最快 | web-design-guidelines | 装完即用，零配置零依赖声明 | ## 结论 web-design-guidelines 证明了一件事：Skill 的竞争力不在你往 SKILL.md 里塞多少知识，而在你把知识放在哪。59 万用户安装的其实不是一份 UI 规范，而是一根永远指向最新规范的指针。对想动手写 Skill 的读者，本期的可抄清单是：description 里写用户原话而非功能清单；内容会过时的 Skill 考虑运行时拉取并接受其信任代价；确定性操作下沉到脚本；多 Skill 家族用共享模板生成。这四种写法在同一个仓库里并存且各自拿到几十万安装，说明 Skill 设计没有唯一正解——只有与你更新频率、token 预算、信任边界相匹配的选择。 ## 参考来源 1. [Skills Leaderboard — skills.sh](https://skills.sh) — 总榜安装量与排名（web-design-guidelines 591.4K 第37、vercel-react-best-practices 675.7K 第12），2026-08-31 快照 2. [vercel-labs/agent-skills 仓库文件树](https://api.github.com/repos/vercel-labs/agent-skills/git/trees/main?recursive=1) — 各 Skill 文件尺寸、rules/ 目录 70 个规则文件、CI 构建包、共享 _template.md 的 git sha 3. [web-design-guidelines/SKILL.md 原文](https://raw.githubusercontent.com/vercel-labs/agent-skills/main/skills/web-design-guidelines/SKILL.md) — 逐段引用来源 4. [react-best-practices/SKILL.md 原文](https://raw.githubusercontent.com/vercel-labs/agent-skills/main/skills/react-best-practices/SKILL.md) — 8 类优先级表与 70 条规则速览 5. [vercel-labs/agent-skills README](https://raw.githubusercontent.com/vercel-labs/agent-skills/main/README.md) — 安装命令、规则类别口径（README 的 40+ 与 SKILL.md 的 70 差异）、vercel-deploy-claimable 说明 > [!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 等场景全覆盖。