Agent Skills 创建与使用最佳实践

如何从真实 expertise 出发创建高质量的 Skill——上下文优化、控制校准、有效指令模式与验证迭代。

从真实 Expertise 出发

创建 Skill 时最常见的陷阱是让 LLM 在没有提供领域专属上下文的情况下生成 Skill——仅依赖 LLM 的通用训练知识。结果通常是模糊、通用的流程（"适当处理错误"、"遵循认证最佳实践"），而不是具体的 API 模式、边界情况和项目惯例。

有效的 Skills 必须源于真实的专业经验。

从实际任务中提取

与 Agent 完成一个真实任务，在过程中提供上下文、纠正和偏好。然后将其中的可复用模式提取出来封装成 Skill。关注以下方面：

成功的步骤 — 导致成功的操作序列
你做的纠正 — 你引导 Agent 方向的地方（如"用库 X 而不是 Y"、"检查边界情况 Z"）
输入/输出格式 — 数据的输入和输出长什么样
你提供的上下文 — 项目特定的事实、惯例或约束

从现有项目产出物中合成

当你已有大量现有知识时，可以将其输入 LLM 并让它合成 Skill。从真实的事故报告和运行手册合成的数据管道 Skill，比从通用的"数据工程最佳实践"文章合成的 Skill 更有价值，因为它捕获了你的 schema、故障模式和恢复流程。

好的来源材料：

内部文档、运行手册和风格指南
API 规范、schema 和配置文件
代码审查评论和 issue tracker（捕获反复出现的关注点和审查者预期）
版本控制历史，尤其是 patch 和 fix（通过实际变更揭示模式）
真实故障案例及其解决方案

通过真实执行精炼

Skill 的初稿通常需要精炼。在真实任务上运行 Skill，然后将结果——所有结果，不仅仅是失败——反馈到创建过程中。问自己：什么触发了误报？什么被遗漏了？什么可以删除？

即使只是一轮"执行-然后修改"也能显著提升质量，复杂领域通常需要多轮。

阅读 Agent 执行追踪，而不仅仅是最终输出。如果 Agent 在无效步骤上浪费时间，常见原因包括：指令太模糊（Agent 尝试多种方法才找到有效的）、指令不适用于当前任务（Agent 还是遵循了）、或者提供了太多选项而没有明确的默认值。

智慧地使用上下文

一旦 Skill 激活，其完整的 SKILL.md 体就会加载到 Agent 的上下文窗口中，与对话历史、系统上下文和其他激活的 Skills 竞争注意力。Skill 中的每一个 token 都在与窗口中的其他内容竞争。

补充 Agent 所缺，省略 Agent 所知

聚焦于 Agent没有你的 Skill 就会做错的内容：项目特定的惯例、领域专属流程、非显而易见的边界情况、以及特定的工具或 API。你不需要解释什么是 PDF、HTTP 如何工作、或者数据库迁移是什么。

太冗长：

markdown

## Extract PDF text

PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. pdfplumber is recommended because it handles most cases well.

更好：

markdown

## Extract PDF text

Use pdfplumber for text extraction. For scanned documents, fall back to
pdf2image with pytesseract.

```python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()


对每一段内容问自己："如果没有这条指令，Agent 会做错吗？"如果答案是否，就删掉它。如果不确定，就测试它。如果 Agent 在没有该 Skill 的情况下也能完整处理任务，那么这个 Skill 可能没有增加价值。

### 设计连贯的单元

决定一个 Skill 应该覆盖什么，就像决定一个函数应该做什么一样：你希望它封装一个连贯的工作单元，能够与其他 Skills 很好地组合。

- **范围太窄**：一个任务需要多个 Skills 加载，导致开销和冲突指令
- **范围太宽**：难以精确激活，指令中包含不相关的内容

一个用于查询数据库并格式化结果的 Skill 可能是一个连贯单元，而一个同时覆盖数据库管理的 Skill 可能就想做太多了。

### 适度的详细程度

过于全面的 Skills 可能害处大于好处——Agent 难以提取相关部分，可能会追求被不适用于当前任务的指令触发的无效路径。简洁、逐步的指导配合一个工作示例，通常比究尽的文档表现更好。当你发现自己在覆盖每一个边界情况时，考虑大多数是否更适合由 Agent 自己的判断来处理。

### 用渐进式披露结构化大型 Skills

将 `SKILL.md` 保持在 500 行以内和 5,000 tokens 以下——只包含 Agent 每次运行都需要的核心指令。当一个 Skill 合法地需要更多内容时，将详细参考材料移至 `references/` 目录中的单独文件。

关键是告诉 Agent**什么时候**加载每个文件。"如果 API 返回非 200 状态码，读取 `references/api-errors.md`"比"查看 references/ 了解详情"更有用。这让 Agent 按需加载上下文，而不是一次性加载。

## 校准控制程度

不是 Skill 的每一部分都需要相同级别的规范性。将指令的具体程度与任务的脆弱性匹配。

### 匹配具体程度与脆弱性

**给 Agent 自由**，当多种方法都有效且任务容忍变化时：

```markdown
## Code review process

1. Check all database queries for SQL injection (use parameterized queries)
2. Verify authentication checks on every endpoint
3. Look for race conditions in concurrent code paths
4. Confirm error messages don't leak internal details

规范化，当操作脆弱、一致性重要或必须遵循特定序列时：

markdown

## Database migration

Run exactly this sequence:

```bash
python scripts/migrate.py --verify --backup

Do not modify the command or add additional flags.


大多数 Skills 是混合的。独立校准每一部分。

### 提供默认值，而非菜单

当多种工具或方法都可行时，选择一个默认值并简短提及替代方案，而不是将它们作为等同选项呈现。

**选项太多**：
```markdown
You can use pypdf, pdfplumber, PyMuPDF, or pdf2image...

清晰的默认值加逃生口：

markdown

Use pdfplumber for text extraction:

```python
import pdfplumber

For scanned PDFs requiring OCR, use pdf2image with pytesseract instead.


### 倾向程序而非声明

Skill 应该教会 Agent**如何解决**一类问题，而不是**对某个具体实例产生什么**。

**特定答案**（仅对此任务有用）：
```markdown
Join the `orders` table to `customers` on `customer_id`, filter where
`region = 'EMEA'`, and sum the `amount` column.

可复用方法（适用于任何分析查询）：

markdown

1. Read the schema from `references/schema.yaml` to find relevant tables
2. Join tables using the `_id` foreign key convention
3. Apply any filters from the user's request as WHERE clauses
4. Aggregate numeric columns as needed and format as a markdown table

这并不意味着 Skills 不能包含具体细节——输出格式模板、"永远不输出 PII"等约束、工具特定指令都是有价值的。关键在于方法应该通用，即使个别细节是具体的。

有效指令的模式

Gotchas 部分

许多 Skills 中最有价值的内容是 gotchas 列表——违背合理假设的环境特定事实。这不是通用建议（"适当处理错误"），而是具体的纠正，告诉 Agent 不被告知的话会犯什么错误：

markdown

## Gotchas

- The `users` table uses soft deletes. Queries must include
  `WHERE deleted_at IS NULL` or results will include deactivated accounts.
- The user ID is `user_id` in the database, `uid` in the auth service,
  and `accountId` in the billing API. All three refer to the same value.
- The `/health` endpoint returns 200 as long as the web server is running,
  even if the database connection is down. Use `/ready` to check full
  service health.

将 gotchas 放在 SKILL.md 中以便 Agent 在遇到情况之前阅读它们。当 Agent 犯了一个你必须纠正的错误时，将该纠正添加到 gotchas 部分。这是改进 Skill 迭代的最直接方式之一。

输出格式模板

当需要 Agent 以特定格式产生输出时，提供模板。这比用散文描述格式更可靠，因为 Agent 在模式匹配方面表现很好。

markdown

## Report structure

Use this template, adapting sections as needed for the specific analysis:

```markdown
# [Analysis Title]

## Executive summary
[One-paragraph overview of key findings]

## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data

## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation


短模板可以放在 `SKILL.md` 内联；较长模板或仅在某些情况下需要的模板，存储在 `assets/` 中并从 `SKILL.md` 引用，以便按需加载。

### 多步骤工作流的检查清单

明确的检查清单帮助 Agent 跟踪进度并避免跳过步骤，尤其是当步骤有依赖关系或验证门槛时。

```markdown
## Form processing workflow

1. [ ] Validate all required fields are present
2. [ ] Check field types match schema (string, number, date)
3. [ ] Run business rule validation
4. [ ] If validation fails, return error with specific field names
5. [ ] If validation passes, save to database and return success ID

验证循环

在关键步骤后插入验证检查，确保输出质量：

markdown

## Plan-validate-execute

1. Plan the approach based on the user's request
2. Validate the plan against constraints in `references/constraints.md`
3. Execute the plan
4. Verify the output matches expected format
5. If verification fails, revise and retry

捆绑可复用脚本

将复杂的逻辑封装在 scripts/ 目录中的可执行脚本里，而不是在 SKILL.md 中用自然语言描述。脚本应该：

自包含或清晰文档化依赖
包含有帮助的错误消息
优雅地处理边界情况

迭代优化流程

草稿 — 从真实任务中提取模式
测试 — 在多个真实任务上运行，记录误报和遗漏
精炼 — 删除冗余内容，添加纠正到 gotchas
验证 — 使用 skills-ref 检查格式
部署 — 提交到 Git 仓库，通过 PR 审查
监控 — 持续收集使用反馈，迭代改进

Agent Skills 创建与使用最佳实践 ​

从真实 Expertise 出发 ​

从实际任务中提取 ​

从现有项目产出物中合成 ​

通过真实执行精炼 ​

智慧地使用上下文 ​

补充 Agent 所缺，省略 Agent 所知 ​

有效指令的模式 ​

Gotchas 部分 ​

输出格式模板 ​

验证循环 ​

捆绑可复用脚本 ​

迭代优化流程 ​

延伸阅读 ​

Agent Skills 创建与使用最佳实践

从真实 Expertise 出发

从实际任务中提取

从现有项目产出物中合成

通过真实执行精炼

智慧地使用上下文

补充 Agent 所缺，省略 Agent 所知

有效指令的模式

Gotchas 部分

输出格式模板

验证循环

捆绑可复用脚本

迭代优化流程

延伸阅读