Perplexity SKILL 设计实践：AI Agent 开发进阶指南

最近，Perplexity 团队将他们内部维护数百个 Skill 的完整方法论公开了。结合原文与近期在 Agent 项目中的实践，一个核心感受愈发清晰：编写 Skill 与编写代码，本质上是两种截然不同的活动。甚至可以说，许多在软件开发中被奉为圭臬的最佳实践，在 Skill 设计领域可能需要完全反过来。

原文：Designing, Refining, and Maintaining Agent Skills at Perplexity

Python 之禅 vs Skill 之禅

Perplexity 团队巧妙地借用了 Python 之禅（PEP 20）作为参照。他们发现，这二十条箴言中，至少有一半在编写 Skill 时是失效的，甚至是背道而驰的。

一句话概括：编写 Skill 并非编写软件，而是在为模型构建上下文。两者的约束条件与设计原则天差地别。若以写代码的直觉去写 Skill，结果往往不尽如人意。

其中最后一条尤其值得玩味。曾有一段时间，撰写 Skill 时习惯性地像编写 README 一样，将步骤拆解得极其细致、力求“易懂”，结果效果反而更差。后来才明白，如果一段内容对人类而言易于理解，那么模型大概率也不需要额外的指导。Skill 中真正应该填充的，恰恰是那些“难以解释”的部分——边界案例、踩坑记录以及品味判断。

Skill 到底是什么？一个四面体定义

Perplexity 为 Skill 提供了一个立体的四面体定义：一个 Skill 同时是以下四样东西。

Skill 是一个目录（Directory）

A Skill is a Directory

Perplexity 强调，Skill 不是一个孤立的文件，而是一个具备中心-辐射（hub-and-spoke）结构的目录。这种结构是整个 Skill 体系的骨架。

一个标准的 Skill 目录结构如下所示：

my-skill/
├── SKILL.md        # frontmatter + 主指令（hub）
├── scripts/        # agent 直接运行的代码，别让它现写
├── references/     # 重文档，按需加载
├── assets/         # 模板、schema、数据文件
└── config.json     # 首次使用的用户配置

每一项设计都有其明确的意图。

Perplexity 分享了一个关于“所得税计算”Skill 的真实案例，极具启发性。该 Skill 需要覆盖多达1945条税收法典内容。最初的版本是将所有内容平铺在一个目录中，结果模型的表现甚至比不加载该 Skill 时更差——上下文过大，模型根本无法聚焦重点。

解决方案是重构为三层嵌套的主题结构：顶层约300个主题，中层聚合为20个领域，每个领域内部再细分为约15个主题。辅以自定义搜索工具和快速引导机制，才最终将税务相关任务的能力夯实。

关键认知：层级是有代价的——每增加一层，就意味着多一份信息架构上的人工梳理成本。但梳理得当后，模型的查阅精度将呈指数级提升。这并非无脑堆叠层次，而是在“模型的选择压力”与“信息的组织精度”之间寻求精妙平衡。

Skill 是一种格式（Format）

SKILL.md 文件头部的 frontmatter 包含两个核心字段，理解其语义至关重要：

• name：必须全小写、无空格、可使用连字符；必须与目录名完全一致；这是 Skill 的全局唯一标识符。
• description：这是路由触发器，而非内部文档说明。这是新手最容易失败的地方。

Perplexity 反复强调：description 不应写成“这个 Skill 能做什么”，而应描述“在什么情况下应该加载这个 Skill”。

应该是 "Load when..."，而不是 "This Skill does..."。

原因在于，description 在系统的索引（Index）阶段就会被注入模型的上下文。模型据此做出路由决策——判断当前任务是否需要加载此 Skill。如果 description 仅描述功能，模型将无从判断加载时机；只有明确触发条件，路由决策才能准确无误。

除了 name 和 description，frontmatter 还可包含：

• depends: —— 声明依赖的其他 Skill，系统会递归加载。
• metadata: —— 用于审查和评估的元数据。

不同 Agent 系统可在此基础上定义自己的字段。一个值得注意的细节是，像 Claude Computer 这样的系统，会在解析阶段剥离 frontmatter 后再将内容呈现给模型。这意味着，Agent 运行时看到的是 SKILL.md 的正文及附属文件，而 depends: 等配置信息已被系统消费，不会占用宝贵的模型上下文。这实现了在不污染上下文的前提下，保留丰富的配置能力。

Skill 是可被调用的（Invocable）

Skill 并非静态绑定，而是在运行时按需加载的。以 Perplexity Computer 为例，其加载流程大致如下：

1. Agent 调用 load_skill(name="...")。
2. Computer 将 Skill 目录复制到隔离沙箱。
3. 按 depends: 递归加载依赖的 Skill。
4. 剥离 frontmatter，Agent 最终只看到正文及附属文件。

不同系统在此基础上有不同的设计选择。例如，有的系统选择不暴露完整文件层级，让模型通过文件系统操作自行探索；有的则会提供文件树映射（但可能加以截断或深度限制）。Computer 为了保持上下文洁净，默认不暴露完整层级，但支持按 Skill 进行覆盖配置。

Skill 是渐进的（Progressive）

这是整篇文章最核心的概念，也是最值得反复琢磨的框架：三档上下文成本模型。

这个分层之所以至关重要，是因为每一层的“预算心态”完全不同：

• Index 阶段 —— 全局税（最严格）：这100个token是每个用户每次会话都要支付的“固定成本”。如果系统有100个Skill，Index阶段就要消耗10,000 tokens。这意味着description必须极致精炼，每个Skill的描述不能超过约100 tokens，这本质上是在训练信息压缩能力。
• Load 阶段 —— 任务税（中等严格）：这5,000个token是Skill被加载后的常驻开销。如果一个会话同时加载3个Skill，就是15,000 tokens。这意味着SKILL.md正文里的每一句话都必须有其价值，不应包含模型已知的内容，或那些可以通过附属文件渐进加载的内容。
• Runtime 阶段 —— 按需付费（最宽松）：这部分可以非常“重”——即使是20,000 tokens的分支逻辑也没问题，但只在Agent真正去读取时才会计费。这意味着复杂的条件逻辑、厚重的文档、大段参考资料都应放在这里，通过目录结构让模型按需读取。“渐进披露”是控制上下文成本的核心杠杆。

过去常见的误区是把所有内容都塞进SKILL.md。理解这个三档模型后才明白，编写Skill不是“写文档”，而是做信息架构设计——每个字节都必须放在它该在的位置。

何时真正需要编写一个Skill？

Perplexity团队表示，这是他们被问及最多的问题。他们的标准答案是：没有先验答案。正确的方法是，先不添加任何Skill，运行几次核心查询，观察Agent的表现。如果它能独立搞定，那么就不需要Skill。

这是一个重要的方法论：先验证必要性，再投入开发。

真正需要编写Skill的场景

• 领域知识：涉及高度专业化、模型训练数据中稀缺的知识，例如特定公司的内部API规范、小众领域的行业术语。
• 流程约束：需要遵循特定、不可更改的步骤序列，例如合规审批流程、安全审计清单。
• 品味与判断：涉及主观偏好或“感觉”，这是训练数据难以捕捉的。

最后一类尤其值得展开。Perplexity的设计总监Henry Modisett编写了许多设计相关的Skill，其中每一行内容都是关于“哪种字体感觉对、哪种不对”的判断。例如该用什么字体、不该用什么字体、字体搭配产生的“感觉”、布局的审美偏好等。这些都是训练数据里学不到的品味判断，只能通过Skill注入。这也正是Skill被称为“为模型构建上下文”的原因——它传递的并非知识，而是判断框架。

不需要编写Skill的场景

• 通用知识或模型已充分掌握的内容。
• 可以通过简单提示（prompt）解决的问题。
• 看起来像一份“很好的文档”的内容。

Perplexity特别强调了最后一点：如果你写的东西看起来像一份“优秀的人类文档”，那么它很可能是一个“糟糕的Skill”。给人看的好文档和给模型看的好Skill，其最佳形式截然不同。

每个Skill都是一项税负

整篇文章中，最具价值的认知或许是这句话：每个Skill都是一项税负。

这项“税”体现在三个层面：

1. Index税：每增加一个Skill，所有用户的每次会话都要多支付约100 tokens。
2. Load税：当Skill被错误加载时，将浪费约5,000 tokens的上下文。
3. 回归税：新增一个Skill，可能导致所有其他Skill的表现变差（远距离作用）。

第三点尤其反直觉，也最容易被忽视。Perplexity的原话是：“每次你增加一个额外的Skill，你都在冒让其他每一个Skill都略微变差的风险。”

原因在于，所有Skill的description都在同一个Index中竞争模型的注意力。新增一个Skill的描述，可能会分散模型对原有Skill的注意力，导致路由决策出错。这不是系统缺陷，而是所有基于共享上下文的系统固有的耦合问题。

实用的自检标准

Perplexity提供了一个极简的自检问题：“如果删掉这句话，Agent会不会做错？”如果答案是不会，那么这句话就是在浪费所有人的资源。

每个token都必须有存在的理由。编写Skill的一大挑战恰恰在于“写短”。Perplexity引用了帕斯卡在1657年的名言：“这封信写得这么长，只因为我没时间把它写短。”这句话用在Skill编写上再贴切不过。如果一个Skill能在5分钟内写完并提交PR，那它大概率不及格——不是因为写得快，而是因为尚未花时间将其压缩到应有的精炼程度。

让LLM自己写Skill有效吗？

Perplexity给出了一个尖锐的结论：早期研究表明，让LLM自己撰写Skill，平均来看模型无法从中获得任何益处。

原话是：“模型无法可靠地撰写它消费时能受益的那种程序性知识。”这并非全盘否定LLM的辅助作用，而是指出：Skill的核心内容——那些陷阱、品味判断和边界案例——目前仍然高度依赖人类经验的注入。模型可以辅助润色、生成初稿，但最核心的判断框架仍需人来构建。

五步法：从零构建一个Skill

Perplexity提供了一套非常实操的Skill撰写流程。值得关注的不仅是步骤本身，更是步骤间的依赖关系，特别是“先写评估集”和“description是最难的一步”这两个核心认知。

Step 0：先写评估集

这是最易被跳过，却也是最重要的步骤。评估集的来源主要有三类：真实用户查询、内部测试用例、以及常见的失败模式。其中，负面样本往往比正面样本更具价值。一个“何时不该加载此Skill”的例子，比十个“何时该加载”的例子更能帮助模型做出正确的路由决策。

Perplexity还强调要进行“禁止加载”测试，确保语义相近但分属不同Skill的查询不会被错误路由。

Step 1：撰写Description

这是整个Skill中最难写的一行。Perplexity的原话是：“这是Skill里最难写的一行。”原因在于，description决定路由，而路由错误是所有错误的源头。撰写description时，甚至无需关心Skill的正文内容，只需回答一个问题：在什么情况下应该加载这个Skill？

检查清单：

• 以 "Load when..." 开头。
• 控制在50词以内（约100 tokens）。
• 描述用户意图（最好使用真实查询中的表达）。
• 避免描述工作流（不要写“这个Skill会先做A再做B”）。

Perplexity给出了一个关于监控PR的Skill的优秀示范：

• ❌ 避免写成：“Monitor pull request status and notify on changes”。
• ✅ 应该写成工程师在沮丧时会说的话：“babysit my PR”、“watch CI”、“make sure this lands”。

核心洞察：description不是在描述Skill的能力，而是在匹配用户的真实表达。用户不会说“请帮我监控pull request的状态变化”，他们会说“帮我盯着这个PR”。

Step 2：撰写正文

这是另一个容易踩坑的环节。与人类交流和与LLM交流，完全是两回事。

❌ 避免像写给人看的文档那样罗列命令：

git log  # find the commit
git checkout main
git checkout -b 
git cherry-pick 

✅ 应该像写给模型的指令那样描述意图与约束：

Cherry-pick the commit onto a clean branch. Resolve conflicts preserving intent. If it can't land cleanly, explain why.

区别何在？关键在于不要“轨道化”。给模型列出精确的命令序列，就像给老司机画一张“第一步踩油门、第二步松离合”的地图——不仅多余，而且一旦偏离预设轨道，模型可能会死板地继续执行下一步，而非灵活处理。

最高价值的内容是“陷阱记录”——每次Agent执行翻车，都应记录下来，转化为Skill中的一条注意事项。这些负面示例是模型最需要、但训练数据中最稀缺的信号。

如果Skill中有部分内容是条件触发或特别“重”的，应将其从SKILL.md这个“中心”移出，放到附属文件这个“辐射端”中，利用渐进加载机制按需读取。

Step 3：善用目录结构

一个小技巧：如果发现SKILL.md正文超过约5,000 tokens，就需要警惕了。此时应审视哪些内容可以移至附属文件，哪些可以渐进加载。正文应只保留最核心的指令和陷阱记录。

Step 4：迭代

Perplexity建议在分支上反复运行评估后再合并。理想的工作流是：从主分支开始，不添加Skill；运行核心查询，建立评估基线；编写Skill并反复迭代；提交PR时，一次性为评审者提供完整的变更集和评估集。

评审者会感谢你——评审一个完整的Skill及评估集，远比评审连续十几个增量变更要容易得多（当然，新增陷阱记录这类小改动除外）。

需要特别注意：description上的微小措辞改动，可能对路由产生巨大影响（包括对其他Skill的溢出效应）。因此，所有description的调优都应在合并前完成，避免合并后再修改。

Step 5：发布

完成上述步骤后，即可发布。

如何&维护Skill？发布才是开始

Perplexity说得很直白：发布之后，真正的维护工作才刚刚开始。一个Skill上线后，会进入持续的维护循环，Perplexity将此模式称为“陷阱飞轮”。

维护决策矩阵

当发现Agent执行出错或表现不佳时，首先需要判断问题的根源：是路由错误（不该加载时加载了，或该加载时没加载），还是加载后执行错误？前者需要调整description，后者则需要在Skill正文中追加陷阱记录或优化指令。

“主要追加”哲学

Skill的维护遵循“主要追加”原则——大部分时间是在追加陷阱记录，而非修改描述或扩展指令。陷阱记录是负面示例，追加它不会改变模型的正面行为模式，只是告知模型“此处有一个已知陷阱”。而指令层面的改动则需要非常谨慎，因为它会影响模型的正面行为路径。

一个警示信号：如果合并后第一件事就是修改description，那基本就跑偏了。因为description决定路由，修改它会对所有其他Skill产生溢出影响。

评估套件

Perplexity内部运行多种评估以确保Skill质量：

• Skill加载评估：检查路由精度——精确率、召回率、禁止加载检查。确保Skill在该加载时加载，不该加载时不加载，并且新Skill不会破坏已有Skill的边界。
• 渐进加载评估：检查渐进加载是否生效。例如，金融Skill加载后，是否读取了FORMATTING.md？
• 端到端评估：运行完整的Agent循环，使用LLM作为裁判基于评分标准进行打分。

必须进行多模型评测

这是许多团队可能忽略的一点。Perplexity Computer至少同时支持三个系列的编排模型：GPT、Claude Opus、Claude Sonnet。而Sonnet和GPT在Skill行为上存在不小差异——同一个description，不同模型的理解方式不同，路由决策也不同。

因此，Perplexity的要求是：同一个Skill必须进行跨模型评测。仅在GPT上测试通过，并不代表在Claude上也能正常工作。

这一点，从事Agent开发的厂商和团队有必要高度重视。当前许多方案是“绑定一个模型做演示”，但生产环境迟早要面临多模型切换或模型升级的问题。提前建立跨模型评估体系，是在为未来节省成本。

核心要点总结

通读原文并结合实践，对于从事Agent/Skill开发的同学而言，以下几点最具借鉴意义：

1. Skill不是新文档：别把README当Skill写。给人类的好文档，给模型大概率是无效信息。编写Skill的语境是“模型已经知道基础操作，我需要告诉它何时避免犯错”。
2. Description是最难的一行：它决定路由，而非描述功能。以"Load when..."开头，控制在50词以内，使用用户的真实表达，而非技术化的功能描述。
3. 陷阱记录是无价的：出错就追加一条，长期积累形成飞轮。Skill是“主要追加”的——用得越久，壁垒越高。
4. 每个Skill都是一项税负：添加前先自问：“没有它，Agent会出错吗？”如果不会，就别加。Skill的数量是负债，而非资产。
5. 必须进行多模型评测：避免只与单一模型耦合。建立跨模型的评估套件，是Skill从演示走向生产的必经之路。
6. 远距离作用是真实存在的：新增一个Skill可能导致另一个毫不相关的Skill变差——这是共享上下文的固有风险。每次新增Skill都必须运行全量回归评估。

最后的思考

基于自身及外部的实践来看，一个略显尖锐的事实是：让LLM自动编写Skill，目前的研究结论是收效甚微。

Skill的构建，在当下仍然高度依赖人类注入“判断”——那些边界案例、品味偏好以及“千万别这么做”的经验。

但这并不意味着Skill的维护是纯手工的苦力活。Perplexity的“陷阱飞轮”指明了一条道路：Skill的价值是随时间累积的。每一次投入都不会白费——每条陷阱记录都是一次性的投入，却带来永久性的收益。

最具启发性的认知更新莫过于“三档上下文成本”框架。过去编写Skill时缺乏如此清晰的成本分层概念，倾向于将所有内容塞进SKILL.md。理解这个框架后才意识到，Index、Load、Runtime三档预算，每一档的心态都截然不同。

• Index阶段：在与所有其他Skill竞争模型的注意力 → 必须极简。
• Load阶段：在消耗用户的任务预算 → 必须高效。
• Runtime阶段：在为模型提供弹药 → 可以丰富，但需按需。

如果你的团队正在使用Claude Skills，或在Computer/Codex上构建Agent，那么Perplexity的这篇文章值得收藏并反复阅读。Skill设计是Agent系统的核心基础设施——你的Agent能达到何种高度，很大程度上取决于你的Skill设计处于何种水平。

Start small, stay focused, let gotchas grow.