QwenPaw Skill 编写最佳实践¶

本文总结了基于 todo 和 wiki 两个真实 skill 提炼出的 SKILL.md 编写规范，帮助开发者写出仅靠一份文件就能让 agent 独立运行的 skill。

核心概念¶

SKILL.md 是 agent 的唯一指令源 — agent 只读这一份文件就能完成所有操作，不依赖外部搜索
Frontmatter 是触发入口 — name 和 description 决定了 agent 何时加载这个 skill
References 是按需展开的辅助材料 — setup、模板、参考数据等不放进正文，避免上下文膨胀
可执行性优先 — 每条操作指南必须是可直接复制执行的 SQL/命令，不留占位符

详解¶

Frontmatter 写法¶

Frontmatter 是 SKILL.md 最关键的部分。agent 通过它判断"这个 skill 是否和当前用户请求相关"。

---
name: todo
description: |
  任务待办管理 skill。通过自然语言操作 MySQL 数据库中的待办事项。
  当用户提到待办、任务管理、todo list、添加任务、查看任务、标记完成、
  清理任务、归档旧任务时，使用此 skill。
  支持增删改查和基于 LRU 策略的自动归档。
---

`name` 字段¶

使用小写 kebab-case 或纯小写：todo、wiki、file-reader
与 skill 目录名保持一致
简短，不超过 2 个单词

`description` 触发词设计¶

description 是 agent 路由决策的核心依据。写好它需要遵循以下原则：

原则	说明	反例
枚举用户可能的原话	把触发词直接写进去，而不是描述功能	~~"管理任务的工具"~~
覆盖中英文	中文用户和英文用户都可能触发	只写中文触发词
包含近义词和口语化表达	"记一下"、"提醒我"、"todo list"	只写正式术语
一句话说明核心能力	让 agent 知道这个 skill 能做什么	只列触发词不说明功能
末尾写一句话总结支撑能力	便于 agent 快速理解 scope	—

好的 description 示例：

任务待办管理 skill。通过自然语言操作 MySQL 数据库中的待办事项。
当用户提到待办、任务管理、todo list、添加任务、查看任务、标记完成、
清理任务、归档旧任务时，使用此 skill。
支持增删改查和基于 LRU 策略的自动归档。

差的 description 示例：

管理任务。  ← 太模糊，agent 不知道何时触发

正文结构¶

正文遵循固定结构，让 agent 能按顺序读取并理解整个 skill 的能力边界。

# Skill 名称

一句话概述

## 工具说明        ← 依赖什么外部工具，不可用时怎么办
## 表/数据结构     ← 数据库 schema、文件格式等
## 操作指南        ← 核心：触发词 + 可执行命令
## LRU/策略        ← 业务逻辑（如有）
## 交互原则        ← agent 的行为边界
## 输出格式        ← 展示规范

工具说明¶

必须明确告诉 agent：

依赖什么工具：如 mysql_query MCP 工具
调用方式：通过 execute_shell_command 执行，还是直接使用 MCP
不可用时的降级方案：引导用户参考 references/setup.md 完成配置

## 工具说明

本 skill 依赖 **MySQL MCP 工具** `mysql_query`。所有数据库操作都通过该工具执行。

调用方式：使用 `execute_shell_command` 执行 MySQL MCP 查询，或直接使用 MCP 工具（如可用）。

如果 MCP 工具不可用，引导用户参考 `references/setup.md` 完成配置。

表/数据结构¶

完整展示 schema，不要省略字段。agent 需要知道所有字段才能写出正确的 SQL。

## 表结构

\```sql
CREATE TABLE IF NOT EXISTS todos (
    id               BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    title            VARCHAR(500) NOT NULL,
    ...
);
\```

操作指南（核心）¶

每个操作包含三个要素：触发词、SQL/命令、边界条件。

### 添加任务

触发词：添加任务 / 新建待办 / 提醒我做 / 记一下

\```sql
INSERT INTO todos (title, description, priority)
VALUES ('<标题>', '<描述>', '<优先级>');
\```

- 优先级默认 `medium`
- 用户说"紧急/urgent/马上/ASAP" → `urgent`
- 用户说"重要" → `high`
- 添加后执行 LRU 检查（见下方淘汰策略）

关键设计点：

设计点	说明	为什么重要
列出触发词	`触发词：添加任务 / 新建待办 / 提醒我做 / 记一下`	agent 直接匹配用户意图
可复制的 SQL	不用 `<placeholder>` 填参数，而是写清参数含义	agent 知道该填什么
参数映射规则	明确自然语言到字段值的映射	agent 说"紧急"时知道映射为 `urgent`
边界条件	列出每种操作的限制和特殊情况	避免 agent 做出不合理操作
关联操作	指向其他操作（如"见下方淘汰策略"）	agent 能自动串联操作流

References 目录组织¶

References 用于存放按需展开的辅助材料，避免 SKILL.md 正文过长。

skills/todo/
├── SKILL.md              ← agent 始终加载
└── references/
    └── setup.md          ← 仅在需要配置时读取

skills/wiki/
├── SKILL.md
└── references/
    ├── article-template.md   ← 写文档时参考
    └── mkdocs-nav.md         ← 更新导航时参考

什么内容放 references¶

放 references	放 SKILL.md 正文
安装配置指南（setup）	核心操作指南
模板和格式规范	数据结构定义
参考数据（如现有目录结构）	交互原则
第三方文档摘要	工具依赖说明

references 文件的命名¶

使用 kebab-case：setup.md、article-template.md、mkdocs-nav.md
文件名应直观表达内容
一个文件聚焦一个主题

让 Agent 仅看 SKILL.md 就能运行¶

以下是确保 agent 不需要额外搜索就能独立运行的关键设计：

1. 自包含的命令模板¶

每个操作指南必须包含完整的、可直接执行的 SQL/命令。不要写"根据需要构造 SQL"，而是写出来：

\```sql
INSERT INTO todos (title, description, priority)
VALUES ('<标题>', '<描述>', '<优先级>');
\```

2. 自然语言到结构化数据的映射¶

明确告诉 agent 如何理解用户的口语化表达：

- 用户说"紧急/urgent/马上/ASAP" → `urgent`
- 用户说"重要" → `high`
- 用户说"不急/有空/low" → `low`

3. 工作流串联¶

在操作指南中明确标注操作之间的依赖关系：

- 添加后执行 LRU 检查（见下方淘汰策略）
- 匹配多条时列出匹配项让用户确认
- 用 `SELECT` 先查再改，避免误操作

4. 工具查找方式¶

如果 skill 有自己的脚本或模板，告诉 agent 如何定位它们：

## 工作流程

### 1. 查找 skill 路径

\```
# 用 glob_search 找到本 skill 的位置
glob_search(pattern="**/wiki/SKILL.md")
\```

找到后，skill 目录路径为结果中 `SKILL.md` 所在的目录（去掉 `/SKILL.md` 后缀）。

5. 降级方案¶

当依赖的外部工具不可用时，告诉 agent 该怎么做：

如果 MCP 工具不可用，引导用户参考 `references/setup.md` 完成配置。

交互原则¶

SKILL.md 末尾必须定义 agent 的行为边界，防止 agent 做出用户不期望的操作：

## 交互原则

- **模糊匹配时确认**：关键词匹配多条任务，列出选项让用户选
- **操作前预览**：删除/归档前，先 `SELECT` 显示受影响的事项
- **自然语言理解**：用户说"帮我记一下明天要买菜" → 添加任务"买菜"
- **状态转换合理**：不允许 archived → in_progress 等不合理跳转

交互原则的核心模式：

模式	说明	示例
确认机制	破坏性操作前必须确认	删除前先列出受影响条目
预览机制	执行前展示将要发生的事	SQL 执行前先 SELECT
合理性检查	拒绝不合理的状态跳转	archived 不能直接变 in_progress
意图理解	从口语中提取结构化信息	"明天要买菜" → title="买菜"

输出格式¶

定义 agent 的展示规范，让输出风格一致：

## 输出格式

查询结果用表格展示：

| ID | 标题 | 状态 | 优先级 | 更新时间 |
|----|------|------|--------|----------|
| 1  | xxx  | 待办 | 高     | 08-31    |

操作结果用简洁确认：
- ✓ 已添加任务：XXX
- ✓ 已完成任务：XXX

常见陷阱¶

陷阱一：使用占位符而非完整命令

不要写 INSERT INTO table (col) VALUES (?)，agent 不知道 ? 该填什么。写完整模板并说明参数来源。

陷阱二：依赖 agent 自己搜索

不要写"参考官方文档"或"搜索相关 API"。agent 的 SKILL.md 必须自包含所有必要信息。

陷阱三：description 太简略

只写"任务管理工具"会导致 agent 无法准确判断何时触发。必须枚举具体触发词。

陷阱四：references 目录缺失

安装配置、模板等辅助材料不放正文，但必须放在 references 中。否则 agent 在需要时无处可查。

陷阱五：缺少交互原则

不定义行为边界，agent 可能直接删除数据而不确认，或在模糊匹配时随机选择。交互原则是安全网。

两个 Skill 的设计模式对比¶

维度	todo skill	wiki skill
核心操作	CRUD（SQL）	文件操作（shell）
数据结构	MySQL 表结构	MkDocs 目录结构
外部依赖	MySQL MCP	SSH + Git
references	setup.md（配置指南）	article-template.md + mkdocs-nav.md
工作流特点	每次操作独立	多步骤流水线（检查→克隆→编辑→推送）
交互原则重点	模糊匹配确认、操作前预览	章节不确定时必须询问

练习题¶

题目一：为一个「笔记管理」skill 设计 frontmatter

答案

---
name: notes
description: |
  笔记管理 skill。支持添加、搜索、编辑和删除 Markdown 笔记。
  当用户提到记笔记、写笔记、查找笔记、搜索笔记、
  编辑笔记、删除笔记、笔记管理时，使用此 skill。
  支持标签分类和全文搜索。
---

题目二：以下 SKILL.md 有哪些问题？

---
name: mytool
description: 一个好用的工具
---
# MyTool
这个工具可以帮你做很多事情。
需要用什么命令请参考官方文档。

答案

name 不规范：应使用小写 kebab-case
description 太模糊：没有触发词，agent 不知道何时加载
正文缺乏结构：没有工具说明、操作指南、交互原则
依赖外部搜索：写了"参考官方文档"，agent 无法独立运行
没有 references：没有提供任何辅助材料

题目三：什么时候应该把内容放 references 而不是正文？

答案

当内容满足以下任一条件时，应放 references： 1. 按需使用：不是每次调用都需要（如安装配置指南） 2. 内容较长：放正文会膨胀上下文（如模板、参考数据） 3. 独立性强：本身是一份完整的参考文档（如 API 文档摘要）

正文应该只放：核心操作指南、数据结构定义、交互原则、工具依赖说明。

QwenPaw Skill 编写最佳实践¶

核心概念¶

详解¶

Frontmatter 写法¶

name 字段¶

description 触发词设计¶

正文结构¶

工具说明¶

表/数据结构¶

操作指南（核心）¶

References 目录组织¶

什么内容放 references¶

references 文件的命名¶

让 Agent 仅看 SKILL.md 就能运行¶

1. 自包含的命令模板¶

2. 自然语言到结构化数据的映射¶

3. 工作流串联¶

4. 工具查找方式¶

5. 降级方案¶

交互原则¶

输出格式¶

常见陷阱¶

两个 Skill 的设计模式对比¶

练习题¶

相关链接¶

`name` 字段¶

`description` 触发词设计¶