一文读懂 Skills｜从概念到实操的完整指南

写在前面

Agent 正在经历从"聊天机器人"到"得力干将"的进化，而 Skills 正是这场进化的关键催化剂。

你是否曾被 Agent 的"不听话"、"执行乱"和"工具荒"搞得焦头烂额？

本文将带你一文弄懂 Skills ——这个让 Agent 变得可靠、可控、可复用的"高级技能包"。我们将从 Skills 是什么、如何工作，一路聊到怎样写好一个 Skills，并为你推荐实用的社区资源，带领大家在 TRAE 中实际使用 Skills 落地一个场景。

无论你是开发者还是普通用户，都能在这里找到让你的 Agent "开窍"的秘诀。

那些让人抓狂的 Agent 调教时刻

场景一：规则失效的绝望

周五下午 5 点，你盯着屏幕上那份长达 3000 字的 agent.md 规则文件，里面详细写着：

"在处理用户数据时，必须先验证权限"
"生成代码时，务必遵循项目的 ESLint 规范"
"调用 API 前，请检查环境变量配置"

你花了整整一下午精心打磨这些规则，甚至用加粗、高亮、emoji 来强调重点。

结果呢？Agent 就像没看见一样，依然我行我素：直接操作数据库不管权限，生成的代码满屏 ESLint 报错，API 调用失败因为它压根没检查配置。

你开始怀疑人生：这些规则到底有没有被读取？

场景二：执行失控的混乱

你尝试换个思路，既然写规则不管用，那就写详细的 Prompt 吧。于是你开始了 Prompt 工程的修炼之路：

版本 1.0："请帮我生成一个登录页面"（结果：样式丑到爆）
版本 2.0："请帮我生成一个现代化的、响应式的、带动画效果的登录页面"（结果：过度设计，加载巨慢）
版本 3.0："请帮我生成一个简洁的登录页面，使用 Tailwind CSS，包含邮箱和密码输入框，一个登录按钮，不要添加多余的动画"（结果：这次倒是简洁了，但忘了加表单验证）

每次都要重新调整 Prompt，每次结果都不太一样。这种不稳定性，让你觉得自己不是在开发，而是在抽奖。

场景三：工具迷失的无奈

听说 MCP（Model Context Protocol）很强大，可以给 Agent 集成各种工具。你兴冲冲地配置了一堆：文件操作工具、数据库查询工具、API 调用工具、代码分析工具。

配置文件写得漂漂亮亮，工具列表长长一串。然后你满怀期待地对 Agent 说："帮我查询一下数据库中的用户列表"

Agent 回复："抱歉，我没有可用的数据库查询工具"

你：？？？

这些问题的共同点

如果上面这些场景让你感同身受，恭喜你，你不是一个人在战斗。根据社区调研，超过 80% 的 Agent 开发者都遇到过类似问题。

这些问题的根本原因是：传统的 Agent 配置方式（规则文件 + Prompt + 工具列表）是静态的、分散的、不可控的。

静态：规则一次性加载，无法动态调整
分散：知识、流程、工具分散在不同地方，Agent 难以整合
不可控：执行过程像黑盒，出了问题难以定位

而 Skills，正是为了解决这些问题而生的。它提供了一种结构化、可复用、可控制的方式，让 Agent 从"不听话的助手"变成"靠谱的专家"。

什么是 Skills

起源：从 Anthropic 到社区标准

"Skills" 这个概念最早由 Anthropic 公司提出，作为其大模型 Claude 的一种能力扩展机制。

2024 年初，Anthropic 团队在开发 Claude 的过程中发现：虽然大模型很聪明，但在处理特定领域任务时，往往需要大量的上下文信息。如果把这些信息全部塞进 Prompt，会导致 Token 消耗巨大、执行不稳定、难以复用。

于是，Anthropic 提出了 Skills 的概念：把完成某个特定任务所需的领域知识、操作流程、工具调用、最佳实践等，全部封装成一个独立的"技能包"，让 Agent 可以按需加载和执行。

这个设计理念迅速得到了社区的认可。如今，Skills 已经成为大多数 Agent 开发工具和 IDE 都支持的一种标准扩展规范。

核心定义：一个技能包里有什么？

一个 Skills 通常以一个文件夹的形式存在，里面主要装着三样东西：

my-skill/
├── SKILL.md          # 说明书（核心）
├── scripts/          # 操作脚本（可选）
│   ├── process.py
│   └── validate.sh
└── references/       # 参考资料（可选）
    ├── api-docs.md
    └── examples.json

SKILL.md 是核心文件，包含元数据（YAML frontmatter）和说明文档（Markdown 正文）。scripts/ 存放可执行脚本，references/ 存放参考资料。

生活化类比：Skills 就像专家的工具箱

如果还是觉得抽象，我们用一个生活化的例子来理解：

假设你要装修房子，你会怎么做？

方案 A：自己摸索（传统 Prompt 方式）
你在网上搜索"如何装修房子"，然后把所有信息都告诉装修工人。问题是：信息太多工人记不住，每次都要重复一遍，工人可能理解偏差导致执行走样。

方案 B：请专业团队（Skills 方式）
你直接找一个专业的装修团队，他们自带标准流程、专业工具、经验积累。你只需要说："我要装修房子，现代简约风格，预算 20 万"，团队就能按照标准流程，使用专业工具，高质量完成任务。

Skills 就是这样的"专业团队"：

SKILL.md = 标准流程手册
scripts/ = 专业工具箱
references/ = 经验知识库

一句话总结

如果把 Agent 比作一个有很大潜力的大脑，那 Skills 就像是给这个大脑的一套套能反复用的"高级武功秘籍"。有了它，Agent 能从一个"什么都略知一二"的通才，变成在特定领域"什么都擅长"的专家。

Skills 的工作原理

核心设计：渐进式加载机制

Skills 最巧妙的设计，就是它的三层渐进式加载机制。

为什么需要渐进式加载？如果把所有 Skills 的所有内容都一次性加载到上下文中，会导致 Token 消耗巨大、信息过载、效率低下。

解决方案：按需加载，用多少加载多少。具体怎么做？三层加载：

Level 1：元数据（始终加载）

内容：Skills 的"名片"（name、description）
加载时机：Agent 启动时
作用：让 Agent 知道"我有哪些技能可用"
Token 消耗：极低（每个 Skills 只有几十个 Token）

Level 2：说明文档（触发时加载）

内容：SKILL.md 的正文部分（工作流程、最佳实践、操作指南）
加载时机：只有当用户请求匹配 Skills 描述时，才加载
Token 消耗：中等（几百到几千 Token）

Level 3：资源与代码（按需加载）

内容：详细文档、可执行脚本、参考资料
加载时机：只有在执行过程中需要时，才读取或执行
Token 消耗：几乎为零（脚本代码不进入上下文，只有执行结果进入）

调用逻辑：从理解意图到稳定执行

Agent 是如何智能地选择并执行一个 Skills 的呢？整个过程分为四步：

意图匹配：Agent 扫描所有 Skills 的元数据，找到最匹配的那个
读取手册：使用 bash 命令读取 SKILL.md 文件，将说明文档加载到上下文
按需执行：按照流程一步步执行，如果需要则读取参考资料或执行脚本
反馈结果：完成任务展示结果，或遇到问题请求帮助

Skills vs. 其他概念的区别

在 Agent 开发中，有很多容易混淆的概念：Skills、Command、MCP……让我们用一个厨房的例子来理解：

概念	类比	特点	适用场景
Command	微波炉加热	一键完成、固定功能、快速简单	简单重复操作（格式化代码、运行测试）
MCP	厨房用具	单一功能、需要手动操作、可组合	基础操作（文件读写、数据库查询）
Skills	菜谱+厨具套装	完整流程、包含工具和知识、可自主执行	复杂多步骤任务（代码审查、文档生成）

它们可以组合使用：一个 Skills 内部可以调用多个 MCP 工具、使用 Command 快捷指令、组合其他 Skills。

什么是好的 Skills

写 Skills 和写代码一样，有好坏之分。让我们通过对比来理解：

Good Skills vs Bad Skills

案例：代码审查 Skills

❌ Bad Skills

yaml

---
name: "代码审查"
description: "审查代码"
---
请帮我审查代码，找出问题。

问题：Description 太模糊、没有具体流程、没有标准、没有示例。

✅ Good Skills

yaml

---
name: "代码审查专家"
description: "对 JavaScript/TypeScript 代码进行全面审查，检查代码规范、安全漏洞、性能问题和最佳实践"
---

## 角色定义
你是一位资深的前端代码审查专家，拥有 10 年以上的 JavaScript/TypeScript 开发经验。

## 审查流程
### 1. 代码规范检查
- 命名规范（驼峰命名、常量大写等）
- 代码格式（缩进、空格、换行）
- 注释完整性

### 2. 安全漏洞扫描
- XSS 风险点
- SQL 注入可能性
- 敏感信息泄露

### 3. 性能问题分析
- 不必要的重复计算
- 内存泄漏风险
- 可优化的循环

### 4. 最佳实践检查
- 是否遵循 SOLID 原则
- 是否有适当的错误处理
- 是否有单元测试

## 输出格式
（包含完整的输出格式示例）

## 示例
（包含完整的输入输出示例）

## 注意事项
- 不要过度吹毛求疵，关注真正重要的问题
- 提供具体的修改建议，而不是只指出问题

好 Skills 的五大特征

原子性（Atomicity）：一个 Skills 只做一件事，但把这件事做到极致
给例子（Few-Shot Prompting）：提供具体的输入输出示例，让 Agent 一看就懂
立规矩（Structured Instructions）：定角色、拆步骤、画红线
造接口（Interface Design）：明确定义输入参数和输出格式
勤复盘（Iterative Refinement）：把 Skills 当作产品来迭代，持续优化

如何写好 Skills：实战指南

让我们通过一个真实案例，一步步创建一个可用的 Skills。

实战案例：创建一个"Git Commit 规范" Skills

需求背景：团队使用 Conventional Commits 规范，但新人经常写出不规范的 commit message。我们需要一个 Skills 来帮助生成规范的 commit。

步骤 1：明确职责（原子性）

这个 Skills 要解决什么问题？→ 生成符合 Conventional Commits 规范的 commit message
它的边界在哪里？→ 只负责生成 commit message，不负责执行 git commit
它和其他 Skills 的关系？→ 可以被"代码提交" Skills 调用

步骤 2：编写元数据

yaml

---
name: "Git Commit 规范专家"
description: "根据代码变更生成符合 Conventional Commits 规范的 commit message，支持 feat/fix/docs/style/refactor/test/chore 等类型"
---

步骤 3：定义角色和流程

markdown

## 角色定义
你是一位经验丰富的 Git 工作流专家，深谙 Conventional Commits 规范。

## Conventional Commits 规范
### 格式
<type>(<scope>): <subject>

<body>

<footer>

### Type 类型
- feat: 新功能
- fix: Bug 修复
- docs: 文档变更
...

## 工作流程
1. 分析代码变更内容
2. 判断 commit 类型
3. 确定影响范围
4. 编写简洁的主题
5. 如有必要，添加详细说明

步骤 4：提供示例（Few-Shot）

markdown

## 示例

### 示例 1：新功能
**代码变更**：添加了用户登录功能

**输出**：
feat(auth): add user login functionality

Implement JWT-based authentication with email and password.
Includes login form validation and error handling.

Closes #45

步骤 5：添加注意事项

markdown

## 注意事项
### ✅ 应该做的
- 使用现在时、祈使句
- 主题简洁明了，50 字符以内
- Breaking Changes 必须在 footer 中明确标注

### ❌ 不应该做的
- 不要使用模糊的描述
- 不要在主题中使用句号
- 不要在一个 commit 中混合多种类型的变更

步骤 6：测试和迭代

实际测试这个 Skills，收集不符合预期的情况，分析原因并优化。

社区热门 Skills 推荐

Claude 官方 Skills

📚 官方 Skills 仓库：https://github.com/anthropics/skills

官方 Skills 列表

Skills 名称	功能描述	适用场景
code-review	代码审查专家	检查代码规范、安全漏洞、性能问题
frontend-design	前端设计专家	创建现代化的响应式页面
api-design	API 设计专家	设计 RESTful API，生成 OpenAPI 文档
database-schema	数据库设计专家	设计数据库结构，优化查询性能
testing	测试专家	编写单元测试、集成测试
documentation	文档专家	生成技术文档、API 文档

如何选择合适的 Skills？

评估标准：

匹配度：是否解决你的实际问题？
质量：是否有完整的文档和示例？
维护：是否持续更新？
社区：是否有人使用和反馈？

选择建议：

新手：从官方 Skills 开始，选择通用性强的 Skills
进阶用户：根据项目需求选择垂直领域 Skills，Fork 社区 Skills 进行定制
团队使用：建立团队 Skills 库，制定 Skills 编写规范

如何在 TRAE 里快速使用

Skills 创建

TRAE 提供了三种创建 Skills 的方式：

方式一：设置中直接创建

按下快捷键 Cmd + ,（Mac）或 Ctrl + ,（Windows）打开设置面板
在左侧找到「规则技能」选项
点击「创建」按钮
填写 Skills 名称、描述、主体
点击「确认」保存

方式二：直接解析 SKILL.md

在项目目录下创建 .trae/skills/my-skill/ 目录
将 Skills 文件放入对应目录
重启 TRAE 或刷新 Skills 列表

方式三：在对话中创建

TRAE 中内置了 skills-creator Skills，你可以直接对话创建：

你：帮我创建一个 Skills，用于生成 API 文档

Agent：好的，我来帮你创建...

Skills 使用

在 TRAE 里使用 Skills 很容易，只需在对话框中用日常语言说明你的需求：

你：帮我设计一个有科技感的登录页面

Agent：（自动调用 "frontend-design" Skills）
好的，我来为你设计一个现代科技感的登录页面...

实践场景举例：基于飞书文档的 Spec Coding

什么是 Spec Coding？

Spec Coding 提倡"先思考后行动"，通过详细定义可以执行的需求规范（Specification）来推动 AI 开发。流程包含"需求分析、技术设计、任务拆解"的文档编写，最后让 AI 根据规范完成编码。

场景分析

我们需要：

不同的 Skills 来满足不同场景下的文档编写需求
飞书工具 Skills 来教会 Agent 如何使用飞书文档进行创作协同

多角色专家 Skills

Skills 名称	职责	输入	输出
需求分析专家	分析用户需求，输出需求文档	用户描述	需求分析文档（飞书）
技术设计专家	设计技术方案，输出设计文档	需求文档	技术设计文档（飞书）
任务拆解专家	拆解开发任务，输出任务清单	设计文档	任务清单文档（飞书）
代码实现专家	根据任务清单编写代码	任务清单	代码文件

总结

通过不同角色 Skills 的分工协作，借助飞书文档形成协作闭环，有效解决了 Agent "不听话、执行乱、工具少" 的问题，让 AI 从 "对话助手" 真正转变为 "可信赖的实干家"。

Q & A | 一些常见问题

Q1: 为什么我写的 Skills 不生效？

A: 十有八九是你的 Description 没写好。Agent 通过 Description 判断什么时候该用哪个 Skills。

改进建议：

使用清晰、具体的描述
包含关键词（技术栈、功能、场景）
参考官方 Skills 的 Description 写法

Q2: 使用 Skills 的效果会受模型影响吗？

A: 会有影响。更强大的模型主要影响"挑选"和"安排" Skills 的能力，而 Skills 本身决定了执行的稳定性。

Q3: Skills 是不是万能的？

A: 不是。Skills 擅长处理流程明确、边界清晰的任务，不擅长高度创造性的任务、实时动态决策、单纯的知识问答。

Q4: 我可以修改社区的 Skills 吗？

A: 当然可以！大多数 Skills 都支持 Fork 并进行二次开发。

Q5: 多个 Skills 之间会不会冲突？

A: 有可能，但可以通过明确 Description、定义优先级、手动指定来避免。

Q6: Skills 可以调用其他 Skills 吗？

A: 可以，而且这是一个强大的功能。

Q7: Skills 的性能开销大吗？

A: 设计得当的话，开销很小。元数据约 50 Token，说明文档 500-2000 Token，脚本几乎不消耗 Token。

Q8: 如何调试 Skills？

A: 查看 Agent 思考过程、测试 Description 匹配、逐步测试、添加日志、版本对比。

结语｜让 Agent 成为你真正的"行动派"

Skills 的出现，为 AI 从"对话式助手"转变为"可信赖的执行者"搭建了关键的技术桥梁。

它用结构化的方法把领域知识、操作流程和工具调用逻辑封装起来，解决了 Agent 规则失效、执行失控的混乱问题，让 AI 的能力输出变得可以控制、值得信赖且高效。

Skills 的核心价值

精准击中痛点：通过三级加载机制，在功能深度和上下文效率之间找到绝佳平衡。

生态赋能，降低门槛：官方和社区提供丰富资源，让普通用户也能快速复用成熟能力。

未来展望

随着 AI 模型能力的提升与 Skills 生态的进一步完善，我们有望看到：

更多跨领域 Skills
更强的可组合性
更智能的自适应
更完善的生态

行动起来

不妨从今天开始，尝试创建你的第一个 Skills：

识别你的专业领域：你最擅长什么？你经常重复做什么？
封装成 Skills：写下工作流程、总结最佳实践、提供具体示例
分享给社区：让更多人受益、获得反馈、推动生态发展

将你最擅长的领域经验封装成可复用的能力，让 AI 成为你延伸专业价值的放大器。

参考资源

官方文档

作者：咸鱼，TRAE 开发者用户
扩写：基于原文核心要点深度扩展
最后更新：2024-01-22

一文读懂 Skills｜从概念到实操的完整指南 ​

写在前面 ​

那些让人抓狂的 Agent 调教时刻 ​

场景一：规则失效的绝望 ​

场景二：执行失控的混乱 ​

场景三：工具迷失的无奈 ​

这些问题的共同点 ​

什么是 Skills ​

起源：从 Anthropic 到社区标准 ​

核心定义：一个技能包里有什么？ ​

生活化类比：Skills 就像专家的工具箱 ​

一句话总结 ​

Skills 的工作原理 ​

核心设计：渐进式加载机制 ​

Level 1：元数据（始终加载） ​

Level 2：说明文档（触发时加载） ​

Level 3：资源与代码（按需加载） ​

调用逻辑：从理解意图到稳定执行 ​

Skills vs. 其他概念的区别 ​

什么是好的 Skills ​

Good Skills vs Bad Skills ​

案例：代码审查 Skills ​

好 Skills 的五大特征 ​

如何写好 Skills：实战指南 ​

实战案例：创建一个"Git Commit 规范" Skills ​

步骤 1：明确职责（原子性） ​

步骤 2：编写元数据 ​

步骤 3：定义角色和流程 ​

步骤 4：提供示例（Few-Shot） ​

步骤 5：添加注意事项 ​

步骤 6：测试和迭代 ​

社区热门 Skills 推荐 ​

Claude 官方 Skills ​

官方 Skills 列表 ​

如何选择合适的 Skills？ ​

如何在 TRAE 里快速使用 ​

Skills 创建 ​

方式一：设置中直接创建 ​

方式二：直接解析 SKILL.md ​

方式三：在对话中创建 ​

Skills 使用 ​

实践场景举例：基于飞书文档的 Spec Coding ​

什么是 Spec Coding？ ​

场景分析 ​

多角色专家 Skills ​

总结 ​

Q & A | 一些常见问题 ​

Q1: 为什么我写的 Skills 不生效？ ​

Q2: 使用 Skills 的效果会受模型影响吗？ ​

Q3: Skills 是不是万能的？ ​

Q4: 我可以修改社区的 Skills 吗？ ​

Q5: 多个 Skills 之间会不会冲突？ ​

Q6: Skills 可以调用其他 Skills 吗？ ​

Q7: Skills 的性能开销大吗？ ​

Q8: 如何调试 Skills？ ​

结语｜让 Agent 成为你真正的"行动派" ​

Skills 的核心价值 ​

未来展望 ​

行动起来 ​

参考资源 ​

官方文档 ​

一文读懂 Skills｜从概念到实操的完整指南

写在前面

那些让人抓狂的 Agent 调教时刻

场景一：规则失效的绝望

场景二：执行失控的混乱

场景三：工具迷失的无奈

这些问题的共同点

什么是 Skills

起源：从 Anthropic 到社区标准

核心定义：一个技能包里有什么？

生活化类比：Skills 就像专家的工具箱

一句话总结

Skills 的工作原理

核心设计：渐进式加载机制

Level 1：元数据（始终加载）

Level 2：说明文档（触发时加载）

Level 3：资源与代码（按需加载）

调用逻辑：从理解意图到稳定执行

Skills vs. 其他概念的区别

什么是好的 Skills

Good Skills vs Bad Skills

案例：代码审查 Skills

好 Skills 的五大特征

如何写好 Skills：实战指南

实战案例：创建一个"Git Commit 规范" Skills

步骤 1：明确职责（原子性）

步骤 2：编写元数据

步骤 3：定义角色和流程

步骤 4：提供示例（Few-Shot）

步骤 5：添加注意事项

步骤 6：测试和迭代

社区热门 Skills 推荐

Claude 官方 Skills

官方 Skills 列表

如何选择合适的 Skills？

如何在 TRAE 里快速使用

Skills 创建

方式一：设置中直接创建

方式二：直接解析 SKILL.md

方式三：在对话中创建

Skills 使用

实践场景举例：基于飞书文档的 Spec Coding

什么是 Spec Coding？

场景分析

多角色专家 Skills

总结

Q & A | 一些常见问题

Q1: 为什么我写的 Skills 不生效？

Q2: 使用 Skills 的效果会受模型影响吗？

Q3: Skills 是不是万能的？

Q4: 我可以修改社区的 Skills 吗？

Q5: 多个 Skills 之间会不会冲突？

Q6: Skills 可以调用其他 Skills 吗？

Q7: Skills 的性能开销大吗？

Q8: 如何调试 Skills？

结语｜让 Agent 成为你真正的"行动派"

Skills 的核心价值

未来展望

行动起来

参考资源

官方文档