Agent Skills

仓库在 .agents/skills/ 中维护面向编码 Agent 的项目级 Skills。Skills 是辅助工作流，不替代 AGENTS.md 中的架构、安全和验证要求。

当前 Skills

Skill	适用场景	位置
Better Auth 最佳实践	Better Auth 配置、插件、session、账号绑定和认证 API	.agents/skills/better-auth-best-practices/
前端设计	新建或重做页面、组件和视觉交互	.agents/skills/frontend-design/
Turborepo	turbo.json、任务依赖、缓存、filter 和 CI 优化	.agents/skills/turborepo/
Vercel React 最佳实践	React/Next.js 性能审查与重构	.agents/skills/vercel-react-best-practices/

使用原则

Agent 在任务明确匹配 Skill 描述时应先读取对应 SKILL.md，再执行代码修改。多个 Skill 同时适用时，只选择覆盖任务所需的最小集合。

Better Auth 相关任务

调整登录、插件、OAuth Provider、用户字段或 session 时，使用 Better Auth Skill，并遵守仓库数据库流程：

pnpm dlx auth@1.7.1 generate --yes \
  --config packages/auth/src/index.ts \
  --output packages/db/src/schema/auth.ts
pnpm db:generate
pnpm db:migrate

db:push 只用于可丢弃的本地数据库临时验证。

Next.js 前端任务

• 修改 Next.js 代码前先阅读 apps/web/node_modules/next/dist/docs/ 中对应文档。
• 页面/组件设计使用 Frontend Design Skill。
• React/Next.js 性能实现或审查使用 Vercel React Skill。
• apps/web 不得导入服务端 package；共享契约放入 @IAM/contracts。

Monorepo 任务

涉及 Turbo pipeline、缓存、workspace filter 或 CI 编排时使用 Turborepo Skill。先核对根 package.json、turbo.json 和各 workspace 脚本，避免文档与实际任务名不一致。

维护 Skills

新增、删除或重命名 .agents/skills/* 后，应同步更新本页。Skill 内的命令也必须固定到项目实际依赖版本，避免使用可能改变行为的 latest。