技能
技能是赋予每个智能体领域专业知识的结构化知识包。它们不仅仅是提示 —— 它们包含执行协议、技术栈参考、代码模板、错误处理手册、质量检查清单和少样本示例，以为 token 效率设计的两层架构组织。
两层设计
第一层：SKILL.md（约 800 字节，始终加载）
每个技能在其根目录下都有一个 SKILL.md 文件。当技能被引用时，它始终被加载到上下文窗口中。它包含：
- YAML 前置元数据，包含
name和description（用于路由和显示） - 何时使用 / 何时不使用 —— 明确的激活条件
- 核心规则 —— 领域中最关键的 5-15 条约束
- 架构概览 —— 代码应如何组织
- 库列表 —— 批准的依赖及其用途
- 引用 —— 指向第二层资源的指针（永不自动加载）
前置元数据示例：
---
name: oma-frontend
description: Frontend specialist for React, Next.js, TypeScript with FSD-lite architecture, shadcn/ui, and design system alignment. Use for UI, component, page, layout, CSS, Tailwind, and shadcn work.
---
description 字段至关重要 —— 它包含技能路由系统用于将任务匹配到智能体的路由关键词。
第二层：resources/（按需加载）
resources/ 目录包含深层执行知识。这些文件仅在以下情况下加载：
- 智能体被显式调用（通过
/command或智能体 skills 字段） - 当前任务类型和难度需要特定资源
这种按需加载由上下文加载指南（.agents/skills/_shared/core/context-loading.md）管理，它将任务类型映射到每个智能体所需的资源。
文件结构示例
.agents/skills/oma-frontend/
├── SKILL.md ← 第一层：始终加载（约 800 字节）
└── resources/
├── execution-protocol.md ← 第二层：分步工作流
├── tech-stack.md ← 第二层：详细技术规范
├── tailwind-rules.md ← 第二层：Tailwind 特定约定
├── component-template.tsx ← 第二层：React 组件模板
├── snippets.md ← 第二层：可复制粘贴的代码模式
├── error-playbook.md ← 第二层：错误恢复流程
├── checklist.md ← 第二层：质量验证清单
└── examples/ ← 第二层：少样本输入/输出示例
└── examples.md
.agents/skills/oma-backend/
├── SKILL.md
├── resources/
│ ├── execution-protocol.md
│ ├── examples.md
│ ├── orm-reference.md ← 领域特定（ORM 查询、N+1、事务）
│ ├── checklist.md
│ └── error-playbook.md
└── stack/ ← 由 /stack-set 生成（语言特定）
├── stack.yaml
├── tech-stack.md
├── snippets.md
└── api-template.*
.agents/skills/oma-design/
├── SKILL.md
├── resources/
│ ├── execution-protocol.md
│ ├── anti-patterns.md
│ ├── checklist.md
│ ├── design-md-spec.md
│ ├── design-tokens.md
│ ├── prompt-enhancement.md
│ ├── stitch-integration.md
│ └── error-playbook.md
├── reference/ ← 深层参考材料
│ ├── typography.md
│ ├── color-and-contrast.md
│ ├── spatial-design.md
│ ├── motion-design.md
│ ├── responsive-design.md
│ ├── component-patterns.md
│ ├── accessibility.md
│ └── shader-and-3d.md
└── examples/
├── design-context-example.md
└── landing-page-prompt.md
每技能资源类型
| 资源类型 | 文件名模式 | 目的 | 加载时机 |
|---|---|---|---|
| 执行协议 | execution-protocol.md | 分步工作流：分析 -> 规划 -> 实现 -> 验证 | 始终（随 SKILL.md） |
| 技术栈 | tech-stack.md | 详细技术规范、版本、配置 | 复杂任务 |
| 错误手册 | error-playbook.md | 带"三击出局"升级的恢复流程 | 仅在出错时 |
| 检查清单 | checklist.md | 领域特定的质量验证 | 在验证步骤 |
| 代码片段 | snippets.md | 可直接复制的代码模式 | 中等/复杂任务 |
| 示例 | examples.md 或 examples/ | LLM 的少样本输入/输出示例 | 中等/复杂任务 |
| 变体 | stack/ 目录 | 语言/框架特定参考（由 /stack-set 生成） | 当 stack 存在时 |
| 模板 | component-template.tsx、screen-template.dart | 样板文件模板 | 创建组件时 |
| 领域参考 | orm-reference.md、anti-patterns.md 等 | 特定子任务的深层领域知识 | 任务类型特定 |
共享资源（_shared/）
所有智能体共享来自 .agents/skills/_shared/ 的公共基础。分为三类：
核心资源（.agents/skills/_shared/core/）
| 资源 | 目的 | 加载时机 |
|---|---|---|
skill-routing.md | 将任务关键词映射到正确的智能体。包含技能-智能体映射表、复杂请求路由模式、智能体间依赖规则、升级规则和回合限制指南。 | 由编排器和协调技能引用 |
context-loading.md | 定义为哪种任务类型和难度加载哪些资源。包含每个智能体的任务类型到资源映射表和条件协议加载触发器。 | 在工作流开始时（步骤 0 / 阶段 0） |
prompt-structure.md | 定义每个任务提示必须包含的四个要素：目标、上下文、约束、完成条件。包含 PM、实现和 QA 智能体的模板。列出反模式。 | 由 PM 智能体和所有工作流引用 |
clarification-protocol.md | 定义不确定性级别（LOW/MEDIUM/HIGH）及每级的操作。包含不确定性触发器、升级模板、每种智能体类型的必需验证项和子智能体模式行为。 | 需求模糊时 |
context-budget.md | Token 预算管理。定义文件读取策略（使用 find_symbol 而非 read_file）、每个模型层级的资源加载预算（Flash：约 3,100 token / Pro：约 5,000 token）、大文件处理和上下文溢出症状。 | 在工作流开始时 |
difficulty-guide.md | 将任务分类为简单/中等/复杂的标准。定义预期回合数、协议分支（快速通道 / 标准 / 扩展）和误判恢复。 | 在任务开始时（步骤 0） |
reasoning-templates.md | 常见决策模式的结构化推理填空模板。 | 复杂决策期间 |
quality-principles.md | 适用于所有智能体的 4 条通用质量原则。 | 在以质量为中心的工作流（ultrawork）开始时 |
vendor-detection.md | 检测当前运行时环境的协议（Claude Code、Codex CLI、Gemini CLI、Antigravity、CLI 回退）。使用标记检查：Agent 工具 = Claude Code、apply_patch = Codex、@-语法 = Gemini。 | 在工作流开始时 |
session-metrics.md | 澄清债务（CD）评分和会话指标追踪。定义事件类型（clarify +10、correct +25、redo +40）、阈值（CD >= 50 = RCA、CD >= 80 = 暂停）和集成点。 | 编排会话期间 |
common-checklist.md | 复杂任务最终验证时应用的通用质量清单。 | 复杂任务的验证步骤 |
lessons-learned.md | 过去会话经验的存储库，从澄清债务违规和被丢弃的实验自动生成。 | 错误后和会话结束时引用 |
api-contracts/ | 包含 API 契约模板和生成的契约的目录。template.md 定义每个端点的格式（方法、路径、请求/响应模式、认证、错误）。 | 规划跨边界工作时 |
运行时资源（.agents/skills/_shared/runtime/）
| 资源 | 目的 |
|---|---|
memory-protocol.md | CLI 子智能体的内存文件格式和操作。定义启动时、执行期间和完成时的协议，使用可配置的内存工具（read/write/edit）。包含实验追踪扩展。 |
execution-protocols/claude.md | Claude Code 特定的执行模式。供应商为 claude 时由 oma agent:spawn 注入。 |
execution-protocols/gemini.md | Gemini CLI 特定的执行模式。 |
execution-protocols/codex.md | Codex CLI 特定的执行模式。 |
execution-protocols/qwen.md | Qwen CLI 特定的执行模式。 |
供应商特定的执行协议由 oma agent:spawn 自动注入 —— 智能体无需手动加载。
条件资源（.agents/skills/_shared/conditional/）
这些仅在执行过程中满足特定条件时加载：
| 资源 | 触发条件 | 加载方 | 大约 Token |
|---|---|---|---|
quality-score.md | 支持质量度量的工作流中开始 VERIFY 或 SHIP 阶段 | 编排器（传递给 QA 智能体提示） | 约 250 |
experiment-ledger.md | 建立 IMPL 基线后首次记录实验 | 编排器（内联，在基线测量后） | 约 250 |
exploration-loop.md | 同一个关卡因同一问题失败两次 | 编排器（内联，在启动假设智能体之前） | 约 250 |
预算影响：如果 3 个全部加载约 750 token。由于是条件加载，典型会话加载 1-2 个。Flash 级别预算保持在约 3,100 token 分配内。
技能如何通过 skill-routing.md 路由
技能路由映射定义了任务如何匹配到智能体：
简单路由（单一领域）
包含 "Build a login form with Tailwind CSS" 的提示匹配关键词 UI、component、form、Tailwind，路由到 oma-frontend。
复杂请求路由
多领域请求遵循既定的执行顺序：
| 请求模式 | 执行顺序 |
|---|---|
| "Create a fullstack app" | oma-pm -> (oma-backend + oma-frontend) 并行 -> oma-qa |
| "Create a mobile app" | oma-pm -> (oma-backend + oma-mobile) 并行 -> oma-qa |
| "Fix bug and review" | oma-debug -> oma-qa |
| "Design and build a landing page" | oma-design -> oma-frontend |
| "I have an idea for a feature" | oma-brainstorm -> oma-pm -> 相关智能体 -> oma-qa |
| "Do everything automatically" | oma-orchestrator（内部：oma-pm -> 智能体 -> oma-qa） |
智能体间依赖规则
可以并行运行（无依赖）：
- oma-backend + oma-frontend（当 API 契约已预先定义时）
- oma-backend + oma-mobile（当 API 契约已预先定义时）
- oma-frontend + oma-mobile（彼此独立）
必须顺序运行：
- oma-brainstorm -> oma-pm（设计先于规划）
- oma-pm -> 所有其他智能体（规划先行）
- 实现智能体 -> oma-qa（实现后审查）
- oma-backend -> oma-frontend/oma-mobile（当没有预定义 API 契约时）
QA 始终在最后，除非用户仅请求审查特定文件。
Token 节省计算
考虑一个 5 智能体编排会话（pm、backend、frontend、mobile、qa）：
不使用渐进式披露：
- 每个智能体加载所有资源：每个约 4,000 token
- 总计：5 x 4,000 = 20,000 token 在任何工作开始前消耗
使用渐进式披露：
- 所有智能体仅第一层：5 x 800 = 4,000 token
- 仅为活跃智能体加载第二层（通常同时 1-2 个）：+1,500 token
- 总计：约 5,500 token
节省：约 72-75%
在 flash 级别模型（128K 上下文）上，这意味着拥有 125K token 可用于工作而非 108K —— 对于复杂任务来说意义重大。
按任务难度加载资源
难度指南将任务分为三个级别，决定加载多少第二层内容：
简单（预期 3-5 回合）
单文件变更、需求明确、重复现有模式。
加载：仅 execution-protocol.md。跳过分析，使用最小检查清单直接实现。
中等（预期 8-15 回合）
2-3 个文件变更、需要一些设计决策、将模式应用到新领域。
加载：execution-protocol.md + examples.md。标准协议，简要分析和完整验证。
复杂（预期 15-25 回合）
4+ 个文件变更、需要架构决策、引入新模式、依赖其他智能体。
加载：execution-protocol.md + examples.md + tech-stack.md + snippets.md。扩展协议，带检查点、执行中进度记录和包含 common-checklist.md 的完整验证。
上下文加载任务映射（按智能体）
上下文加载指南提供详细的任务类型到资源映射。以下是关键映射：
后端智能体
| 任务类型 | 所需资源 |
|---|---|
| CRUD API 创建 | stack/snippets.md（路由、schema、模型、测试） |
| 认证 | stack/snippets.md（JWT、密码）+ stack/tech-stack.md |
| 数据库迁移 | stack/snippets.md（迁移） |
| 性能优化 | examples.md（N+1 示例） |
| 现有代码修改 | examples.md + Serena MCP |
前端智能体
| 任务类型 | 所需资源 |
|---|---|
| 组件创建 | snippets.md + component-template.tsx |
| 表单实现 | snippets.md（表单 + Zod） |
| API 集成 | snippets.md（TanStack Query） |
| 样式 | tailwind-rules.md |
| 页面布局 | snippets.md（网格）+ examples.md |
设计智能体
| 任务类型 | 所需资源 |
|---|---|
| 设计系统创建 | reference/typography.md + reference/color-and-contrast.md + reference/spatial-design.md + design-md-spec.md |
| 着陆页设计 | reference/component-patterns.md + reference/motion-design.md + prompt-enhancement.md + examples/landing-page-prompt.md |
| 设计审计 | checklist.md + anti-patterns.md |
| 设计令牌导出 | design-tokens.md |
| 3D / 着色器效果 | reference/shader-and-3d.md + reference/motion-design.md |
| 无障碍审查 | reference/accessibility.md + checklist.md |
QA 智能体
| 任务类型 | 所需资源 |
|---|---|
| 安全审查 | checklist.md（安全章节） |
| 性能审查 | checklist.md（性能章节） |
| 无障碍审查 | checklist.md（无障碍章节） |
| 完整审计 | checklist.md（完整）+ self-check.md |
| 质量评分 | quality-score.md（条件） |
编排器提示组合
编排器为子智能体组合提示时，仅包含与任务相关的资源：
- 智能体 SKILL.md 的核心规则部分
execution-protocol.md- 匹配特定任务类型的资源（来自上述映射）
error-playbook.md（始终包含 —— 恢复是必不可少的）- Serena 内存协议（CLI 模式）
这种有针对性的组合避免加载不必要的资源，最大化子智能体可用于实际工作的上下文空间。