> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 技能

现成的指令集，教你的编码智能体按 kit 期望的方式完成常见的 supastack 工作。

## 什么是技能

supastack 内置 Agent Skills：当工作匹配时，编码智能体会加载这些简短、面向任务的指令。智能体不必在每次提示中猜测 kit 的约定，而是对功能、支付、数据库变更和测试遵循相同的步骤。技能遵循开放的 Agent Skills 格式，因此可在 Claude Code、Cursor、Codex、GitHub Copilot、Gemini CLI 及其他兼容智能体中使用。


## 技能的位置

技能位于 `.agents/skills/`，每个技能一个文件夹，内含 `SKILL.md`。`.claude/skills/` 中存放供 Claude Code 使用的相同副本。


## 哪些智能体读取它们

Codex、Cursor、GitHub Copilot、Gemini CLI 和 OpenCode 读取 `.agents/skills/`；Claude Code 读取 `.claude/skills/`。当请求与技能的描述匹配时，智能体会自动选用；你也可以点名，比如说“use the `database-schema-change` skill”。


## 哪些仓库包含它们

all-platforms 仓库包含全部技能。web、mobile 和 desktop 仓库包含适用于各自平台的技能；端到端测试和 CI 技能仅随 all-platforms 仓库提供。


## 设置与环境

让 kit 运行、部署和配置到位的技能。

- **本地环境设置** (`local-environment-setup`) — 初始化或修复本地环境时使用：首次克隆、.env 缺失或损坏、Postgres、迁移或端口问题。
- **部署与环境变量** (`deploy-and-env-vars`) — 部署、选择托管目标，或添加/修改环境变量时使用。
- **添加依赖** (`adding-a-dependency`) — 添加、升级、移动或移除 npm 依赖，或 CI 的许可证/审计检查失败时使用。
- **从上游升级** (`upgrading-from-upstream`) — 把更新的 supastack 版本引入基于它构建的产品时使用。


## 构建功能

在各平台添加产品功能的技能。

- **添加 Web 功能** (`add-a-web-feature`) — 添加自带数据、server actions、导航和测试的产品页面或版块时使用。
- **添加 API 端点** (`add-an-api-endpoint`) — 添加或修改公开的 /api/v1 端点、其 OpenAPI 文档或 API 密钥权限范围时使用。
- **添加 UI 组件** (`add-a-ui-component`) — 构建遵循 kit 样式规则的版块、区块、表单控件或可复用组件时使用。
- **更改主题或样式** (`change-the-theme-or-style`) — 改变产品外观时使用：设计风格、配色包、密度、圆角、字体或布局。
- **添加营销页面或博客文章** (`add-a-marketing-page-or-blog-post`) — 添加或编辑公开页面、定价页、法律页面、博客文章或文档指南时使用。
- **添加移动端页面** (`add-a-mobile-screen`) — 在 Expo 移动应用中添加或修改页面时使用。
- **添加桌面端能力** (`add-a-desktop-capability`) — 修改 Tauri 桌面应用时使用：窗口、托盘、全局快捷键或自动更新。
- **添加通知** (`add-a-notification`) — 添加应用内通知、推送通知或摘要条目时使用。


## 认证与支付

登录、计费与套餐相关技能。

- **添加认证方式** (`add-an-auth-method`) — 修改登录方式时使用：社交登录、魔法链接、邮箱验证码、passkey 或两步验证。
- **添加支付服务商** (`add-a-payment-provider`) — 启用计费服务商，或编写带 checkout、客户门户和 webhook 的新计费适配器时使用。
- **调整套餐与定价** (`change-plans-and-pricing`) — 添加、重命名套餐或调整价格时使用：价格、试用、席位、权益、用量上限或积分。


## 数据与集成

数据库模式、AI、任务、邮件、存储与翻译的技能。

- **数据库模式变更** (`database-schema-change`) — 添加或修改表、列、索引或关系并生成迁移时使用。
- **添加 AI 功能** (`add-an-ai-feature`) — 添加模型调用、聊天或智能体工具、持久化 AI 任务、预算或自带密钥时使用。
- **添加后台任务** (`add-a-background-job`) — 添加在请求后、定时或按工作区运行的任务时使用。
- **添加或编辑邮件** (`add-or-edit-an-email`) — 添加或修改事务性邮件，或更换投递服务商时使用。
- **使用文件存储** (`use-file-storage`) — 添加头像、logo、附件等上传或文件存储功能时使用。
- **添加翻译** (`add-translations`) — 添加或修改用户可见文案、翻译或新增语言时使用。


## 质量与交付

测试、验证、评审与 CI 的技能。

- **编写单元测试** (`writing-unit-tests`) — 编写或修复 Vitest 单元测试或集成测试时使用。
- **编写 E2E 测试** (`writing-e2e-tests`) — 在本地或 CI 中添加或修复 Playwright 端到端测试时使用。
- **验证变更** (`verify-changes`) — 在交接、提交或创建 pull request 前，选择并运行正确的检查时使用。
- **调试失败的 CI 运行** (`debugging-a-failing-ci-run`) — GitHub Actions 运行失败、需要定位并修复原因时使用。
- **评审 PR** (`reviewing-a-pr`) — 评审 pull request 或 diff 的正确性、工作区隔离和约定时使用。


## 添加自己的技能

新建一个文件夹，文件夹名与 frontmatter 中的 `name` 一致，并写好说明何时使用的 `name` 和 `description`。同时把它复制到 `.claude/skills/`，让所有智能体都能找到。


## 下一篇

[用编码代理构建](https://supastack.dev/zh/docs/web/agents.md)