This commit is contained in:
@@ -0,0 +1,9 @@
|
||||
# AI
|
||||
|
||||
本章记录 AI 辅助开发相关的实践经验与工具使用指南。
|
||||
|
||||
## 文章列表
|
||||
|
||||
| 文章 | 说明 |
|
||||
|------|------|
|
||||
| [Skill 编写最佳实践](skill-best-practices.md) | 基于真实 skill 提炼的 SKILL.md 编写规范 |
|
||||
@@ -0,0 +1,351 @@
|
||||
# QwenPaw Skill 编写最佳实践
|
||||
|
||||
!!! note "本文总结了基于 todo 和 wiki 两个真实 skill 提炼出的 SKILL.md 编写规范，帮助开发者写出仅靠一份文件就能让 agent 独立运行的 skill。"
|
||||
|
||||
---
|
||||
|
||||
## 核心概念
|
||||
|
||||
1. **SKILL.md 是 agent 的唯一指令源** — agent 只读这一份文件就能完成所有操作，不依赖外部搜索
|
||||
2. **Frontmatter 是触发入口** — `name` 和 `description` 决定了 agent 何时加载这个 skill
|
||||
3. **References 是按需展开的辅助材料** — setup、模板、参考数据等不放进正文，避免上下文膨胀
|
||||
4. **可执行性优先** — 每条操作指南必须是可直接复制执行的 SQL/命令，不留占位符
|
||||
|
||||
## 详解
|
||||
|
||||
### Frontmatter 写法
|
||||
|
||||
Frontmatter 是 SKILL.md 最关键的部分。agent 通过它判断"这个 skill 是否和当前用户请求相关"。
|
||||
|
||||
```yaml
|
||||
---
|
||||
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：
|
||||
|
||||
1. **依赖什么工具**：如 `mysql_query` MCP 工具
|
||||
2. **调用方式**：通过 `execute_shell_command` 执行，还是直接使用 MCP
|
||||
3. **不可用时的降级方案**：引导用户参考 `references/setup.md` 完成配置
|
||||
|
||||
```markdown
|
||||
## 工具说明
|
||||
|
||||
本 skill 依赖 **MySQL MCP 工具** `mysql_query`。所有数据库操作都通过该工具执行。
|
||||
|
||||
调用方式：使用 `execute_shell_command` 执行 MySQL MCP 查询，或直接使用 MCP 工具（如可用）。
|
||||
|
||||
如果 MCP 工具不可用，引导用户参考 `references/setup.md` 完成配置。
|
||||
```
|
||||
|
||||
#### 表/数据结构
|
||||
|
||||
完整展示 schema，不要省略字段。agent 需要知道所有字段才能写出正确的 SQL。
|
||||
|
||||
```markdown
|
||||
## 表结构
|
||||
|
||||
\```sql
|
||||
CREATE TABLE IF NOT EXISTS todos (
|
||||
id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
|
||||
title VARCHAR(500) NOT NULL,
|
||||
...
|
||||
);
|
||||
\```
|
||||
```
|
||||
|
||||
#### 操作指南（核心）
|
||||
|
||||
每个操作包含三个要素：**触发词**、**SQL/命令**、**边界条件**。
|
||||
|
||||
```markdown
|
||||
### 添加任务
|
||||
|
||||
触发词：添加任务 / 新建待办 / 提醒我做 / 记一下
|
||||
|
||||
\```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"，而是写出来：
|
||||
|
||||
```markdown
|
||||
\```sql
|
||||
INSERT INTO todos (title, description, priority)
|
||||
VALUES ('<标题>', '<描述>', '<优先级>');
|
||||
\```
|
||||
```
|
||||
|
||||
#### 2. 自然语言到结构化数据的映射
|
||||
|
||||
明确告诉 agent 如何理解用户的口语化表达：
|
||||
|
||||
```markdown
|
||||
- 用户说"紧急/urgent/马上/ASAP" → `urgent`
|
||||
- 用户说"重要" → `high`
|
||||
- 用户说"不急/有空/low" → `low`
|
||||
```
|
||||
|
||||
#### 3. 工作流串联
|
||||
|
||||
在操作指南中明确标注操作之间的依赖关系：
|
||||
|
||||
```markdown
|
||||
- 添加后执行 LRU 检查（见下方淘汰策略）
|
||||
- 匹配多条时列出匹配项让用户确认
|
||||
- 用 `SELECT` 先查再改，避免误操作
|
||||
```
|
||||
|
||||
#### 4. 工具查找方式
|
||||
|
||||
如果 skill 有自己的脚本或模板，告诉 agent 如何定位它们：
|
||||
|
||||
```markdown
|
||||
## 工作流程
|
||||
|
||||
### 1. 查找 skill 路径
|
||||
|
||||
\```
|
||||
# 用 glob_search 找到本 skill 的位置
|
||||
glob_search(pattern="**/wiki/SKILL.md")
|
||||
\```
|
||||
|
||||
找到后，skill 目录路径为结果中 `SKILL.md` 所在的目录（去掉 `/SKILL.md` 后缀）。
|
||||
```
|
||||
|
||||
#### 5. 降级方案
|
||||
|
||||
当依赖的外部工具不可用时，告诉 agent 该怎么做：
|
||||
|
||||
```markdown
|
||||
如果 MCP 工具不可用，引导用户参考 `references/setup.md` 完成配置。
|
||||
```
|
||||
|
||||
### 交互原则
|
||||
|
||||
SKILL.md 末尾必须定义 agent 的行为边界，防止 agent 做出用户不期望的操作：
|
||||
|
||||
```markdown
|
||||
## 交互原则
|
||||
|
||||
- **模糊匹配时确认**：关键词匹配多条任务，列出选项让用户选
|
||||
- **操作前预览**：删除/归档前，先 `SELECT` 显示受影响的事项
|
||||
- **自然语言理解**：用户说"帮我记一下明天要买菜" → 添加任务"买菜"
|
||||
- **状态转换合理**：不允许 archived → in_progress 等不合理跳转
|
||||
```
|
||||
|
||||
交互原则的核心模式：
|
||||
|
||||
| 模式 | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| 确认机制 | 破坏性操作前必须确认 | 删除前先列出受影响条目 |
|
||||
| 预览机制 | 执行前展示将要发生的事 | SQL 执行前先 SELECT |
|
||||
| 合理性检查 | 拒绝不合理的状态跳转 | archived 不能直接变 in_progress |
|
||||
| 意图理解 | 从口语中提取结构化信息 | "明天要买菜" → title="买菜" |
|
||||
|
||||
### 输出格式
|
||||
|
||||
定义 agent 的展示规范，让输出风格一致：
|
||||
|
||||
```markdown
|
||||
## 输出格式
|
||||
|
||||
查询结果用表格展示：
|
||||
|
||||
| ID | 标题 | 状态 | 优先级 | 更新时间 |
|
||||
|----|------|------|--------|----------|
|
||||
| 1 | xxx | 待办 | 高 | 08-31 |
|
||||
|
||||
操作结果用简洁确认：
|
||||
- ✓ 已添加任务：XXX
|
||||
- ✓ 已完成任务：XXX
|
||||
```
|
||||
|
||||
## 常见陷阱
|
||||
|
||||
!!! warning "陷阱一：使用占位符而非完整命令"
|
||||
不要写 `INSERT INTO table (col) VALUES (?)`，agent 不知道 `?` 该填什么。写完整模板并说明参数来源。
|
||||
|
||||
!!! warning "陷阱二：依赖 agent 自己搜索"
|
||||
不要写"参考官方文档"或"搜索相关 API"。agent 的 SKILL.md 必须自包含所有必要信息。
|
||||
|
||||
!!! warning "陷阱三：description 太简略"
|
||||
只写"任务管理工具"会导致 agent 无法准确判断何时触发。必须枚举具体触发词。
|
||||
|
||||
!!! warning "陷阱四：references 目录缺失"
|
||||
安装配置、模板等辅助材料不放正文，但必须放在 references 中。否则 agent 在需要时无处可查。
|
||||
|
||||
!!! warning "陷阱五：缺少交互原则"
|
||||
不定义行为边界，agent 可能直接删除数据而不确认，或在模糊匹配时随机选择。交互原则是安全网。
|
||||
|
||||
## 两个 Skill 的设计模式对比
|
||||
|
||||
| 维度 | todo skill | wiki skill |
|
||||
|------|------------|------------|
|
||||
| 核心操作 | CRUD（SQL） | 文件操作（shell） |
|
||||
| 数据结构 | MySQL 表结构 | MkDocs 目录结构 |
|
||||
| 外部依赖 | MySQL MCP | SSH + Git |
|
||||
| references | setup.md（配置指南） | article-template.md + mkdocs-nav.md |
|
||||
| 工作流特点 | 每次操作独立 | 多步骤流水线（检查→克隆→编辑→推送） |
|
||||
| 交互原则重点 | 模糊匹配确认、操作前预览 | 章节不确定时必须询问 |
|
||||
|
||||
## 练习题
|
||||
|
||||
??? question "题目一：为一个「笔记管理」skill 设计 frontmatter"
|
||||
??? success "答案"
|
||||
```yaml
|
||||
---
|
||||
name: notes
|
||||
description: |
|
||||
笔记管理 skill。支持添加、搜索、编辑和删除 Markdown 笔记。
|
||||
当用户提到记笔记、写笔记、查找笔记、搜索笔记、
|
||||
编辑笔记、删除笔记、笔记管理时，使用此 skill。
|
||||
支持标签分类和全文搜索。
|
||||
---
|
||||
```
|
||||
|
||||
??? question "题目二：以下 SKILL.md 有哪些问题？"
|
||||
```markdown
|
||||
---
|
||||
name: mytool
|
||||
description: 一个好用的工具
|
||||
---
|
||||
# MyTool
|
||||
这个工具可以帮你做很多事情。
|
||||
需要用什么命令请参考官方文档。
|
||||
```
|
||||
??? success "答案"
|
||||
1. **name 不规范**：应使用小写 kebab-case
|
||||
2. **description 太模糊**：没有触发词，agent 不知道何时加载
|
||||
3. **正文缺乏结构**：没有工具说明、操作指南、交互原则
|
||||
4. **依赖外部搜索**：写了"参考官方文档"，agent 无法独立运行
|
||||
5. **没有 references**：没有提供任何辅助材料
|
||||
|
||||
??? question "题目三：什么时候应该把内容放 references 而不是正文？"
|
||||
??? success "答案"
|
||||
当内容满足以下任一条件时，应放 references：
|
||||
1. **按需使用**：不是每次调用都需要（如安装配置指南）
|
||||
2. **内容较长**：放正文会膨胀上下文（如模板、参考数据）
|
||||
3. **独立性强**：本身是一份完整的参考文档（如 API 文档摘要）
|
||||
|
||||
正文应该只放：核心操作指南、数据结构定义、交互原则、工具依赖说明。
|
||||
|
||||
## 相关链接
|
||||
|
||||
- [QwenPaw 官方文档](https://qwenpaw.agentscope.io/) — 框架使用指南
|
||||
- [QwenPaw GitHub](https://github.com/agentscope-ai/QwenPaw) — 源码与示例
|
||||
- [todo skill](https://github.com/agentscope-ai/QwenPaw) — 本文分析的 todo skill 示例
|
||||
- [wiki skill](https://github.com/agentscope-ai/QwenPaw) — 本文分析的 wiki skill 示例
|
||||
@@ -127,3 +127,6 @@ nav:
|
||||
- 部署与 CI/CD: qiniu-cloud/deployment-cicd.md
|
||||
- 安全·认证·数据: qiniu-cloud/security-auth-data.md
|
||||
- 简历技术要点: qiniu-cloud/resume-tech-points.md
|
||||
- AI:
|
||||
- ai/index.md
|
||||
- Skill 编写最佳实践: ai/skill-best-practices.md
|
||||
|
||||
Reference in New Issue
Block a user