Skill不是文档,是产品入口

编码 Agent 接 API，最怕三件事：用过期方法、乱猜 CLI 参数、读了五页文档还没找到正解。Langfuse 的 Marc Klingen 发现，问题不在 Agent 不够强，而在产品还没有给 Agent 一份 可执行的操作指南。Skill 的真正价值，不是把文档塞进上下文，而是把产品入口改造成 Agent 能稳定走完的路径。

Langfuse 的 Marc Klingen 提出一个判断：skill 正在成为软件产品的新入口。过去，开发者想给 AI 应用接入可观测性、评估或 prompt 管理，需要读几百页文档，自己建立一套理解，再把这套理解翻译成代码。现在，很多用户默认希望编码 Agent 能直接带着他们完成配置。

这个期待改变了基础设施公司写文档、做工具的方式。Langfuse 做了一个给编码 Agent 使用的 skill，让用户不再依赖模型训练语料里过期的记忆，而是按最新文档和最佳实践接入 tracing、prompt management 和 evals。团队最后得到的核心经验很简单：skill 不是把文档复制进一个文件，而是一份紧凑的操作指南，帮助 Agent 找到正确上下文、问对问题，并避开那些可预见的坑。

Skill 像一本给开放式 Agent 用的说明书

Klingen 用魔方解释 skill 的作用。小孩拿到魔方后，可以转动每一个面，但如果没有说明书，所有动作很难变成有效进展。一旦有了说明书，同一个工具就变得可解。

编码 Agent 也一样。它能跑 shell、改文件、读文档、调工具，但开放能力不等于稳定执行。固定 workflow 和 autonomous agent 的争论里，skill 正好落在中间：workflow 可靠但范围窄，Agent 灵活但容易发散。skill 给 Agent 一条结构化捷径，让它不用把任务压扁成死板流程，也能更可靠地往目标走。

这在跨领域请求里尤其重要。一个密码重置 workflow 可以处理密码重置，一个邮箱修改 workflow 可以处理邮箱修改。但当用户在同一次对话里说「帮我重置密码，顺便改邮箱」时，硬路由就开始别扭。Agent 可以逐步补齐两个领域的上下文；skill 让这个补齐过程不那么随机。

Langfuse 为什么需要一个 Skill

Langfuse 已经长成一个基础设施产品，文档有 478 页，覆盖 tracing、prompt management、evals 等多个功能区。深度是好事，但也带来一个问题：用户和编码 Agent 都不应该先爬完整座文档山，才能做出一个像样的实现决策。

Langfuse 过去一直刻意保持不强绑定架构。它不强推某一种端到端 chatbot 写法，而是把 tracing、规模化、可定制性和 API 做扎实。这种灵活性以前会让它在面对更强 opinionated 的工具时显得不够「一键」。但在 Agent 时代，Klingen 认为这反而是优势：基础设施保持灵活，具体应用怎么接入由 Agent 根据项目来适配。

编码 Agent 第一次靠训练语料里的记忆写出 Langfuse 接入代码时，效果会让人惊喜。但产品继续演进后，这种记忆就会变成负担。接口会变，方法会消失，模型会幻觉出过去存在、现在已经不可用的 API。Langfuse 做过一次测试：Claude Code 先用过期上下文添加 tracing，发现跑不通后，才去抓最新文档修复。任务最后能完成，但浪费了时间，trace 也很差，只看到两次 LLM 调用，看不到 Agent 到底做了什么。

Langfuse skill 的目标，就是给每个用户一个随叫随到的 Langfuse 专家：它能按最新文档、最佳实践和项目实际情况，帮助用户设置 observability、prompt management 和 evals。

构建 Langfuse Skill 的六个经验

1. 看 trace 能解决大部分问题

Langfuse 给 Claude Code 做了 instrumentation，然后自己使用自己的产品。团队让 Agent 执行 Langfuse 接入任务，再回头看 trace：它在哪里绕路，在哪里幻觉，在哪里多走了不必要的步骤。

这个过程暴露了很多具体问题。比如，为了让人类更容易上手，Langfuse 过去会减少必填环境变量，默认选择一个数据区域。对 Agent 来说，这种便利没那么重要：多设一个变量不费劲，选错区域却可能有影响。所以 skill 被调整为要求 Agent 识别用户实际使用的数据区域，而不是默认欧洲。

团队还看到了 CLI 参数幻觉。修法并不复杂：更明确地要求 Agent 使用 help flag。多跑一次帮助命令，比猜错再修快得多。

2. Agent 需要一张信息地图

Langfuse 已经有很完整的文档站，但编码 Agent 仍然需要知道从哪里开始找。团队把类似 llms.txt 的索引作为 Agent sitemap 暴露出来，并让 skill 指示 Agent 先去那里了解可用文档。

他们还优化了文档格式。有些 Agent 默认抓 HTML，这会浪费 token，也增加解析噪音。Langfuse 明确告诉 Agent：文档可以用 Markdown 形式获取，也可以通过 .md 后缀访问。这样 Agent 能更干净地消费同一份内容。

3. 自然语言搜索端点会形成反馈回路

Langfuse 原本就有一个基于检索的 docs Q&A Agent。团队把这套 retrieval stack 包成搜索端点给编码 Agent 用。这样 Agent 不必抓五个页面再慢慢筛，而是可以直接用自然语言提问，拿回相关文档片段。

这同时解决了两个问题。第一，Agent 能更快完成当前任务。第二，Langfuse 能看到真实生产信号：Agent 到底在搜什么。如果很多 Agent 都在问同一个问题，就说明文档或 skill 需要改进。

4. 基础 eval 比没有 eval 强

评估一个 skill 很难，因为 Langfuse 用户做的 AI 系统差别很大：聊天应用、实时语音、视频生成、后台发票处理，什么都有。团队没有等一个完美 benchmark，而是先做了一小组 sample repository 和自然语言检查项。

比如，如果样例应用使用 OpenAI 和 retrieval，检查项就要求最后的 trace 里出现 OpenAI instrumentation 和 retrieval spans。这些检查基于运行 skill 前后的文件系统和 git diff，再交给 LLM-as-a-judge 判断。它们不复杂，但足以让团队在修改 skill 时知道有没有破坏明显行为。

5. 动态内容应该引用，不应该复制

做 skill 时，很容易想把大量产品文档直接粘进去。这样看起来更自包含，但也复制了一份注定会过期的知识。Klingen 的判断是：变化快的内容应该引用，而不是复制。

skill 应该承载稳定指导：怎么思考、去哪里找、该问什么问题、要避开什么错误模式。API 细节、最新接口、示例代码这类变化快的内容，应该留在源文档里，需要时再抓取。

6. Auto-research 有用，但目标函数必须写对

Langfuse 还用 Agent 来改进 skill 本身。团队定义了一个目标任务：帮助用户把本地 Git 仓库里的 prompts 迁移到 Langfuse prompt management。auto-research loop 提出了六个改进建议，团队最后采纳了三个。

这个实验有效，但也暴露了一个陷阱。当目标函数优化「更少轮次」时，研究 Agent 会删掉抓取文档的指令，因为跳过文档能让任务更短。这刚好破坏了 skill 的核心价值：长期保持上下文最新。另一个重要行为——把 prompt versions 关联到 production traces——如果没有写进目标函数，相关改进也会被当成无关内容删掉。

结论是，优化压力会沿着目标函数走。如果目标函数没有写进质量、安全和长期可维护性，Agent 真的可能把它们优化掉。

仍然没解决的三个问题

Klingen 认为，skill 还有三个开放问题。

第一个是版本。用户本地安装的 skill 本质上是一份缓存快照。如果它已经三个月没更新，Agent 需要知道自己该刷新。最简单的版本也许只是给 skill 加一个时间戳。

第二个是分发。skill 仍然需要安装进 Agent 环境，而每个编码 Agent 的处理方式都不一样。Klingen 不太期待每个厂商都做一套插件市场。更简单的「well-known skill」发现机制可能更实用，尤其当它的信任等级并不低于公开网页时。

第三个是目标。skill 应该追求最快的 aha moment，还是直接把用户带到最完整的最佳实践？一个真正完善的 eval 系统，AI engineering 团队可能要花几个月设计。让 Agent 一次性做完，可能会让用户被大量问题淹没。更现实的路线也许是渐进式：先把初始接入跑通，之后用户再调用 skill 继续改进。

Skill 正在成为产品界面

Langfuse 现在已经在文档里大力推荐 skill，因为很多用户不想再直接读文档。他们想让编码 Agent 直接「把这件事加进去」，在必要时解释取舍，并交付一个能工作的配置。

这会改变文档的角色。文档不再只是写给人看的页面，也会成为 Agent 的原材料。API 不再只是后端接口，也会成为 Agent 批量执行 UI 工作的方式。一个好的 skill 也不再只是小便利，而会变成用户真正完成工作的产品界面。

Skill issue: Lessons from skilling up coding agents to use Langfuse – Marc Klingen, Clickhouse by AI Engineer