为什么 Python 之禅在 Agent Skills 里是错的
Perplexity 的前沿智能体产品建立在模块化 Agent Skills 的知识与领域专业知识基础之上。我们维护着一个跨技术环境的精选 Skills 库。这些 Skills 包括驱动 Perplexity Computer 的通用工具、在金融、法律、医疗等垂直领域的能力，以及满足用户需求的超长尾模块。一些 Skills 很少被调用，但调用时至关重要。为确保用户体验始终如一地出色，Perplexity 的 Agents 团队将 Skill 质量置于与代码质量同等重要的位置。
开发高质量 Skill 所需要的直觉和最佳实践，与传统软件开发截然不同。Agents 团队审查许多工程师在工作中开发的 Pull Request。结果几乎总是大量的评论和修订建议。这是因为许多编写代码的有用模式在 Skill 创建中变成了反模式。
例如，如果你取 PEP20（Python 之禅）中的某些格言，很快就会发现编写好的 Python 代码与编写好的 Skills 截然不同。在这 20 行智慧中，至少有一半在编写 Skills 时完全错误或具有误导性。以下是其中的五条：
| |
|---|
| Skill 是一个文件夹，而非文件。复杂性即是功能。 |
| |
| |
| Gotchas 才是特殊情形（它们是最高价值的内容）。 |
| |
本文档是 Perplexity 工程师在开发和审查 Skills 时使用的指南。我们也公开发布此指南，以便我们的发现和学习成果能惠及更广泛的社区。无论你是日常工作中设计生产 Skills 的工程师、希望在自己最熟悉的领域开发自己 Skill 的 Computer 用户，还是两者兼有，本指南都适合你。
什么是 Skill？
当你编写一个 Skill 时，你不是在编写普通的软件（尽管 Skills 现在是智能体系统的主要逻辑引擎的一部分）。相反，你是在为模型及其环境构建上下文。Skill 有不同的约束和不同的设计原则。如果你像写代码一样写 Skill，你会失败。
一个 Skill 至少是以下四样东西，尤其是在 Perplexity 的构建背景下。
Skill 是一个目录
Skill 不仅仅是一个单一的 SKILL.md 文件。在许多情况下，一个 Skill 包含多个文件。在以你的 Skill 命名的目录下，你可能有：
这种中心-辐射模式允许你保持 Skills 非常专注和紧凑，人们可以用非常有创意的方式使用文件夹结构。有时，特别是复杂的 Skills 会受益于多层次层级结构，以帮助模型更好地导航。假设一个 Skill 需要跨 300 个主题的知识，可分为 20 个主题领域。在 300 个主题中可靠地选择正确主题，即使对于当今最好的前沿模型也是一个未解决的挑战。相比在 15 个主题中选择，模型更容易在 20 个领域之一中定位。
作为多级层级结构提供价值的一个例子，我们的团队在过去的税收季节在使用 Computer 驱动的美国所得税功能 Skills 中采用了三层主题嵌套。由于税法的复杂性，这种层级结构绝对是不可或缺的：在早期测试中，向模型呈现一个包含美国《国内收入法典》全部 1945 条的单一文件夹，导致性能比完全不加载 Skill 还要差。将信息组织成逻辑细分对于确保高精度读取操作是不可或缺的。
然而，这种层级结构并非免费的。增加层级需要增加信息架构的策划水平以管理产生的间接寻址。我们设计了快速参考指南、自定义搜索工具和其他工具，以支持模型以最小的间接寻址定位信息。在这种情况下，做艰苦的策划工作最终产生了积极的结果：一个允许模型执行税收相关任务的 Skill，比单独使用通用工具要能力强得多。
核心要点：复杂信息需要多级层级结构来帮助模型精确定位，而非简单堆砌。
Skill 是一种格式
Skill 是一种格式。核心根 SKILL.md 文件必须同时具有名称和描述。此外，Skill 必须与 Skill 所在的目录名精确映射。名称必须全部小写字符，不能有空格，可以使用连字符。描述是路由触发器。这是一个常见的失败点：描述不是 Skill 功能的内部文档。它相当于给模型的指令，告知何时加载 Skill。所以，你经常会看到"Load when"，而不是"This Skill does"。这很重要，因为大多数实现在将描述注入模型上下文时就是这样做的。
在前言中，还有"depends:"，允许你创建层级 Skill 依赖关系，以及"metadata:"，用于审查和评估。不同的智能体系统甚至可以定义自己的前言字段，以特定于这些系统的方式使用。作为替代方案，Skill 特定的元数据可以打包在辅助的 JSON 或 YAML 配置文件中。当构建需要促进每个 Skill 不同运行时行为的智能体系统而不污染模型上下文时，这是可取的。最后，可以通过在读取时剥离 Skill 前言来实现类似行为。Computer 采用这种方法，允许配置保存在根 SKILL.md 文件中。解析逻辑需要仔细注意细节，如果某些字段在模型上下文中很有用，你可能希望实现条件性剥离。
注意事项：描述（Description）是路由触发器，不是文档。"Load when..."而非"This Skill does"。
Skill 是可调用的
Skill 是可调用的。智能体在运行时加载 Skill。重要的是，Skills 并非总是捆绑到上下文中。默认情况下，大多数智能体系统在特定需要时逐步展开 Skills。
在我们实现的 Computer 中，上下文成本至少有三个层级。以下是过程：
- Computer 调用
load_skill(name="...") - Computer 将 Skill 目录复制到隔离的执行沙箱
- Computer 递归自动加载"depends:"标签中的依赖
- Computer 然后剥离前言，智能体因此只看到正文和其他文件
不同的智能体系统可以选择以不同方式暴露 Skill 内容。例如，某些系统可能选择完全不暴露文件层级，让模型通过文件系统操作发现层级。其他系统可能选择给模型一个完整的文件树映射，截断到某个截断点和/或深度限制。为了保持上下文清洁，Computer 从调用上下文中省略完整的文件层级；但是，这可以通过每个 Skill 覆盖。
Skill 是渐进式的
Skills 是渐进式的。在 Computer 中，有三个不同层级的上下文成本，我们在不同阶段承担所有这三个成本：
| | | |
|---|
| 每个非隐藏 Skill 的 name: description | | |
| | | |
| scripts/、references/、assets/、subskills、FORMATTING.md、SPECIAL_CASES.md 中的文件 | | |
Computer 构建一个 Skill 索引，其中包含每个可用 Skill 的名称和描述。预算非常紧张，因为你在每个会话中为每个用户支付此费用。这在对话开始时注入到系统提示中。模型可以访问一堆命名的 Skills 和描述，以便决定是否调用"load_skill()"。进入此索引的门槛极高。你的 Skill 需要非常有用，而且描述需要非常密集和简洁，因为每个人一直都在为此支付费用。
在智能体系统加载 Skill 后，是完整的 SKILL.md 正文。正文文本最好不要超过 5000 个 Token。即使如此，你也希望每个句子都很重要，因为一旦你加载了 Skill，对话剩余部分必须支付该成本直到你达到压缩边界。许多线程加载三到五个不同的 Skills，倍增了这个成本。有很多冗余内容的 Skills 几乎肯定会降低其他 Skills 以及整体智能体能力。简而言之，如果你的 Skill 加载后没有做正确的事情，那就是浪费上下文。
最后的渐进层级是脚本或特殊案例，如 subskills 或 formatting。这是你想要放置无界条件分支逻辑的地方。智能体只在需要时使用它，这意味着你放入这里的门槛要低得多。
核心要点：索引层级每个 Token 都重要；加载层级更宽松；运行时层级最宽松，可为零到无限。
何时需要 Skill？
Agents 团队经常被问到在给定领域或用例中是否真正需要 Skill。我们很少能从第一性原理得到确定的答案。真正找出答案的唯一方法是先从没有 Skill 的智能体开始，运行几个关键查询，然后确定智能体是否做得好。
需要 Skill 的场景
有许多任务在训练模型中是分布内的。只有当你希望以某种特定方式改变行为，而无法用提示中的一句话来改变时，才需要应用 Skill。所以，当智能体没有特殊上下文会出错时，或者如果你需要跨运行非常一致但存在一些不一致性或非确定性的情况时，你需要 Skill。
可能是你的知识是持久的但不在训练数据中。可能存在截止日期或企业特定的工作流程，或者可能是品味问题。例如，我们在 Computer 中有一些由 Henry Modisett（我们的设计主管）编写的与设计相关的 Skills。这些 Skills 中每个 Token 都存在的原因是因为 Henry 在设计网站和 PDF 方面有很好的品味。Henry 指定使用哪些字体和不使用哪些字体，这些字体的感觉如何，以及模型无法从训练数据中学习的其他判断事项。
不需要 Skill 的场景
我们看到许多 Skills 中工程师编写了一系列需要按顺序执行的 git 命令。这是不必要的，因为模型已经知道如何做，这意味着它是很棒的文档但不是好的 Skill。
我们看到 Skills 重述系统提示中的指令。你不需要为此使用 Skill。与大多数请求相关的知识应该包含在全局上下文中，而非条件加载的 Skill 中。
如果有些东西变化得比你维护它的速度还快，你不需要 Skill。例如，如果你正在访问某个远程 MCP 端点及其工具或这些工具的版本变化频繁，你不应该将这些注入到 Skill 中。如果你这样做，最终只会产生漂移，模型会犯错误。
核心要点：每个 Skill 都是一种税。每个会话、每个用户都在支付 Token 成本。
如何构建 Skill？
换句话说，你需要在编写的任何 Skill 中注入你的观点。遵循这些步骤。
步骤 0：编写评估
首先编写一些评估。你可以从以下来源获取评估案例：
- 邻居混淆：接近你的领域边界但路由到另一个 Skill
至少，你应该确保正在测试 Skill 是否在需要时加载。理想情况下，你可以从生产环境采样一些。你也可以考虑已知错误案例：也许你着手编写 Skill 的整个原因是因为你注意到的一个特定失败，或者你正在重构，并且有两个紧密相关的领域被一个 Skill 覆盖时存在一些混淆。
从类似的负面和正面例子开始。负面例子非常强大，可能比正面例子更重要。
核心要点：负面例子极其强大，可能比正面例子更重要。
步骤 1：编写描述
这是 Skill 中最难写的一行。它是路由触发器，不是文档。要正确获取名称和描述，你不关心 Skill 的内容。你只关心 Skill 是否在正确的时机加载并注入且没有偏离目标的副作用，这是头号失败模式。每次添加额外的 Skill，你都冒着让每个其他 Skill 变差一点的风险，所以你需要确保最小化回归。
同样，不好的描述描述了 Skill 做什么或为什么有用。好的描述说明智能体何时应该加载 Skill。例如，假设你有一个用于监控 Pull Request 的东西。不要写 Skill 做什么。当工程师们感到沮丧并希望你确保他们的 PR 正常工作时，他们会说什么，比如"babysit"或"watch CI"或"make sure this lands"。
快速检查清单：
真实查询是你可以用 80-20 覆盖的内容。通常两三个例子效果很好。恰好添加不多不少的内容并不容易。
步骤 2：编写正文
接下来，编写 Skill 本身的内容。注意这不是步骤 0 或步骤 1。
向 LLM 传达工作流程与向同事传达工作流程完全不同，甚至与向运行时系统传达也不同。学习新软件工具时，工程师可能需要阅读文档，从有经验的人那里获得演练，并学习如何使用工具。同时，对于至少存在一年的几乎任何软件工具，你只需要提它的名称，LLM 就有你需要的所有信息。
在编写正文时，跳过明显的事情。许多工程师在编写列出某人需要运行的每个命令的 README.md 方面有很多经验。当编写 Skill 时，很容易退回到那种感觉，因为感觉像是在写文档，但如果你这样做，你的 Skill 将是垃圾。所以，不要写出一系列命令。
例如，你不需要写：git log # find the commit; git checkout main; git checkout -b <clean-branch>; git cherry-pick <commit>;
而是写："Cherry-pick the commit onto a clean branch. Resolve conflicts preserving intent. If it can't land cleanly, explain why."
后者会让模型做得更好，而不是前者过度规定的一系列命令，尤其是在出问题的时候。不要铁路化或过度规定，这是脆弱的，而是在多种方法可以工作的地方保持灵活。同样，对人类好的文档通常对模型是坏的文档。
接下来，专注于 gotchas 或负面例子。这些是极其高信号的内容，因为它们经常指导模型不要做什么。如果你每次在智能体绊倒时添加一行，你将通过运行它学习，gotchas 将有机地增长。
最后，如果有条件性的或内容极重的部分，把它从作为中心的 SKILL.md 中拿出来，放到辐射文件之一中。把它放进一个可以渐进加载的辅助文件中，我们接下来会深入探讨。
步骤 3：使用层级结构
当你有脚本、引用或使用某些特定工具时，利用 Skill 层级结构：
scripts/：智能体每次运行都会重新发明的确定性逻辑。给它要组合的代码，而非重建。references/：仅在满足条件时加载的重文档。"如果 API 返回非 200，请阅读 api-errors.md"。assets/：智能体复制和填充的输出模板。report-template.md、输出模式。config.json：首次运行的用户设置。询问 Slack 频道，保存，下次重用。
对于任何条件性或从主 Skill 分支的内容，将其拆分到一个文件夹中。同样，对于特别复杂的 Skills，你还需要仔细考虑功能应该作为单个 Skill 实现还是作为 Skill 集合（可能具有基于 depends: 的加载关系）。
步骤 4：迭代
接下来，在分支上做大量迭代。在主分支上从没有 Skill 开始，做一些迭代，建立你的关键查询集，并运行一堆评估。任何审查你 Skill 代码的人都会感谢你提交一个包含评估集的单一变更集。审查连续的增量更改（新的 gotcha 除外）非常困难，所以尽量最小化它。
你可能会做很多小的词汇更改。描述中的小词汇更改可以对路由产生巨大影响（包括对其他 Skills 的溢出效应），所以在步骤 5 之前完成所有这些工作。
步骤 5：发布
发布它。
如何维护 Skill？
现在你已经编写了一个 Skill，你必须维护它。
Gotchas 飞轮
从这个角度来看，你的 gotchas 列表往往会大幅增长或变化。我们经常看到工程师做未评估的 PR，例如，更改描述。如果你在你的 Skill 合并后更改描述，你就偏离了轨道。如果你更改决定路由 Skill 的东西，你需要写一些支持更改的评估。
Skills 几乎是仅追加的。Gotchas 部分随时间累积最多价值：
- 智能体偏离目标加载 Skill → 收紧描述并添加负面评估
- 智能体应该在应该加载时未加载 → 添加关键词和正面评估
在内部测试或生产中注意到单个失败案例并添加 gotcha 是很容易的。这是一个负面例子，所以它真的不是更改显式指导，而是让模型知道，"嘿，有这个已知的失败。"
当你从 80-20 发展到达到 99.9% 或 99.99% 的成功率时，扩展这个 gotcha 列表很容易。当你看到这些负面例子时，你应该主要追加到 gotcha 部分。你不应该添加更长的指令或更改描述。
评估套件
在 Perplexity，我们运行许多评估套件来检查不同的事情。有 Skill 加载和 Skill 文件读取，检查 Skill 加载本身的精确率、召回率和禁止检查。智能体会在应该路由到你的 Skill 时路由吗？这些确保新 Skills 不会破坏现有边界。
还有评估可以检查适当的渐进加载。智能体可能加载了 Skill，但它是否读取了辅助文件？例如，如果你有一个用于财务查询的财务 Skill，它是否读取了特殊的 FORMATTING.md 文件？
还有用于 Skills 的端到端任务完成域内完成的评估。我们运行完整的智能体循环，并使用 LLM 评判根据明确定义的标准 rubric 对结果进行评分。
最后，针对不同模型运行这些评估很重要。Computer 支持至少三种不同的编排模型系列：GPT、Claude Opus 和 Claude Sonnet。你希望针对这些不同的智能体编排器运行你的 Skill 加载和域 Skills，以确保你不会获得不同行为。Sonnet 和 GPT 在 Skills 方面表现相当不同。
技术特点：Gotchas 是最高价值内容。从薄开始，随着智能体失败而增长。
最终思考和要点
你构建的 Skills 越多，你就越擅长构建它们。如果你不尝试使用 Skills 自动化或使你日常做的事情更可重复，请立即开始。
构建 Skills 的行为让你更擅长构建更多 Skills，而且它们在自动化业务流程方面非常有效。如果你能够描述你在每次站会前、每个 sprint 结束时，或者作为工程师每天、每周甚至每季度做的任何事情，你应该编写一个 Skill 来收回你的时间。
也就是说，请记住 Skill 不容易甚至不总是必要的。少即是多。其他要点：
- 在 Skill 之前编写评估。为相邻但不同的 Skills 包含负面例子和禁止加载。
- 描述是困难的部分。"Load when..."（每个词都花费注意力）。
- Gotchas 是极其高价值的内容。从薄开始，随着智能体失败而增长。
- 请记住，通过添加新 Skill，你可以轻松破坏其他预先存在的 Skill，即使你没有触及它（谨防远处的作用）。
- 每次编写和维护 Skill 时，使用所有可用工具。如果你想了解更多信息，Agent Skills 网站有很多好例子，我们的内部仓库和公共生态系统中也有许多精心设计的 Skills 的例子。
文档来源：Agent Skills at Perplexity
原始作者：Perplexity Agents 团队
本文由 AI 助手整理优化，欢迎关注、分享转载，请注明出处
10个月宝宝每天需要喝多少奶粉？
