tool-creator: Скилл для создания инструментов Strands SDK

--- name: tool-creator description: This skill should be used when users want to create a new tool for the Strands SDK agent system. It supports creating both agent-as-a-tool (complex agents wrapped as tools) and regular tools (simple function-based tools). Use this skill when users request to create, build, or add a new tool. --- # Tool Creator Skill This skill provides comprehensive guidance for creating effective tools for the Strands SDK-based agent system. It supports two types of tools: **Agent-as-a-Tool** (agents wrapped as tools) and **Regular Tools** (function-based tools). ## About Tools in This System Tools extend agent capabilities by providing: 1. **Agent-as-a-Tool**: Specialized agents with their own prompts, models, and sub-tools 2. **Regular Tools**: Direct function execution for system operations, API calls, or data processing ### Tool Anatomy Every tool in `src/tools/` consists of: ```python # Required components TOOL_SPEC = { "name": "tool_name", "description": "What the tool does", "inputSchema": {"json": {...}} } def handle_tool_name(param: Annotated[type, "description"]): """Implementation logic""" pass def tool_name(tool: ToolUse, **kwargs: Any) -> ToolResult: """Strands SDK tool wrapper""" pass ``` ## Tool Creation Process Follow these steps to create a tool. The process supports both full specification upfront and interactive information gathering. ### Step 1: Determine Tool Type **Automatic Detection:** - If user mentions "agent tool", "agent-as-a-tool", or describes complex multi-step operations → Agent-as-a-Tool - If user mentions "simple tool", "regular tool", or describes direct operations → Regular Tool - If ambiguous → Ask user **Question to ask if ambiguous:** ``` Which type of tool would you like to create? 1. **Agent-as-a-Tool**: A specialized agent with its own prompt, model, and sub-tools (e.g., coder_agent_tool, reporter_agent_tool) - Use when: Complex reasoning, multi-step operations, or domain expertise needed 2. **Regular Tool**: A simple function-based tool (e.g., bash_tool, python_repl_tool) - Use when: Direct operations like API calls, file operations, or system commands ``` ### Step 2: Gather Basic Tool Information Collect the following information. If user provided some details already, only ask for missing information. **Required for Both Types:** 1. **Tool Name** (if not provided) - Question: "What should the tool be named? (Use snake_case, e.g., 'data_analyzer_tool')" - Validation: Must end with '_tool', use snake_case 2. **Tool Description** (if not provided) - Question: "What does this tool do? Provide a clear description of its purpose and capabilities." - This becomes the tool's description field that helps other agents decide when to use it 3. **Input Parameters** (if not provided) - Question: "What input parameters does this tool need?" - For agent tools, typically: `task` (string describing what to do) - For regular tools: specific parameters (e.g., `cmd` for bash, `code` for python) ### Step 3: Gather Type-Specific Information #### For Regular Tools: Collect these details (skip if already provided): 1. **Implementation Logic** - Question: "What operation should this tool perform? (e.g., execute subprocess, call API, read file)" - Common patterns: subprocess execution, HTTP requests, file operations, data transformations 2. **Error Handling** - Question: "What errors should be handled? (Default: try/except with error logging)" 3. **External Dependencies** (optional) - Question: "Does this tool require external libraries? If yes, which ones?" #### For Agent-as-a-Tool: Collect these details (skip if already provided): 1. **Agent's Purpose and Role** - Question: "What is the agent's primary purpose? What role does it play in the system?" - This informs the system prompt creation 2. **Agent Model Type** - Question: "Which LLM model should the agent use?" - Options: - `claude-sonnet-3-7` (recommended for most tasks) - `claude-sonnet-4` (advanced reasoning) - `claude-sonnet-3-5-v-2` (legacy) 3. **Reasoning Capability** - Question: "Should this agent use extended thinking/reasoning? (True/False)" - Default: False - Use True for: complex analysis, planning, strategic decisions 4. **Prompt Caching** - Question: "Should prompt caching be enabled? (Recommended: True for agents called frequently)" - Default: (True, None) 5. **Sub-tools** (if not provided) - Question: "Which tools should this agent have access to?" - Common options: `python_repl_tool`, `bash_tool`, `file_read` - Reference existing tools in `src/tools/` 6. **System Prompt Creation** - **IMPORTANT**: For system prompt creation, refer to `references/system-prompt-guidelines.md` - If user hasn't provided a system prompt, ask: "Do you want to create a custom system prompt for this agent?" - If yes: Use system-prompt-writer guidelines from references to create an effective prompt - If no: Create a basic prompt based on the agent's purpose ### Step 4: Create the Tool File Generate the tool file in `src/tools/` using the appropriate template: - **Regular Tool**: Use `templates/regular_tool_template.py` - **Agent-as-a-Tool**: Use `templates/agent_tool_template.py` **File Creation Steps:** 1. Load the appropriate template 2. Replace template variables with gathered information 3. If creating system prompt: - Create prompt file in `src/prompts/[tool_name_without_tool].md` - Follow system-prompt-writer guidelines from `references/system-prompt-guidelines.md` - Use proper template variable escaping (double braces `{{}}` for code samples) 4. Write the tool file to `src/tools/[tool_name].py` 5. Inform user of file locations ### Step 5: Validation and Next Steps After creating the tool: 1. **Verify File Creation** - Confirm tool file exists at `src/tools/[tool_name].py` - If agent tool with prompt, confirm prompt file at `src/prompts/[name].md` 2. **Integration Guidance** - Inform user how to import and use the new tool: ```python from src.tools.[tool_name] import [tool_name] # Use in agent agent = strands_utils.get_agent( agent_name="example", tools=[tool_name, other_tool], ... ) ``` 3. **Testing Recommendations** - Suggest testing the tool in isolation - For agent tools: Test with sample tasks - For regular tools: Test with sample inputs ## Key Design Principles ### For All Tools 1. **Clear Naming**: Tool names should be descriptive and end with `_tool` 2. **Comprehensive Descriptions**: Description should clearly state what the tool does and when to use it 3. **Annotated Parameters**: Use `Annotated[type, "description"]` for all parameters 4. **Consistent Error Handling**: Return error messages, don't raise exceptions 5. **Logging**: Use color-coded logging for visibility ### For Agent-as-a-Tool 1. **Global State Integration**: Always access `_global_node_states` for shared context 2. **Streaming Support**: Use async streaming pattern with `process_streaming_response_yield` 3. **State Updates**: Update clues, history, and messages in shared state 4. **Response Format**: Use standard response format templates 5. **Prompt Templates**: Use `apply_prompt_template()` with proper context variables ### For Regular Tools 1. **Simplicity**: Keep logic straightforward and focused 2. **Decorator Usage**: Use `@log_io` decorator for input/output logging 3. **Subprocess Safety**: Set timeouts and handle errors for subprocess calls 4. **Result Formatting**: Return results in consistent format (e.g., `"cmd||output"`) ## Common Patterns ### Pattern 1: Agent Tool with Analysis Capabilities ```python # Agent for data analysis tasks - Model: claude-sonnet-3-7 - Reasoning: False - Tools: [python_repl_tool, bash_tool] - Purpose: Execute data analysis and calculations ``` ### Pattern 2: Agent Tool for Report Generation ```python # Agent for creating reports - Model: claude-sonnet-3-7 - Reasoning: False - Tools: [python_repl_tool, bash_tool, file_read] - Purpose: Generate formatted reports from analysis results ``` ### Pattern 3: Simple Execution Tool ```python # Tool for direct command execution - Type: Regular Tool - Operation: subprocess.run() - Error Handling: Capture stderr, return error messages ``` ## References - **System Prompt Creation**: See `references/system-prompt-guidelines.md` for comprehensive prompt writing guidance - **Template Files**: See `templates/` for tool code templates - **Example Tools**: See `references/tool-examples.md` for complete real-world examples ## Iteration and Improvement After creating the initial tool: 1. **Test with Real Scenarios**: Try the tool with actual use cases 2. **Gather Feedback**: Identify what works and what doesn't 3. **Refine Prompts**: For agent tools, improve system prompts based on behavior 4. **Optimize Parameters**: Adjust input schemas if needed 5. **Update Documentation**: Keep descriptions accurate The goal is creating **effective, reliable tools** that seamlessly integrate with the Strands SDK agent system.