PostHog团队分享编写AI代理技能的经验

Ian Vanagas 2026年8月3日 71 7 5 分享 我们正式迷上了 skill。PostHog 团队已经向内部 skill 商店发布了 226 个 skill，代码库中 28 个不同产品共有 187 个 SKILL.md 文件。所有人都在用 skill 来改进 PostHog 以及自己的工作流。

它们之所以不可或缺，是因为 agent 会失忆。每次对话，它们都要从头重新认识你的代码库和工作流。它们会选错工具、踩进同样的坑、重复过去的错误。它们最终总能搞明白，但代价是浪费时间和 token。

这对讨厌重复自己的工程师来说很烦。所以他们才会做自动化、写抽象层、随手备着好用的脚本。skill 就是这种本能用在 agent 上的产物。写一次，就再也不用向 agent 解释了。

以下是我们关于如何写出真正有用的 skill 的全部经验，无论是对你还是对你的产品。

Agent 能学会整门编程语言、几乎能搞懂你扔给它的任何工具，还能在循环中自我改进——但前提是它有相应的上下文。

上下文通常是在开头一次性全部塞进去的，这就限制了 agent 可用的信息量。skill 把这个逻辑反了过来。它不在开头加载所有内容，而是逐步披露信息。只有当 agent 判断某个 skill 相关时，才会加载它的信息，无论是主 SKILL.md 文件，还是其中的引用和脚本。这意味着好的 skill 实际上充当路由器。

首先，agent 需要选择加载这个 skill。skill 的名称和描述应当说明何时该用它，而不是它是什么，因为只有这部分始终存在于上下文中。

---

name: querying-posthog-data description: ‘Required reading before writing any HogQL/SQL or calling execute-sql against PostHog. Use whenever the user wants to search, find, or do complex aggregations PostHog entities (insights, dashboards, cohorts, feature flags, experiments, surveys, hog flows, data warehouse, persons, etc.) and query analytics data (trends, funnels, retention, lifecycle, paths, stickiness, web analytics, error tracking, logs, sessions, LLM traces). Covers HogQL syntax differences from ClickHouse SQL, system table schemas (system.*), available functions, query examples, and the schema-discovery workflow.’

名称和第一句话定义了何时该读这个 skill。 中间那句定义了何时该用它。 最后一句定义了这个 skill 是做什么的。 skill 太多或描述太长都会出问题。我们为 PostHog AI 构建（太多）skill 时，就吃了这个苦头。随着 skill 描述占满 agent 的上下文窗口，agent 的效果开始下降。Databricks 也发现，随着 skill 数量增加，agent 选错 skill 的情况越来越多。

skill 内部的各个小节同样需要充当路由器。我们那个 SQL skill 的其余部分是一个精简的工作流，链接到 26 个 schema 文件、22 个示例查询模式和一份函数索引。这实现了进一步的渐进式披露。

如果做对了，skill 能帮 agent 用更少的 token 更快成功，而这只是因为上下文没有被一次性加载。

试试这个：用渐进式披露的视角读一遍你的 skill。名称和描述有助于它们被发现吗？它们的拆分方式能让 agent 只加载自己需要的部分吗？

如果你看到一条带“fix”的 commit，去看它的 diff。 如果 diff 涉及 auth.py，读第 40–120 行。 如果函数超过 50 行，标记出来。 找出最近看起来有风险的改动并解释原因。从 commit 历史开始。

两者精神相同，但第一个规定得过于具体。一旦仓库的实际情况与 skill 的预期不符，它立刻就失效了。第二个能存活下来，是因为它拥抱了模糊性，agent 可以真正去看眼前的东西。

这就是把 skill 当成代码来对待会出错的原因。skill 是代码的超集。它们能做到代码能做的一切（因为 agent 会写代码），还能做到很多代码做不到的事（因为它们很聪明）。agent 能处理你 skill 中无法预见的场景，比如错误或运行时上下文，但前提是你允许它们这么做。

这意味着 skill 应该在以下方面保持精确：

目标。“完成”是什么样子？如果你不说，agent 就会替你做决定。给它看看好的结果长什么样，或者给它自我验证的方法。例如，creating-an-endpoint skill 要求 agent“用示例 payload 调用 endpoint-run 来确认，以验证响应的结构。”

约束。防止灾难的边界和护栏。

它无法自行推导的上下文。你的数据在哪里、该用哪个工具、否则它只能靠猜的 schema。

步骤。你不必规定该检查哪些文件。告诉它去理解 billing 是怎么工作的，它自己会找到。

失败。你不可能预知所有会出错的情况。agent 能读错误信息，你付钱给它就是为了让它自己搞明白。

运行时细节。数据实际长什么样。行号、文件列表、数量、版本和输出，变化频率都比你想象的高。

过度具体化会把 skill 变成工作流，剥掉你花钱买来的智能。让路径保持模糊，agent 才能获得所需的灵活性，去做你想让它做的事。

试试这个：让 skill 少一些规定性。给 agent 它需要的工具和你希望它达成的目标，然后让它自己找办法。

产品、API、CLI、MCP、模型、行为、最佳实践都在变。当这些变化让 skill 失效时，大多数人只是临时打补丁，但每次这么做都浪费时间和 token。

你可以比这更主动。防止腐化归根结底靠三条原则：

把持久结构与易变内容分开。手写那些很少变化的部分，引用那些会漂移的部分。

指向单一事实来源。对我们来说就是文档。指向具体 URL 的 skill，比把全部内容单独抄进去的 skill 更不容易过时。

（原文较长，此处译出前 6000 字，完整内容请点「打开原文」。）