摘要：本文系统讲解 Agent Skill 的核心概念、基础结构、五种设计模式及工程化开发流程，提供中英文对照的代码审查 Skill 模板，帮助读者从零掌握 Skill 编写与团队落地方法。

一、引言：从"一次性 Prompt"到"可复用 Skill"

你是否遇到过这样的困境？

每次让 AI 帮助审查代码，都要重复说一遍"请检查安全性、可维护性、性能和代码风格"。每次让 AI 生成 API 文档，都要花时间解释文档的格式要求。每次让 AI 处理数据，都要叮嘱它不要修改原始数据、要保留处理日志。

这些重复的解释，本质上都是一次性 Prompt 的局限。

当我们把 AI 应用到真实工作中，会发现有些任务会反复出现，每次都要重新解释规则不仅耗时，还会导致输出不稳定——有时候 AI 审查得仔细，有时候又漏掉某些检查项。更糟糕的是，这些规则难以共享给团队成员，大家各自为战，风格不统一。

Agent Skill 正是为解决这些问题而生的。

Skill 不是单条 Prompt，而是一个可复用、可测试、可迭代的结构化能力包。它把任务相关的指令、流程、边界规则和输出标准封装在一起，让 AI 在需要时自动加载、按规范执行、产出稳定结果。

本文将带你从零理解 Skill 的核心概念，掌握编写高质量 Skill 的方法，并提供一个可直接复用的实战模板。读完本文，你将能够：

• 理解 Skill 与 Prompt、MCP、Rules 等相关概念的区别
• 掌握 Skill 的标准结构和编写规范
• 学会根据任务类型选择合适的设计模式
• 设计并测试一个最小可用的 Skill
• 在团队中落地 Skill 治理流程

二、Skill 到底是什么？

2.1 一个更精确的定义

经过对多篇权威资料的分析，我们把 Agent Skill 定义为：



Skill 是一个可复用的、结构化的 Agent 行为包，用 SKILL.md 声明触发条件、执行流程、边界规则、输出标准，并可通过脚本、参考文档和资源文件增强确定性与复用性。

”

这个定义有几个关键点：

2.2 Skill 不是 Prompt

很多人容易把 Skill 和 Prompt 混为一谈，但它们有本质区别：

举一个形象的例子：

• Prompt 像是点餐时口头告诉服务员"我要一份不加辣的宫保鸡丁，少放花生，多加点葱"
• Skill 像是把这道菜的完整菜谱写下来，以后任何服务员都能按照菜谱做出标准口味

2.3 Skill 的本质

Skill 的核心不是"写更好的提示词"，而是围绕任务、工具、流程、资源和输出边界设计结构化行为单元。

这意味着一个好的 Skill 需要考虑：

• 任务边界：这个 Skill 负责什么、不负责什么
• 工具配合：需要调用哪些工具、脚本或外部系统
• 流程步骤：完成任务的标准步骤是什么
• 资源依赖：需要哪些参考文档、模板或数据
• 输出标准：结果应该长什么样、如何验证

三、Skill 的基础结构

3.1 最小结构

一个 Skill 可以极其简单，只需要一个文件：

skill-name/
└── SKILL.md

SKILL.md 是 Skill 的核心入口，包含所有必要的指令和元数据。

3.2 完整目录结构

对于更复杂的 Skill，常见的完整结构是：

skill-name/
├── SKILL.md          # 必需：YAML frontmatter + Markdown 指令
├── sc ripts/          # 可选：可执行脚本（Python、Shell、Node 等）
├── references/       # 可选：按需加载的参考文档
└── assets/           # 可选：模板、资源文件

各部分的职责分工：

3.3 SKILL.md 的格式规范

SKILL.md 由两部分组成：

• YAML frontmatter：机器可读的元数据
• Markdown body：给模型读的操作说明

基础格式：

---
name: my-skill
desc ription: Use this skill when the user needs to do something...
---

# My Skill

## Purpose

This skill helps the agent achieve X.

## Steps

1. First step...
2. Second step...

3.4 必填字段与可选字段

3.5 name 字段的写法规范

好例子：

• name: pdf-processing
• name: code-review
• name: data-analysis
• name: api-design-check

坏例子：

• name: PDF-Processing # 不要大写
• name: -pdf # 不要以短横线开头
• name: pdf--processing # 不要连续短横线
• name: my cool skill # 不要空格

四、触发机制：desc ription 怎么写？

4.1 作用原理

Skill 的触发不是靠硬编码关键词，而是让模型根据 desc ription 判断任务是否匹配。

这意味着：

• 用户说"帮我看看这段代码"可能被 Skill 识别为代码审查请求
• 用户说"检查一下 API 设计合不合理"也可能触发代码审查 Skill
• 但"帮我写一首诗"不应该触发代码审查

desc ription 写得好不好，直接决定 Skill 能否被正确触发。

4.2 好 desc ription 的组成

一个有效的 desc ription 应该包含：

• 这个 Skill 做什么：简明扼要描述核心能力
• 用户什么时候会需要它：真实使用场景
• 用户可能怎么表达：包含触发短语和关键词
• 哪些情况不应该触发它：负面案例（可选但推荐）

好例子：

desc ription: |
  Analyze CSV, TSV, Excel, and tabular data files. Use this skill when the
  user wants to clean, summarize, transform, compare, visualize, or derive
  insights from structured data, even if they do not explicitly say "data analysis".
  Do not use for real-time streaming data or binary file formats.

坏例子：

desc ription: Helps with data.

4.3 写作原则

4.4 常见描述模板

数据分析类：

desc ription: |
  Analyze CSV, TSV, Excel, and tabular data files. Use when the user wants
  to clean, summarize, transform, compare, visualize, or derive insights
  from structured data, even if they do not explicitly say "data analysis".

代码审查类：

desc ription: |
  Review code changes, pull requests, diffs, or snippets for correctness,
  security, maintainability, performance, and style. Use when the user asks
  to review, check, audit, inspect, or give feedback on code.

API 规范类：

desc ription: |
  Enforce API development standards when adding, modifying, or deleting API
  endpoints. Use when the user mentions OpenAPI, endpoint changes, backward
  compatibility, API documentation, contract tests, or unit test generation.

五、渐进式加载：解决上下文膨胀

5.1 问题背景

如果我们把所有 Skill 的完整内容都塞进 AI 的上下文，会发生什么？

• 上下文急剧膨胀，处理速度变慢
• 不同 Skill 的规则相互干扰
• 大量低频信息占用宝贵 token 预算

5.2 三层加载机制

Skill 的核心机制是渐进式加载（Progressive Disclosure），只在需要时加载对应层级的内容：

5.3 这个机制的价值

• 不把所有规则塞进上下文：只加载当前任务需要的
• 只在需要时读取完整内容：节省 token
• 长文档拆到 references/ 后可按需加载：避免上下文爆炸
• 让大量 Skill 可以共存：一个 Agent 可以管理数十个 Skill

5.4 知识组织的大小建议

六、五种核心设计模式

根据实际任务类型，Skill 应该采用不同的内部结构。以下是五种最常用的设计模式。

6.1 线性流程（Linear Flow）

适用场景：部署、安装、导出、迁移等明确步骤的操作。

结构特点：按顺序执行，每步结果作为下一步输入。

## Workflow

### Step 1: 准备环境
- 检查依赖版本
- 验证权限

### Step 2: 执行部署
- 执行部署脚本
- 监控进度

### Step 3: 验证结果
- 运行健康检查
- 确认服务可用

6.2 决策树（Decision Tree）

适用场景：多产品选型、多路径诊断、需要根据条件分支的场景。

结构特点：条件分支 + 按需加载，每个分支处理一种情况。

## Decision Tree

### 用户的需求类型？

├─ 数据分析
│  └─ 进入数据分析流程
├─ 代码审查
│  └─ 进入代码审查流程
└─ 文档生成
   └─ 进入文档生成流程

6.3 循环迭代（Loop Iteration）

适用场景：写作、设计、代码改进等需要反复调整的任务。

结构特点：do → validate → refine → loop，直到满足质量标准或达到最大迭代次数。

## Workflow

### Iteration Loop

1. **Generate**: 根据要求生成初稿
2. **Validate**: 运行验证脚本检查质量
3. **Refine**: 根据验证结果改进
4. **Loop**: 如果未通过验证且还有迭代次数，返回步骤 1

### Exit Conditions
- 验证通过
- 达到最大迭代次数（默认 3 次）
- 用户手动确认完成

6.4 接力棒循环（Relay Loop）

适用场景：长期项目、跨 session 持续推进的任务。

结构特点：每次处理一小部分，保存状态，下一次从断点继续。

## Workflow

### Session Start
1. 读取项目状态文件
2. 确定当前阶段和待办项

### Session Work
3. 处理当前阶段任务
4. 更新状态文件
5. 记录下次从哪里继续

### Session End
6. 保存上下文到状态文件
7. 生成进度报告

6.5 多阶段 + 检查点（Multi-Stage with Gates）

适用场景：咨询、研究、产品发现等有明确阶段和决策点的项目。

结构特点：阶段之间有门禁（Go/No-Go），只有满足条件才能进入下一阶段。

## Stages

### Stage 1: 需求理解
**Gate**: 是否有清晰的目标和约束？

### Stage 2: 方案设计
**Gate**: 方案是否覆盖所有关键需求？

### Stage 3: 实现规划
**Gate**: 实现计划是否可行？

### Stage 4: 执行与验证
**Gate**: 所有验收标准是否满足？

6.6 模式选择决策树

你的 Skill 需要做什么？
├─ 执行一个明确步骤的操作
│  └─ 线性流程
├─ 在大量选项中选正确方向
│  └─ 决策树 + 按需加载
├─ 在单次会话中反复做、验、改
│  └─ 循环迭代
├─ 跨多个 session 持续推进长期项目
│  └─ 接力棒循环
├─ 跨多天 / 多周，有阶段和 Go/No-Go 决策
│  └─ 多阶段 + 检查点
└─ 需要模型深度分析，而不是快速执行
   └─ 思维框架（参考模式）

七、Skill 开发工程化流程

7.1 为什么需要工程化

Skill 开发不是"写完 prompt 就完事了"，而是一个需要测试、评估、迭代的工程过程。原因是：

• 泛化 vs 过拟合：不要为了某个测试样例写死规则，要提取可迁移的行为模式
• 解释为什么：现代模型更容易遵守有原因、有上下文的规则，而不是机械堆叠 ALWAYS / NEVER
• 脚本化重复逻辑：如果模型每次都要写同样的小脚本，就应该把它沉淀到 sc ripts/

7.2 TDD 方法论：红绿重构

Skill 开发可以借鉴 TDD 的思路：

7.3 测试设计

在开发 Skill 之前，需要准备测试用例：

验证清单：

• [ ] 是否应该触发却没触发
• [ ] 是否不该触发却触发了
• [ ] desc ription 是否太宽或太窄
• [ ] 是否包含用户真实表达方式

7.4 三类子 Agent（可选）

对于高价值 Skill，可以引入三类子 Agent 进行系统化评估：

7.5 迭代原则

每次改进都问：

• 这是通用问题，还是个别案例？
• 能不能用一句原则解决？
• 能不能放 references？
• 能不能用脚本解决？
• 是否会增加误触发？
• 是否会增加主文件长度但收益很低？

八、Skill 与相关概念的区别

在 Agent 生态中，Skill 不是孤立存在的，它与多个相关概念相互配合。

8.1 Skill vs MCP

最强组合：

• MCP = 工具入口
• Skill = 工作流说明书
• sc ripts = 确定性执行器
• references = 领域知识库
• assets = 输出模板

8.2 Skill vs Rules

8.3 Skill vs Slash Command

可以理解为：Slash Command 是 Skill 的显式入口之一。

8.4 各概念分工

• Prompt 是一句话。
• Skill 是一个可复用工作流。
• MCP 是工具入口。
• Rules 是全局约束。
• Slash Command 是快捷动作。

好的 Agent 系统，需要把它们分工清楚。

九、好 Skill 的共同特征与质量检查

9.1 好 Skill 的八大特征

9.2 开发检查清单

开发前：

• [ ] 是否明确了 2-3 个真实使用场景
• [ ] 是否知道用户会怎么表达需求
• [ ] 是否明确不适用场景
• [ ] 是否选择了合适设计模式

文件结构：

• [ ] 目录名是 kebab-case
• [ ] 主文件名严格为 SKILL.md
• [ ] name 与目录名一致
• [ ] desc ription 包含做什么和何时用

指令质量：

• [ ] 每一步只做一件事
• [ ] 有明确输入要求
• [ ] 缺输入时知道如何提问
• [ ] 有明确输出格式
• [ ] 高风险操作默认安全

测试：

• [ ] 10 个应触发请求
• [ ] 5 个不应触发请求
• [ ] 同一请求重复运行 3 次
• [ ] 与无 Skill 输出对比

9.3 推荐指标

十、实战模板：代码审查 Skill（中英文对照）

10.1 英文模板

---
name: code-review
desc ription: |
  Review code changes, pull requests, diffs, or snippets for correctness,
  security, maintainability, performance, and style. Use when the user asks
  to review, check, audit, inspect, or give feedback on code. Trigger phrases
  include "review this code", "check for bugs", "look at my PR", "audit the
  changes", or "what do you think of this implementation".
  Do not use for style-only requests without substance.
license: MIT
me tadata:
  author: your-team
  version: 0.1.0
---

# Code Review Skill

## Purpose

This skill helps the agent perform thorough, consistent code reviews by
following a structured review process and checklist.

## When to Use

Use when:
- User asks to review code, PR, or diff
- User wants feedback on implementation quality
- User requests bug hunting or security audit
- User asks to check code style and best practices

Do not use when:
- User asks for style-only changes without substance
- User just wants auto-formatting (not review)
- Request is about documentation only

## Review Process

### Step 1: Understand Context

- Identify the programming language and fr amework
- Note the purpose of the changed code
- Check if tests are included

### Step 2: Security Review

Check for:
- SQL injection vulnerabilities
- Command injection risks
- Sensitive data exposure
- Authentication/authorization issues
- Input validation

### Step 3: Correctness Review

Check for:
- Logic errors
- Off-by-one errors
- Null pointer / undefined handling
- Race conditions
- Resource leaks

### Step 4: Performance Review

Check for:
- N+1 query problems
- Unnecessary iterations
- Missing indexes
- Memory inefficiencies

### Step 5: Maintainability Review

Check for:
- Code duplication
- Naming clarity
- Function complexity (> 20 lines = red flag)
- Missing documentation

## Output Format

Return review in this structure:

```markdown
## Code Review Summary

**Overall**: [Pass / Needs Work / Needs Discussion]

## Issues Found

### Critical
1. [Issue desc ription] (line X)
   - [Why it's a problem]
   - [Suggested fix]

### Minor
...

## Recommendations

- [Optional improvements not blocking merge]

## Approvals Required

- [ ] Security review
- [ ] Performance review
- [ ] Maintainability review

Examples

Good Trigger

User: “Can you review this PR? I’m concerned about the authentication flow.”

Assistant will: Load code-review skill and perform full security + correctness review.

Bad Trigger

User: “Format this code please.”

Assistant will: Decline and explain this is formatting, not review.

Troubleshooting

### 10.2 中文模板

```yaml
---
name: code-review
desc ription: |
  审查代码变更、Pull Request、diff 或代码片段的正确性、安全性、可维护性、
  性能和代码风格。当用户要求审查、检查、审计、检查代码或提供反馈时触发。
  触发短语包括"帮我审查代码"、"检查一下bug"、"看看我这个PR"、"审计这些变更"、
  或"你觉得这个实现怎么样"。
  不适用于纯格式调整请求。
license: MIT
me tadata:
  author: your-team
  version: 0.1.0
---

十一、总结

核心要点

• Skill 不是 Prompt：Skill 是可复用、可测试、可迭代的结构化能力包
• desc ription 决定触发：必须认真写，要覆盖真实用户表达方式
• 渐进式加载：主文件保持短，长资料拆到 references/
• 不同任务用不同模式：线性流程、决策树、循环迭代、接力棒、多阶段
• Skill 要测试和迭代：写完不管只会越来越差

快速检查清单

下次写 Skill 之前，先回答这 5 个问题：

1. 这个任务会不会重复出现？
2. 用户通常怎么表达这个需求？
3. 正确完成的标准是什么？
4. 哪些步骤可以自动化验证？
5. 需要哪些参考资料？

如果 3 个以上是"是"，就值得写成一个 Skill。

推荐学习书籍 《CDA一级教材》适合CDA一级考生备考，也适合业务及数据分析岗位的从业者提升自我。完整电子版已上线CDA网校，累计已有10万+在读~ !

免费加入阅读：https://edu.cda.cn/goods/show/3151?targetId=5147&preview=0