How to use the Tool Calling Tutor agent skill

What is an agent skill, and what does this one make the agent do?

An agent skill is a folder with a SKILL.md file and optional reference files that an agent can load when a task matches the skill's description. This one is named tool-calling-tutor and is aimed at tool-calling or ReAct-style agents, where a model chooses functions to call.

Instead of guessing a fix, the skill makes the agent first identify your symptom, then follow a structured diagnosis. It coaches you rather than writing the whole program for you.

• LLM does not call your tool: it checks tool descriptions and whether tool boundaries overlap.
• Tool is called with wrong arguments: it checks parameter types, required fields and enum values.
• ReAct loop runs forever or skips a step: it checks control flow, such as message history, tool_call_id and a max_iter limit.
• Designing a new tool: it walks you through a five-step schema method (Define, Describe, Type, Constrain, Error pattern).

How do you install the tool-calling-tutor skill?

You can install it in one of two ways. Download the ZIP from this page and unzip it into a skills folder. Use ~/.claude/skills/ to make it available to you across projects, or a project's .claude/skills/ folder to limit it to one project.

Alternatively, upload the skill in the Claude apps under Settings → Capabilities → Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload

How do you trigger the skill with a natural request?

The skill's description tells the agent when to load it, so you can simply describe the problem. The README also says you can open it directly with /tool-calling-tutor in Claude Code.

Name the symptom in your own words. If the symptom is clear, the skill goes straight to the matching branch. If it is not, the agent asks one multiple-choice question first.

• "My agent never calls the search tool; it answers in plain text."
• "The model passes temperature as a string and the call fails."
• "My ReAct loop keeps calling the same tool forever."
• "I'm writing a new tool and don't know how to design its schema."

What do you get back when it runs?

For a symptom about calling, the skill asks you to check tool descriptions for vague wording, overlapping tool boundaries and questions that need no tool at all. For arguments, it checks whether every parameter is typed as string when it should be a number, whether required fields are listed, and whether enums would narrow the values. For loops, it checks whether assistant responses go back into messages, whether tool results carry tool_call_id, and whether a max_iter cap exists.

The skill points to reference files for each branch, including a debug flowchart, a schema evolution worked example with bad and good versions, and a comparison of Anthropic and OpenAI-compatible tool-calling formats. It also points to example starters in the wider awesome-agentic-ai-zh repository.

What does it need from you, and what does it not do?

You need an existing tool-calling agent project or a plan for one, and access to whatever LLM SDK or model you use. The skill does not specify an SDK, so it asks which one you use, or checks tool-calling support with a fixed test input.

The skill routes away from framework-specific questions (LangChain, LangGraph, CrewAI, Pydantic AI), MCP server design, production monitoring and observability, and general prompt engineering. It is not meant for people with no agent project to debug, because its guidance assumes code and API responses.

• Requires: an agent project or plan, plus access to your LLM SDK or model
• Runs scripts: no
• Uses network: no
• Out of scope: frameworks, MCP server design, production observability and cost tracking, general prompting

Safety notes: scripts and network access

According to the skill's listing, it does not run scripts and does not use the network. Its files are Markdown reference notes, plus an evals folder with a check_evals.py script and an evals.json file. The check_evals.py script is in the package; the listing does not say it runs as part of normal use.

Because the skill is MIT licensed, you can read every file before installing it. Reading SKILL.md takes a few minutes and shows exactly what the agent will be told to do.

• Read SKILL.md and the references/ folder before installing.
• Treat the examples as starting points, and check any code you copy against your own SDK's documentation.

Tips for getting the most from it

Describe the exact symptom and paste the failing tool schema and a short example of the model's response. The skill's advice depends on the structure of the schema and the response shape, so concrete details help.

Write a mock-based test before connecting a real model. The skill recommends mocking the response shape of your SDK, keeping the model and settings the same for a fixed input, and only then testing against a live LLM. Keep your tool errors structured, with an error message and retry hint tied to the call ID, and let your application decide how many retries happen rather than the model.

• Give the agent the schema, the SDK you use and one failing example.
• Test with mocks first, then with a real model.
• Compare results using the same fixed input and settings each time.