跳到主要内容

工具设计技能

为代理设计清晰的工具接口,说明输入、输出、选择时机和可恢复错误。

社区 · Muratcan Koylan
作者Muratcan Koylan
许可证MIT
来源muratcankoylan/Agent-Skills-for-Context-Engineering · GitHub 上的 SKILL.md
适用于Claude Code · Codex、Gemini CLI、Cursor、Copilot
读取源文件日期

tool-design 技能改善代理与可调用工具之间的接口。

它把每个工具视为契约,明确何时选择、接受哪些输入、返回什么,以及失败后如何恢复;不负责实现工具后端。

摘自该技能的 SKILL.md: ## Gotchas

这是 Muratcan Koylan 发布的社区技能,未经我们或 Anthropic 审核。技能可以让智能体运行代码、读取文件或访问网络。安装前请阅读它的 SKILL.md 和文件夹中的每个脚本,留意任何与其声称用途不符的内容。

功能

  1. 检查重复名称和含糊描述。
  2. 定义参数、响应格式和错误恢复。
  3. 测试代理是否选择并正确使用目标工具。

产出内容

  • 工具契约、修改后的描述和验证计划。

适用场景

  • 代理选错工具或反复提供无效参数。

不适用的场景

  • 选择整个系统架构,或把无关操作合并成过大的工具。

所需条件

  • 需要能读取文件的代理,以及真实工具结构、行为和失败案例。
  • 可选 Python 生成器使用模板和启发式评分,不能证明描述改善了真实工具选择。

技能包含的文件

文件或文件夹用途
SKILL.md工具契约指导、示例和设计陷阱。
references/best_practices.mdPython 描述生成器,以及设计与整合参考指南。
scripts/description_generator.pyPython 描述生成器,以及设计与整合参考指南。

2026-11-20 在仓库中查到的许可证:MIT。

示例提示词

安装后输入下面任意一条;在提示词中点名技能,可确保它被使用。

  • 重写此工具契约,明确默认值和可恢复错误。
  • 先检查这些重叠的工具名称,再建议整合。
  • 为同一个搜索操作设计简洁和详细两种响应。

如何安装 tool-design

保留参考资料与示例

复制完整文件夹。上下文工程插件会同时安装合集中的其他技能;仅需一个技能时使用文件夹安装。

文字指南和 Python 模板不需要外部服务。真实选择测试需要你的代理和工具实现;此处未验证托管上传与 API 执行。

技能(Skill)是一个包含 SKILL.md 文件的文件夹。只需安装一次;智能体会在每次会话开始时读取它的简短描述,只有请求匹配时才加载完整说明。选择你使用的环境:

Claude Code:从插件市场安装

  1. 在终端中用 claude 启动 Claude Code。
  2. 添加插件市场(每台电脑一次):
    /plugin marketplace add muratcankoylan/Agent-Skills-for-Context-Engineering
  3. 安装插件。Claude Code 会先显示插件详情:确认它会添加哪些内容(技能、Hooks、MCP 服务器),然后选择安装给你自己、给该仓库的所有人,还是仅在该仓库中给你自己使用。
    /plugin install context-engineering@context-engineering-marketplace
  4. 输入 / 查找 /context-engineering:tool-design,或直接提出任务。

也可以不进入会话,直接在 shell 中运行:

claude plugin marketplace add muratcankoylan/Agent-Skills-for-Context-Engineering
claude plugin install context-engineering@context-engineering-marketplace

插件会整体安装,因此会附带其他技能,包括 context-fundamentals, context-degradation, context-compression, context-optimization, self-managed-context, multi-agent-patterns, long-horizon-prompting, memory-systems, filesystem-context, hosted-agents, evaluation, advanced-evaluation, harness-engineering, project-development, bdi-mental-states, latent-briefing, self-improvement-loops。

Claude Code:把文件夹复制到技能文件夹

把技能文件夹放到 ~/.claude/skills/,可在这台电脑的所有项目中使用;放到仓库内的 .claude/skills/,则与在该仓库工作的所有人共享(记得提交)。

git clone --depth 1 https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering.git
mkdir -p ~/.claude/skills
cp -R Agent-Skills-for-Context-Engineering/skills/tool-design ~/.claude/skills/

Claude Code 会在会话期间识别这些文件夹中新增或修改的技能。如果会话开始时技能文件夹还不存在,请运行一次 /reload-skills。然后输入 /tool-design,或直接描述任务。

在 Windows 上,请在 Git Bash 或 WSL 中运行这些命令,或用文件资源管理器把文件夹复制到同样的位置。

Codex、Gemini CLI、Cursor 和 GitHub Copilot

这些智能体读取同样的 SKILL.md 文件夹。四者在项目中都认可的文件夹是 .agents/skills/,所以下面的命令把技能复制到那里:

git clone --depth 1 https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering.git
mkdir -p .agents/skills
cp -R Agent-Skills-for-Context-Engineering/skills/tool-design .agents/skills/
智能体项目文件夹用户文件夹说明
OpenAI Codex
.agents/skills/
~/.agents/skills/
输入 $ 或运行 /skills 来选择技能;当任务匹配时,Codex 也会自动选用。
Gemini CLI
.agents/skills/
.gemini/skills/
~/.agents/skills/
~/.gemini/skills/
也可以用 gemini skills install <git URL> --path <folder> --consent 从 Git 安装。2026 年 6 月 18 日起,Google 已用 Antigravity CLI 取代 Gemini CLI,面向免费层级和 Google One 用户;Antigravity 在项目中使用 .agents/skills/,个人使用 ~/.gemini/config/skills/。
Cursor
.agents/skills/
.cursor/skills/
~/.agents/skills/
~/.cursor/skills/
在 Agent 聊天中输入 / 选择技能。Cursor 也会读取 Claude Code 的 .claude/skills/ 文件夹。
GitHub Copilot
.github/skills/
.agents/skills/
.claude/skills/
~/.copilot/skills/
~/.agents/skills/
适用于 Copilot CLI、云端智能体,以及 VS Code、Visual Studio 和 JetBrains 中的智能体模式(IDE 支持取决于版本)。也可以运行 gh skill install OWNER/REPOSITORY SKILL(公开预览版,需 GitHub CLI 2.90.0 或更高版本)。
只安装你信任的技能. Anthropic 的建议是只使用可信来源的技能,其他技能在使用前要读完每个文件:技能可能以其描述中未提及的方式,指示智能体运行命令、读取文件或发送数据。

这些步骤的来源

已于 2026-11-14 对照各厂商的文档核实:

支持下一步操作的契约

名称和描述应帮助代理区分真实候选工具。说明默认值、输入约束和输出结构,不要只依赖暗示性的名称。

按任务提供简洁或详细输出。错误消息应让纠正操作可行,而不是诱发反复盲目重试。

按真实任务验证整合

减少工具数量是一种设计选择,不保证性能提升。使用同一组代表性任务对比成功率、参数错误和恢复情况。

附带生成器可起草描述,但其启发式检查不能验证后端行为、权限或代理是否理解接口。

关于 tool-design 的常见问题

它会构建 MCP 服务吗?

不会。它可指导工具契约,但传输、认证和后端执行仍需实现。

是否应整合所有工具?

不应。只在适合时整合重叠任务,保持无关操作分离,并测试新接口。

错误响应应包含什么?

说明失败原因,以及重试前应修改的输入或状态,不泄露敏感实现细节。

示例质量分数等于实测代理表现吗?

不是。它们检查文本模式与元数据;应通过代表性代理运行验证选择与恢复能力。

更多 AI 技能

相关技能

技能分类