Claude Agent 开发者必看：anthropic-agents Skill 的 6 大避坑指南
写 Claude Agent 之前，先把这张决策表看完
Claude Code 刚出来那会儿，我折腾了两周才搞明白：为什么同样写 tool definitions，用 JSON schema 和用 Python type hints，Claude 的行为完全不一样？为什么 tool_use_id 必须一字不差地 match？为什么 stop_reason 的判断能直接决定你的 agent 是在「思考」还是「死循环」？
后来我找到了这个 Skill——anthropic-agents，作者是 MattMagg。它不教你「怎么用 Claude」，而是直接告诉你「写 Claude Agent 必须绕开的坑」，以及「什么场景下该用什么模式」。
一张表解决选型问题
这个 Skill 最核心的是一个决策框架表：
- 基础 tool use → 用
"claude tool definition"模式 - 需要循环执行 → 用
"claude agentic loop"，一直跑到 stop_reason 不是 tool_use - 要操控电脑/GUI → 用
"claude computer use"，但必须带 beta header - 复杂推理任务 → 用
"claude extended thinking" - 多轮对话上下文 → 用
"claude conversation history"
每个模式背后都对应一个 RAG Query，直接查文档，不用自己试错。
6 个 Claude 专属陷阱
这些坑你但凡踩过一个，就会明白为什么这个 Skill 存在：
- Tool schemas 必须用 JSON Schema——不是 Python type hints，格式不对 Claude 根本不认识你的 tool
- tool_use vs tool_result——调用是 tool_use，返回是 tool_result，发出去时必须带 exact tool_use_id
- ANTHROPIC_API_KEY——这个环境变量名是固定的，写错一个字都不认
- Max tokens 必须指定——不然 Claude 不知道什么时候该停
- stop_reason 必须检查——不判断这个，你的 agent 永远不会正常退出
- Computer use 需要 beta header——少了这个，截图功能全挂
5 步构建 Claude Agent 工作流
Skill 里给了一套完整的从零搭建流程：
- SDK Setup — 查 RAG 装 Anthropic Python SDK
- Tool Schema Definition — 定义 name、description、input_schema（必须是 JSON Schema 格式）
- Message Construction — 构建 messages 和 tool_choice
- Tool Response Handling — 用 tool_result 的 content block 响应，tool_use_id 必须 match
- Agentic Loop — 循环直到 stop_reason 不是 tool_use
每一步都有对应的 RAG Query，直接调用 agentic-rag-sdk 查文档，不用翻官方 wiki。
错误模式对照表
Skill 还附了一个常见错误表，格式是「症状 → 原因 → RAG Query」，拿来 debug 效率很高：
- Tool 没被调用 → 查
"tool input_schema" - Tool 响应被忽略 → 查
"tool_result matching" - Loop 停不下来 → 查
"stop_reason end_turn" - Rate limit 报错 → 查
"anthropic rate limits" - Schema 校验失败 → 查
"json schema tool"
值得关注的两个高级特性
Computer Use 和 Extended Thinking 是 Claude 区别于其他模型的特殊能力。Computer Use 需要 beta header 和截图处理；Extended Thinking 则适合复杂的多步推理。这两个场景在 Skill 里都有对应的 RAG Query 和配置说明。
这个 Skill 的价值不在于教你概念，而在于把 MattMagg 上百小时的踩坑经验整理成了一套拿来就用的决策表和错误对照表。写 Claude Agent 之前过一遍，能省很多调试时间。
GitHub 仓库 · AI & ML · Smithery
评论区
登录后可评论。