Perplexity 是怎么设计、打磨和维护 Agent Skills 的
Perplexity 是怎么设计、打磨和维护 Agent Skills 的
“原文链接:https://research.perplexity.ai/articles/designing-refining-and-maintaining-agent-skills-at-perplexity
Perplexity 这套前沿 Agent 产品,骨子里靠的是一堆模块化的 Agent Skills——把那些专业知识和实操经验打包成一个个可调用的能力单元。Perplexity 内部维护着一个精挑细选的 Skill 库,覆盖各种技术场景:Perplexity Computer 里那些通用工具大多都是 Skill 撑起来的;金融、法律、医疗这些垂直领域有专门的能力模块;还有一长串针对各种用户细分需求的小模块。这里头有些 Skill 平时根本用不上,但一旦触发就特别关键。所以 Perplexity 的 Agents 团队一直把 Skill 质量看得跟代码质量一样重。
但话说回来,写一个高质量 Skill 所需要的直觉和最佳实践,跟写传统软件完全是两码事。Agents 团队 review 过工程师们写的大量 PR——这些工程师本身水平都很高,但写出来的 Skill 几乎都得返工,评论意见和修改建议一长串。原因很简单:很多写代码时是好习惯的模式,到了写 Skill 这里就成了反模式。
举个直观的例子,拿 PEP20 - Python 之禅 来对照一下,就能很明显地看出来:写好 Python 代码的那套思维,跟写好 Skill 完全不是一回事。Python 之禅那 20 条里头,至少有一半放在写 Skill 的语境下要么是错的,要么是会把人带沟里去的。挑五条对照看看:
| Python 之禅 | Skill 之禅 |
|---|---|
笔者要分享的这份指南,是 Perplexity 内部工程师在开发和评审 Skill 时实际在用的文档。这次也把它公开出来,希望踩过的坑、悟出来的道理能让更多人受益。无论是日常要写生产级 Skill 的工程师,还是想在自己擅长的领域里给 Computer 做个专属 Skill 的普通用户,这份文档都用得上。
到底什么是 Skill?
写 Skill 的时候,做的不是传统意义上的软件开发——尽管 Skill 现在确实已经成了 Agent 系统主要的逻辑核心之一。更准确地说,写 Skill 是在为模型和它所处的环境构建上下文。 Skill 有它自己的一套约束和设计原则,按写代码的思路去写 Skill,铁定翻车。
具体来说,从 Perplexity 的实践看,Skill 至少包含四层含义。
Skill 是一个目录
Skill 不是一个孤零零的 SKILL.md 文件。很多情况下,一个 Skill 会包含好几个文件。在以 Skill 命名的目录下,通常会有 SKILL.md(frontmatter 元数据加上指令本体)、scripts/(Agent 直接调用的代码,省得它每次都重新发明轮子)、references/(体量较大的文档,按需加载)、assets/(模板、schema、各种数据),以及 config.json(首次使用时的用户配置)。
这种"中心-辐条"的结构能让 Skill 保持高度聚焦和精简,而且文件夹结构本身就可以玩出很多花样。对于特别复杂的 Skill 来说,多层嵌套的目录结构能帮模型更好地导航。打个比方,如果一个 Skill 涉及 300 个主题、可以归到 20 个大领域下面——让今天最强的前沿模型从 300 个里精确挑出一个,仍然是个没解决的难题;但让它先在 20 个领域里挑一个,再在某个领域下的 15 个主题里挑一个,难度立马降下来了。
举个真实案例。这次美国报税季,Perplexity 在打造 Computer 美国所得税相关能力时,团队就用了三层嵌套的目录结构。这种层级在面对税法这种复杂场景时简直是必需品:早期测试的时候,他们试过把美国《国内税收法典》全部 1,945 个条款一股脑塞进一个文件夹里给模型,结果模型表现比根本不加载这个 Skill 还要糟糕。后来按逻辑重新切分成多层级,效果立竿见影。
不过这种层级结构也不是白来的。层级越深,对信息架构的精细打磨要求就越高,否则就要被多层间接寻址搞晕。团队为此专门做了快速参考索引、定制化的搜索工具等等,就是为了让模型尽可能少绕弯路就能定位到信息。这种笨功夫做扎实之后,最终的结果是值得的:模型在处理税务相关任务时,比单纯依赖通用工具强了不止一个档次。
补充:目录树与各文件的用途
来自另一译本。用这张图定位脚本、条件参考、模板与初次设置。
skill-name/
├── SKILL.md # 前置元数据和指令
├── scripts/ # Agent 运行的代码(而不是让它现场发明代码)
├── references/ # 厚重的参考文档,根据条件加载
├── assets/ # 模板、架构和数据
└── config.json # 用户首次运行时的设置Skill 是一种格式
Skill 同时是一种格式约定。根目录下的 SKILL.md 文件必须包含 name 和 description。而且这个 name 必须跟 Skill 所在的目录名严格一致,全部小写、不能有空格、可以用连字符。
这里头 description 这个字段是路由触发器,这是个常见的失误点:很多人把它当成"这个 Skill 是干啥的"内部文档来写,错。它实际上是给模型看的——告诉模型什么时候该加载这个 Skill。所以地道的写法是 "Load when..."(什么时候加载),而不是 "This Skill does..."(这个 Skill 做什么)。这事很重要,因为大部分实现都是把 description 直接注入到模型上下文里的。
frontmatter 里还有 depends:,可以用来构建 Skill 之间的层级依赖关系;以及 metadata:,主要用于评审和评估。不同的 Agent 系统还可以自定义 frontmatter 字段,按各自系统的需求灵活使用。当然也可以走另一条路:把 Skill 专属的元数据放进单独的 JSON 或 YAML 配置文件里。这种做法适合那种希望 Skill 能有不同运行时行为、又不想用细枝末节污染模型上下文的 Agent 系统。还有一种类似的玩法是在读取时把 frontmatter 给剥掉。Computer 用的就是后面这种方案——配置都保留在 SKILL.md 文件里,但在解析时小心处理;如果有些字段对模型上下文有用、有些没用,还可以做条件性剥离。
Skill 是可调用的
Skill 是可调用的,Agent 在运行时按需加载。重点:Skill 不会一股脑全部塞进上下文。 大多数 Agent 系统默认是按需逐步展开。
在 Computer 里,Skill 加载的过程大致是这样:Computer 先调用 load_skill(name="..."),把 Skill 目录复制到隔离的执行沙箱里,再递归加载 depends: 标签里声明的依赖,最后把 frontmatter 剥掉,所以 Agent 看到的只有正文内容和附属文件。
不同的 Agent 系统可以用不同方式暴露 Skill 内容。有些系统选择压根不暴露文件层级结构,让模型自己通过文件系统操作去发现;有些则把整个文件树(带截断或深度限制)给模型一份地图。Computer 选的是默认不在调用上下文里展开完整文件层级,但这个行为可以按 Skill 单独配置覆盖。
Skill 是渐进式的
Skill 是渐进式的。Computer 里有三层不同的上下文成本,每一层在不同阶段付出:
| 层级 | 加载内容 | 预算 | 何时付费 |
|---|---|---|---|
name: description | |||
SKILL.md 正文 | |||
scripts/references/、assets/ 里的文件,子 Skill,FORMATTING.md、SPECIAL_CASES.md 等 |
Computer 会先构建一个 Skill 索引,里面是每个可用 Skill 的 name 和 description。这个索引的预算特别紧——单 Skill 100 token 出头,越短越好。为啥这么抠门?因为这成本是每个 session、每个用户都要付的,它会被注入到对话最开头的系统提示词里。模型拿到这堆 Skill 名字和描述,才能决定要不要调用 load_skill()。所以能进这个索引的门槛极高:你的 Skill 必须确实有用,而且描述必须做到极度…