CH-04 能力扩展：Skill 系统

图 4-1：Skill 系统三层结构与优先级

4.1 Skill 是什么

在豆包工作的术语中，Skill（技能）是一个可被 Agent 自主发现和加载的能力包。每个 Skill 是一个目录，核心是一个 SKILL.md 文件——它用 YAML frontmatter 声明名称和触发描述，用 Markdown 正文告诉 Agent 何时使用这个 Skill、如何执行、有哪些约束和资源。

Skill 不是传统意义上的插件。传统插件（如 Chrome Extension）需要用户手动安装和启用，通过预定义的 API 扩展宿主功能。Skill 更像是一本"操作手册"：它不直接执行代码，而是告诉模型在什么场景下应该做什么、用什么工具、遵循什么流程。模型读取 SKILL.md 后，按照其中的指引调用工具完成任务。

这种设计来自 Anthropic 的 AgentSkills 规范，核心理念是"模型拾取"（model pickup）而非"程序调用"：模型根据用户意图和 Skill 描述自主判断是否需要加载某个 Skill，不需要硬编码的触发逻辑。

4.2 103 个预装 Skill：全量分类

豆包工作 2.25.18 在 .doubaowork/agent_mode/workspace/.skills/ 下预装了 103 个 Skill。对全部 SKILL.md 的 frontmatter 进行提取和分类后，得到以下分布：「源码」

这个分类表揭示了几个重要信息：

第一，飞书生态是最大的 Skill 集群。 23 个飞书 Skill 覆盖了文档、表格、多维表格、日历、即时通讯、邮箱、任务、审批、考勤、视频会议、妙记、云盘、知识库、OKR、通讯录、项目、画板、纪要等飞书全家桶。这说明豆包工作的核心场景之一是"在飞书里干活"——Agent 可以直接操作飞书的各种业务对象，而不需要用户手动复制粘贴。

第二，工具基建 Skill 提供了 Agent 的"元能力"。 doubao-app-builder（生成网页应用）、doubao-visualization（数据可视化）、doubao-pdf（PDF 处理）、doubao-cron-scheduler（定时任务）、browser-task（浏览器自动化）等 Skill 不是面向特定业务领域，而是扩展 Agent 本身的执行能力。它们是"工具的工具"。

第三，专业领域 Skill 形成了完整的工作流。 金融投研的 14 个 Skill 从选股、财报分析、行业研究到估值建模形成闭环；法律合规的 8 个 Skill 从合同起草、审查到补充协议、DPA 覆盖了合同全生命周期；学术的 7 个 Skill 从文献调研、论文写作到格式排版覆盖了发表全流程。这不是零散的功能堆砌，而是按工作流组织的能力矩阵。

第四，所有 103 个 Skill 都没有设置 disable-model-invocation: true。 这意味着所有预装 Skill 都允许模型自主拾取，不需要用户通过 skill:// 链接显式调用。这与 WorkBuddy 不同——WorkBuddy 有部分 Skill 设置了 disable-model-invocation，需要用户主动触发。「源码」

4.3 Skill 的文件结构

一个典型的 Skill 目录结构如下：

skill-name/
├── SKILL.md              # 核心文件：frontmatter + 能力说明 + 使用指引
├── references/           # 参考文档（可选）
│   ├── domain-model.md
│   ├── project-layout.md
│   └── ...
├── scripts/              # 可执行脚本（可选）
│   ├── init_project.py
│   └── validate.py
└── assets/               # 模板和静态资源（可选）
    ├── templates/
    └── images/

4.3.1 SKILL.md 的 frontmatter

每个 SKILL.md 以 YAML frontmatter 开头，包含三个字段：

---
name: skill-name
description: 一句话描述这个 Skill 做什么、什么时候使用。
disable-model-invocation: false  # 可选，默认 false
---

description 是最关键的字段。它是模型判断"是否需要加载这个 Skill"的唯一依据。模型在会话开始时会扫描所有 Skill 的 name 和 description（不是完整正文），当用户请求匹配某个 description 时，才读取完整的 SKILL.md 正文。

这种设计控制了初始上下文的大小：103 个 Skill 的 name + description 总共只占几千 token，但完整的 SKILL.md 正文加起来可能超过百万 token。模型只在需要时才加载完整内容。

4.3.2 references/：参考文档

复杂的 Skill 会把详细规范拆到 references/ 目录下。例如 zhijian-bluebook Skill 有 domain-model.md、project-layout.md、state-and-gates.md、evidence-contract.md 等多个参考文档，SKILL.md 正文只包含路由逻辑和核心流程，详细规范在需要时按需读取。

这是一种渐进式信息披露：SKILL.md 是"目录"，references/ 是"章节"。模型先读目录，再根据任务需要读具体章节。

4.3.3 scripts/：可执行脚本

部分 Skill 附带 Python 或 Shell 脚本，用于执行确定性操作（初始化项目、验证状态、编译产物等）。脚本通过 Bash 工具调用，SKILL.md 中会说明何时调用哪个脚本、传什么参数。

脚本的存在让 Skill 不只是"文字指引"，还可以包含可执行的自动化逻辑。但脚本本身不具备智能——它执行固定的操作，智能部分仍由模型通过工具调用编排。

4.4 Skill 的发现与加载流程

图 4-2：Skill 发现与延迟加载流程

根据系统提示词中的规则和运行时观测，Skill 的发现与加载流程如下：「实测」

1. 会话开始
   ↓
2. 扫描多个 Skill 根目录：
   - .skills/（预装，App 管理）
   - .user_skills/（用户自定义）
   - 其他可能的根目录（Vault .agents/skills/ 等）
   ↓
3. 读取每个 SKILL.md 的 frontmatter（name + description）
   ↓
4. 用户发送消息
   ↓
5. 模型判断用户意图是否匹配某个 Skill 的 description
   ↓
6. 匹配 → 读取完整 SKILL.md 正文
   ↓
7. 按 SKILL.md 指引执行（可能继续读取 references/ 或调用 scripts/）
   ↓
8. 不匹配 → 直接用基础工具回答

4.4.1 多根目录扫描

豆包工作的 Skill 发现不限于 .skills/ 目录。系统提示词中列出了多个 Skill 根目录，包括：

• 应用内置的 .skills/（103 个预装 Skill）
• 用户级的 .user_skills/（默认为空）
• 项目级的 .agents/skills/（如 Vault 中的 zhijian-bluebook）
• 其他可能的系统级和用户级路径

这种多根目录设计允许不同层级的 Skill 共存：应用提供基础能力，用户添加个人 Skill，项目提供团队共享 Skill。当同名 Skill 出现在多个根目录时，优先级规则未在本地证据中确认。

4.4.2 disable-model-invocation

frontmatter 中的 disable-model-invocation: true 会阻止模型自主拾取该 Skill。设置了这个标志的 Skill 只能通过用户显式调用（如在消息中附加 skill:// 链接）触发。

在 103 个预装 Skill 中，这个标志全部为 false 或未设置（默认 false）。但用户自定义 Skill 可以设置它——如果某个 Skill 只应该在用户明确要求时执行（比如涉及敏感操作），设置这个标志可以防止模型误触发。

4.4.3 Skill 与工具的关系

Skill 和工具（Tool）是两个不同的概念：

• 工具是模型可以直接调用的函数（如 Read、Bash、image_gen），有明确的参数 schema，在系统提示词中定义。
• Skill 是 Markdown 文档，告诉模型如何组合工具完成特定类型的任务。

一个 Skill 通常会指导模型使用多个工具。例如 doubao-pdf Skill 会告诉模型如何用 Bash 调用 PDF 处理工具、如何用 Read 读取 PDF 内容、如何用 Write 输出结果。Skill 本身不增加新的工具能力，它增加的是"使用工具的知识和流程"。

但有些 Skill 会引入新的工具。例如 seed-finance-search、medical-search、seed-legal-search 等 Skill 实际上是工具的包装——它们的 SKILL.md 描述了何时使用对应的搜索工具，工具本身通过延迟加载（tool_search）获得。在这种情况下，Skill 既是工具的说明书，也是工具的触发器。

4.5 .user_skills/：用户自定义 Skill

.user_skills/ 目录用于存放用户自己创建的 Skill。在目标版本中，这个目录默认为空。「源码」

用户可以按照 SKILL.md 规范创建自己的 Skill：

1. 在 .user_skills/ 下新建一个目录（如 my-workflow/）
2. 创建 SKILL.md，写好 frontmatter（name + description）
3. 在正文中描述触发条件、执行步骤、使用的工具和参考文档
4. 可选：添加 references/、scripts/、assets/

创建后，模型在下次会话（或刷新 Skill 列表后）会自动发现这个 Skill。当用户请求匹配 description 时，模型会加载并按指引执行。

这是豆包工作留给用户的主要 Harness 扩展点。与 WorkBuddy 的 plugins/ 系统相比，.user_skills/ 更轻量——不需要写代码、不需要配置 JSON、不需要注册入口，一个 Markdown 文件就是一个 Skill。但它也更受限——Skill 只能指导模型使用已有工具，不能像 WorkBuddy 插件那样注册新的 MCP 服务器或添加新的工具类型。

4.6 在线技能商店：技能、连接器与工作伙伴

2026 年 8 月 21 日，豆包工作上线了"技能·连接器·工作伙伴"功能，官方宣布已上架超过 200 个技能和连接器。「官方」这与本地预装的 103 个 Skill 是什么关系？

4.6.1 三个概念

根据官方公告和产品界面，豆包工作的能力市场分为三层：

• 技能（Skill）：完成特定任务的能力包，与本地 Skill 概念一致。在线技能可能是本地 Skill 的超集——部分技能预装在本地，其他技能按需从服务端加载。
• 连接器（Connector）：对接外部服务的适配器，如飞书、GitHub、数据库、企业内部系统。连接器本质上是 MCP 服务器的产品化包装——用户通过图形界面配置认证和连接，底层通过 MCP 协议通信。
• 工作伙伴（Work Partner）：面向特定岗位或场景的预置 Agent，如"HR 助手""财务分析师""代码审查员"。工作伙伴可能有自己的系统提示词、工具集和 Skill 组合，是 MainAgent 之下的专业化 Agent。

4.6.2 本地 103 与在线 200+ 的关系

本地 103 个 Skill 和在线 200+ 技能不是矛盾关系，而是包含与补充关系：

1. 本地 103 个 Skill 是"出厂预装"的核心能力，随 App 分发，离线可用。
2. 在线 200+ 技能包含了预装技能和更多可选技能，用户可以从技能商店添加。
3. 连接器和工作伙伴主要通过在线配置和服务端下发，本地只存储配置和认证信息。

Preferences 文件中的 saman.local_storage_for_web.launcher.skills_exposed 和 discovered_skills 字段支持这个判断：它们缓存了技能列表和图标，包含 agentId、botId、commandId 三种标识符，说明技能来源多样（Agent 类型、Bot 类型、命令类型）。「源码」

4.6.3 技能数据的标识符

从 Preferences 中提取的技能数据结构显示，每个技能包含：

• id：技能唯一标识
• name：显示名称
• icon：图标 URL
• agentId/botId/commandId：后端标识符（三选一或组合）
• type：技能类型

agentId 和 botId 的存在暗示在线技能可能由字节的 Bot 平台（Coze/扣子）提供——每个技能背后可能是一个配置好的 Bot 或 Agent，通过 API 调用。commandId 则可能对应客户端本地的快捷命令。「推断」

4.7 编写自定义 Skill 的实践建议

基于对 103 个预装 Skill 的分析，可以总结出编写高质量 SKILL.md 的几个实践要点：

4.7.1 description 是最重要的字段

description 决定了模型何时加载你的 Skill。它应该：

• 明确说明触发场景（"当用户要求 X 时使用"）
• 包含关键词和同义词（模型可能用不同表述描述同一需求）
• 不要过于宽泛（"处理文件"会匹配太多场景）或过于狭窄（只匹配一种说法）
• 用一句话说清"做什么"和"何时用"

观察预装 Skill 的 description 写法，好的例子如："用于用户提交论文、学位论文或参考文献清单后，系统审查参考文献真实性"——触发条件明确，任务边界清晰。

4.7.2 正文结构

一个好的 SKILL.md 正文通常包含：

1. 能力边界：这个 Skill 做什么、不做什么
2. 前置条件：使用前需要检查什么（文件是否存在、依赖是否安装）
3. 执行流程：分步骤的操作指引，每步说明用什么工具、预期什么结果
4. 错误处理：常见失败情况和恢复方式
5. 输出规范：产物格式和交付方式
6. 参考文档：指向 references/ 目录下的详细规范

4.7.3 渐进式披露

不要把所有信息塞进 SKILL.md 正文。把详细规范、模板、示例放在 references/ 下，正文只保留路由逻辑和核心流程。模型在需要时才读取参考文档，避免一次性占用过多上下文。

4.7.4 脚本与 Markdown 的分工

• 确定性操作（文件初始化、格式验证、数据转换）写成 scripts/ 中的脚本
• 需要判断和决策的步骤留在 Markdown 正文中，由模型执行
• 脚本应该有明确的输入输出和错误码，SKILL.md 说明何时调用

4.8 Skill 生态的演进趋势

4.8.1 从预装到市场

103 个预装 Skill 是"出厂配置"，200+ 在线技能是"应用商店"。这个演进路径与智能手机的生态发展类似：早期手机预装应用，后来出现应用商店，最终第三方开发者成为生态主力。

豆包工作的技能商店目前可能仍以字节官方提供的技能为主，但基础设施已经具备：技能有唯一 ID、图标、类型标识（agentId/botId/commandId），通过服务端下发和更新。如果开放第三方发布，.user_skills/ 的本地 Skill 机制可以作为开发者测试和调试的入口，在线商店作为分发渠道。

4.8.2 连接器的 MCP 本质

"连接器"是产品概念，MCP 服务器是技术实现。用户看到的是"连接飞书""连接 GitHub""连接数据库"的图形化配置界面，底层是 mcp-helper 建立 MCP 连接、OAuth 认证、工具发现。

这种产品化包装很重要。MCP 协议对普通用户来说太技术化了——STDIO、SSE、JSON-RPC 这些概念不应该出现在用户界面上。连接器把技术复杂性隐藏在图形界面后面，用户只需要登录授权就能使用外部工具。

4.8.3 工作伙伴的定位

"工作伙伴"是三个概念中最模糊的。从名称和产品描述推测，它可能是：

• 预置了特定系统提示词和工具集的专业化 Agent
• 面向特定岗位（HR、财务、法务）的垂直解决方案
• 可以在对话中 @ 调用的 Bot（类似 Coze Bot）

工作伙伴与 Skill 的区别可能在于：Skill 是"能力包"（告诉 Agent 怎么做某类任务），工作伙伴是"角色"（一个有特定身份和专长的 Agent）。工作伙伴可能拥有自己的系统提示词、独立的对话上下文和专属工具集，是 MainAgent 可以委派任务的"专家同事"。

如果这个推测正确，工作伙伴就是多 Agent 架构的产品化——OrganizeAgent 创建的 SubAgent 可以是一个预置的工作伙伴，而不是临时生成的通用 Agent。「推断」

4.9 Skill 系统的架构判断

判断一：Skill 是豆包工作 Harness 中最开放的层。 系统提示词不可改、身份不可改、记忆不可见、沙箱不可控，但 Skill 完全开放——用户可以写自己的 SKILL.md，放在 .user_skills/ 下即可被 Agent 拾取。这是豆包工作留给用户的主要定制入口，也是它与 WorkBuddy 在可扩展性上最接近的设计。「推断」

判断二：Skill 生态的重心在飞书和专业领域。 23 个飞书 Skill 占预装总量的 22%，加上金融、法律、医疗、学术等专业领域，超过 60% 的 Skill 面向工作场景。这与"豆包工作"的品牌定位一致——它不是一个通用聊天助手，而是一个工作生产力工具。「源码」

判断三：Skill 与 MCP/连接器是互补关系，不是替代关系。 Skill 提供"怎么做"的知识（流程、步骤、判断逻辑），MCP/连接器提供"连什么"的通道（外部服务、数据源、API）。一个完整的工作流通常同时需要两者：Skill 指导 Agent 编排步骤，MCP 连接器提供与外部系统的通信能力。「推断」

判断四：在线技能商店是平台化的关键一步。 103 个预装 Skill 是字节自己提供的，200+ 在线技能暗示了第三方生态的可能性。如果豆包工作开放技能开发平台（类似 Coze 的 Bot 商店），开发者可以发布自己的 Skill，豆包工作就从"工具"变成了"平台"。但目前没有公开证据表明第三方开发者可以发布技能。「推断」

下一章将进入协议层，分析豆包工作最有技术深度的原生组件——用 Rust 编写的 MCP 助手，它如何支持三种传输协议、完整 OAuth 和 FFI 桥接。

CHAPTER 05 · ZJBB-004