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

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

一、什么是 Skill

1.1 概念定义

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

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

1.2 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 是"教你怎么修手表"。

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 加载策略

4.2 路由/匹配机制

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

推荐的混合路由策略：

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 设计层面

7.2 编写层面

7.3 测试层面

7.4 生态层面

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

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