Skill 全方位介绍：从概念到实践的 Agent 技能开发指南

泡菜鱼137

286人浏览 · 2026-06-23 12:43:11

泡菜鱼137 · 2026-06-23 12:43:11 发布

在 AI Agent 应用开发中，Skill（技能）是一个核心抽象，它将 Agent 的能力模块化、可复用化。本文从概念、架构、编写实践到调度机制，全面介绍 Skill 的设计与实现。

一、什么是 Skill

1.1 概念定义

Skill 是 AI Agent 系统中一种可插拔的能力单元。它将特定领域的知识、操作流程、工具调用封装为一个独立模块，在 Agent 运行时被按需加载和激活。

用一句话概括：Skill 是 Agent 的"专业领域培训包"——当 Agent 需要完成某项特定任务时，加载对应的 Skill，Agent 就临时获得了该领域的专业知识和工作流指导。

1.2 Skill 解决的核心问题

问题	没有 Skill 时	有 Skill 时
领域知识不足	Agent 对特定领域（如地图 API、品牌设计）缺乏深度了解	Skill 注入领域专用知识
行为不可控	Agent 自由发挥，质量不稳定	Skill 约束行为边界，保证输出质量
复用性差	每次都要在 prompt 中重复描述	Skill 一次编写，处处复用
上下文膨胀	所有知识常驻 system prompt	按需加载，节省 token
协作困难	个人经验难以沉淀	Skill 可共享、版本化管理

1.3 Skill 在 Agent 架构中的位置

┌─────────────────────────────────────┐
│           用户请求 (User)            │
└──────────────┬──────────────────────┘
               ▼
┌─────────────────────────────────────┐
│         Agent 运行时 (Runtime)       │
│  ┌──────────────────────────────┐   │
│  │     System Prompt (基础)      │   │
│  └──────────────────────────────┘   │
│  ┌──────────────────────────────┐   │
│  │   Skill A  │ Skill B │ ...   │   │  ← 按需激活
│  └──────────────────────────────┘   │
│  ┌──────────────────────────────┐   │
│  │     工具集 (Tools/MCP)        │   │
│  └──────────────────────────────┘   │
└──────────────┬──────────────────────┘
               ▼
┌─────────────────────────────────────┐
│           执行结果 (Output)          │
└─────────────────────────────────────┘

Skill 位于 System Prompt 和 Tools 之间：它不直接调用工具，而是教会 Agent 如何用工具完成特定领域的任务。

二、Skill 与其他概念的对比

2.1 Skill vs Tool (工具)

维度	Tool	Skill
本质	一个可调用的函数/API	一套领域知识 + 工作流
粒度	原子操作（读文件、发请求）	复合能力（设计品牌、审查代码）
触发方式	Agent 主动调用	用户指定或路由匹配
包含内容	函数签名 + 描述	领域知识 + 规则 + 示例 + 约束

Tool 是"螺丝刀"，Skill 是"教你怎么修手表"。

2.2 Skill vs MCP (Model Context Protocol)

MCP 是工具/资源的标准化接入协议，解决的是"怎么连接到外部系统"的问题。Skill 解决的是"接入之后怎么把事情做专业"的问题。

更详细的对比可参考《MCP与Skill的区别与适用场景》。

2.3 Skill vs Plugin (插件)

Plugin 通常包含可执行代码，有独立的运行时逻辑。Skill 更偏向声明式——它主要由 prompt 指令、知识描述和规则组成，由 Agent 的 LLM 来理解和执行。Skill 更"轻"，不需要独立的执行环境。

三、Skill 的架构设计

3.1 Skill 的核心组成

一个完整的 Skill 通常包含以下部分：

my-skill/
├── SKILL.md              # 技能主文件：何时触发 + 做什么
├── references/           # 参考资料（可选）
│   ├── api-guide.md
│   └── examples.md
├── scripts/              # 辅助脚本（可选）
│   └── validate.sh
└── assets/               # 静态资源（可选）
    └── templates/

SKILL.md 是 Skill 的灵魂，它通常包含以下区块：

(1) 元信息 (Frontmatter)

---
name: my-skill
description: 一句话描述技能用途，用于路由和匹配
version: 1.0.0
triggers:
  - 关键词1
  - 关键词2
---

(2) 触发条件 (Trigger / When to Use)

定义什么情况下应该激活这个 Skill。可以是关键词匹配、任务类型匹配，或用户显式指定。

(3) 能力声明 (Capabilities)

明确告诉 Agent 这个 Skill 能做什么、不能做什么，划定能力边界。

(4) 领域知识 (Domain Knowledge)

注入该领域的关键知识点——API 特性、设计规范、常见陷阱等。

(5) 工作流/规则 (Workflow / Rules)

具体的执行步骤、质量要求和约束条件。

3.2 Skill 的架构模式

模式一：声明式 Skill（Prompt-only）

最常见的形式。Skill 完全由自然语言描述的能力指引组成，由 LLM 解析和遵循。

优点：开发成本极低，无需编程，迭代快速
缺点：执行力依赖模型能力，不可做精确计算
适用：设计规范、代码审查、文档生成等"软"任务

模式二：混合式 Skill（Prompt + 脚本）

Skill 文件中引用可执行脚本，Agent 在适当时机调用。

优点：可以执行确定性操作（验证、计算、转换）
缺点：需要维护脚本代码，有环境依赖
适用：需要精确计算的场景（构建、测试、数据校验）

模式三：工具增强式 Skill（Prompt + MCP/API）

Skill 指导 Agent 使用特定的 MCP 服务或 API 来完成专业任务。

优点：打通外部系统，能力扩展性强
缺点：依赖外部服务可用性
适用：集成特定平台（数据库、云服务、第三方 API）

四、Skill 的加载与调度机制

4.1 加载策略

策略	描述	优/缺点
常驻加载	Skill 始终在 system prompt 中	响应快，但占 token
按需加载	请求到来时匹配并注入	省 token，但有匹配延迟
分层加载	元数据常驻，完整内容按需	兼顾响应速度和 token 消耗
上下文注入	识别到相关场景时动态注入	最灵活，需强路由能力

4.2 路由/匹配机制

用户请求 → 路由层 → 匹配 Skill → 注入 Prompt → Agent 执行
              │
              ├── 关键词匹配（快速，但粗糙）
              ├── 语义匹配（embedding 相似度，较准）
              ├── 显式调用（用户 /skill-name，最精准）
              └── 混合策略（分级匹配，推荐方案）

推荐的混合路由策略：

第一优先级：用户显式指定（/brandkit）
第二优先级：关键词精确命中（任务描述中出现"品牌设计"→ brandkit）
第三优先级：语义相似度兜底（没有任何匹配时，用 embedding 找最相关的）

4.3 多 Skill 共存

当请求匹配到多个 Skill 时：

互斥 Skill：只激活最相关的一个，避免指令冲突
协作 Skill：允许同时激活，按优先级排序注入
冲突检测：元信息中声明互斥关系，路由层自动处理

五、如何编写一个优秀的 Skill

5.1 编写原则

原则一：单一职责

一个 Skill 只做好一件事。如果一个 Skill 既教设计又教后端，拆分它。

✅ 好：高德地图 JSAPI 开发技能
❌ 差：前端开发全能技能（包含地图、UI、动画等）

原则二：指令具体化

不要说"做好设计"，要说"字体行高 1.5，最大宽度 72ch，卡片圆角 12px"。

✅ 好：使用 Inter 字体，标题 2xl (1.5rem)，正文 base (1rem)，行高 1.6
❌ 差：使用好看的字体和合理的字号

原则三：边界清晰

明确声明 Skill 不做什么，防止 Agent 越界。

原则四：示例驱动

在 Skill 中嵌入 2-3 个典型的使用示例，这比长篇规则更有效。

原则五：版本化管理

Skill 内容会迭代，使用版本号标记，便于追溯和回滚。

5.2 Skill 编写模板

以下是一个标准 Skill 的编写模板：

---
name: my-skill-name
description: 简短描述，用于路由匹配（1-2 句话）
version: 1.0.0
triggers:
  - 触发词1
  - 触发词2
conflicts:
  - conflicting-skill-name  # 互斥的 Skill
---

# Skill Name

## 概述
这个 Skill 解决什么问题，适用于什么场景。

## 何时激活
- 用户请求涉及 XXX 时
- 用户显式调用 `/my-skill-name` 时
- 任务描述匹配 YYY 时

## 核心能力
1. 能力一：具体描述
2. 能力二：具体描述

## 工作流程
1. 步骤一：做什么
2. 步骤二：做什么
3. 步骤三：输出什么

## 关键规则
- 规则 1：必须做什么
- 规则 2：禁止做什么
- 规则 3：当 XXX 时优先 YYY

## 示例

### 示例一：基础用法
**输入**：用户的请求
**期望输出**：Agent 应该做什么

### 示例二：边界情况
**输入**：边界请求
**处理方式**：正确处理方式

## 参考资源
- 相关文档链接
- API 参考
- 设计规范

5.3 Skill 编写实战示例

下面是一个简化的"代码审查 Skill"示例：

---
name: code-reviewer
description: 对代码变更进行安全审查和代码质量审查
version: 1.0.0
triggers:
  - 代码审查
  - code review
  - 安全检查
  - pr review
---

# Code Reviewer Skill

## 概述
对当前分支的代码变更进行自动化审查，关注安全性、性能和代码质量。

## 何时激活
- 用户请求 review、审查代码
- 用户请求检查安全性
- 创建 PR 前的预检查

## 审查清单

### 安全检查（必须）
1. 是否存在 SQL 注入风险（拼接 SQL 字符串）
2. 是否存在 XSS 风险（未转义的用户输入渲染）
3. 是否存在敏感信息泄露（密钥、token 硬编码）
4. 是否存在路径遍历风险（用户输入用于文件路径）

### 性能检查
1. 循环内是否有不必要的数据库查询（N+1 问题）
2. 大列表是否缺少分页或虚拟滚动
3. 是否存在未清理的定时器/订阅（内存泄漏）

### 代码质量
1. 函数是否单一职责（超过 50 行需关注）
2. 命名是否语义清晰
3. 错误处理是否恰当

## 输出格式
按严重程度排序：🔴 阻断 > 🟡 警告 > 🔵 建议

## 审查禁区
- 不审查第三方库的代码（node_modules, vendor）
- 不纠结纯风格问题（交给 lint 工具）
- 不对不确定的安全问题做武断结论

六、Skill 的生命周期管理

6.1 生命周期阶段

创建 → 注册 → 匹配 → 加载 → 激活 → 执行 → 卸载 → 更新/废弃
  │      │      │      │      │      │      │      │
  │      │      │      │      │      │      │      └── 迭代或退休
  │      │      │      │      │      │      └── 会话结束或切换 Skill
  │      │      │      │      │      └── Agent 按照 Skill 指引执行
  │      │      │      │      └── Skill 内容注入上下文
  │      │      │      └── Skill 内容读入内存
  │      │      └── 路由层匹配到该 Skill
  │      └── 将 Skill 注册到路由表
  └── 编写 Skill 文件，放置到 Skills 目录

6.2 版本管理策略

Skills/
├── brandkit/
│   ├── v1/
│   │   └── SKILL.md
│   └── v2/
│       └── SKILL.md
└── code-reviewer/
    └── SKILL.md  (latest)

建议：

大版本号变更时保留旧版本，给用户迁移时间
元信息中声明 version 字段
废弃的 Skill 标记 deprecated: true 而非直接删除

6.3 热加载与热更新

生产环境中的 Skill 系统应支持：

热加载：新增 Skill 文件后自动注册，无需重启
热更新：修改 SKILL.md 后自动生效
灰度发布：新版本先给部分用户试用

七、Skill 开发的最佳实践

7.1 设计层面

先定义边界，再填充内容。想清楚 Skill 不做什么，比想清楚它做什么更重要。
Skill 之间的职责不重叠。如果两个 Skill 的触发条件和能力有大量交集，考虑合并或重新划分。
Skill 不替代文档。Skill 是"执行指南"，不是"参考手册"。保持精简，只写 Agent 执行时需要的东西。

7.2 编写层面

指令用祈使句。Agent 对祈使句的遵循度远高于描述句。

✅ "使用 16px 字号，行高 1.5"
❌ "通常我们会用 16px 的字号"

关键规则前置。最重要的约束放在 Skill 文件的最前面，后面即使被截断也不影响核心行为。
正反示例并重。既展示正确做法，也展示典型错误。

量化一切可量化的。

✅ "函数不超过 50 行，参数不超过 4 个"
❌ "函数不要太长，参数不要太多"

7.3 测试层面

为每个 Skill 编写测试用例：典型场景输入 → 期望激活哪个 Skill → 期望输出什么
边界测试：测试 Skill 的互斥关系、优先级排序是否正确
回归测试：Skill 更新后，确保旧用例仍然通过

7.4 生态层面

建立 Skill 市场：让团队成员可以发布和发现 Skill
使用统计：记录每个 Skill 的激活频率、成功率，驱动优化
反馈闭环：收集用户对 Skill 执行结果的反馈，持续迭代

八、常见的 Skill 设计反模式

反模式	问题	改进
万能 Skill	一个 Skill 覆盖所有场景，臃肿难维护	拆分为多个职责单一的 Skill
空壳 Skill	只有触发词，没有实质指引	补充具体的领域知识和规则
过约束 Skill	规则过多过死，Agent 无法灵活应变	区分"硬约束"和"软建议"
硬编码 Skill	把具体数据（IP、账号）写进 Skill	使用变量或配置引用
冲突不自知	两个 Skill 给出矛盾指令	声明互斥关系或优先级
僵尸 Skill	写了之后从不更新，逐渐过时	定期审查，及时更新或废弃

九、Skill 的未来演进方向

9.1 可组合 Skill

未来的 Skill 之间可以像微服务一样组合调用：一个"全栈应用开发 Skill"可能内部由"前端 Skill"、"后端 Skill"、"数据库 Skill"组合而成。

9.2 自进化 Skill

Agent 在执行任务时，将成功经验和发现的陷阱自动沉淀到 Skill 中，形成自我改进的闭环。

9.3 跨平台 Skill

一套 Skill 定义，可以运行在不同 Agent 框架（Claude Code、Cursor、Copilot 等）中，类似"一次编写，处处运行"。

9.4 可验证 Skill

Skill 中包含形式化的验证规则（不仅是自然语言），Agent 执行后自动校验输出是否合规。

十、总结

Skill 是 AI Agent 开发中的核心抽象，它将"教 Agent 做专业的事"这个过程标准化、模块化。

关键要点回顾：

Skill 的本质：领域知识 + 工作流指引的封装包
Skill ≠ Tool：Tool 是原子操作，Skill 是复合能力
架构核心：元信息 → 路由匹配 → 上下文注入 → Agent 执行
编写核心：单一职责、指令具体、边界清晰、示例驱动
管理核心：生命周期追踪、版本化、热加载

Skill 不是银弹——如果一个任务的复杂度超出了"知识注入 + 规则约束"能解决的范围（比如需要复杂的确定性计算），那么应该考虑 Plugin 或直接写代码。Skill 最佳的应用场景是那些需要深度领域知识来引导 LLM 行为的任务——设计规范、代码规范、安全审查、特定 API 的使用指导等。

本文基于 AI Agent 应用开发的实践经验总结，适用于 Claude Code、Cursor、Copilot 等主流 Agent 平台的 Skill 开发。

MCP技术社区

欢迎加入 MCP 技术社区！与志同道合者携手前行，一同解锁 MCP 技术的无限可能！

更多推荐

AI Agent中的function call详解

本文系统解析了AI Agent中function call（函数调用/工具调用）的核心机制与实践要点。关键点包括：1）模型仅输出结构化调用请求，实际执行由宿主程序完成；2）完整调用回路包含工具注册、模型决策、宿主执行、结果回传和最终回答五个步骤；3）工具定义（Schema）的质量直接影响调用准确性，需明确名称、描述和参数规范；4）进阶功能如并行调用、多步循环等支持复杂任务；5）工程实践中需防范参数