预置 Skills

Skills 解决什么问题

.agents/skills 是 repo-local 的 AI 工作流目录。它们不承担页面功能；它们给 AI 编码工具加载专项能力：遇到 Better Auth、Zeabur、Cloudflare、文档收录、UI 审查等任务时，AI 可以先读取对应 Skill，再按项目约定做事。

这类能力适合封装三种东西：

容易记错的命令、配置和版本差异
需要长期遵守的项目工作流
不适合每次都重新解释的领域经验

除了 .agents/skills，这个模板还会使用依赖包自带的 TanStack Intent Skills。触发入口写在根目录 AGENTS.md 的 Skill Loading 区块：较大的任务开始前，AI 需要先运行 vpx @tanstack/intent@latest list；如果某个本地 skill 命中当前任务，再运行 vpx @tanstack/intent@latest load <package>#<skill> 读取对应 SKILL.md。

这里的 local 表示 skill 跟随当前仓库安装的依赖版本，例如 node_modules/.pnpm/@tanstack+react-start.../node_modules/@tanstack/react-start/skills/...。它来自依赖包发布内容，和 .agents/skills 这种仓库自维护目录分属两类。

这样做的价值是让 AI 按当前 TanStack Start / Router 版本处理路由、loader、server functions、SSR、auth guards 等容易记错的细节。

常用命令：

vpx @tanstack/intent@latest list
vpx @tanstack/intent@latest load @tanstack/react-start#react-start
vpx @tanstack/intent@latest load @tanstack/start-client-core#start-core
vpx @tanstack/intent@latest load @tanstack/router-core#router-core/data-loading

一般使用模板时不需要手动执行这些命令；当你看到 AI 先列 skill 或加载某个 TanStack skill，就是它在执行根 AGENTS.md 的仓库约定。

Codex 插件准备

如果你用 Codex 做 Apple 平台开发，建议先在 Codex 插件页搜索 xcode，安装这两个插件：

Build iOS Apps：给 Codex 接上 iOS 的 Xcode 工作流。它能帮你跑 Simulator、构建和调试 SwiftUI App，处理 App Intents / App Shortcuts，也能辅助看性能、内存泄漏和大文件 UI 重构。
Build macOS Apps：给 Codex 接上 macOS 原生开发工作流。它能帮你处理 SwiftUI / AppKit、窗口和菜单、Xcode 构建运行、测试失败、签名权限、打包和公证准备。

Codex 插件页搜索 xcode 后显示 Build iOS Apps 和 Build macOS Apps

可以把它们理解成 Codex 的 Apple 开发助手。普通 Codex 可以改代码和跑命令；装上这两个插件后，它更知道 Xcode、模拟器、日志、性能工具、签名和打包流程怎么串起来。

如果你做的是 Expo 移动端，仍优先按移动端 Skills / 插件推荐选择 Expo / React Native 能力；如果你做的是 Tauri 桌面端，仍优先按桌面端 Skills / 插件推荐处理 Tauri、Rust 和权限边界。

Repo-local 预置清单

分组	Skills	主要用途
模板初始化	`01mvp-template-initializer`	把 01MVP 模板改成一个具体产品网站
UI 审查	`web-design-guidelines`	检查界面可用性、可访问性和基础设计质量
认证	`better-auth-best-practices`、`better-auth-security-best-practices`、`email-and-password-best-practices`	Better Auth、密码登录、会话、安全加固
数据库	`products/01mvp/packages/db/AGENTS.md` + `.agents/workflow.md`	Drizzle schema、migration、数据库连接和本地迁移流程
Monorepo	`vite-plus`	Vite Plus 任务、缓存、过滤、包边界和 CI 运行方式
部署与云服务	`zeabur-deploy`、`zeabur-variables`、`zeabur-domain-url`、`workers-best-practices`、`wrangler`	Zeabur 部署、环境变量、域名，以及 Cloudflare Workers 代码和 Wrangler 命令
文档与内容	`shoulu`、`jta`	资料收录进 01MVP 文档、JSON i18n 翻译
视觉产物	`html2png`	把 HTML 渲染成 PNG 截图或发布素材

这个清单来自当前仓库的 .agents/skills 目录。以后新增、删除或升级 Skill 时，以仓库内容为准。

怎么让 AI 使用它们

通常不需要手动打开 Skill 文件。你可以直接描述任务：

用 01mvp-template-initializer 帮我把这个模板初始化成一个面向独立开发者的 AI 工具站。

帮我改 Drizzle schema 并生成迁移，注意先读 products/01mvp/packages/db/AGENTS.md。

帮我部署到 Zeabur，使用现有服务，不要创建重复服务。

如果任务里出现明确的技术栈或工作流，AI 会优先读取相关 Skill，再做代码或文档修改。

什么时候新增一个 Skill

新增 Skill 的判断很简单：如果一段工作流会重复出现，而且每次都要解释同一批约束，就值得沉淀。

适合新增 Skill 的例子：

01MVP 模板初始化
付费文档发布流程
会员权益和支付联调
某个固定部署平台的排障流程
特定内容格式的多平台发布流程

不适合新增 Skill 的例子：

只用一次的临时需求
普通代码风格偏好
已经写在 AGENTS.md 里的通用项目规则
可以直接从官方文档查到、且不会反复用到的单条命令

维护建议

Skill 的 description 要写清触发场景，否则 AI 不容易自动选中。
SKILL.md 保持短，复杂细节放到 references/。
不要在 Skill 里塞用户看不懂的内部记录；它应该指导工作流，不是保存过程日志。
升级外部 Skill 后，至少做一次真实任务或小型验证，确认新规则没有和 01MVP 项目约定冲突。