我之所以把这篇写得更长,是因为我没有闲暇时间把它缩短。 —— 十七世纪法国思想家 布莱兹·帕斯卡(Blaise Pascal)
帕斯卡的这句名言,现在成了 Perplexity 开发者的核心准则。
Perplexity 认为,开发高质量 Agent Skill 所需的直觉和实践方法,与构建传统软件完全不同。在 Perplexity 内部,工程师们提交的 Skill 代码经常会被打回重写,因为许多在编写传统代码时非常有用的模式,在创建 Skill 时反而成了错误的范式。
例如,如果你参考 PEP20(也就是著名的「Python 之禅」),你会发现写好 Python 代码和写好 Skill 完全是两回事。在这 20 条智慧格言中,至少有一半在编写 Skill 时是完全错误甚至具有误导性的。
下面是其中的五条:
为了帮助开发者,Perplexity 公开了他们内部使用的设计指南。这份指南是 Perplexity 全体工程师在开发和评审 Skill 时使用的核心文档。
什么是 Skill?
当你编写一个 Skill 时,不是在编写普通的软件,而是在为模型及其运行环境构建「语境」(Context)。
在 Perplexity 的体系中,一个 Skill 包含四个维度:
Skill 是一个目录
Skill 不仅仅是一个单独的 SKILL.md 文件。在很多情况下,一个 Skill 包含多个文件。在以你的 Skill 命名的目录下,通常会有以下结构:
skill-name/├── SKILL.md # 前置元数据和指令├── scripts/ # Agent 运行的代码(而不是让它现场发明代码)├── references/ # 厚重的参考文档,根据条件加载├── assets/ # 模板、架构和数据└── config.json # 用户首次运行时的设置
这种「枢纽与辐辏」(hub-and-spoke)模式能让 Skill 保持非常聚焦且精炼。你可以非常创意地利用文件夹结构。有时,特别复杂的 Skill 能够从多层分级结构中受益,这有助于模型更好地定位。
假设一个 Skill 需要涵盖 300 个主题,你可以将其归纳为 20 个领域。即便对当今最先进的模型来说,直接从 300 个主题中选出正确的那一个也是一项尚未解决的挑战。相比之下,让模型先锁定 20 个领域中的一个,再从该领域下的 15 个主题中做选择,难度会大幅降低。
Skill 是一种格式
Skill 本身就是一种格式。核心的根文件 SKILL.md 必须同时具备名称(name)和描述(description)。而且,这个 Skill 的名称必须与其所在的目录名称完全匹配。
名称要求:
- • 必须全部小写
- • 不能有空格
- • 可以使用连字符
描述部分是「路由触发器」(routing trigger)。这是一个容易出错的地方:描述并不是为了记录 Skill 做了什么的内部文档,它其实是写给模型的指令,告诉模型在什么时候加载这个 Skill。
所以,你经常会看到描述里写的是「Load when...」(当……时加载),而不是「This Skill does...」(这个 Skill 的功能是)。这一点非常关键,因为大多数系统实现都会将这段描述直接注入到模型的上下文中。
在前置元数据(frontmatter)中,还有两个重要字段:
- •
depends::允许你创建层级化的 Skill 依赖关系 - •
metadata::用于评审和评估
不同的智能体系统甚至可以定义属于自己的前置元数据字段。作为一种替代方案,Skill 特有的元数据也可以打包在辅助的 JSON 或 YAML 配置文件中。如果你正在构建的系统需要为每个 Skill 提供不同的运行时行为,又不想让那些琐碎的细节「污染」模型的上下文,这种做法就很合适。
最后,也可以通过在读取时剥离(stripping)前置元数据来达到类似效果。Perplexity Computer 就采用了这种方法,让配置信息可以保留在根文件 SKILL.md 中。这需要在解析逻辑上非常细致,你可能还会根据需要实现「条件剥离」,以便保留某些对模型上下文有用的字段。
Skill 是可调用的
Skill 是可调用的。智能体会在运行时加载 Skill。需要注意的是,Skill 并不总是被捆绑在上下文中。在默认情况下,大多数智能体系统会根据具体的需要,渐进式地展开(unfold)这些 Skill。
在 Computer 的实现中,这个过程包含以下几个步骤:
-
- 系统调用
load_skill(name="...")
- 系统调用
-
- 系统将 Skill 目录复制到隔离的执行沙箱中
-
- 系统根据
depends:标签,递归地自动加载所有依赖项
- 系统根据
-
- 系统剥离前置元数据,因此智能体最终只能看到正文内容和附加文件
不同的智能体系统可以选择不同的方式来展示 Skill 内容。例如,有些系统可能完全不展示文件层级,让模型通过文件系统操作自行去发现。而另一些系统可能会向模型提供整个文件树的映射(可能会有截断或深度限制)。为了保持上下文的简洁,Computer 默认在调用上下文中省略了完整的文件层级,不过这一点可以针对单个 Skill 进行覆盖设置。
Skill 是渐进式的
Skill 具有渐进性。在 Computer 中,上下文成本分为三个阶段产生:
Computer 会为每一个可用的 Skill 构建一个包含名称和描述的索引。这个索引的预算极其紧张,每个 Skill 只有大约 100 tokens 左右(越短越好)。之所以要求如此严苛,是因为每一位用户在每一次会话中,都要为这个索引支付成本。它会在对话最开始时就被注入到系统提示词中。模型通过查看这些 Skill 名称和描述,来决定是否要调用 load_skill()。
进入这个索引的门槛非常…