# 从装第一个技能到自己写一个：AI 技能（Skills）的完整上手路径

从安装、调用，到看懂 SKILL.md 的触发机制，再到写出自己第一个可用的技能

> SKILL.md · AI 智能体 · 工作流自动化 · 约 5 分钟 · 10 月 10 日

## 本篇要点

1. 技能本质是一个文件夹加一份 SKILL.md，用自然语言写明某类任务的做法，装进 AI 后按场景自动或手动调用。
2. 安装入口：豆包在「插件·技能·伙伴」→「技能」，千问办公在「扩展」→「技能」，技能文件存在 ~/.qwenworkcn/skills/。
3. 调用技能主要靠三种方式：输入 / 手动选、点「更多技能」浏览、直接描述需求让 AI 自动匹配。
4. 千问办公里 @ 是添加上下文（文件、文件夹），不是调技能；豆包里 / 和 @ 都能用于搜索技能。
5. SKILL.md 的 frontmatter 用 YAML 格式，只有 name 和 description 两个必需字段。
6. description 是技能被触发的唯一依据：AI 每次对话开始只扫 name 和 description，所以“何时使用”必须写进 description，不能放在正文。
7. 内容分三层加载：元数据始终在、正文触发后加载、scripts/references/assets 按需读取，所以正文只写核心流程，细节放 references/。
8. 自己写技能可以从“先跑通一次再让 AI 沉淀”或“对话共创”起步，再过渡到手写；正文用祈使句写操作步骤。
9. 设计要点：一个技能只干一件事，名称与文件夹名一致，写完要用匹配 description 的说法测一遍触发。
10. 豆包的本地电脑和云电脑技能默认不互通，两边都要用一般需装两遍；技能管“怎么做”，插件/连接器管数据读写。

---

豆包和千问办公（QwenWork）里的“技能”，是同一套东西：**一个文件夹，里面放一份提前写好的工作指南，让 AI 遇到某类任务时按固定步骤、固定格式来做。**

没有技能时，你每次都得把要求、格式、步骤重新交代一遍。技能把这些固化下来，之后你只说需求。这条路分四步：装一个、用起来、看懂它、自己写一个。

## 第一步：装一个现成的技能

两个产品的入口都在左侧导航：

- **豆包**：左侧「插件·技能·伙伴」→「技能」页面。里面分“豆包推荐的技能”（平台官方的）和“企业提供的技能”（管理员配置的）。找到后点右边的「安装」。
- **千问办公**：左侧「扩展」→「技能」，进入 Skill 广场，分类浏览或搜索关键词，点安装。技能实际落在 `~/.qwenworkcn/skills/` 目录下。

两边都有开箱即用的内置技能，覆盖文档、表格、PPT、设计、数据分析这些常见场景。千问办公还预装了 `find-skills`（帮你搜技能）和 `create-skill`（教你建技能）。

## 第二步：把它用起来

有三种调用方式，日常记住前两种就够：

1. **输入 `/`**：弹出已安装技能的列表，搜索选中。这是最快的手动指定方式。
2. **点「更多技能」**：入口在输入框下方，浏览着挑。
3. **直接描述需求**：不指定，让 AI 自己判断该用哪个。不确定有没有对应技能时，这种方式最好用。

这里有个容易搞混的点：**千问办公里 `@` 是添加上下文**（文件、文件夹），不是调技能；豆包里 `/` 和 `@` 都可以用来搜索技能。两家在这块行为不一致，用的时候留意一下。

## 第三步：看懂 SKILL.md

技能的关键在一个文件：`SKILL.md`。

### 先认识 YAML

`SKILL.md` 开头有一段被 `---` 包起来的内容，用的是 **YAML** 格式。你可以把它理解成一种“用 `键: 值` 一行行写配置”的格式，靠换行和缩进表示层次，不需要大括号或逗号。这段内容叫 **frontmatter**（前置元数据）。

```markdown
---
name: weekly-report
description: 把一周的工作记录整理成周报。当用户提到周报、weekly report，或要求汇总本周工作时使用。
---
```

frontmatter 里只有两个必需字段：`name`（技能名）和 `description`（描述）。

### 理解触发机制：为什么我装了技能它却没被用上

这是整套机制里最该弄明白的一点。

AI 在**每次对话开始时**，并不会读取所有技能的完整内容，只扫一遍每个技能的 `name` 和 `description`。当你的请求和某个 description 对上了，它才去读那个技能的完整正文。

所以 **`description` 是技能被触发的唯一依据**。这带来两个直接结论：

- 所有“什么时候该用我”的信息，都要写进 `description`，不能放在正文里。正文是触发之后才加载的，等 AI 读到正文时，它已经决定要用了——那时才说“何时使用”已经晚了。
- `description` 要写全触发场景，包括关键词和同义词（因为同一个人可能用不同说法描述同一件事）。既不能太宽（“处理文件”会匹配太多场景），也不能太窄（只认一种说法）。

### 分层加载：正文该写多少

顺着上面的机制，`SKILL.md` 的内容实际上分三层：

| 层 | 内容 | 什么时候加载 |
|---|---|---|
| L1 | `name` + `description` | 每次对话开始，始终在 |
| L2 | `SKILL.md` 正文 | 技能被触发后才加载 |
| L3 | `scripts/`、`references/`、`assets/` | AI 按需读取 |

因为 L2 是要占上下文的，**正文只写核心流程和路由逻辑**；详细规范、模板、示例放进 `references/`，AI 需要时才读。

一个完整技能的目录长这样，只有 `SKILL.md` 是必需的：

```
weekly-report/
├── SKILL.md          # 必需：frontmatter + 正文
├── scripts/          # 可选：给 AI 执行的脚本
├── references/       # 可选：给 AI 读的参考资料
└── assets/           # 可选：直接用在产出里的模板
```

## 第四步：自己写一个

你不用一开始就手写 YAML。有两条更平缓的路径：

**路径 A：先跑通，再沉淀。** 把一个任务手动做一遍，跑通之后对 AI 说：

```text
把刚才这个流程沉淀成一个 Skill，
包括需要我准备什么材料、你的处理规则、以及输出格式。
下次我只说 XXX 就能直接跑。
```

**路径 B：对话共创。** 豆包里点「+ 添加」→「与豆包对话新建技能」，描述技能名称、触发场景、执行指令；千问里直接说“创建一个 skill”，会触发 `create-skill` 引导你走完。

有了这两个基础，再看手写就不难了。上面那个 `weekly-report` 的正文可以这样写：

```markdown
按以下步骤生成周报：

1. 读取用户提供的本周记录。
2. 按「已完成 / 进行中 / 阻塞 / 下周计划」四块归类。
3. 每条用一句话，动词开头，不写形容词。
4. 输出 Markdown，不要额外解释。
```

正文用**祈使句**写指令，别写成散文——祈使句天然就是指令，歧义最少。

写完后，豆包可以「上传技能」导入本地文件夹（至少要包含 `SKILL.md`，开头必须有 YAML 格式的名称和描述）；千问办公在「扩展」→「技能」里点安装技能上传 `SKILL.md` 及辅助文件，也可以把 GitHub 上的技能仓库链接发给它，让它自动下载到 `~/.qwenworkcn/skills/`。

### 三个决定成败的细节

- **一个技能只干一件事。** 写“Excel 数据透视表”“PDF 表单填写”这种具体的，不要写“文档处理”。大功能拆成小技能。
- **名字和文件夹名保持一致**，用小写字母、数字和连字符。
- **写完自己测一遍**：用一个和 `description` 匹配的说法提问，看它是否自动调用；不调用，多半是 description 写窄了。

## 两个容易踩的坑

**豆包的本地电脑和云电脑，安装的技能默认不互通。** 如果某个技能两边都要用，一般得装两遍。规划任务前先想清楚这次在哪跑。

**技能和插件（连接器）不是一回事。** 技能解决“怎么做”，插件/连接器解决“数据从哪读、往哪写”。两者配合：技能负责分析执行，连接器负责取数写数。

## 术语表

- 技能（Skill）：一个文件夹加一份 SKILL.md，把某类任务的步骤、格式、注意事项提前写好，让 AI 复用。
- SKILL.md：技能的唯一必需文件，开头是 frontmatter，后面是用 Markdown 写的操作指令。
- frontmatter：SKILL.md 开头被 `---` 包起来的一段内容，用 YAML 写成，声明技能的 name 和 description。
- YAML：一种用“键: 值”一行行写配置的格式，靠换行和缩进表示层次，不用大括号或逗号。
- description：frontmatter 里的描述字段，是 AI 判断“要不要用这个技能”的唯一依据，需写清做什么、何时用。
- 分层加载：元数据每次对话都加载，正文只在触发后加载，脚本和参考文档按需读取；这是正文要写精简的原因。
- 触发：AI 根据请求与 description 是否匹配，自己决定加载哪个技能，无需用户显式指定。
- Skill 广场：千问办公内置的技能市场，汇集官方和社区贡献的技能，可分类浏览和安装。

## 来源

1. [在豆包工作中使用技能 — 豆包工作帮助中心](https://www.doubao.com/work/docs/zh-cn/articles/081010973544-skills)
2. [技能 — 千问办公（QwenWork）阿里云帮助中心](https://help.aliyun.com/zh/qwenwork/skills)
3. [Extra08 如何写出好的 Skill.md — datawhalechina/hello-agents](https://github.com/datawhalechina/hello-agents/blob/main/Extra-Chapter/Extra08-%E5%A6%82%E4%BD%95%E5%86%99%E5%87%BA%E5%A5%BD%E7%9A%84Skill.md)
4. [Agent Skills 规范（中文）](https://agentskills.zhcn.dev/specification)

---

原文：https://pangzhengboyin.com/articles/ai-skills-from-install-to-authoring-189a6c4e

> **庞征博引** · 想学的，慢慢都会
>
> 庞征博引是把想学的东西写成连载的 AI 学习工具。说出想学什么，它会先了解你的基础，再把主题写成一篇篇 5–10 分钟能读完的文章；边读边问，接下来学什么跟着你走。这篇就是这样写出来的。
>
> 开始你自己的连载 → https://pangzhengboyin.com