ByteNote

本文基于 SkillsBench 团队的研究成果，介绍写好 Agent Skills 的 7 个核心原则。该研究通过 84 个任务、7,308 条轨迹、7 种模型配置的测试，揭示了 Skills 效果差异巨大的原因。

一个反直觉的发现

Anthropic 提出 Agent Skills 概念后，社区迅速积累了成千上万的 Skills。但有个问题没人系统回答过：这些 Skills 真的有用吗？

SkillsBench 团队做了件扎实的事：他们策划了 84 个任务，覆盖 11 个领域，跑了 7,308 条轨迹，测试了 7 种模型配置。结果发现——

Skills 的效果差异巨大：

好的 Skills 能让成功率提升 +51.9%
差的 Skills 会让成功率下降 -39.3%
甚至，让模型自己写 Skills 是负效果

"Models cannot reliably author the procedural knowledge they benefit from consuming."

这意味着什么？写好 Skills 是一门手艺，不是把文档丢给 Agent 就行。

原则 1：人工编写 > 模型生成

数据说话：

Skills 来源	平均效果
人工编写的 Skills	+16.2%
模型自生成的 Skills	-1.3%

让模型自己写 Skills？实验证明这是徒劳的。

为什么？ 模型可以识别"需要领域知识"，但生成的步骤往往：

太笼统（"用 pandas 处理数据"）
缺细节（没有具体 API 调用）
错重点（列出工具但不讲 workflow）

启示： Skills 需要人工提炼领域经验。不能指望 Agent 自己总结怎么做事。

原则 2：少即是多（数量）

数据：

每个任务的 Skills 数量	提升效果
1 个	+17.8%
2-3 个	+18.6% ✅
4+ 个	+5.9% ❌

反直觉： 给 Agent 更多 Skills，效果反而更差。

为什么？ 认知过载。Agent 面临选择困难，或者把不相关的 Skill 硬套到当前任务。

启示： 每个任务配套 2-3 个 Skills 最优。SkillBank 检索时应该优先返回最相关的几个，而不是罗列所有可能相关的。

原则 3：详细 > 全面（长度）

数据：

Skills 文档复杂度	效果
Detailed（详细）	+18.8%
Compact（简洁）	+17.1%
Standard（标准）	+10.1%
Comprehensive（全面）	-2.9% ❌

又一个反直觉发现： 过长的文档反而有害。

"Comprehensive" 看上去美好——覆盖所有 edge cases、详尽解释原理。但实际上：

占用宝贵的 context budget
Agent 难以从长篇中定位关键步骤
重要信息淹没在噪声里

启示： 控制 Skills 长度在 800-1500 tokens。聚焦核心步骤，细节可以放在代码示例里。

原则 4：程序性 > 陈述性

SkillsBench 明确定义了什么是 Skills：

类型	是 Skills 吗？	为什么
系统 Prompt	❌	缺乏结构化组件
Few-shot 示例	❌	陈述性，不是程序性
RAG 检索结果	❌	事实性，不是流程性
工具文档	❌	描述能力，不是指导使用
程序性指导	✅	描述"怎么做"

关键区别：

❌ "Python 是编程语言"（是什么）
✅ "用 pandas 读取 CSV 的三步流程"（怎么做）

启示： Skills 必须包含可执行的步骤、代码示例、验证检查点。

原则 5：领域差异巨大

数据（Skills 提升效果按领域）：

领域	提升效果	原因
Healthcare	+51.9%	专业流程知识模型缺乏
Manufacturing	+41.9%	特定领域 heuristics
Software Engineering	+4.5%	模型已有足够预训练知识
Mathematics	+6.0%	逻辑推理而非流程

启示：

领域知识越专、模型预训练越少，Skills 价值越大
通用编程任务写 Skills 收益有限
医疗、制造、金融等垂直领域最需要投入 Skills

原则 6：模块化与组合

SkillsBench 的 Skills 设计强调：

Task-class applicability：适用于一类任务，不是单一实例
Portability：基于文件系统，易于编辑、版本、共享
Composability：多个 Skills 可以组合使用

结构：

text

skills/
├── skill_name/
│   ├── SKILL.md          # 程序性指导（必需）
│   ├── examples/         # 示例代码
│   ├── templates/        # 可复用模板
│   └── scripts/          # 可执行脚本

启示： 设计 Skills 时考虑复用性。一个 Skill 解决一类问题，不是一次性的硬编码。

原则 7：验证与迭代

SkillsBench 的每个任务都有确定性验证器（deterministic verifier）。这不是用 LLM 评判，而是程序化断言：

python

# 示例：验证输出格式是否正确
def test_output_format():
    result = run_agent_with_skill(task, skill)
    assert result["status"] == "success"
    assert "expected_field" in result["data"]
    assert len(result["data"]["items"]) > 0

启示：

写 Skill 时必须配套验证方法
在测试任务上跑通再投入使用
成功率低于 70% 的 Skill 需要重写

模板实战：SKILL.md

基于以上 7 个原则，以下是推荐模板：

yaml

---
name: "skill_name"
description: "一句话描述这个技能解决什么问题（控制在 20 字内）"
tags: ["domain", "task_type"]
---

## 适用场景

- **什么时候用**：触发条件（2-3 个 bullet）
- **输入**：格式要求
- **输出**：期望结果
- **前提条件**：依赖/环境

## 核心步骤（3-5 步）

1. **第一步名称**

   ```python
   # 可执行的代码

关键参数说明
常见错误

第二步名称
python
```
# 可执行的代码
```
第三步名称
python
```
# 可执行的代码
```

完整示例