2026-4-21 【架构】前端通用skill

在 vercel-labs/agent-skills 这个仓库中，Vercel 将其十余年的前端工程经验拆解成了多个高度模块化的指令集。这些 Skill 并非零散的 Tips，而是一套互补的、具有层级感的架构方案。

以下是对该仓库中最具代表性的几个前端 Skill 的深度对比：

核心 Skill 对比矩阵

Skill 名称	核心定位 (Objective)	关注点 (Focus)	规模与深度	适用场景
react-best-practices	性能与效率	异步瀑布流、Bundle 大小、RSC 边界、重渲染优化	57 条规则 / 8 大分类	生产环境调优、架构代码审查
web-design-guidelines	交互与合规	100% 可访问性 (A11y)、响应式、UX 细节、i18n	100+ 审计规则	UI 验收、确保交互逻辑无硬伤
composition-patterns	工程与整洁	组件组合模式、消除 “Boolean Prop Hell”	侧重架构设计模式	基础组件库设计、重构复杂组件
building-components	实现规范	组件 API 设计、无头组件 (Headless)、样式隔离	侧重代码实现细节	新业务组件开发指导
ai-elements	AI 原生交互	基于 shadcn/ui 的 AI 适配组件	库与模式结合	开发 AI Chat、生成式 UI 界面

代表性 Skill 深度拆解

1. `react-best-practices` —— 性能优化的“手术刀”

这是 Vercel 最引以为傲的 Skill。它将性能优化从“凭感觉”变成了“查表法”。

核心逻辑：优先级排序。它强制 AI 优先处理异步瀑布流 (Async Waterfalls)，其次是 Bundle Size，最后才是微小的 Re-render。
典型指令：
- “禁止在循环中等待 Promise，必须使用 Promise.all。”
- “将数据拉取逻辑移动到 Server Component，利用 Suspense 开启流式渲染。”

2. `web-design-guidelines` —— 体验的“质检员”

这是一个极度细致的 Skill，甚至包含了对暗黑模式、字体平滑、以及 ARIA 属性的强制要求。

核心逻辑：从 UI 还原度转向“用户体验合规性”。它不仅看好不好看，更看好不好用。
典型指令：
- “所有交互元素（按钮/链接）在移动端必须有 44x44px 的点击区域。”
- “图片必须携带精准的 alt 属性，且布局必须防止 CLS（累积布局偏移）。”

3. `composition-patterns` —— 架构的“指南针”

该 Skill 专注于解决 React 开发中常见的“组件臃肿”问题。

核心逻辑：提倡组合 (Composition) 优于配置 (Configuration)。它引导 AI 编写通过 children 组合的组件，而不是通过 20 个 Props 来控制内部逻辑的黑盒。
典型场景：当你让 AI 写一个复杂的 Modal 或 DataGrid 时，加载此 Skill 能显著提升代码的可扩展性。

为什么 Vercel 要把它们拆开？

通过分析这些 Skill，你可以发现它们验证了模块化 Skill 规划的三个优势：

按需注入，节省 Token：
如果你只是在写一个不涉及性能的静态页面，加载 react-best-practices 会浪费上下文并干扰 AI 决策。
职责分离 (SoC)：
react-best-practices 负责快不快，web-design-guidelines 负责美不美/好不好用。当它们冲突时（例如为了极致性能减少了 A11y 标签），明确的 Skill 边界有助于你手动介入权重。
渐进式增强：
基础开发用 building-components，进阶优化用 react-best-practices。

总结建议

如果你要效仿 Vercel 规划自己的 Skill 库，可以按照以下路径组合：

日常开发：building-components + composition-patterns
上线前 Review：web-design-guidelines + react-best-practices

前言

前端通用skill规划应包含：架构、规范、设计、性能、兼容、安全等方面；对于后台管理类React技术栈下通用skill，采用1+N模式混合模式：即一个核心总控 Skill + 多个垂直领域 Skill。核心目的是在保证上下文不冗余的前提下，让 AI 具备全局一致性的决策能力。

graph TD
    %% 定义输入
    Start((业务需求/后端接口)) --> Input[AI Agent / IDE 上下文]

    %% 第一阶段：核心架构
    subgraph Stage1 [01. 核心架构与规范: frontend-admin-core]
        direction TB
        A1[项目骨架生成] --> A2[组件/Hook 逻辑剥离]
        A2 --> A3[TypeScript 强类型契约]
    end

    %% 第二阶段：双重优化与加固
    subgraph Stage2 [生产增强引擎]
        direction LR
        subgraph P [02. 性能与效率: frontend-performance]
            P1[并行请求/缓存] --- P2[虚拟列表/懒加载]
        end
        subgraph S [03. 质量与安全: frontend-safe]
            S1[异常边界/防白屏] --- S2[脱敏/CSRF/XSS 防御]
        end
    end

    %% 第三阶段：验收交付
    subgraph Stage3 [04. 交付与验收: frontend-delivery]
        direction TB
        D1[远程代码评审 CR] --> D2[需求实现闭环验证]
        D2 --> D3[生产环境 Ready 检查]
        D3 --> D4[UI 冒烟与回归测试]
    end

    %% 连接各阶段
    Input --> Stage1
    Stage1 -->|符合规约的代码| Stage2
    Stage2 -->|优化加固后的代码| Stage3
    Stage3 -->|验收通过| Ship((发布生产))
    Stage3 -.->|验收失败| Stage1

    %% 样式美化
    style Stage1 fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    style Stage2 fill:#f1f8e9,stroke:#33691e,stroke-width:2px
    style Stage3 fill:#fff3e0,stroke:#e65100,stroke-width:2px
    style Start fill:#ececec,stroke:#666
    style Ship fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px

一、架构与规范 frontend-admin-core

定位：定义“代码长什么样”。解决后端同学最容易出现的“万能组件”和“散漫样式”问题。

组件设计：composition-patterns (组件组合)、building-components (构建基础)，强制采用组合模式。禁止通过过多的布尔值 Props 控制逻辑，优先使用 children 或 Slot 模式。
编码规范：所有组件接口必须由 TypeScript interface 定义。严禁在组件逻辑中使用 any。
交互规范：复用 web-design-guidelines。所有异步按钮必须具备 loading 状态；所有交互必须符合 44px 点击热区准则。
目录结构：强制执行 features/ 目录模式，逻辑、类型、UI 物理隔离。

1.1 composition-patterns

工程与整洁：组件组合模式、消除 “Boolean Prop Hell”侧重架构设计模式基础组件库设计、重构复杂组件

1.2 building-components

实现规范组件：API 设计、无头组件 (Headless)、样式隔离侧重代码实现细节新业务组件开发指导

1.3 web-design-guidelines

交互合规：100% 可访问性 (A11y)、响应式、UX 细节、i18n100+ 审计规则UI 验收、确保交互逻辑无硬伤

二、性能与效率 frontend-performance

定位：定义“跑得有多快”。确保后台系统在处理大数据量时依然丝滑。

数据拉取优化 (Anti-Waterfall)：复用 Vercel 针对 Suspense 和 Promise.all 的指令。禁止在循环中发起请求，强制请求并行化。
运行性能 (Rendering)：针对后台管理场景，强制对超过 50 行的列表使用虚拟滚动 (Virtual Scrolling) 评估。
加载性能 (Web Vitals)：LCP 必须小于 2.5s，CLS 必须小于 0.1。AI 在建议图片或大组件导入时，必须自动应用 dynamic() 懒加载。
缓存策略：强制使用 stale-while-revalidate 策略配置 TanStack Query，减少不必要的 Loading 闪烁。

react-best-practices 异步瀑布流、Bundle 大小、RSC 边界、重渲染优化 57 条规则 / 8 大分类生产环境调优、架构代码审查

三、质量与安全 frontend-safe

定位：定义“代码有多稳”。前端防御意识。

健壮性编码：异常处理，强制处理所有 API 的 Error Boundary。AI 生成代码时，必须包含 try-catch 或全局错误捕获逻辑。
前端安全防御：
- XSS：严禁使用 dangerouslySetInnerHTML。
- 敏感信息：禁止在客户端存储明文的敏感数据（如用户手机号），必须在渲染层进行脱敏。
- CSRF：所有 Mutation 操作必须携带自定义 Header 或校验 Token。
单元测试：AI 生成核心业务逻辑后，必须同步产出对应的 Vitest 单元测试用例。
react-best-practices (类型安全部分)

四、交付与验收 frontend-delivery

定位：定义“能不能上线”。这是最后的闸门，负责闭环审查。

代码审核 frontend-remote-code-review：此部分为“元技能”，通过引用上述三个 Skill 进行综合判定。闭环研发交付质量，远程代码评审，追加行内评论。
产出闭环验证：比对需求文档与最终实现。AI 需列出清单：已实现的 UI 交互、已覆盖的边界情况、已配置的权限点。
生产环境 Ready 检查：
- 检查是否移除了所有 console.log。
- 检查是否配置了生产环境的 API BaseURL。
- 检查国际化（i18n）文案是否全部提取。
验收交付产物
- UI自动化回归与冒烟测试

使用场景

日常开发：架构与规范 frontend-admin-core
上线前 Review：frontend-performance + frontend-safe + frontend-delivery

skill

#大模型

2026-4-21 【架构】前端通用skill

https://zhangyingxuan.github.io/2026-4-21 【架构】前端通用skill/

作者

blowsysun

许可协议

2026-4-16 【架构】多媒体&动画处理上一篇

2026-4-21 【架构】前端通用skill 下一篇

2026-4-21 【架构】前端通用skill

核心 Skill 对比矩阵

代表性 Skill 深度拆解

1. react-best-practices —— 性能优化的“手术刀”

2. web-design-guidelines —— 体验的“质检员”

3. composition-patterns —— 架构的“指南针”

为什么 Vercel 要把它们拆开？

总结建议

​前言​

一、架构与规范 frontend-admin-core

1.1 composition-patterns​

1.2 building-components​

1.3 web-design-guidelines

二、性能与效率 frontend-performance​

三、质量与安全 frontend-safe​

四、交付与验收 frontend-delivery​

使用场景​

1. `react-best-practices` —— 性能优化的“手术刀”

2. `web-design-guidelines` —— 体验的“质检员”

3. `composition-patterns` —— 架构的“指南针”

前言

1.1 composition-patterns

1.2 building-components

二、性能与效率 frontend-performance

三、质量与安全 frontend-safe

四、交付与验收 frontend-delivery

使用场景