# 4.4 智能体技能：能力扩展规范

**智能体技能（Agent Skills）** 是一种用于扩展 AI 智能体能力与专业知识的开放格式实践。它提供了一种轻量级、可移植的方式来封装领域知识和工作流程。

> **说明** **定位说明**：本节讨论的是 **Agent Skills 开放标准** 这一层，即以 `SKILL.md` 为核心的可移植技能格式。不同厂商产品还可能提供 rules、subagents、project instructions、`AGENTS.md` 等其他“指令表面”，它们不等同于 Agent Skills，也不应混写成同一套加载机制。建议先写清标准层，再分别说明各产品是否兼容、如何映射。

## 4.4.1 什么是智能体技能

Skills 是一种简单的开放格式，用于赋予智能体新的能力和专业知识。与工具连接协议提供系统连接能力不同，Skills 专注于 **过程性知识** 的封装。

> 工具连接协议是 **通道**，技能是 **智慧**。
>
> 工具连接协议解决“通过什么做”，技能解决“如何做”。

Skills 为智能体系统带来了以下核心价值：

* **领域专业知识**：将法律审查流程、数据分析管道等专业知识封装为可复用指令
* **新能力扩展**：赋予智能体创建演示文稿、构建工具服务、分析数据集等能力
* **可重复工作流**：将多步骤任务转化为一致、可审计的工作流程
* **跨平台互操作**：在不同 Skills 兼容的智能体产品间复用相同技能

2026 年的论文 *SkillsBench: Benchmarking How Well Agent Skills Work Across Diverse Tasks* 给出了一个重要的经验事实：**Skill 不是“可有可无的提示词附件”，而是一个可以被单独测量、并且经常显著提升智能体表现的工程变量。**

该论文的核心贡献是通过严格的实验设计量化了 Skills 的效果。论文把任务分为 **无 Skills**、**人工策展 Skills**、**模型自生成 Skills** 三种条件进行比较，覆盖 11 个领域、86 个任务。其主要发现包括：

* **人工策展的 Skills 平均能显著提升完成率**，说明高质量过程性知识在推理时注入是有效的。
* **模型现写的 Skills 平均没有稳定收益**，说明“会使用程序性知识”和“会编写高质量程序性知识”是两种不同能力。
* **领域差异极大**：在某些领域收益很高，在另一些领域甚至可能带来负收益，说明 Skill 必须面向任务类别精确设计，而不是抽象地“加说明书”。
* **聚焦型 Skill 往往优于大而全的文档**：2 到 3 个模块、围绕一个清晰工作流组织的 Skill，通常比塞满背景材料的综合手册更有效。
* **小模型 + 好 Skill 可以逼近大模型裸跑**：这说明 Skill 不只是“锦上添花”，也是一种现实的成本优化手段。

这几个结论对工程实践有直接影响：如果一个团队已经在做工具调用、RAG 和记忆系统，却还没有把“任务类程序知识”当成独立资产管理，那么通常还有一整块性能提升空间没有被系统开发。

进一步的 Skill 优化研究则把这件事推进到“可训练资产”层面。以 SkillOpt 为代表的方法不直接更新模型权重，而是把单个 Skill 文档视为冻结智能体的外部状态：目标智能体先在任务集上执行当前 Skill 并产生 scored rollout，优化器再根据成功和失败轨迹提出受控的新增、删除或替换编辑，候选 Skill 只有在 held-out 验证集上严格提升时才被接受。这个过程说明，高质量 Skill 的维护不应停留在“写一份说明书”，而应具备版本、评估、回归和拒绝编辑记录。

## 4.4.2 Skills 工作机制

Skills 采用三阶段加载机制：

```mermaid
flowchart LR
    %% Agentic Design System
    classDef agent fill:#e6f7ff,stroke:#1890ff,stroke-width:2px;
    classDef tool fill:#f6ffed,stroke:#52c41a,stroke-width:2px;
    classDef user fill:#fff7e6,stroke:#fa8c16,stroke-width:2px;

    a["1. 发现"] --> b["2. 激活"] --> c["3. 执行"]

    subgraph discovery ["启动阶段"]
        a
        d["加载名称 + 描述"]
    end

    subgraph activation ["匹配阶段"]
        b
        e["加载完整 SKILL.md"]
    end

    subgraph execution ["执行阶段"]
        c
        f["按需加载脚本/参考/资源"]
    end

    class a user;
    class b agent;
    class c tool;
    class d user;
    class e agent;
    class f tool;
```

图 4-5：Skills 三阶段加载机制

1. **发现（Discovery）**：启动时仅加载每个技能的 name 和 description，足以判断其相关性
2. **激活（Activation）**：当任务匹配某个技能的描述时，将完整 SKILL.md 指令加载到上下文
3. **执行（Execution）**：智能体按照指令执行，按需加载引用的文件或执行捆绑的脚本

## 4.4.3 Skill 目录结构

一个 Skill 的标准目录结构如下：

```mermaid
mindmap
    root((skill-name/))
        SKILL.md["SKILL.md<br>必需：指令 + 元数据"]
        scripts/["scripts/<br>可选：可执行代码"]
        references/["references/<br>可选：参考文档"]
        assets/["assets/<br>可选：模板、资源"]
```

| 目录/文件         | 说明                           |
| ------------- | ---------------------------- |
| `SKILL.md`    | **必需**。包含元数据和详细指令            |
| `scripts/`    | 可执行脚本，应自包含或清晰声明依赖            |
| `references/` | 技术参考文档，如 REFERENCE.md、领域专用文档 |
| `assets/`     | 模板、图片、数据文件等资源                |

## 4.4.4 SKILL.md 格式规范

SKILL.md 由 YAML Frontmatter 和 Markdown 正文两部分组成。

### 前置元数据（必需）

以下是一个完整的 YAML Frontmatter 示例：

```yaml
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
license: Apache-2.0
compatibility: Designed for agentic coding hosts
allowed-tools: Bash(git:*) Bash(jq:*) Read
metadata:
  author: example-org
  version: "1.0"
---
```

| 字段              | 要求 | 说明                    |
| --------------- | -- | --------------------- |
| `name`          | 必需 | 1-64 字符，仅小写字母、数字和连字符  |
| `description`   | 必需 | 1-1024 字符，描述功能和使用场景   |
| `license`       | 可选 | 许可证信息                 |
| `compatibility` | 可选 | 环境要求，如“需要 git、docker” |
| `allowed-tools` | 可选 | 预授权工具列表               |
| `metadata`      | 可选 | 自定义键值对                |

### 正文内容

正文采用 Markdown 格式，应包含：

* 分步骤指令
* 输入输出示例
* 常见边界情况处理

以下是一个 SKILL.md 正文的典型结构示例（示意采用英文小节名，实际项目可使用中文）：

```markdown
# PDF 处理

### 何时使用

当用户需要处理 PDF 文件时使用本技能。

### 如何抽取文本

1. 使用合适的 PDF 解析工具抽取文本。

### 如何填写表单

...
```

## 4.4.5 渐进式披露

Skills 采用三层加载机制优化上下文使用：

| 层级                | 内容                           | Token 预算         | 加载时机           |
| ----------------- | ---------------------------- | ---------------- | -------------- |
| 元数据 (Metadata)    | name + description           | \~100 tokens     | 启动时加载所有 Skills |
| 指令 (Instructions) | 完整 SKILL.md 正文               | <5000 tokens（建议） | 任务匹配时激活        |
| 资源 (Resources)    | scripts/、references/、assets/ | 按需               | 执行时按需加载        |

这种设计确保：

* 启动时上下文开销极小
* 仅在需要时加载详细指令
* 大型资源文件按需获取

结合工业实践与 SkillsBench 的结论，可以把高质量 Skill 的设计原则概括为三条：

1. **写过程，不写答案**：Skill 应该告诉智能体“如何排查、如何验证、如何收尾”，而不是把某一道题的最终输出直接塞进去。
2. **聚焦任务类，不追求百科全书**：一个 Skill 最好只覆盖同一类问题的稳定工作流。功能边界越清晰，触发越稳定，负迁移越少。
3. **把确定性逻辑下沉到脚本和资源**：长文档、模板、校验脚本、示例数据尽量放在按需层，而不是把所有内容堆进 `SKILL.md`。

如果一个 Skill 变成了“十几页背景知识 + 各种顺手都想塞进去的技巧合集”，它大概率已经从“高密度程序性知识包”退化成了“低命中率说明书”。

## 4.4.6 Skill 的局限与进化方向

当前的 Skill 框架已成为 Agent 软件的“及格线”，但并非最终形态。TiDB CTO 黄东旭在 QCon 2026 指出，未来 Agent 系统需要更复杂的抽象形式，具备以下特性：

1. **可调试性（Debuggability）**：Skill 应该能像软件模块一样被诊断、定位和修复错误
2. **可分发性（Distributability）**：不仅可复用，还能跨智能体系统、跨组织分发和版本管理
3. **知识蒸馏（Knowledge Distillation）**：能够将复杂的人类专家知识编码为可学习、可优化的形式，而非单纯的指令文本

当前 Skill 主要以自然语言指令存在，缺乏结构化的执行语义和自适应能力。下一代 Agent 基础设施可能需要结合 GStack、Superpower 等更有结构的知识表达方式，实现“人机协同生成”——即通过自然语言与 Agent 协同迭代定义 Skill，而非单向的人工编写。这样的演进将使 Skill 从“静态知识包”升级为“动态学习资产”。

如果把这个方向工程化，Skill 的生命周期至少应包含四个动作：先用真实或合成任务建立基线，再把失败轨迹压缩为候选规则，然后通过小步编辑更新 Skill，最后用未参与编辑的评估集决定是否发布。这里的关键不是“让智能体随便改自己的说明”，而是把自我改进限制在可审计、可回滚、可验证的配置层。

## 4.4.7 Skills 与工具连接协议的协同

技能和工具连接协议是互补的：技能定义“做什么”和“怎么做”，协议提供“用什么工具做”。

### 协同架构

```mermaid
graph TD
    %% Agentic Design System
    classDef agent fill:#e6f7ff,stroke:#1890ff,stroke-width:2px;
    classDef tool fill:#f6ffed,stroke:#52c41a,stroke-width:2px;

    subgraph Workflow [智能体工作流]
        Skill[/"Skill 业务规则配置"/]
    end

    subgraph Execution [调用多个工具服务执行]
        S1[CRM 工具服务]
        S2[消息工具服务]
        S3[Google Drive]
        S4[知识库工具服务]
    end

    Skill --> S1
    Skill --> S2
    Skill --> S3
    Skill --> S4

    class Skill agent;
    class S1,S2,S3,S4 tool;
```

图 4-6：Skills 与工具连接协议协同架构

*注：Skill 定义了工作流程、业务规则和质量标准等过程性知识。例如“查询客户数据时，先检查 CRM，再交叉验证 Slack”。*

### 边界划分

| 维度 | 协议负责        | 技能负责      |
| -- | ----------- | --------- |
| 核心 | 连接能力        | 领域知识      |
| 内容 | API 格式、查询语法 | 工作流程、业务规则 |
| 指令 | 工具使用提示      | 多工具编排逻辑   |
| 粒度 | 单个服务        | 跨服务流程     |

**经验法则**：

* 协议指令覆盖 **如何正确使用服务及其工具**；Skill 指令覆盖 **如何在特定流程或多服务工作流中使用它们**。

### 实际案例

下面用两个示例展示 Skill 如何把“方法论与流程”固化为可复用能力。

**案例 1：财务分析 Skill**

```markdown
# Comparable Company Analysis Skill

### 工作流程

1. 从财务数据工具服务拉取指标
2. 从补充数据工具服务获取额外字段
3. 应用估值方法论（Skill 定义）
4. 格式化输出符合合规要求（Skill 定义）
```

**案例 2：会议准备 Skill**

```markdown
# Meeting Intelligence Skill

### 工作流程

1. 通过知识库工具服务搜索相关项目页面
2. 通过知识库工具服务获取历史会议记录
3. 整理为两份文档：内部预读 + 外部议程
4. 通过知识库工具服务保存到指定位置
```

## 4.4.8 Skills 生态与企业部署

### 组织级管理

在团队/组织场景下，Skills 往往需要被当成“可审计的组织资产”来管理：版本控制、审批、权限与分发。

**集中配置能力**：

* 组织管理员可从管理设置集中配置 Skills
* 管理员配置的 Skills 默认为所有用户启用
* 用户仍可选择关闭个别 Skills 以自定义体验
* 确保团队使用一致、经批准的工作流

**部署优势**：

* 统一标准：整个组织遵循相同的工作流程
* 质量控制：IT 团队审核和批准 Skills
* 快速推广：一次配置，全员可用
* 灵活性：用户保留个性化选择权

### 版本化与回归

当 Skill 被用于关键业务流程时，建议把它当作“可发布的软件资产”治理：

* **版本管理**：为 Skill 建立语义化版本号与变更日志，支持回滚。
* **审批与灰度**：在推广到全员前先做小范围试点，避免一次性引入大范围回归。
* **回归样例集**：为核心 Skill 维护最小回归用例（输入、期望输出结构、失败诊断），每次更新前后对比。

### Skills 目录与生态

生态与具体合作伙伴会随时间变化；工程上更重要的是：能否把 Skill 当成可版本化的资产（仓库管理）、能否做审批与分发、能否与权限/审计体系集成。

### 创建与编辑体验优化

**简化创建流程**：

* **描述即创建**：描述需求，由系统/助手协助构建 Skill
* **直接编写**：直接编写指令文件
* **文件夹上传**：上传完整的 Skill 文件夹结构
* **Skill creator / scaffolding 工具**：部分宿主会提供内置创建器，帮助生成初始 Skill 结构

**完整预览功能**：

* 启用前查看 Skill 完整内容
* 理解 Skill 具体做什么
* 审核指令的安全性和合理性

**助手辅助编辑**：

* 助手可帮助编辑现有 Skills
* 根据反馈优化指令
* 迭代改进工作流

### 跨平台可用性

Agent Skills 作为开放标准，目标是让同一个 `SKILL.md` 目录结构在多个兼容宿主之间复用；但**具体产品表面必须分开描述**：

* **标准层**：Skill 是目录 + `SKILL.md` + 可选的 `scripts/`、`references/`、`assets/`，宿主按“发现 → 激活 → 按需加载”使用它。
* **兼容宿主层**：像 Codex 这类已公开支持 Agent Skills 的宿主，会扫描技能目录并显式或隐式激活 `SKILL.md`。
* **非等价表面**：另一些产品可能提供 rules、subagents、组织级工作流模板或浏览器扩展中的技能入口；它们是否直接兼容 Agent Skills，要以各自官方文档为准，不能把 UI 入口、配置路径或 API 端点写成通用规范。

> **说明** **工程建议**：写文档时先描述开放标准，再单列“OpenAI/Codex”“Anthropic/Claude”“其他 IDE/客户端”等厂商章节，分别说明触发方式、权限前置条件和分发机制。

## 4.4.9 最佳实践

在开发和使用 Agent Skills 时，遵循经过验证的最佳实践可以显著提高技能的质量和可用性，避免常见的陷阱。

### Skill 设计原则

* **功能聚焦**：每个 Skill 专注于一个明确的领域或工作流
* **自文档化**：任何人阅读 SKILL.md 都能理解其功能
* **可移植性**：Skills 就是文件，易于编辑、版本控制和分享

### 避免常见问题

* **避免指令冲突**：如果工具服务指定返回 JSON，而 Skill 要求 Markdown 表格，智能体需要猜测。让工具服务处理连接，Skill 处理呈现。
* **保持复用性**：一个工具服务可支持多个 Skills；一个 Skill 可编排多个工具服务。
* **利用渐进式加载**：将详细参考资料放在 references/ 目录，仅在需要时加载

### 验证工具

可以使用项目提供的校验脚本或自定义 linter 来验证 Skill 格式：

```bash
<skill-linter> check ./my-skill
```

> **提示** **相关资源**：建议在项目内维护一份“Skill 规范/示例/校验工具”的链接清单，并定期核验有效性。

***

**下一节**: [4.5 浏览器自动化与计算机操作](/agentic_ai_guide/di-yi-bu-fen-dan-ti-zhi-neng-jia-gou/04_tools/4.5_browser.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://yeasy.gitbook.io/agentic_ai_guide/di-yi-bu-fen-dan-ti-zhi-neng-jia-gou/04_tools/4.4_skills.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.