📚 编程进阶教程站

第 23 章 · 编写高质量技能 ​

本章目标：掌握 SKILL.md 正文结构惯例、description 写作技巧、资源引用规则，能独立编写一个可直接使用的生产级技能。

23.1 Description 的"好坏对比" ​

description 是整个技能最关键的字段——它直接决定 agent 是否会在正确时机加载你。官方给出的对比示例：

yaml
# 差：模糊，agent 无法判断适用时机
description: Helps with PDFs.

# 好：具体、包含触发词
description: >
  Extracts text and tables from PDF files, fills PDF forms, and merges
  multiple PDFs. Use when working with PDF documents or the user mentions
  PDF extraction, form filling, or merging.

另一个常见错误是写成功能说明书而非触发条件：

yaml
# 错误：描述功能
description: This skill parses changelog entries and validates them against git commits.

# 正确：描述触发场景
description: >
  Verify CHANGELOG.md entries match git commits since the last tag.
  Use when the user says "check changelog", "validate release notes",
  or is preparing a release.

记忆口诀

写"什么时候用我"，不要写"我能做什么"。

23.2 正文结构惯例 ​

SKILL.md 正文没有强制格式，但社区形成了四个常用小节：

markdown
---
name: my-skill
description: >
  Trigger phrase here.
---

# My Skill Name

## Setup
一次性的初始化步骤（如安装依赖、配置密钥）。

## Steps
按序执行的步骤清单，每步带具体命令或路径。

## Rules
行为约束：什么不能做、什么必须遵守。

## Examples
1–2 个典型输入输出示例，帮助 agent 理解期望行为。

Setup 节的作用 ​

Setup 用于一次性配置，不该每次运行都执行：

markdown
## Setup
1. Install dependencies: `pip install -r requirements.txt`
2. Set API key: `export MY_API_KEY=sk-xxx`

Steps 节的写法 ​

Steps 要具体到可执行，避免"分析代码"这种模糊指令：

markdown
## Steps

1. 找到上一个发布 tag：
   ```bash
   git describe --tags --abbrev=0
  1. 列出该 tag 之后的提交（git log <tag>..HEAD --oneline）， 归类为 Added / Changed / Fixed。
  2. 读取 CHANGELOG.md，检查每条已归类提交是否出现在未发布区块。
  3. 汇报：缺失条目以列表输出；全部覆盖则打印 "OK"。

## 23.3 资源引用规则

技能正文中引用外部资源时，**必须使用相对于技能目录的路径**：

```markdown
# 正确：相对路径
See [the reference guide](references/REFERENCE.md) for details.
Run `./scripts/process.sh <input>` to execute.

# 错误：绝对路径（迁移后失效）
See [/home/user/.pi/skills/my-skill/references/...](...)

官方规范要求：

"Use relative paths from the skill directory."

这意味着技能的整个目录可以整体移动或分发，引用依然有效。

23.4 完整示例：changelog-check 技能 ​

下面是一个可直接使用的完整技能：

text
~/.pi/agent/skills/changelog-check/
├── SKILL.md
└── references/
    └── format.md      # Keep-a-Changelog 格式说明

SKILL.md 内容：

markdown
---
name: changelog-check
description: >
  Verify CHANGELOG.md covers all notable changes since the last git tag.
  Use when preparing releases or the user mentions changelog.
---

# Changelog Check

## Steps

1. Find the previous release tag:
   ```bash
   git describe --tags --abbrev=0
  1. List commits since that tag and classify into Added / Changed / Fixed.
  2. Read CHANGELOG.md and check every classified commit appears in the unreleased section.
  3. Report: missing entries as a list; if complete, print "OK".

Rules ​

  • Do not modify CHANGELOG.md unless explicitly asked.
  • Ignore merge commits and chore: commits with no user impact.

References ​

See references/format.md for the expected Keep-a-Changelog format details.


## 23.5 验证与调试方法

编写技能后，如何确认它工作正常？

### 方法一：手动触发测试

```bash
# 强制加载技能并执行
/skill:changelog-check v2.1.0

方法二：观察 system prompt ​

在 agent 启动时检查 system prompt 中是否出现了你的技能 description：

bash
# Claude Code 可打开系统提示查看
# 或在会话中输入 /help 查看可用技能列表

方法三：检查加载日志 ​

大多数工具会在加载技能时输出日志，包含：

  • 技能名称
  • 是否匹配触发条件
  • 加载耗时

常见坑

技能描述写得太宽泛（如 "Helps with code"）会导致误触发——agent 在无关任务时也加载你的技能，浪费上下文。描述越具体，触发越精准。

本章小结 ​

  • description 决定触发，要写"什么时候用我"而非"我能做什么"；
  • 正文建议分 Setup / Steps / Rules / Examples 四节；
  • 资源引用必须用相对技能目录的路径；
  • 用 /skill:name 手动测试，观察 system prompt 验证加载。

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. 关于 SKILL.md 的 description 字段，以下哪种写法最符合官方建议？

2. 技能正文中引用外部资源文件时，正确的做法是？

3. 以下哪个字段缺失会导致技能被拒绝加载？

4. Skills 的"渐进披露"机制是指什么？

🛠️ 动手实践 ​

  1. 为本站的 pytest 教程编写一个 pytest-review 技能：当用户说"审查测试"时，检查测试文件是否遵循最佳实践（断言丰富、fixture 命名规范等）。
  2. 故意写一个模糊的 description（如 "Helps with testing"），观察它是否会在无关任务中被误触发。
  3. 在技能正文中添加一个 references/api.md 引用，验证相对路径加载是否正常工作。

完成练习后，进入下一章：技能生态与团队治理。