guide

# 单技能执行

单技能执行是快速路径，一个智能体，一个领域，一个聚焦的任务。没有编排开销，没有多智能体协调。技能从你的自然语言提示自动激活。

---

## 何时使用单技能

当你的任务满足以下所有条件时使用：

- **属于单一领域**：整个任务属于前端、后端、移动端、数据库、设计、基础设施或其他单一领域
- **自包含**：不需要跨领域 API 契约变更，前端任务不需要后端变更
- **范围明确**：你知道输出应该是什么（一个组件、一个端点、一个模式、一个修复）
- **无需协调**：其他智能体不需要在之前或之后运行

**单技能任务示例：**
- 构建一个 UI 组件
- 添加一个 API 端点
- 修复一层中的一个 Bug
- 设计一个数据库表
- 编写一个 Terraform 模块
- 翻译一组 i18n 字符串
- 创建一个设计系统章节

**切换到多智能体**（`/work` 或 `/orchestrate`）的时机：
- UI 工作需要新的 API 契约（前端 + 后端）
- 一个修复在多层之间产生级联影响（调试 + 实现智能体）
- 功能跨越前端、后端和数据库
- 第一次迭代后范围扩展到超出单一领域

---

## 预检清单

提示之前，回答以下四个问题（它们对应[提示结构](/docs/core-concepts/skills)的四个要素）：

| 要素 | 问题 | 为什么重要 |
|------|------|----------|
| **目标** | 应该创建或更改什么具体产物？ | 防止歧义："添加一个按钮"与"添加一个带验证的表单" |
| **上下文** | 适用什么技术栈、框架和约定？ | 智能体从项目文件检测，但明确指定更好 |
| **约束** | 必须遵循什么规则？（样式、安全、性能、兼容性） | 没有约束，智能体使用可能不符合你项目的默认值 |
| **完成条件** | 你将检查什么验收标准？ | 给智能体一个目标，给你一个验证清单 |

如果提示中缺少任何要素，智能体将：
- **LOW 不确定性：** 应用默认值并列出假设
- **MEDIUM 不确定性：** 提出 2-3 个选项并按最可能的继续
- **HIGH 不确定性：** 阻塞并提问（不会编写代码）

---

## 提示模板

```text
Build <specific artifact> using <stack/framework>.
Constraints: <style, performance, security, or compatibility constraints>.
Acceptance criteria:
1) <testable criterion>
2) <testable criterion>
3) <testable criterion>
Add tests for: <critical test cases>.
```

### 模板拆解

| 部分 | 目的 | 示例 |
|------|------|------|
| `Build <specific artifact>` | 目标：创建什么 | "Build a user registration form component" |
| `using <stack/framework>` | 上下文：技术栈 | "using React + TypeScript + Tailwind CSS" |
| `Constraints:` | 智能体必须遵循的规则 | "accessible labels, no external form libraries, client-side validation only" |
| `Acceptance criteria:` | 完成条件：可验证的结果 | "1) email format validation 2) password strength indicator 3) submit disabled while invalid" |
| `Add tests for:` | 测试要求 | "valid/invalid submit paths, edge cases for email validation" |

---

## 真实示例

### 前端：登录表单

```text
Create a login form component in React + TypeScript + Tailwind CSS.
Constraints: accessible labels, client-side validation with Zod, no external form library beyond @tanstack/react-form, shadcn/ui Button and Input components.
Acceptance criteria:
1) Email validation with meaningful error messages
2) Password minimum 8 characters with feedback
3) Disabled submit button while form is invalid
4) Keyboard and screen-reader friendly (ARIA labels, focus management)
5) Loading state while submitting
Add unit tests for: valid submission path, invalid email, short password, loading state.
```

**预期执行流程：**

1. **技能激活：** `oma-frontend` 激活（关键词："form"、"component"、"Tailwind CSS"、"React"）
2. **难度评估：** 中等（2-3 个文件，需要关于验证 UX 的一些设计决策）
3. **加载的资源：**
   - `execution-protocol.md`（始终）
   - `snippets.md`（表单 + Zod 模式）
   - `component-template.tsx`（React 结构）
4. **CHARTER_CHECK 输出：**
   ```
   CHARTER_CHECK:
   - Clarification level: LOW
   - Task domain: frontend
   - Must NOT do: backend API, database, mobile screens
   - Success criteria: form validation, accessibility, loading state, tests
   - Assumptions: Next.js App Router, @tanstack/react-form + Zod, shadcn/ui, FSD-lite architecture
   ```
5. **实现：**
   - 创建 `src/features/auth/components/login-form.tsx`（带 `"use client"` 的客户端组件）
   - 创建 `src/features/auth/utils/login-schema.ts`（Zod schema）
   - 创建 `src/features/auth/components/skeleton/login-form-skeleton.tsx`
   - 使用 shadcn/ui `<Button>`、`<Input>`、`<Label>`（只读，不修改）
   - 表单由 `@tanstack/react-form` 与 Zod 验证处理
   - 使用 `@/` 绝对导入
   - 每个文件一个组件
6. **验证：**
   - 检查清单：ARIA 标签存在、语义化标题、键盘导航有效
   - 移动端：在 320px 视口正确渲染
   - 性能：无 CLS
   - 测试：Vitest 测试文件位于 `src/features/auth/utils/__tests__/login-schema.test.ts`

---

### 后端：REST API 端点

```text
Add a paginated GET /api/tasks endpoint that returns tasks for the authenticated user.
Constraints: Repository-Service-Router pattern, parameterized queries, JWT auth required, cursor-based pagination.
Acceptance criteria:
1) Returns only tasks owned by the authenticated user
2) Cursor-based pagination with next/prev cursors
3) Filterable by status (todo, in_progress, done)
4) Response includes total count
Add tests for: auth required, pagination, status filter, empty results.
```

**预期执行流程：**

1. **技能激活：** `oma-backend` 激活（关键词："API"、"endpoint"、"REST"）
2. **栈检测：** 读取 `pyproject.toml` 或 `package.json` 确定语言/框架。如果 `stack/` 存在，从中加载约定。
3. **难度评估：** 中等（2-3 个文件：路由、服务、仓储，加上测试）
4. **加载的资源：**
   - `execution-protocol.md`（始终）
   - `stack/snippets.md`（如果可用，路由和分页查询模式）
   - `stack/tech-stack.md`（如果可用，框架特定 API）
5. **CHARTER_CHECK：**
   ```
   CHARTER_CHECK:
   - Clarification level: LOW
   - Task domain: backend
   - Must NOT do: frontend UI, mobile screens, database schema changes
   - Success criteria: authenticated endpoint, cursor pagination, status filter, tests
   - Assumptions: existing JWT auth middleware, PostgreSQL, existing Task model
   ```
6. **实现：**
   - Repository：`TaskRepository.find_by_user(user_id, cursor, status, limit)` 使用参数化查询
   - Service：`TaskService.get_user_tasks(user_id, cursor, status, limit)`，业务逻辑包装
   - Router：`GET /api/tasks` 带 JWT 认证中间件、输入验证、响应格式化
   - 测试：未认证返回 401、分页返回正确游标、过滤有效、空结果返回 200 和空数组

---

### 移动端：设置界面

```text
Build a settings screen in Flutter with profile editing (name, email, avatar), notification preferences (toggle switches), and a logout button.
Constraints: Riverpod for state management, GoRouter for navigation, Material Design 3, handle offline gracefully.
Acceptance criteria:
1) Profile fields pre-populated from user data
2) Changes saved on submit with loading indicator
3) Notification toggles persist locally (SharedPreferences)
4) Logout clears token storage and navigates to login
5) Offline: show cached data with "offline" banner
Add tests for: profile save, logout flow, offline state.
```

**预期执行流程：**

1. **技能激活：** `oma-mobile` 激活（关键词："Flutter"、"screen"、"mobile"）
2. **难度评估：** 中等（设置界面 + 状态管理 + 离线处理）
3. **加载的资源：**
   - `execution-protocol.md`
   - `snippets.md`（界面模板、Riverpod provider 模式）
   - `screen-template.dart`
4. **CHARTER_CHECK：**
   ```
   CHARTER_CHECK:
   - Clarification level: LOW
   - Task domain: mobile
   - Must