Cursor Skills 使用指南

本项目集成了多个 Cursor Skills，帮助 AI 助手更好地理解项目结构和最佳实践。

可用的 Skills

Better Auth 最佳实践

提供 Better Auth 认证框架的集成指南和最佳实践

代码审查

对 Git 工作区中的代码修改进行全面审查

创建认证层

指导在 TypeScript/JavaScript 应用中添加认证功能

React 组合模式

React 组件组合模式，避免布尔属性泛滥，构建灵活的组件库

React 最佳实践

Vercel 的 React 和 Next.js 性能优化指南，包含 57 条规则

Web 设计指南

审查 UI 代码是否符合 Web 界面设计指南

Better Auth 最佳实践

Skill 名称: better-auth-best-practices

描述: 提供 Better Auth TypeScript 认证框架的集成指南和最佳实践。

主要功能

Better Auth 配置选项参考
数据库适配器使用指南
会话管理最佳实践
插件集成方法
安全配置检查清单
常见问题排查

使用场景

当需要：

配置 Better Auth 认证系统
添加新的认证功能（OAuth、2FA、Passkey 等）
排查认证相关问题
优化认证配置

关键信息

环境变量:

BETTER_AUTH_SECRET - 加密密钥（至少 32 字符）
BETTER_AUTH_URL - 基础 URL

CLI 命令:

# 应用数据库迁移
npx @better-auth/cli@latest migrate

# 生成 Prisma/Drizzle schema
npx @better-auth/cli@latest generate

# 添加 MCP 到 AI 工具
npx @better-auth/cli mcp --cursor

重要提示: 添加或修改插件后需要重新运行 CLI 命令。

代码审查

Skill 名称: code-review

描述: 对 Git 工作区中的代码修改进行全面审查，发现潜在问题并提供改进建议。

主要功能

按严重级别分类问题（Critical/Medium/Low）
安全漏洞检测
性能问题识别
代码质量评估
测试覆盖检查

使用场景

当需要：

审核代码变更
检查 PR 质量
验证修改是否符合项目规范
完成代码修改后验证质量

审查维度

🔴 Critical - 必须修复

安全漏洞（注入、XSS、权限绕过）
数据安全问题
稳定性问题（崩溃、死循环）

🟡 Medium - 建议修复

逻辑或边界条件问题
性能问题（N+1 查询）
错误处理不完善
兼容性问题

🟢 Low - 可选优化

命名问题
代码重复
注释缺失

触发方式

直接要求：“请审查我的代码”
使用命令：/code-review
完成一组修改后自动触发

创建认证层

Skill 名称: create-auth-skill

描述: 指导在 TypeScript/JavaScript 应用中添加认证功能。

主要功能

新项目认证设置
现有项目认证集成
认证迁移指南
插件选择建议
安全配置检查清单

使用场景

当需要：

在新项目中添加认证
在现有项目中集成认证
迁移现有认证系统
添加新的认证功能

决策树

新项目？
├─ 是 → 完整设置流程
└─ 否 → 已有认证？
    ├─ 是 → 迁移/增强
    └─ 否 → 添加到现有项目

安装步骤

安装 Better Auth: npm install better-auth
创建 auth.ts 配置文件
创建 auth-client.ts 客户端配置
设置路由处理器
运行数据库迁移
添加功能插件

React 组合模式

Skill 名称: vercel-composition-patterns

描述: React 组合模式，用于构建灵活、可维护的 React 组件。避免布尔属性泛滥，使用组合组件、状态提升和内部组合。这些模式使代码库在扩展时更容易被人类和 AI 代理使用。

主要功能

组件架构 (高优先级)
- 避免布尔属性泛滥 - 使用组合而非布尔属性自定义行为
- 复合组件 - 使用共享上下文构建复杂组件
状态管理 (中优先级)
- 解耦实现 - Provider 是唯一知道如何管理状态的地方
- 上下文接口 - 定义包含 state、actions、meta 的通用接口用于依赖注入
- 状态提升 - 将状态移到 Provider 组件中以供兄弟组件访问
实现模式 (中优先级)
- 显式变体 - 创建显式变体组件而非布尔模式
- 优先使用 children 而非 render props - 使用 children 进行组合

使用场景

当需要：

重构具有多个布尔属性的组件
构建可复用的组件库
设计灵活的组件 API
审查组件架构
使用复合组件或上下文提供者

规则优先级

优先级	类别	影响	前缀
1	组件架构	HIGH	`architecture-`
2	状态管理	MEDIUM	`state-`
3	实现模式	MEDIUM	`patterns-`

详细文档

每个规则文件包含：

为什么重要的简要说明
错误的代码示例及解释
正确的代码示例及解释
额外的上下文和参考

完整指南请参考：.agents/skills/vercel-composition-patterns/AGENTS.md

React 最佳实践

Skill 名称: vercel-react-best-practices

描述: Vercel Engineering 维护的 React 和 Next.js 性能优化综合指南。包含 57 条规则，涵盖 8 个类别，按影响优先级排序，指导自动化重构和代码生成。

主要功能

1. 消除瀑布流 (CRITICAL)

async-defer-await - 将 await 移到实际使用的分支中
async-parallel - 对独立操作使用 Promise.all()
async-dependencies - 使用 better-all 处理部分依赖
async-api-routes - 在 API 路由中尽早启动 promise，延迟 await
async-suspense-boundaries - 使用 Suspense 流式传输内容

2. 打包大小优化 (CRITICAL)

bundle-barrel-imports - 直接导入，避免 barrel 文件
bundle-dynamic-imports - 对重型组件使用 next/dynamic
bundle-defer-third-party - 在 hydration 后加载分析/日志
bundle-conditional - 仅在功能激活时加载模块
bundle-preload - 在悬停/聚焦时预加载以提高感知速度

3. 服务端性能 (HIGH)

server-auth-actions - 像 API 路由一样验证服务器操作
server-cache-react - 使用 React.cache() 进行每请求去重
server-cache-lru - 使用 LRU 缓存进行跨请求缓存
server-dedup-props - 避免 RSC props 中的重复序列化
server-serialization - 最小化传递给客户端组件的数据
server-parallel-fetching - 重构组件以并行化获取
server-after-nonblocking - 对非阻塞操作使用 after()

4. 客户端数据获取 (MEDIUM-HIGH)

client-swr-dedup - 使用 SWR 进行自动请求去重
client-event-listeners - 去重全局事件监听器
client-passive-event-listeners - 对滚动使用被动监听器
client-localstorage-schema - 版本化和最小化 localStorage 数据

5. 重渲染优化 (MEDIUM)

rerender-defer-reads - 不要订阅仅在回调中使用的状态
rerender-memo - 将昂贵的工作提取到记忆化组件中
rerender-memo-with-default-value - 提升默认非原始 props
rerender-dependencies - 在 effects 中使用原始依赖
rerender-derived-state - 订阅派生的布尔值，而非原始值
rerender-derived-state-no-effect - 在渲染期间派生状态，而非 effects
rerender-functional-setstate - 为稳定回调使用函数式 setState
rerender-lazy-state-init - 为昂贵值向 useState 传递函数
rerender-simple-expression-in-memo - 避免对简单原始值使用 memo
rerender-move-effect-to-event - 将交互逻辑放在事件处理程序中
rerender-transitions - 对非紧急更新使用 startTransition
rerender-use-ref-transient-values - 对瞬态频繁值使用 refs

6. 渲染性能 (MEDIUM)

rendering-animate-svg-wrapper - 动画化 div 包装器，而非 SVG 元素
rendering-content-visibility - 对长列表使用 content-visibility
rendering-hoist-jsx - 在组件外部提取静态 JSX
rendering-svg-precision - 降低 SVG 坐标精度
rendering-hydration-no-flicker - 对仅客户端数据使用内联脚本
rendering-hydration-suppress-warning - 抑制预期的失配
rendering-activity - 对显示/隐藏使用 Activity 组件
rendering-conditional-render - 对条件使用三元运算符，而非 &&
rendering-usetransition-loading - 对加载状态优先使用 useTransition

7. JavaScript 性能 (LOW-MEDIUM)

js-batch-dom-css - 通过类或 cssText 分组 CSS 更改
js-index-maps - 为重复查找构建 Map
js-cache-property-access - 在循环中缓存对象属性
js-cache-function-results - 在模块级 Map 中缓存函数结果
js-cache-storage - 缓存 localStorage/sessionStorage 读取
js-combine-iterations - 将多个 filter/map 合并为一个循环
js-length-check-first - 在昂贵比较之前检查数组长度
js-early-exit - 从函数中提前返回
js-hoist-regexp - 在循环外提升 RegExp 创建
js-min-max-loop - 对 min/max 使用循环而非 sort
js-set-map-lookups - 对 O(1) 查找使用 Set/Map
js-tosorted-immutable - 对不可变性使用 toSorted()

8. 高级模式 (LOW)

advanced-event-handler-refs - 在 refs 中存储事件处理程序
advanced-init-once - 每次应用加载初始化一次
advanced-use-latest - 用于稳定回调 refs 的 useLatest

使用场景

当需要：

编写新的 React 组件或 Next.js 页面
实现数据获取（客户端或服务端）
审查代码的性能问题
重构现有的 React/Next.js 代码
优化打包大小或加载时间

规则优先级

优先级	类别	影响	前缀
1	消除瀑布流	CRITICAL	`async-`
2	打包大小优化	CRITICAL	`bundle-`
3	服务端性能	HIGH	`server-`
4	客户端数据获取	MEDIUM-HIGH	`client-`
5	重渲染优化	MEDIUM	`rerender-`
6	渲染性能	MEDIUM	`rendering-`
7	JavaScript 性能	LOW-MEDIUM	`js-`
8	高级模式	LOW	`advanced-`

详细文档

每个规则文件包含：

为什么重要的简要说明
错误的代码示例及解释
正确的代码示例及解释
额外的上下文和参考

完整指南请参考：.agents/skills/vercel-react-best-practices/AGENTS.md

Web 设计指南

Skill 名称: web-design-guidelines

描述: 审查 UI 代码是否符合 Web 界面设计指南。用于审查 UI、检查可访问性、审核设计、审查 UX 或检查网站是否符合最佳实践。

主要功能

从源 URL 获取最新的设计指南
读取指定的文件（或提示用户提供文件/模式）
对照获取的指南中的所有规则进行检查
以简洁的 file:line 格式输出发现的问题

使用场景

当需要：

审查 UI 代码
检查可访问性
审核设计
审查 UX
检查网站是否符合最佳实践

工作原理

从源 URL 获取最新指南
读取指定的文件（或提示用户提供文件/模式）
对照获取的指南中的所有规则进行检查
以指南中指定的格式输出发现的问题

指南来源

在每次审查前获取最新指南：

https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md

使用 WebFetch 检索最新规则。获取的内容包含所有规则和输出格式说明。

使用方法

当用户提供文件或模式参数时：

从上述源 URL 获取指南
读取指定的文件
应用获取的指南中的所有规则
使用指南中指定的格式输出发现的问题

如果未指定文件，将询问用户要审查哪些文件。

如何使用 Skills

在 Cursor 中使用

Skills 会自动加载，当你的问题或任务与某个 Skill 相关时，AI 助手会自动使用相应的 Skill。

显式触发

你也可以在对话中明确提到：

“使用 better-auth-best-practices skill 检查我的认证配置”
“运行 code-review 审查我的代码”
“使用 create-auth-skill 帮我添加认证功能”
“使用 vercel-composition-patterns 重构这个组件”
“应用 vercel-react-best-practices 优化性能”
“使用 web-design-guidelines 审查我的 UI”

Skill 位置

Skills 位于两个位置：

.cursor/skills/ - Cursor Skills（用于 Cursor IDE）：

.cursor/skills/
├── better-auth-best-practices/
│   └── SKILL.md
├── code-review/
│   └── SKILL.md
└── create-auth-skill/
    └── SKILL.md

.agents/skills/ - Agent Skills（用于 AI 代理）：

.agents/skills/
├── vercel-composition-patterns/
│   ├── SKILL.md
│   ├── AGENTS.md
│   └── rules/
├── vercel-react-best-practices/
│   ├── SKILL.md
│   ├── AGENTS.md
│   └── rules/
└── web-design-guidelines/
    └── SKILL.md

最佳实践

明确需求: 在请求帮助时，尽量明确你的目标和约束条件
提供上下文: 分享相关的代码片段或错误信息
迭代改进: 根据 Skill 的建议逐步改进代码
验证结果: 使用 Skill 后，验证建议是否适合你的项目

Cursor Skills 使用指南

可用的 Skills

Better Auth 最佳实践

主要功能

使用场景

关键信息

代码审查

主要功能

使用场景

审查维度

🔴 Critical - 必须修复

🟡 Medium - 建议修复

🟢 Low - 可选优化

触发方式

创建认证层

主要功能

使用场景

决策树

安装步骤

React 组合模式

主要功能

使用场景

规则优先级

详细文档

React 最佳实践

主要功能

1. 消除瀑布流 (CRITICAL)

2. 打包大小优化 (CRITICAL)

3. 服务端性能 (HIGH)

4. 客户端数据获取 (MEDIUM-HIGH)

5. 重渲染优化 (MEDIUM)

6. 渲染性能 (MEDIUM)

7. JavaScript 性能 (LOW-MEDIUM)

8. 高级模式 (LOW)

使用场景

规则优先级

详细文档

Web 设计指南

主要功能

使用场景

工作原理

指南来源

使用方法

如何使用 Skills

在 Cursor 中使用

显式触发

Skill 位置

最佳实践

相关资源