Introduction: Why Skill Design Matters
In Part 1, we covered the concept of Skills in Claude, and in Part 2, we walked through the flow for registering and managing Skills. In Part 3, we dive into best practices for actually designing and defining Skills. The schema definition, parameter design, and description optimization of a Skill directly determine whether Claude can select the right tool. It is no exaggeration to say that the quality of your design determines the performance of your agent.
Basic Structure of a Schema Definition
Claude's Tool Use defines tools based on JSON Schema. The minimum required elements are name, description, and input_schema [Source: https://docs.anthropic.com/en/docs/build-with-claude/tool-use].
{ "name": "search_financial_data", "description": "Retrieves financial data for a specified company. Returns metrics such as revenue, operating profit, and EBITDA.", "input_schema": { "type": "object", "properties": { "ticker": { "type": "string", "description": "Stock ticker symbol (e.g., AAPL, TSLA)" }, "period": { "type": "string", "enum": ["annual", "quarterly"], "description": "The period type of the financial data to retrieve" }, "fiscal_year": { "type": "integer", "description": "The target fiscal year (e.g., 2024)" } }, "required": ["ticker", "period"] } } In this example, ticker and period are required parameters, while fiscal_year is optional. By appropriately distinguishing between required and optional fields, Claude can decide whether to prompt the user for missing information or to fill it in with a default value.
Principles of Parameter Design
1. Maintain Appropriate Granularity
Parameters cause problems when they are either too fine-grained or too coarse. Research that achieved first place on the DABStep benchmark using NVIDIA NeMo Agent Toolkit adopted a design philosophy called "Reusable Tool Generation," strictly managing granularity so that each tool has a single responsibility [Source: https://huggingface.co/blog/nvidia/nemo-agent-toolkit-data-explorer-dabstep-1st-place]. The same research empirically demonstrated the trade-off: tools that are too general-purpose suffer lower selection accuracy, while tools that are too specialized lose reusability.
2. Use enums to Constrain Choices
Allowing free-form input for string parameters creates a risk that Claude will pass unexpected values. Enumerating allowed values with enum eliminates this risk. The period field above is a typical example.
3. Precise Type Specification
Take care not to confuse integer with number, or string with array. Type mismatches are a leading cause of runtime errors.
Optimizing Descriptions
Tool-Level description
The description field is the single most important element in determining which Skill Claude will invoke. Always include the following points.
- What the tool does (concisely, starting with a verb)
- When it should be used
- The format and content of the data returned
- Cases where it should not be used (if applicable)
Bad example: "Retrieves financial data" Good example: "Retrieves quarterly and annual financial statement data for a specified company. Does not include real-time stock prices or forecast data. Ticker symbol and period are required."
Parameter-Level description
The description of each parameter is equally important. In particular, specify the following explicitly.
- The format of the value (e.g., "UTC datetime string in ISO 8601 format")
- The allowed range (e.g., "an integer from 1 to 100")
- Concrete examples (e.g., "e.g., 2024-Q1")
Common Design Anti-Patterns
Anti-Pattern 1: Mixed Responsibilities Packing multiple functions into a single Skill reduces Claude's selection accuracy. "Data retrieval" and "data processing" should be defined as separate Skills.
Anti-Pattern 2: Ambiguous Naming Avoid generic names like process_data or handle_request. Commit to specific naming such as calculate_revenue_growth_rate.
Anti-Pattern 3: Omitting the description As the number of tools grows, Skills with absent or thin descriptions are almost never invoked. Especially when multiple similar tools exist, the description must clearly indicate how to differentiate between them.
Handling Conflicts Between Multiple Skills
When multiple similar Skills exist, adding a comparative statement to the description — such as "Use this tool instead of tool Y when X" — reduces incorrect selections [Source: https://docs.anthropic.com/en/docs/build-with-claude/tool-use#best-practices-for-tool-definitions]. For example, if a Skill that reads from a database coexists with a Skill that reads from an API, the description of each should explicitly state the trade-offs (speed, freshness, cost).
Summary and Preview of the Next Part
Designing Skills is equivalent to writing a specification document that Claude will read. Mastering the three axes — type definitions in the schema, appropriate use of required versus optional fields, and clear descriptions — is the most direct path to improving agent accuracy.
In Part 4, we will explain orchestration techniques for integrating the Skills you have designed into an actual agent loop and making multiple Skills work together in a coordinated manner.
Category: LLM | Tags: Claude, AIエージェント, Tool Use, LLM, プロンプトエンジニアリング
0 件のコメント:
コメントを投稿