huang-sh/deepscience/create-tooluniverse-skill

Create ToolUniverse Skill

Systematic workflow for creating production-ready ToolUniverse skills.

Core Principles

Build on the 10 pillars from devtu-optimize-skills:

1. TEST FIRST - never document untested tools
2. Verify tool contracts - don't trust function names
3. Handle SOAP tools - add operation parameter
4. Implementation-agnostic docs - no Python/MCP code in SKILL.md
5. Foundation first - query aggregators before specialized tools
6. Disambiguate carefully - resolve IDs properly
7. Implement fallbacks - Primary -> Fallback -> Default
8. Grade evidence - T1-T4 tiers on claims
9. Quantified completeness - numeric minimums per section
10. Synthesize - models and hypotheses, not just lists

See OPTIMIZE_INTEGRATION.md for detailed application of each pillar.

7-Phase Workflow

Total: ~1.5-2 hours (without tool creation).

Phase 1: Domain Analysis

• Gather concrete use cases and expected outputs
• Identify inputs, outputs, and intermediate data types
• Break workflow into logical phases
• Review existing skills in skills/ for patterns

Phase 2: Tool Discovery and Testing

Search tools in /src/tooluniverse/data/*.json (186 tool files). For each tool, read its config to understand parameters and return schema. See PARAMETER_VERIFICATION.md for common pitfalls.

Create and run a test script using test_tools_template.py. For each tool: call with known-good params, verify response format, document corrections. See TESTING_GUIDE.md for the full test suite template and procedures.

Phase 3: Tool Creation (If Needed)

Invoke devtu-create-tool when required functionality is missing and analysis is blocked. Use devtu-fix-tool if new tools fail tests.

Phase 4: Implementation

Create skills/tooluniverse-[domain]/ with:

• python_implementation.py - use only tested tools, try/except per phase, progressive report writing
• test_skill.py - test each input type, combined inputs, error handling

Use templates from CODE_TEMPLATES.md.

Phase 5: Documentation

Write implementation-agnostic SKILL.md using SKILL_TEMPLATE.md. Write multi-implementation QUICK_START.md using QUICKSTART_TEMPLATE.md. Key rules: zero Python/MCP code in SKILL.md, equal treatment of both interfaces in QUICK_START.

See IMPLEMENTATION_AGNOSTIC.md for format guidelines with examples.

Phase 6: Validation

Run the comprehensive test suite (see TESTING_GUIDE.md). Validate against VALIDATION_CHECKLIST.md. Perform manual verification: load ToolUniverse fresh, copy-paste QUICK_START example, verify output works.

Phase 7: Packaging

Create summary document using PACKAGING_TEMPLATE.md. Update session tracking if creating multiple skills.

Skill Integration

Quality Indicators

High quality: 100% test coverage before docs, agnostic SKILL.md, multi-implementation QUICK_START, fallback strategies, parameter corrections table, response format docs.

Red flags: Docs before testing, Python in SKILL.md, assumed parameters, no fallbacks, SOAP tools missing operation, no test script.

Reference Files