Agent Skill 开发指南：从原则到实践

Tiny_React
312 阅读10分钟

引言

在 AI Agent 的开发生态中，Skill 是赋予 Agent 特定能力的核心单元。一个设计良好的 Skill 能让 AI 在特定场景下高效完成任务，而糟糕的 Skill 设计则会导致 Agent 表现不稳定、资源浪费甚至完全失效。

本指南基于 Anthropic 的 Skill 创作最佳实践，为开发者提供从设计原则到具体实施的完整路径。无论你是 AI 产品经理还是技术开发者，都能从中获得实用的指导。

核心原则

简洁至上

Skill 与系统提示、对话历史共享 AI 的上下文窗口。冗长的 Skill 不仅占用宝贵的上下文空间，还会降低 AI 的响应效率。

关键策略：

  • 默认假设 AI 已经具备基础能力，只添加它不知道的专有知识

  • 避免重复解释通用概念（如"什么是 PDF"）

  • 将 SKILL.md 主体控制在 500 行以内

对比示例：

❌ 冗长版本：

首先，你需要了解 PDF 是一种便携式文档格式。然后，你需要使用 Python 的 pypdf 库。
这个库可以读取 PDF 文件。读取后，你需要提取文本...

✅ 简洁版本：

使用 pypdf 提取 PDF 文本，保留表格结构，输出为 Markdown 格式。

设置适当的自由度

不同任务需要不同程度的灵活性。自由度设置不当会导致两个极端：过于严格使 AI 无法应对变化，过于宽松则导致输出不可控。

自由度分级指南：

自由度适用场景示例任务
高多种方法都有效，需要创造性内容创作、头脑风暴、问题诊断
中有首选模式，但允许变体代码重构、报告生成、数据分析
低必须遵循特定流程金融计算、合规检查、API 调用

实践建议：

  • 对于脆弱的操作（如支付处理），使用低自由度并提供详细步骤

  • 对于启发式任务（如文案优化），使用高自由度并提供质量标准

  • 使用配置参数让用户在运行时调整自由度

跨模型测试

同一个 Skill 在不同 AI 模型上的表现可能大相径庭。Haiku 速度快但理解力弱，Opus 能力强但成本高，Sonnet 介于两者之间。

测试策略：

  • 至少在 3 种不同能力级别的模型上测试

  • 记录不同模型的成功率和失败模式

  • 对于必须跨模型使用的 Skill，指令应适用于最弱模型

Skill 结构设计

YAML Frontmatter

每个 Skill 都需要在 SKILL.md 文件顶部声明元数据：

---
name: extracting-pdf-tables
description: 从 PDF 文档中提取表格数据，转换为结构化格式（CSV/JSON），保留表头和数据关系
---

字段规范：

  • name：最多 64 字符，仅小写字母、数字和连字符，不能有 XML 标签

  • description：最多 1024 字符，描述功能和使用场景

命名约定

好的命名能让 AI 快速理解 Skill 的用途。

推荐模式：动名词形式（动词 + -ing）

  • ✅ analyzing-sales-data

  • ✅ generating-unit-tests

  • ✅ formatting-api-responses

避免的命名：

  • ❌ helper（过于通用）

  • ❌ process-data（模糊不清）

  • ❌ my-skill-v2（不专业）

编写有效的描述

描述是 AI 决定是否加载 Skill 的关键依据。

最佳实践：

  • 始终使用第三人称（"该 Skill 用于..."而非"我可以..."）

  • 包含触发关键词和使用场景

  • 说明输入输出格式

示例对比：

❌ 模糊描述：

description: 处理数据

✅ 清晰描述：

description: 从 Excel 文件中读取销售数据，按产品类别聚合，生成包含环比增长的可视化报表，适用于月度业务分析

渐进式披露模式

将复杂信息分层组织，避免一次性加载所有内容。

模式 1：概览 + 引用

## 核心工作流
1. 解析输入参数
2. 执行数据转换（详见 transform.md）
3. 生成报告（详见 reporting.md）

模式 2：领域分组

skill/
├── SKILL.md          # 主入口
├── data/
│   ├── schemas.md    # 数据结构
│   └── examples.md   # 示例数据
└── workflows/
    ├── basic.md      # 基础流程
    └── advanced.md   # 高级流程

模式 3：条件加载

如果处理 PDF 文件，参考 [PDF 特定指南](pdf-handling.md)。
如果处理 Excel 文件，参考 [Excel 特定指南](excel-handling.md)。

关键原则：

  • 保持引用层级为一层（避免嵌套引用）

  • 超过 100 行的引用文件应包含目录

  • 主 SKILL.md 作为导航中心，不是知识仓库

开发流程

工作流设计

对于多步骤任务，清晰的工作流能大幅提升成功率。

基础工作流示例：

## 数据清洗工作流

1. **验证输入**
   - 检查文件格式
   - 验证必需字段
   - 记录原始行数

2. **数据清洗**
   - 移除重复行
   - 处理缺失值（策略：数值用中位数，文本用"未知"）
   - 标准化日期格式为 ISO 8601

3. **质量检查**
   - 统计清洗后行数
   - 计算数据完整度百分比
   - 如果完整度 < 80%，警告用户

4. **输出结果**
   - 保存清洗后的数据
   - 生成数据质量报告

工作流清单（用于复杂任务）：

### 检查清单
- [ ] 已验证所有输入参数
- [ ] 已执行数据备份
- [ ] 已应用所有转换规则
- [ ] 已通过质量检查
- [ ] 已生成审计日志

反馈循环

通过"执行 → 验证 → 修正 → 重复"的循环提升输出质量。

代码质量反馈循环：

## 代码生成流程

1. 根据需求生成初始代码
2. 运行验证器：
   ```python
   # validator.py 检查：
   # - 语法错误
   # - 类型一致性
   # - 安全漏洞（SQL 注入、XSS 等）

  1. 如果验证失败，根据错误信息修正代码

  2. 重复步骤 2-3，直到通过验证或达到 3 次尝试上限

  3. 输出最终代码和验证报告


**内容创作反馈循环：**
```markdown
1. 生成初稿
2. 自我评估：
   - 是否覆盖所有要点？
   - 逻辑是否连贯？
   - 语气是否符合要求？
3. 如果评估发现问题，修订相应部分
4. 最多迭代 2 次，然后输出最佳版本

最佳实践

模板模式

为结构化输出提供明确的模板。

严格模板（低自由度）：

输出格式（严格遵守）：
{
  "status": "success|error",
  "data": {
    "total": 数字,
    "items": [...]
  },
  "timestamp": "ISO 8601 格式"
}

灵活模板（中等自由度）：

报告应包含以下部分，但可以根据数据特点调整顺序和强调重点：
- 执行摘要
- 关键发现（3-5 条）
- 详细分析
- 行动建议

示例模式

提供具体的输入输出示例，帮助 AI 理解期望。

有效示例结构：

## 示例 1：基础场景

**输入：**
```json
{
  "user_id": 12345,
  "action": "purchase",
  "amount": 99.99
}

输出：

{
  "transaction_id": "TXN-2024-001",
  "status": "completed",
  "confirmation": "感谢您的购买！订单已确认。"
}

说明：

  • transaction_id 格式为 TXN-{年份}-{序号}

  • 确认消息应包含感谢和状态


**提供 2-3 个示例，覆盖：**
- 典型场景
- 边缘情况
- 错误处理

### 条件工作流

根据不同条件引导 AI 做出决策。

```markdown
## 错误处理工作流

**步骤 1：错误分类**
- 如果是网络错误 → 转到"重试逻辑"
- 如果是权限错误 → 转到"权限检查"
- 如果是数据错误 → 转到"数据验证"

**步骤 2：重试逻辑**
1. 等待 2 秒
2. 重试请求（最多 3 次）
3. 如果仍失败，记录错误并通知用户

**步骤 3：权限检查**
1. 验证当前用户角色
2. 检查所需权限级别
3. 如果权限不足，返回友好的拒绝消息

**步骤 4：数据验证**
1. 识别无效字段
2. 生成具体的错误消息
3. 建议正确的数据格式

避免时效性信息

Skill 应该是持久有效的，而非与特定时间绑定。

❌ 容易过时：

当前最新的 API 版本是 v3.2（2024 年 1 月发布）

✅ 持久有效：

使用 API 时，检查文档确认当前版本。历史版本参考：
- v2.x：基础功能（已废弃）
- v3.x：引入异步支持（推荐）

常见陷阱

避免 Windows 风格路径

❌ 错误：

file_path = "C:\\Users\\Documents\\data.csv"

✅ 正确：

file_path = "C:/Users/Documents/data.csv"
# 或使用跨平台路径
from pathlib import Path
file_path = Path.home() / "Documents" / "data.csv"

避免提供过多选项

给 AI 太多选择反而会导致决策困难。

❌ 选项过载：

你可以：
1. 生成 CSV 格式
2. 生成 JSON 格式
3. 生成 XML 格式
4. 生成 Parquet 格式
5. 生成自定义格式（需要描述）
6. 混合多种格式...

✅ 清晰指导：

默认输出 JSON 格式。如果用户明确要求其他格式（CSV/XML），则按需转换。

避免假设工具已安装

对于依赖外部工具的 Skill，必须明确说明。

## 依赖项

此 Skill 需要以下 Python 包：
- pandas >= 1.5.0
- openpyxl >= 3.0.0（用于 Excel 支持）

在代码执行环境中，这些包已预装。如果在其他环境运行，请先安装：
```bash
pip install pandas openpyxl


## 评估与迭代

### 首先构建评估

在编写复杂 Skill 之前，先创建评估测试用例。

**评估结构示例：**
```yaml
evaluations:
  - name: basic_extraction
    input:
      file: "test_data/invoice.pdf"
      extract_fields: ["date", "amount", "vendor"]
    expected_output:
      date: "2024-01-15"
      amount: 1299.99
      vendor: "ACME Corp"
    
  - name: table_extraction
    input:
      file: "test_data/report.pdf"
      extract_table: true
    evaluation_criteria:
      - 表格行数应匹配原始文档
      - 数值列不应有格式错误
      - 表头应正确识别

  - name: error_handling
    input:
      file: "test_data/corrupted.pdf"
    expected_behavior:
      - 应返回错误消息而非崩溃
      - 错误消息应说明文件损坏原因

评估驱动开发流程

  1. 识别差距：在实际使用中发现 Skill 的不足

  2. 创建测试用例：将失败场景转化为可重现的测试

  3. 建立基线：记录当前 Skill 的表现

  4. 编写最少指令：只添加解决问题所需的最少内容

  5. 迭代改进：运行评估，根据结果调整

与 AI 协作开发

利用 AI 自身来设计和改进 Skill：

开发流程：

  1. 在没有 Skill 的情况下，与 AI 完成几次任务

  2. 观察并记录可重用的模式和提示

  3. 要求 AI 根据这些对话创建 Skill 草稿

  4. 审查简洁性和信息架构

  5. 使用新 Skill 进行真实测试

  6. 根据测试结果迭代改进

迭代提示词示例：

请基于我们过去 5 次关于数据分析的对话，创建一个 Skill。
要求：
- 识别重复出现的步骤和模式
- 保持指令简洁（主体不超过 300 行）
- 使用渐进式披露组织复杂内容
- 包含 2-3 个典型示例

有效 Skill 清单

在发布 Skill 前，使用此清单进行最终检查：

核心质量

  • 描述具体，包含关键词和使用场景

  • SKILL.md 主体在 500 行以内

  • 无时效性信息，术语一致

  • 示例具体且相关

  • 文件引用为一级深度

  • 适当使用渐进式披露

  • 工作流步骤清晰

代码和脚本（如适用）

  • 脚本有完善的错误处理

  • 所有配置值有合理说明

  • 依赖项已列出并验证

  • 使用正斜杠路径

  • 关键操作有验证步骤

  • 实施了反馈循环

测试

  • 至少创建 3 个评估测试用例

  • 在多个 AI 模型上测试

  • 在真实场景中验证

  • 收集并整合团队反馈

总结

开发高质量的 Agent Skill 是一个平衡艺术：既要提供足够的指导使 AI 准确执行任务，又要保持简洁避免浪费上下文。遵循本指南的原则，从评估驱动的开发开始，通过迭代不断改进，你将能构建出稳定、高效、可维护的 Skill 生态。

记住：最好的 Skill 是那些让 AI 感觉不到它存在的 Skill——它无缝地增强了 AI 的能力，而不是限制或混淆它。

avatar
文章
阅读
粉丝