跳到主内容
智客 ZICQ

技能库 智客分类:Agent 工作流 devtu-fix-tool

Devtu Fix Tool

通过诊断测试失败,找出根源,实施修正,验证解决方案,来修复失败的"工具Universit"工具. 当 Tool University 工具测试失败,返回出错,有计划验证问题时使用,或者当请求调试或修复工具时使用 Tool University 框架.

374 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

通过诊断测试失败、确定根源、执行修正和验证解决方案来纠正失败的工具Universal 工具

何时用

ToolUniversity 工具失败测试,返回错误,有计划验证问题,或者当被请求调试或修复 ToolUniversity 框架中的工具时

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Fix ToolUniverse Tools、First Principles for Bug Fixes、Bug Verification (CRITICAL)、Instructions、Where to Fix、Error Types。 其中含规范建议的小节:输入输出示例。

文件分析

文件分析:除 SKILL.md 外,正文引用了 scripts/test_new_tools.py,属于带资源的技能包,这些文件按需再读。

官方 description(原文)

Fix failing ToolUniverse tools by diagnosing test failures, identifying root causes, implementing fixes, and validating solutions. Use when ToolUniverse tools fail tests, return errors, have schema validation issues, or when asked to debug or fix tools in the ToolUniverse framework.

Fix ToolUniverse ToolsFirst Principles for Bug FixesBug Verification (CRITICAL)InstructionsWhere to FixError Types1. JSON Parsing Errors2. Schema Validation Errors3. Nullable Field Errors4. Mutually Exclusive Parameter Errors5. Mixed Type Field Errors6. Invalid Test Examples

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
devtu-fix-tool
description
Fix failing ToolUniverse tools by diagnosing test failures, identifying root causes, implementing fixes, and validating solutions. Use when ToolUniverse tools fail tests, return errors, have schema validation issues, or when asked to debug or fix tools in the ToolUniverse framework.
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。
指令中引用的文件 · 1
  • scripts/test_new_tools.py

以下路径提取自原文;文件是否齐全请以来源仓库中的完整目录为准。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

该技能引用了附属文件,请从来源获取完整目录;仅复制 SKILL.md 可能缺少依赖。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「devtu-fix-tool」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-4d8d811dfa7606fa-Devtu-%E4%BF%AE%E6%AD%A3%E5%B7%A5%E5%85%B7.html
请存为 .cursor/skills/devtu-fix-tool/SKILL.md 或 .claude/skills/devtu-fix-tool/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。
该技能还带 scripts/、references/、assets/ 等文件,请从 https://github.com/mims-harvard/tooluniverse 取完整目录,不要只建一个 SKILL.md。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/mims-harvard/tooluniverse' --list

npx skills add 'https://github.com/mims-harvard/tooluniverse' --skill 'devtu-fix-tool'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版
--- name: devtu-fix-tool description: Fix failing ToolUniverse tools by diagnosing test failures, identifying root causes, implementing fixes, and validating solutions. Use when ToolUniverse tools fail tests, return errors, have schema validation issues, or when asked to debug or fix tools in the ToolUniverse framework. --- # Fix ToolUniverse Tools Diagnose and fix failing ToolUniverse tools through systematic error identification, targeted fixes, and validation. ## First Principles for Bug Fixes Before writing any fix, ask: **why does the user reach this failure state?** 1. **Prevent, don't recover** — fix the root cause so the failure can't happen, rather than adding hint text after it does 2. **Validate at input, not at output** — wrong parameters, unknown disease names, unsupported drugs should be caught and rejected early with clear guidance, not discovered after a silent API call 3. **Don't mask silent mutations** — if input is auto-normalized (fusion notation, Title Case), either accept both forms natively OR reject with explicit guidance; never silently transform and hide it 4. **Distinguish "no data" from "bad query"** — zero results because the filter is wrong is different from zero results because the data doesn't exist; the response must distinguish these clearly 5. **Fix the abstraction, not the instance** — if a parameter name is inconsistent, fix the interface; don't add an alias list that grows forever **Anti-patterns to avoid:** - Adding hint text to zero-result messages instead of validating upfront - Adding parameter aliases instead of fixing naming consistency - Post-hoc probing to rescue a failed query instead of pre-validating ## Bug Verification (CRITICAL) Before implementing any bug report, **verify it via CLI first**: ```bash python3 -m tooluniverse.cli run '' ``` Many agent-reported bugs are false positives caused by MCP interface confusion. Always confirm the bug is reproducible before implementing a fix. --- ## Instructions When fixing a failing tool: 1. **Run targeted test to identify error**: ```bash python scripts/test_new_tools.py -v ``` 2. **Verify API is correct** - search online for official API documentation to confirm endpoints, parameters, and patterns are correct 3. **Identify error type** (see Error Types section) 4. **Apply appropriate fix** based on error pattern 4. **Regenerate tools** if you modified JSON configs or tool classes: ```bash python -m tooluniverse.generate_tools ``` 5. **Check and update tool tests** if they exist in `tests/tools/`: ```bash ls tests/tools/test__tool.py ``` 6. **Verify fix** by re-running both integration and unit tests 7. **Provide fix summary** with problem, root cause, solution, and test results ## Where to Fix | Issue Type | File to Modify | |------------|----------------| | Binary response | `src/tooluniverse/*_tool.py` + `src/tooluniverse/data/*_tools.json` | | Schema mismatch | `src/tooluniverse/data/*_tools.json` (return_schema) | | Missing data wrapper | `src/tooluniverse/*_tool.py` (operation methods) | | Endpoint URL | `src/tooluniverse/data/*_tools.json` (endpoint field) | | Invalid test example | `src/tooluniverse/data/*_tools.json` (test_examples) | | Tool test updates | `tests/tools/test_*_tool.py` (if exists) | | API key as parameter | `src/tooluniverse/data/*_tools.json` (remove param) + `*_tool.py` (use env var) | | Tool not loading (optional key) | `src/tooluniverse/data/*_tools.json` (use `optional_api_keys` not `required_api_keys`) | ## Error Types ### 1. JSON Parsing Errors **Symptom**: `Expecting value: line 1 column 1 (char 0)` **Cause**: Tool expects JSON but receives binary data (images, PDFs, files) **Fix**: Check Content-Type header. For binary responses, return a description string instead of parsing JSON. Update `return_schema` to `{"type": "string"}`. ### 2. Schema Validation Errors **Symptom**: `Schema Mismatch: At root: ... is not of type 'object'` or `Data: None` **Cause**: Missing `data` field wrapper OR wrong schema type **Fix depends on the error**: - If `Data: None` → Add `data` wrapper to ALL operation methods (see Multi-Operation Pattern below) - If type mismatch → Update `return_schema` in JSON config: - Data is string: `{"type": "string"}` - Data is array: `{"type": "array", "items": {...}}` - Data is object: `{"type": "object", "properties": {...}}` **Key concept**: Schema validates the `data` field content, NOT the full response. ### 3. Nullable Field Errors **Symptom**: `Schema Mismatch: At N->fieldName: None is not of type 'integer'` **Cause**: API returns `None`/`null` for optional fields **Fix**: Allow nullable types in JSON config using `{"type": ["", "null"]}`. Use for optional fields, not required identifiers. ### 4. Mutually Exclusive Parameter Errors **Symptom**: `Parameter validation failed for 'param_name': None is not of type 'integer'` when passing a different parameter **Cause**: Tool accepts EITHER paramA OR paramB (mutually exclusive), but both are defined with fixed types. When only one is provided, validation fails because the other is `None`. **Example**: ```json { "neuron_id": {"type": "integer"}, // ❌ Fails when neuron_name is used "neuron_name": {"type": "string"} // ❌ Fails when neuron_id is used } ``` **Fix**: Make mutually exclusive parameters nullable: ```json { "neuron_id": {"type": ["integer", "null"]}, // ✅ Allows None "neuron_name": {"type": ["string", "null"]} // ✅ Allows None } ``` **Common patterns**: - `id` OR `name` parameters (get by ID or by name) - `acronym` OR `name` parameters (search by symbol or full name) - Optional filter parameters that may not be provided **Important**: Also make truly optional parameters (like `filter_field`, `filter_value`) nullable even if not mutually exclusive. ### 5. Mixed Type Field Errors **Symptom**: `Schema Mismatch: At N->field: {object} is not of type 'string', 'null'` **Cause**: Field returns different structures depending on context **Fix**: Use `oneOf` in JSON config for fields with multiple distinct schemas. Different from nullable (`{"type": ["string", "null"]}`) which is same base type + null. ### 6. Invalid Test Examples **Symptom**: `404 ERROR - Not found` or `400 Bad Request` **Cause**: Test example uses invalid/outdated IDs **Fix**: Discover valid examples using the List → Get or Search → Details patterns below. ### 7. API Parameter Errors **Symptom**: `400 Bad Request` or parameter validation errors **Fix**: Update parameter schema in JSON config with correct types, required fields, and enums. ### 8. API Key Configuration Errors **Symptom**: Tool not loading when API key is optional, or `api_key` parameter causing confusion **Cause**: Using `required_api_keys` for keys that should be optional, or exposing API key as tool parameter **Key differences**: - `required_api_keys`: Tool is **skipped** if keys are missing - `optional_api_keys`: Tool **loads and works** without keys (with reduced performance) **Fix**: Use `optional_api_keys` in JSON config for APIs that work anonymously but have better rate limits with keys. Read API key from environment only (`os.environ.get()`), never as a tool parameter. ### 9. API Endpoint Pattern Errors **Symptom**: `404` for valid resources, or unexpected results **Fix**: Verify official API docs - check if values belong in URL path vs query parameters. ### 10. Transient API Failures **Symptom**: Tests fail intermittently with timeout/connection/5xx errors **Fix**: Use `pytest.skip()` for transient errors in unit tests - don't fail on external API outages. ## Common Fix Patterns ### Schema Validation Pattern Schema validates the `data` field content, not the full response. Match `return_schema` type to what's inside `data` (array, object, or string). ### Multi-Operation Tool Pattern Every internal method must return `{"status": "...", "data": {...}}`. Don't use alternative field names at top level. ## Finding Valid Test Examples When test examples fail with 400/404, discover valid IDs by: - **List → Get**: Call a list endpoint first, extract ID from results - **Search → Details**: Search for a known entity, use returned ID - **Iterate Versions**: Try different dataset versions if supported ## Unit Test Management ### Check for Unit Tests After fixing a tool, check if unit tests exist: ```bash ls tests/tools/test__tool.py ``` ### When to Update Unit Tests Update unit tests when you: 1. **Change return structure**: Update assertions checking `result["data"]` structure 2. **Add/modify operations**: Add test cases for new operations 3. **Change error handling**: Update error assertions 4. **Modify required parameters**: Update parameter validation tests 5. **Fix schema issues**: Ensure tests validate correct data structure 6. **Add binary handling**: Add tests for binary responses ### Running Unit Tests ```bash # Run specific tool tests pytest tests/tools/test__tool.py -v # Run all unit tests pytest tests/tools/ -v ``` ### Unit Test Checklist - [ ] Check if `tests/tools/test__tool.py` exists - [ ] Run unit tests before and after fix - [ ] Update assertions if data structure changed - [ ] Ensure both direct and interface tests pass For detailed unit test patterns and examples, see [unit-tests-reference.md](unit-tests-reference.md). ## Verification ### Run Integration Tests ```bash python scripts/test_new_tools.py -v ``` ### Run Unit Tests (if exist) ```bash pytest tests/tools/test__tool.py -v ``` ### Regenerate Tools After modifying JSON configs or tool classes: ```bash python -m tooluniverse.generate_tools ``` Regenerate after: - Changing `src/tooluniverse/data/*_tools.json` files - Modifying tool class implementations Not needed for test script changes. ## Output Format After fixing, provide this summary: **Problem**: [Brief description] **Root Cause**: [Why it failed] **Solution**: [What was changed] **Changes Made**: - File 1: [Description] - File 2: [Description] - File 3 (if applicable): [Unit test updates] **Integration Test Results**: - Before: X tests, Y passed (Z%), N failed, M schema invalid - After: X tests, X passed (100.0%), 0 failed, 0 schema invalid **Unit Test Results** (if applicable): - Before: X tests, Y passed, Z failed - After: X tests, X passed, 0 failed ## Testing Best Practices ### Verify Parameter Names Before Testing **CRITICAL**: Always read the tool's JSON config or generated wrapper to get the correct parameter names. Don't assume parameter names. **Example of incorrect testing**: ```python # ❌ WRONG - assumed parameter name AllenBrain_search_genes(query='Gad1') # Fails: unexpected keyword 'query' ``` **Correct approach**: ```python # ✅ RIGHT - checked config first # Config shows parameters: gene_acronym, gene_name AllenBrain_search_genes(gene_acronym='Gad1') # Works! ``` **How to find correct parameter names**: 1. Read the JSON config: `src/tooluniverse/data/*_tools.json` 2. Check the generated wrapper: `src/tooluniverse/tools/.py` 3. Look at test_examples in the JSON config ### Systematic Testing Approach When testing multiple tools: 1. **Sample first**: Test 1-2 tools per API to identify patterns 2. **Categorize errors**: Group by error type (param validation, API errors, data structure) 3. **Fix systematically**: Fix all tools with same issue type together 4. **Regenerate once**: Run `python -m tooluniverse.generate_tools` after all JSON changes 5. **Verify all**: Test all fixed tools comprehensively ### Understanding Data Structure Tools can return different data structures: - **Object**: `{"data": {"id": 1, "name": "..."}}` - single result - **Array**: `{"data": [{"id": 1}, {"id": 2}]}` - multiple results - **String**: `{"data": "description text"}` - text response **Test accordingly**: ```python # For object data result = tool() data = result.get('data', {}) value = data.get('field_name') # ✅ # For array data result = tool() items = result.get('data', []) count = len(items) # ✅ first = items[0] if items else {} # ✅ ``` ## Common Pitfalls 1. **Schema validates `data` field**, not full response 2. **All methods need `{"status": "...", "data": {...}}`** wrapper 3. **JSON config changes require regeneration** 4. **Use `optional_api_keys`** for APIs that work without keys 5. **Check official API docs** for correct endpoint patterns 6. **Unit tests should skip** on transient API failures, not fail 7. **Mutually exclusive parameters MUST be nullable** - most common new tool issue 8. **Verify parameter names from configs** - don't assume or guess 9. **Test with correct data structure expectations** - list vs dict vs string ## Debugging - **Inspect API response**: Check status code, Content-Type header, and body preview - **Check tool config**: Load ToolUniverse and inspect the tool's configuration - **Add debug prints**: Log URL, params, status, and Content-Type in the run method ## Quick Reference | Task | Command | |------|---------| | Run integration tests | `python scripts/test_new_tools.py -v` | | Run unit tests | `pytest tests/tools/test__tool.py -v` | | Check if unit tests exist | `ls tests/tools/test__tool.py` | | Regenerate tools | `python -m tooluniverse.generate_tools` | | Check status | `git status --short \| grep -E "(data\|tools\|.*_tool.py\|tests/tools)"` | | Error Type | Fix Location | |------------|--------------| | JSON parse error | `src/tooluniverse/*_tool.py` run() method | | Schema mismatch | `src/tooluniverse/data/*_tools.json` return_schema | | 404 errors | `src/tooluniverse/data/*_tools.json` test_examples or endpoint | | Parameter errors | `src/tooluniverse/data/*_tools.json` parameter schema | | Unit test failures | `tests/tools/test_*_tool.py` assertions | | Tool skipped (optional key) | `src/tooluniverse/data/*_tools.json` use `optional_api_keys` | | API key as parameter | Remove from JSON params, use `os.environ.get()` in Python |

相关技能

Agent 工作流

Skill Creator

创造有效技能指南。 当用户想创造出新的技能(或更新现有的技能),以专业知识,工作流程,或工具集成来扩展克洛德的能力时,应该使用这种技能.

Agent 工作流

Clawdhub

使用ClawdHub CLI搜索,安装,更新并发布从taladhub.com的代理技能. 需要获取苍蝇上的新技能时使用,将安装的技能同步到最新版本或特定版本,或者发布 npm-instainddhub CLI 的新/更新的技能文件夹.

Agent 工作流

Agent Team Orchestration

管弦乐团多代理团队,任务设定周期,交接协议,审查工作流程. 使用时间: (1)建立2+特派员队伍,具有不同专业,(2)确定任务路线和生命周期(收录框_ spec_建设_审查_完成),(3)在特派员之间制定交接协议,(4)建立审查和质量关口,(5)管理特派员之间的交流和文物共享.

Agent 工作流

Superpowers

Spec-first,TDD,子代理驱动的软件开发工作流程. 当:(1)构建任何新功能或应用——触发脑暴_计划_子代理执行回路,(2)调试出一个bug或测试失败——触发系统性的根起过程,(3)用户说"让我们构建","帮助我计划","我想添加X",或"这个被打破",(4)完成一个功…