揭秘Skill：让 AI 成为你的专业助手

前言

你是否想过，为什么有些 AI 能画架构图，有些能操作 Excel，有些能搜索股票？ 秘密就藏在 Skill（技能） 里。今天，让我们一起揭开 Skill 的神秘面纱。

一、我们为什么需要 Skill？

想象一下，你请了一位全能助手，但当你需要他画架构图时，他需要先从头开始学习如何绘制、使用什么工具、遵循什么规范。如果每次都要从零开始学习，那么显然效率会很低。

Skill 就是解决这个问题的，它让 AI 提前"学会"某项专业技能，并在需要时自动调用。

二、什么是 Skill？

Skill（技能） 是一个"知识包"，它告诉 AI 四件事：

• 什么时候用 通过触发词，系统知道何时自动激活这个技能
• 怎么做 详细的指令和步骤，告诉 AI 具体执行方式
• 用什么工具 声明可以调用哪些功能和工具
• 参考资料 模板、示例、规范，确保输出质量

简单来说，Skill = AI 的专业培训手册 + 工具箱。

三、Skill 的组成：解剖一个完整的 Skill

让我们看看一个典型的 Skill 目录结构：

~/.workbuddy/skills/my-skill/
├── SKILL.md
# 核心文件（必需）
├── references/
# 参考文档目录
│   ├── guide.md
# 详细指南
│   └── examples.md
# 示例代码
├── scripts/
# 辅助脚本目录（可选）
│   └── process.py
# 数据处理脚本
└── assets/
# 资源文件目录（可选）
    └── template.svg 
# 图表模板

1. SKILL.md — 核心文件（必需）

这是 Skill 的大脑，包含两部分：

1.1 YAML Frontmatter（元数据）：

---
name: diagram-builder
description: "专业架构图与流程图绘制 skill。触发关键词：架构图、流程图..."
agent_created: true
---

• nameSkill 名称，用于 @skill:name 调用
• description至关重要！ 系统通过这里的关键词判断何时自动触发这个 Skill
• agent_created标记这是 AI 创建的 Skill，允许后续自动更新

1.2 Markdown 指令（工作手册）：

## 概述
本 skill 提供两种图表绘制方式：
1. 内联可视化（推荐）：调用 read_me + show_widget 工具
2. Mermaid 代码块：输出 Mermaid 语法

## 操作步骤
1. 先调用 read_me，加载 diagram 模块
2. 再调用 show_widget，传入 SVG 代码
...

这部分就是 AI 的"工作手册"，告诉它什么时候做什么、用什么工具、遵循什么规范、如何处理异常。

2. references/ — 参考文档（可选）

存放参考文档的目录，类似"知识库"。提供标准化模板确保输出一致性，设计规范与语法参考，以及最佳实践示例。

为什么要有这个目录？主要有以下三点原因：

• 解耦知识与实践：SKILL.md 定义"怎么做"，references/ 提供"参考资料"
• 易于维护：更新模板时，只需修改 reference 文件，无需改动核心指令
• 可扩展：未来可以添加新的参考文档

3. scripts/ — 辅助脚本（可选）

存放 Python、Shell 等可执行脚本。适用于需要复杂计算（坐标运算、数据统计）、调用外部程序、批量处理文件的场景。

4. assets/ — 资源文件（可选）

存放图片模板、图标库、预设配色方案等二进制资源。

四、Skill 的工作原理：从输入到输出

image

下面是 Skill 的完整工作流程：

1. 第1步：用户输入 — 输入 @skill:diagram-builder 画一个架构图，或直接说"画一个架构图"
2. 第2步：触发词检测 — 系统扫描你的输入，在所有 Skill 的 description 字段中搜索匹配关键词
3. 第3步：加载 SKILL.md — 匹配到 Skill 后，读取对应的 SKILL.md 文件
4. 第4步：解析 YAML Frontmatter — 解析文件头部元数据，获取 Skill 名称、描述等
5. 第5步：注入指令到 AI 上下文 — 将 SKILL.md 内容注入 AI 的"工作记忆"，从此刻起 AI 就"学会"了这个 Skill
6. 第6步：AI 执行指令 — AI 按 SKILL.md 中的指令逐步工作：加载设计规范 → 设计布局 → 生成代码
7. 第7步：调用工具 — AI 调用 show_widget 等工具，将内容渲染为可视化图表
8. 第8步：输出结果 — 图表渲染完成，展示给用户
9. 第9步：迭代优化（可选） — 用户反馈后，AI 重新计算调整，再次输出优化结果

五、Skill 系统架构：5 层结构

让我们从更高的视角，看看 Skill 系统的整体架构。（PS下面的架构图就是通过workBuddy创建的一个架构图绘制skill，并进行了对布局、样式、颜色等多轮调优-https://skillhub.cn/skills/diagram-builder）

image

第1层：用户界面层

• 接收你的输入（文本或 @skill 指令）
• 触发词检测器扫描输入，匹配对应的 Skill

第2层：Skill 引擎层

• Skill 加载器：读取 ~/.workbuddy/skills/ 目录下的 SKILL.md 文件
• YAML 解析器：解析文件头部的 YAML frontmatter
• 触发词匹配器：在你的输入和 Skill 的 description 字段之间进行关键词匹配

第3层：AI 执行层

• 上下文注入器：将 SKILL.md 的内容注入到 AI 的上下文中
• 指令执行器：AI 按照注入的指令，逐步执行任务

第4层：工具调用层 AI 可以调用各种工具来完成任务：

• read_me：加载设计系统模块
• show_widget：渲染可视化图表
• Bash：执行 Shell 命令
• Write/Edit：读写文件
• WebFetch：获取网页内容

第5层：存储层 所有 Skill 都存储在 ~/.workbuddy/skills/ 目录下：

• SKILL.md：核心指令文件
• references/：参考文档
• scripts/：辅助脚本
• assets/：资源文件

六、如何使用 Skill？

6.1 自动触发（推荐）

只需在输入中包含触发词，系统就会自动加载：

你：画一个架构图
你：生成一个流程图
你：帮我处理这个 Excel 文件

6.2 手动指定

我们也可以明确指定某个 Skill，使用 @skill: 语法：

你：@skill:diagram-builder 画一个微服务架构图
你：@skill:xlsx 分析这个 Excel 文件
你：@skill:pdf 合并这两个 PDF

6.3 查看可用 Skill

查看已安装的 Skill

你：/skills

七、如何从零创建一个 Skill？

今天我们通过一个完整的示例，学习如何通过使用WorkBuddy，从零开始创建一个属于你自己的Skill。

7.1 使用 skill-creator 创建（推荐）

在对话框中使用向导创建：

你：@skill:skill-creator 帮我创建一个能生成项目报告的 Skill

系统会引导你完成：输入名称 → 编写描述 → 编写指令 → （可选）添加参考文档 → （可选）添加辅助脚本。

7.2 手动创建 Skill

你也可以从零开始手动创建，步骤如下：

第1步：创建目录

mkdir -p ~/.workbuddy/skills/my-skill/references
mkdir -p ~/.workbuddy/skills/my-skill/scripts
mkdir -p ~/.workbuddy/skills/my-skill/assets

第2步：编写 SKILL.md

---
name: my-skill
description: "你的 Skill 描述。触发词：关键词1、关键词2"
agent_created: true
---

# my-skill — Skill 标题

## 概述
简要说明这个 Skill 的用途。

## 使用方式
详细描述如何使用这个 Skill。

## 注意事项
列出需要注意的事项。

7.3 打包和分享

cd ~/.workbuddy/skills/
zip -r my-skill.zip my-skill/

其他人解压到 ~/.workbuddy/skills/ 即可使用。

八、如何优化 Skill？

Skill 不是一次性的，需要持续迭代优化。

8.1 常见问题

• 触发不准确该触发时没触发，或不该触发时触发了
• 输出不符合预期格式不对、内容不完整
• 缺少功能有些场景没覆盖到

8.2 优化 description

好的 description示例：

description: "专业架构图与流程图绘制。支持微服务架构、网络拓扑、业务流程图、数据流图、时序图、状态机、ER图等。触发关键词：架构图、流程图、时序图、状态机、diagram、flowchart、architecture。"

不好的 description示例：

description: "画图工具"

以上两个示例的好坏是显然的，从中我们可以总结出一些原则：功能描述必须足够详细（但不是冗长）、列出中英文触发词、说明使用的工具。

8.3 让 AI 自动优化skill

你知道吗？AI 可以自己优化 Skill。当你发现问题时，只需告诉 AI你的优化思路和方向即可，例如：

你：这个 Skill 的触发不准确，经常误触发。请优化 description。

AI 会自动：读取当前 SKILL.md → 分析问题 → 修改 description → 保存更新。这就是 agent_created: true 的作用——允许 AI 自动更新 Skill。

九、skill最佳实践

• 清晰的 description详细描述功能，列出中英文触发词，说明使用的工具
• 简洁的 SKILL.md清晰标题和分段，给出具体步骤，避免模糊表述
• 充分利用 references/模板和示例放在 references/，SKILL.md 专注于"怎么做"
• 测试边界条件测试各种输入，确保 Skill 正确处理或用错误处理兜底

十、总结与展望

Skill 是 WorkBuddy 的核心能力之一，它让 AI 从"通用聊天助手"变成"专业领域专家"。

通过本文，你应该已经了解：

• ✅ 什么是 Skill — AI 的专业培训手册 + 工具箱
• ✅ Skill 的组成 — SKILL.md（必需）+ references/ + scripts/ + assets/
• ✅ 工作原理 — 触发 → 加载 → 注入 → 执行 → 输出
• ✅ 如何使用 — 自动触发 或 手动指定
• ✅ 如何创建 — 使用 skill-creator 或手动创建
• ✅ 如何优化 — 优化 description、优化指令、让 AI 自动更新

随着 Skill 生态的发展，我们可以期待：Skill 市场、更多官方 Skill、多 Skill 协同。