智能体工具设计指南
帮助你设计清晰、可路由、可恢复的智能体工具接口。
内容强调沙箱、安全约束和避免不必要的工具权限，未见恶意行为或凭据窃取；但对最小权限、用户确认、敏感数据流、外部副作用和回滚没有完整操作要求，因此扣分。
正文结构自洽，包含错误恢复、测试清单和一个可读的 Python 辅助脚本；但脚本缺少测试，评估器存在较粗糙的启发式匹配，且关键工具设计主张未被静态复现，按静态上限并扣除边界与异常处理不足，得分受限。
激活条件、适用范围及与相邻技能的边界描述清楚，且声明平台无关；但没有中文使用指导、输入输出契约模板的完整落地示例，也未明确更多非适用环境边界，因此扣分。
具备清晰的信息架构、渐进式参考文档、示例脚本、版本号、更新时间和 MIT 许可；但缺少明确维护责任人、变更日志、依赖安装说明和稳定更新路径，外部案例引用也未在本材料中充分归因，故未满分。
提供工具描述结构、命名、错误恢复、整合原则、检查清单和生成器，能够直接辅助设计工作；但生成器不是完整工具运行时或 schema 验证器，示例和案例覆盖有限，且部分建议需结合实际系统验证，按静态上限保守扣分。
技能包含可审计的文档、脚本和若干量化案例声称；但没有针对该技能脚本的提交测试或独立复现实验，案例来源仅以名称或占位 claim 标识出现，因此证据覆盖薄弱。
- “执行任意 bash 命令”模式只有在严格隔离、最小权限、资源限制、审计和人工确认下才适用；不要直接授予生产环境或含敏感数据的主机访问权。
- 架构削减案例中的成功率、耗时和 token 数字在本材料中没有可复现实验细节，不能视为普遍保证。
- 工具命名示例与 MCP 实际部署、版本和服务端约束之间仍需核对；脚本生成的描述和错误模板应经过真实 schema、异常输入和 API 行为测试。
这个 Skill 能做什么，适合哪些场景？
这是一个面向智能体工具接口层的 Agent Skill，覆盖工具描述、参数模式、响应格式、命名、错误恢复和 MCP 工具设计。它强调把工具设计成确定性系统与非确定性智能体之间的明确契约，并用工具合并和命名空间减少路由歧义。内容还讨论响应格式优化、原语化工具、工具测试和基于失败案例迭代描述。它适合正在构建或审查智能体工具目录的工程师，不负责项目级流水线架构或是否拆分子智能体的决策。
提供设计和审查单个工具或工具目录的具体方法：规定工具描述应说明功能、使用时机、输入和返回值；为参数补充类型、约束、默认值和示例；建议使用动词-名词命名、统一字段和 MCP 的 ServerName:tool_name 完全限定名称；指导设计可操作的错误信息、简洁或详细响应格式，以及合并重叠工具的决策。它还提供工具审计清单、测试标准和一个用于分析工具失败案例并改写描述的 Python 伪代码模式。
- 智能体经常选错工具时，工程师可用它分析描述重叠并重组工具目录。
- 设计新 API 或 MCP 工具时，团队可用它定义参数模式、返回结构和错误恢复路径。
- 工具调用经常格式错误时，开发者可用它补充格式示例、默认值和约束。
- 工具数量不断增加时，架构师可用它评估命名空间、工具合并和原语化设计。
- 需要降低工具响应对上下文占用时，工程师可用它设计简洁与详细响应模式。
这个 Skill 有哪些优点和局限？
- 覆盖工具描述、模式、响应、命名、错误恢复和目录治理的完整接口层。
- 提供可执行的审计清单和五项测试标准：明确性、完整性、可恢复性、效率和一致性。
- 明确区分工具接口设计与项目架构、多智能体拆分等相邻问题。
- 包含工具合并、响应格式选择和 MCP 完全限定命名等具体建议。
- 它是设计指导，不是可直接运行的工具实现或框架适配器。
- SKILL.md 中的代码主要是 Python 伪代码，未提供该技能专属的自动化测试套件。
- MCP、文件系统和 Unix 工具相关内容是设计模式；实际部署仍需自行提供运行时、权限和实现。
- 部分生产效果属于特定案例或工作负载，技能明确建议在目标工具目录上重新验证。
如何安装这个 Skill？
获取仓库后，将完整的 tool-design 文件夹复制到目标 Agent Skills 目录，保持 SKILL.md 及其目录结构。例如：mkdir -p .codex/skills && cp -R skills/tool-design .codex/skills/；也可复制到 .claude/skills/ 或 .agents/skills/。不要将 SKILL.md 展平成单个文件。仓库还支持作为插件目录使用，但该技能的单独安装步骤之外未说明其他客户端的具体安装流程。
如何使用这个 Skill？
在支持 Agent Skills 的客户端中，将工作描述为工具接口任务，例如：“为这个 MCP 工具设计清晰的描述、参数模式、响应格式和可恢复错误信息，并检查目录中是否存在功能重叠。”当任务单位是单个工具或工具集合时激活；项目流水线架构、子智能体拆分和轨迹级上下文优化应交给其他技能。