tool-wrapper-patternslisted

# Tool Wrapper Patterns ## Overview A reference guide for writing skills that wrap external CLI tools effectively. Based on patterns proven by debug-skill (DAP debugger wrapper) and applicable to any CLI integration. The core insight: an LLM agent interacting with a CLI tool has different needs than a human. Humans scan output visually and issue follow-up commands instinctively. An agent pays per-token for output and per-turn for follow-ups. Design your wrapper to minimize both. --- ## The 6 Principles of Effective Tool Wrapping ### 1. Auto-Context (Single-Command Full State) Every CLI invocation should capture and return the FULL relevant context in one shot. Don't make the agent issue follow-up queries. **Why it matters**: Each follow-up command costs a full agent turn (tool call overhead, context window growth, latency). A wrapper that returns complete state in one shot can save 3-5 turns per interaction. **Examples**: - **Database query skill**: Return results + query plan + row count + execution time, not just results - **Terraform skill**: Return plan output + resource count + drift warnings, not just the plan - **Debug skill**: Return current frame + local variables + watch expressions + breakpoint status, not just the stopped location **Pattern**: ```bash # Bad: Agent needs 4 commands to understand state tool status tool list-resources tool show-errors tool get-config # Good: Single command returns combined context tool status --json | jq '{ status: .st