【译】Claude Code 团队经验：如何用好 Skills

近期 Claude Code 团队新发了不少分享，是一个系列，这是系列的第二篇。

开发一个智能体（Agent）系统，最难的部分之一，就是怎么给它设计"工具箱"（Action Space）。

Claude 是通过调用工具（Tool Calling）来做事的。但在 Claude API 里，有各种各样的工具构建方式，比如执行 bash 命令、调用 Skills，或者最近新出的代码执行功能。

面对这么多选择，你怎么给 Agent 设计工具？是只给它一个全能工具（比如直接执行代码或 bash），还是给它 50 个工具，覆盖它可能遇到的每一种场景？

为了弄明白这个问题，我喜欢把自己代入模型。想象一下，如果给你一道很难的数学题，你希望手头有什么工具？这其实取决于你自己的能力！

给你一张纸是最低配置，但你只能手算。给你一个计算器会好很多，前提是你得知道怎么按那些高级功能键。最快、最强大的工具是一台电脑，但这要求你必须懂编程，能写代码来解题。

这是一个设计 Agent 时非常有用的思维框架。你给它的工具，必须跟它的能力相匹配。 可是，你怎么知道它有多大能耐呢？答案是：去观察它，去读它的输出，去不断实验。你要学会"用 Agent 的眼光看世界"。

在开发 Claude Code 的过程中，我们一直在观察 Claude。下面是我们学到的一些经验。

改进提问方式与 AskUserQuestion 工具

我们在开发 AskUserQuestion 这个工具时，目标是让 Claude 更擅长向用户提问（这通常被称为激发，elicitation）。

虽然 Claude 本来就能用纯文本问问题，但我们发现，回答这些问题通常很费时间。我们该怎么降低这种摩擦，让用户和 Claude 的沟通更高效呢？

尝试 1：修改 ExitPlanTool

我们最初的想法是，在现有的 ExitPlanTool（退出并输出计划的工具）里加一个参数，让它在输出计划的同时，也输出一组问题。这是最容易实现的方法，但它把 Claude 搞糊涂了。因为我们让它同时做两件事：一边给计划，一边问跟计划相关的问题。如果用户的回答和计划冲突了怎么办？Claude 是不是得再调用一次 ExitPlanTool？显然，这条路走不通。

尝试 2：改变输出格式

接着，我们尝试修改 Claude 的系统提示词，让它输出一种特定格式的 Markdown，用来表示问题。比如，我们可以要求它输出一个列表，括号里写上可选项。然后我们通过解析这个格式，在终端里渲染出一个漂亮的提问界面。

这看起来是个通用的改动，Claude 似乎也能做到，但这并不可靠。Claude 有时会多加几句话，有时会漏掉选项，或者干脆用了别的格式。

尝试 3：推出 AskUserQuestion 工具

最后，我们决定专门做一个工具，让 Claude 随时可以调用。当这个工具被触发时，我们会弹出一个对话框显示问题，并暂停 Agent 的运行，直到用户回答完毕。

有了这个工具，我们可以强制 Claude 输出结构化的数据，确保它能给用户提供多个选项。同时，这也让用户能在编写代码（比如在 Agent SDK 或 Skills 里）时灵活地复用这个功能。

最重要的是，Claude 似乎很喜欢用这个工具，输出的结果也很好。如果模型不知道怎么用，再好的工具也是白搭。

这就是 Claude Code 提问功能的最终形态了吗？我们也不确定。就像你在下一个例子中看到的，适合某个模型的方法，不一定适合另一个。

跟着能力一起升级：从 Todos 到 Tasks

当我们刚推出 Claude Code 时，我们意识到模型需要一个 Todo（待办事项）列表来保持专注。它在开始前写下 Todos，然后做完一项划掉一项。为此，我们做了一个 TodoWrite 工具，用来写入和更新任务，并展示给用户。

但即便如此，我们还是经常发现 Claude 会忘了自己要做什么。为了解决这个问题，我们每隔 5 轮对话就会插一条系统提示，提醒它不要忘了目标。

然而，随着模型越来越强，它们不仅不再需要这种提醒，反而觉得 Todo 列表是一种束缚。不断地提醒，会让 Claude 觉得它只能死板地照着清单做，而不敢去修改它。同时，我们发现 Opus 4.5 已经非常擅长使用子代理（subagents）了。可是，不同的子代理怎么去共享和协调一个 Todo 列表呢？

看到这些变化后，我们用 Task 工具取代了 TodoWrite。Todos 的目的是让模型别跑偏，而 Tasks 更像是帮不同的 Agent 互相沟通。Tasks 可以设置依赖关系，可以在不同的子代理间共享进度，模型也可以自由地修改甚至删除它们。

随着模型能力的提升，以前那些不可或缺的工具，现在可能成了它们的枷锁。 我们必须不断审视之前的假设，看看哪些工具还需要。这也是为什么，最好只支持一小撮能力相近的模型，而不是什么模型都支持。

设计一种搜索机制

对 Claude 来说，有一类工具特别重要，那就是搜索工具。有了搜索，它就能自己去寻找上下文。

早期，我们用的是 RAG（检索增强生成）加上向量数据库来给 Claude 提供上下文。虽然 RAG 又快又强大，但它需要建索引，要配置，在不同的运行环境里很容易出问题。更关键的是，这种方式是"喂"给 Claude 上下文，而不是让它自己去找。

既然 Claude 能在网上搜索，那为什么不能让它在你的代码库里搜呢？于是，我们给了 Claude 一个 Grep 工具，让它自己去搜文件、自己构建上下文。

我们发现了一个规律：随着 Claude 变得越来越聪明，只要给它合适的工具，它自己找上下文的能力就会越来越强。

当我们引入 Agent Skills 时，我们正式确立了"渐进式呈现"（progressive disclosure）的理念：让智能体通过不断探索，逐步发现相关的上下文。

Claude 可以读取一个 Skill 文件，这个文件又引用了其他文件，模型顺藤摸瓜，一路读下去。实际上，Skills 最常见的一个用途，就是给 Claude 增加搜索能力，比如教它怎么用某个 API，或者怎么查数据库。

在过去一年里，Claude 从一个基本不会自己找上下文的模型，进化成了能跨越多个文件层级进行嵌套搜索，并精准找到所需信息的熟手。

现在，"渐进式呈现"已经成为我们在不增加新工具的前提下，为模型添加新功能的常用手段。

渐进式呈现：Claude Code 的"使用指南" Agent

目前，Claude Code 大概有 20 个工具。我们一直在问自己：真的需要这么多吗？我们对添加新工具的标准非常高，因为多一个工具，模型就得多考虑一种情况。

比如，我们发现 Claude 不太懂怎么使用 Claude Code 本身。如果你问它怎么添加一个 MCP，或者某个斜杠命令是干嘛的，它根本答不上来。

我们本可以把这些说明全塞进系统提示词里，但用户其实很少问这些。如果全塞进去，不仅浪费上下文空间，还会干扰它的主业：写代码。

所以，我们用上了"渐进式呈现"。我们给了 Claude 一个官方文档的链接，让它在被问到时自己去搜。这招管用，但问题是，为了找一个简单的答案，Claude 经常会把一大堆搜索结果都塞进上下文里。

最后，我们做了一个专门的"Claude Code Guide"子代理。当你问它关于 Claude Code 的问题时，它就会召唤这个子代理。我们给这个子代理写了详细的指令，教它怎么在文档里高效搜索，并且怎么精准回答。

虽然这套方案还不完美（你问它怎么配置自己的时候，它偶尔还是会犯迷糊），但已经比以前好太多了。我们成功地扩展了 Claude 的能力，同时没有增加新的工具。

这是一门艺术，不是科学

如果你指望看完这篇文章，能拿到一套死板的"工具设计法则"，那你要失望了。给模型设计工具，是一门科学，更是一门艺术。它极大地取决于你用的是什么模型，Agent 的目标是什么，以及它在什么样的环境中运行。

你需要多做实验，多读它的输出，多去尝试新东西。

试着用 Agent 的眼光去看世界吧。