仓库定位与目标

vercel-labs/agent-skills 是 Vercel 实验室维护的 Agent 技能集合仓库，其核心目的是为多种 AI 编码 Agent（Claude Code、Codex、Cursor、Antigravity 等）提供可即插即用的领域知识、技能规则与最佳实践。每条"技能（Skill）"本质上是一个目录，内含遵循 Agent Skills 规范的 SKILL.md 以及可选的 AGENTS.md、rules/、references/ 等配套文件。

README.md 概要说明了该仓库作为技能目录的定位，并提供推荐安装入口与目录导航 资料来源：README.md:1-40。AGENTS.md 与 CLAUDE.md 是仓库级别的元文件，为 Agent 在该仓库内工作时提供操作守则 资料来源：AGENTS.md:1-20 资料来源：CLAUDE.md:1-20。

技能清单与目录结构

每个技能单独存放在 skills/<skill-name>/ 子目录下，固定包含一个 SKILL.md 作为入口。SKILL.md 顶部为 YAML frontmatter，描述技能的名称、描述与适配 Agent 等元数据；正文则给出适用场景、触发条件与行为约束。

仓库根目录下的 skills.sh.json 是给 npx skills CLI 使用的元数据清单，列出可被安装或发现的全部技能 资料来源：skills.sh.json:1-40。.gitignore 忽略构建与临时产物，确保仓库只提交可发布的技能源文件 资料来源：.gitignore:1-20。

下表汇总当前社区讨论中频繁出现的核心技能：

资料来源：skills/vercel-react-best-practices/SKILL.md:1-40、skills/vercel-composition-patterns/SKILL.md:1-20、skills/web-design-guidelines/SKILL.md:1-30、skills/vercel-optimize/SKILL.md:1-30。

安装与使用流程

最常见的安装方式是通过 npx skills CLI：

# 安装单个技能
npx skills add vercel-labs/agent-skills vercel-react-best-practices

# 列出已安装技能
npx skills list

# 检查更新
npx skills check

安装时 CLI 会克隆仓库并解析 skills.sh.json 中的技能条目，匹配 name 字段后将对应目录复制到目标 Agent 的技能目录（如 ~/.claude/skills/）。SKILL.md 的 frontmatter 必须以 --- 开头作为首行内容，否则解析器会拒绝该文件 资料来源：skills/vercel-react-best-practices/SKILL.md:1-5。

已知问题与限制

社区已记录下述与"清单与安装"直接相关的痛点：

1. 解析器严格要求 frontmatter 顶格：任何出现在首行 --- 之前的内容（包括 HTML 注释）都会导致 npx skills add 失败并报告 "No valid skills found" 资料来源：skills/web-design-guidelines/SKILL.md:1-5。
2. skills check 报错信息不充分：当上游技能改名或下线时，CLI 没有明确告知迁移路径 资料来源：skills.sh.json:1-40。
3. skills list 缺少来源追溯：仅显示短名与安装路径，无法区分同名但来自不同仓库的技能。
4. 超大型 AGENTS.md 浪费上下文：vercel-react-best-practices 的 AGENTS.md 长达 2,975 行，在加载时几乎占满上下文窗口；社区建议改用渐进加载（references/ 子目录 + 按需读取） 资料来源：skills/vercel-react-best-practices/SKILL.md:120-140。
5. 远程依赖缺少回退：web-design-guidelines 要求 Agent 在运行时拉取 raw.githubusercontent.com 上的 command.md，在无 WebFetch 能力的沙箱环境（如部分 CLI Agent）下会失效 资料来源：skills/web-design-guidelines/SKILL.md:1-30。

对于初次使用者，建议优先核查 SKILL.md frontmatter 格式、用 npx skills list --long（若可用）确认来源，并按需裁剪大型 AGENTS.md 以控制上下文开销。

设计目标与核心约束

该技能的核心约束由 SKILL.md 明确定义：先抓取 Vercel 平台的信号，再根据信号所指向的路由与文件进行定向分析，而非全量读取仓库。该约束解决了「大型 Next.js 仓库上下文溢出」的问题——若代理先把所有文件读入上下文，剩余可用 token 将不足以进行有效推理。

SKILL.md 同时声明了技能的边界：它不直接执行部署，不修改 package.json 中的依赖版本，也不替代人工 code review；它聚焦于「在已有代码与已有 Vercel 数据之间建立可解释的因果链」。

资料来源：skills/vercel-optimize/SKILL.md:1-40

模块组成

技能目录采用「入口 + 库分层 + 脚本」的结构，便于在不同代理运行时复用：

lib/ 下三个子模块构成了一个管道：gates 决定「要不要做」，scanners 决定「读哪些」，sanitizers 决定「读到什么程度」。这种分层使 SKILL.md 中的指引能以纯文本方式被代理理解，而真正的 I/O 与过滤逻辑以 ES Module 形式独立可测。

资料来源：skills/vercel-optimize/lib/gates/index.mjs:1-30、skills/vercel-optimize/lib/scanners/index.mjs:1-30、skills/vercel-optimize/lib/sanitizers/index.mjs:1-30

工作流程

flowchart LR
    A[收集 Vercel 指标] --> B{门控: 信号是否充分?}
    B -- 否 --> A
    B -- 是 --> C[定位受影响的路由与文件]
    C --> D[scanners 按需读取]
    D --> E[sanitizers 清洗]
    E --> F[产出优化建议]

流程的关键在「门控」步骤：lib/gates/index.mjs 暴露的判断函数会评估当前已收集的指标是否覆盖了常见瓶颈（cold start、TTFB、function duration、error rate），未覆盖则阻止代理进入代码扫描阶段。这一机制是「metrics-first」约束的代码级实现。

scripts/scan-codebase.mjs 提供与上述管道等价的 CLI 调用方式，本地开发者可在不启动代理的情况下复现「按指标读文件」的过程，便于回归对比。

资料来源：skills/vercel-optimize/lib/gates/index.mjs:30-80、skills/vercel-optimize/scripts/scan-codebase.mjs:1-60

安装与调用

技能通过标准 skills CLI 安装：

npx skills add vercel-labs/agent-skills vercel-optimize

安装后，metadata.json 中的标识符会被 npx skills list 列出，并按 SKILL.md 中描述的触发条件激活。有用户提议增加 OpenClaw/Hermes 等托管环境的「quick-try」链接，以便在本地安装前先行评估（参见 issue #301），目前该能力尚未合并。

社区曾反馈 npx skills list 仅显示短名与安装路径，未呈现来源仓库（issue #156），这会影响 vercel-optimize 等多来源技能的可识别性。

资料来源：skills/vercel-optimize/metadata.json:1-20、skills/vercel-optimize/SKILL.md:40-60

已知限制

• 依赖外部 Vercel 信号接口；当代理运行环境无网络或被沙箱隔离时，gates 阶段会停滞，技能退化为「仅本地扫描」模式。
• 与其它 vercel 技能（如 vercel-react-best-practices）的 AGENTS.md 大文件策略不同（issue #169），vercel-optimize 通过强制「先指标后代码」避免上下文膨胀。
• SKILL.md 前的任意非 frontmatter 内容会导致 skills add 解析失败（issue #275），本技能的 SKILL.md 严格以 --- 起头以规避此问题。

资料来源：skills/vercel-optimize/SKILL.md:1-10

概览：技能的两类形态

agent-skills 仓库将"技能"作为可分发的最小单元，其中一类专门以编码规范与最佳实践为内容，称为规则类技能。它们以 SKILL.md 作为入口声明元信息与触发条件，通过 AGENTS.md 聚合规则，再借助 packages/skills 提供的 CLI 完成分发。react-best-practices、composition-patterns、react-native-skills 等都是这一形态的典型代表。规则类技能的消费者主要是编码代理，因此其核心设计目标是"按需注入上下文"而非"一次加载全部"。

资料来源：skills/react-best-practices/SKILL.md:1-40

技能文件结构与渐进式披露

每个规则类技能在仓库中遵循统一的目录约定：

• SKILL.md：以 YAML 头声明 name、description、metadata 等字段，正文给出适用场景与触发判断。例如 react-best-practices 的描述明确"React 19+ 与 Next.js 15 App Router 最佳实践"作为触发条件。
• metadata.json：提供可被 CLI 索引的结构化元数据，便于 skills list、skills add 在不读取正文的情况下定位技能。
• rules/：使用统一模板（_template.md）组织单条规则文件，便于按需加载。
• AGENTS.md：在部分技能中作为聚合视图，把全部规则平铺成单一文档。

flowchart LR
  A[SKILL.md<br/>入口与触发条件] --> B[rules/*.md<br/>单条规则]
  A --> C[AGENTS.md<br/>聚合视图]
  D[metadata.json<br/>CLI 索引] --> A
  B -.按需注入.-> E[编码代理]
  C -.一次性加载.-> E

issue #65 引用 agentskills.io 规范建议将 rules/ 改名为 references/，并要求 SKILL.md 仅引用而不内联规则内容，以严格落实渐进式披露。

资料来源：skills/react-best-practices/SKILL.md:1-40、skills/react-best-practices/metadata.json:1-20、skills/react-best-practices/rules/_template.md:1-30

典型规则类技能实例

react-best-practices：覆盖 React 19+ 与 Next.js 15 App Router 的编码规范，rules/ 目录包含 57 条规则文件。issue #169 指出 SKILL.md 第 137 行主动将代理引向 AGENTS.md，而 AGENTS.md 单文件长达 2,975 行 / 83KB，造成显著的上下文浪费。

composition-patterns：聚焦 React 组合模式，与 react-best-practices 在触发判断上有所重叠。issue #286 报告二者之间存在内容不一致，例如 state-lift-state.md 中的示例代码无法正确编译，影响技能间的相互引用。

react-native-skills：与仓库中正式名称 vercel-react-native-skills 容易混淆，issue #292 显示使用 react-native-skills 作为查询关键字时返回"No matching skills found"，说明发布前的命名校验是构建工具链需要补强的环节。

资料来源：skills/composition-patterns/SKILL.md:1-30、skills/react-native-skills/SKILL.md:1-30

构建与分发工具链

分发由 packages/skills 中的 CLI 提供，核心子命令包括 add、list、check、use，构建产物通过 .github/workflows/ 中的 CI 流水线发布，使 npx skills 可直接消费本仓库：

• skills add <repo>：克隆远端仓库后扫描每个子目录，校验 SKILL.md 顶部是否存在合法 YAML 头；issue #275 指出当文件首部含 HTML 注释（如 <!-- AUTO-GENERATED -->）时解析失败并显示"No valid skills found"。
• skills list：当前仅输出短名与安装路径，issue #156 建议补充来源仓库字段以提升可追溯性。
• skills check：用于检测已安装技能是否有更新，issue #152 反映其在技能下线或改名时缺少明确报错。
• skills use <repo>：在不安装的情况下打印技能正文；issue #307 中用户因仓库名拼写错误触发了意外的 GitHub 授权请求，提示命令在远端解析阶段需要更严格的输入校验。

资料来源：skills/react-best-practices/SKILL.md:1-40、skills/react-best-practices/metadata.json:1-20

社区关注的设计权衡

围绕规则类技能的形态，社区讨论折射出两类权衡。其一是聚合便利性 vs 上下文经济性：issue #169 量化了 AGENTS.md 占用 83KB 的代价，主张改用按需加载；其二是跨技能一致性 vs 单一职责：issue #286 显示两个相关技能之间出现规则重复与冲突，需要在构建阶段引入交叉校验。issue #20 进一步提出按 Claude Code Marketplace 的方式引入版本号，使发布产物可被显式锁定。这些反馈共同指向构建工具链的下一步方向：在 CI 中加入 SKILL.md/规则一致性校验、生成可选的"压缩视图"产物，并在 CLI 列表输出中暴露技能来源。

资料来源：skills/react-best-practices/AGENTS.md:1-10

概述

vercel-labs/agent-skills 仓库目前通过 README.md 描述自身为「一系列面向 Vercel 技术栈的可复用 Agent Skills 集合」，并以 skills/ 目录下各子目录（如 react-best-practices、composition-patterns、vercel-optimize 等）的 SKILL.md 与 AGENTS.md 作为发布单元。社区在使用过程中围绕「规范遵循」「文档一致性」「CLI 工具行为」三个层面提出了大量反馈，本页整理了与这些主题直接相关的已知故障模式与社区共识。资料来源：README.md:1-40

渐进式披露规范的实施冲突

社区引用了 agentskills.io 规范中的「渐进式披露（progressive disclosure）」要求，建议将 rules/ 目录重命名为 references/，并避免在 SKILL.md 中内联完整规则。仓库当前的实际实现与此建议存在显著偏差：skills/react-best-practices/AGENTS.md 据 issue #169 报告长达 2,975 行 / 83KB，且与 rules/ 下 57 个独立文件内容重复；其 SKILL.md 第 137 行还被指出「主动引导 agent 读取这个巨型聚合文件」。资料来源：skills/react-best-practices/AGENTS.md:1-2975 这一矛盾在 issue #286 中被进一步放大——state-lift-state.md 中的示例代码被确认存在破损，而同一份规则又在 composition-patterns 的 AGENTS.md 中以不同形式出现。资料来源：skills/composition-patterns/AGENTS.md:1-200

解析器与 CLI 工具的已知缺陷

CLI 工具（npx skills add / list / check / use）是用户接触规范的第一入口，社区集中报告了若干故障模式：

资料来源：README.md:1-120

跨平台兼容性与生态集成

README.md 中列出的安装目标当前覆盖 Claude Code、Codex、Cursor、Antigravity，但 issue #27（6 条评论）请求加入 VS Code Copilot 支持，表明 agent 适配矩阵尚未稳定。资料来源：README.md:40-120 issue #297 中第三方工具 ForgeCat 自行打通了本仓库的 skill / agent / hook 配置，说明生态侧已存在「跨工具适配」的真实需求。资料来源：skills/vercel-optimize/AGENTS.md:1-80 与此同时，issue #307 报告 npx skills use pocock/skills -s teach 在参数错误时会触发 GitHub OAuth 授权请求，反映 CLI 在「仓库名解析失败」路径上仍依赖远端授权而非本地报错。issue #301 提议为 vercel-optimize 增加「quick-try」链接以缓解用户评估成本。资料来源：skills/react-native-skills/AGENTS.md:1-60

待解决的提案与社区共识

当前讨论度较高的长期提案包括：

• #20 RFC：版本化与 Claude Code Marketplace 兼容——主张为技能引入语义版本并支持市场分发。资料来源：skills/react-view-transitions/AGENTS.md:1-60
• #65 遵循 agentskills.io 渐进式披露规范——与 #169 互为补充，强调以 references/ 取代聚合 AGENTS.md。资料来源：skills/react-best-practices/AGENTS.md:1-50
• #105 新增 typescript-best-practices 技能，作为 react-best-practices 的类型系统补充。资料来源：README.md:60-120

综合来看，社区已就「解析器宽松化、规则去重、CLI 错误可观测性、命名一致性、跨 agent 适配」五条主线形成共识，仓库未来的演进需要在这五个维度同步推进，才能让发布单元同时满足内部规范与外部 agent 工具链的约束。资料来源：README.md:1-200

Pitfall Log / 踩坑日志

项目：youdotcom-oss/agent-skills

摘要：发现 12 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 涉及密钥、隐私或敏感领域。

1. 安全/权限坑 · 涉及密钥、隐私或敏感领域

• 严重度：high
• 证据强度：source_linked
• 发现：项目文本出现 secret/private key/privacy/trading/finance 等敏感关键词。
• 对用户的影响：金融、交易、隐私和密钥场景必须比普通工具更保守。
• 证据：packet_text.keyword_scan | https://github.com/youdotcom-oss/agent-skills | matched secret / private key / privacy / trading / finance keyword

2. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 agent-skills 与安装入口 skills 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 复现命令：npx skills
• 证据：identity.distribution | https://github.com/youdotcom-oss/agent-skills | repo=agent-skills; install=skills

3. 安装坑 · 来源证据：🎨 PREA was here — discovered agent-skills

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：🎨 PREA was here — discovered agent-skills
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/youdotcom-oss/agent-skills/issues/9 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

4. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/youdotcom-oss/agent-skills | host_targets=claude_code, claude, cursor, openclaw, mcp_host

5. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/youdotcom-oss/agent-skills | README/documentation is current enough for a first validation pass.

6. 运行坑 · 来源证据：Weekly eval failure — 2026-04-20

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Weekly eval failure — 2026-04-20
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/youdotcom-oss/agent-skills/issues/30 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

7. 运行坑 · 来源证据：Weekly eval failure — 2026-04-27

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Weekly eval failure — 2026-04-27
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/youdotcom-oss/agent-skills/issues/32 | 来源类型 github_issue 暴露的待验证使用条件。

8. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/youdotcom-oss/agent-skills | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/youdotcom-oss/agent-skills | no_demo; severity=medium

10. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/youdotcom-oss/agent-skills | no_demo; severity=medium

11. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/youdotcom-oss/agent-skills | issue_or_pr_quality=unknown

12. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/youdotcom-oss/agent-skills | release_recency=unknown