Teaching Agents Your Local Tools
One of the highest-leverage agent workflows is simple: teach the agent how your local tools work.
You often do not need a custom extension. If a tool has --help, examples, man pages, or internal docs, the agent can inspect them and learn enough to use the tool in the current task.
Tool Learning Prompt
Section titled “Tool Learning Prompt”Learn how to use `acme-cli` for this repository.
Start with:- `acme-cli --help`- `acme-cli deploy --help`- any docs under `docs/deployment/`
Do not run mutating commands.Summarize the safe read-only commands, the dangerous commands, and the exact command you would use for a dry run.This gives the agent permission to learn while keeping execution boundaries clear.
The Tool Onboarding Loop
Section titled “The Tool Onboarding Loop”- Point the agent to the tool entrypoint.
- Let it inspect help output and local docs.
- Ask it to classify safe, risky, and destructive commands.
- Run a read-only or dry-run command first.
- Save durable learning in the right place.
Where To Save What The Agent Learns
Section titled “Where To Save What The Agent Learns”| Knowledge type | Best home | Example |
|---|---|---|
| Always true project commands | CLAUDE.md | build, test, lint, repo conventions |
| Personal preferences | CLAUDE.local.md or user memory | local paths, preferred aliases |
| Repeatable procedure | skill | release workflow, incident checklist |
| Human-invoked shortcut | slash command | /fix-issue, /draft-release-note |
| External system integration | MCP server | issue tracker, database, docs, browser |
| Mandatory enforcement | hook or settings rule | block unsafe migrations, run lint after edits |
Do not put every tool manual into CLAUDE.md. Keep always-loaded memory short. Long procedures belong in skills or docs that the agent loads only when needed.
Safety Rules
Section titled “Safety Rules”- Ask for dry-run or read-only commands first.
- Do not allow broad shell patterns for cloud or database tools.
- Keep destructive commands behind explicit approval.
- Use least-privilege credentials for agent-accessible CLIs.
- Treat generated shell commands as code review material.
- Save exact commands that worked, not vague descriptions.
Example: Saving A Learned Tool Pattern
Section titled “Example: Saving A Learned Tool Pattern”After the agent successfully uses a tool:
Add a concise note to CLAUDE.md with:- the command to run focused tests- the command to run a safe deployment dry run- the command that must never be run without approval
Keep it under 10 lines.For a longer workflow:
Create a skill for this release process instead of expanding CLAUDE.md.The skill should include prerequisites, dry-run checks, approval points,and rollback verification.When MCP Is Worth It
Section titled “When MCP Is Worth It”Use MCP when the agent needs structured, repeated access to a system:
- issue tracker state
- internal docs
- database queries
- monitoring dashboards
- browser automation
- design files
For one-off local commands, a CLI plus good instructions is often enough.