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 之禅
简洁胜于复杂
Skill 是一个文件夹,不是一个文件。复杂本身就是它的特性。
显式胜于隐式
激活靠的是隐式的模式匹配。要做渐进式披露。
稀疏胜于密集
上下文很贵,每个 token 都要尽可能高密度。
特殊情况不足以打破规则
那些"坑"恰恰就是特殊情况——而且是最有价值的内容。
实现起来容易解释,可能就是好主意
容易解释的东西,模型本来就会。删掉。

笔者要分享的这份指南,是 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 里有三层不同的上下文成本,每一层在不同阶段付出:

层级加载内容预算何时付费
Index(索引层)
每个非隐藏 Skill 的 name: description
单 Skill 约 100 token
每个 session、每个用户、永远在付
Load(加载层)
完整的 SKILL.md 正文
约 5,000 token
Skill 被加载时一次性付清
Runtime(运行时层)
scripts/
、references/、assets/ 里的文件,子 Skill,FORMATTING.md、SPECIAL_CASES.md 等
不限
只有 Agent 真去读了才付

Computer 会先构建一个 Skill 索引,里面是每个可用 Skill 的 name 和 description。这个索引的预算特别紧——单 Skill 100 token 出头,越短越好。为啥这么抠门?因为这成本是每个 session、每个用户都要付的,它会被注入到对话最开头的系统提示词里。模型拿到这堆 Skill 名字和描述,才能决定要不要调用 load_skill()。所以能进这个索引的门槛极高:你的 Skill 必须确实有用,而且描述必须做到极度…

— 以上为试看内容(约 40%),开通会员后阅读全文 —