Tavily Skill
Tavily 的 /search、/extract、/crawl、/map、/research 五个核心 endpoint 各自的参数、计费和状态码规则都不共用同一套心智模型，直接照搬其他搜索或抓取 API 的经验很容易踩坑。最典型的两个坑：`max_results` 的默认值在官方 OpenAPI 规范、Best Practices 页和 CLI 文档里给出三种不一致的说法（10 vs 5）；`/research` 创建任务成功返回 201、结果还在跑时轮询返回 202、任务完成或失败都返回 200，只看状态码会把跑完但失败的任务误判成功。
安装
选你用的 Agent，复制命令。
npx -y skills add fxp/skillify --skill tavily --agent claude-code --yes装到项目的 .claude/skills/；加 -g 装到全局。装完需要你手动执行 /reload-plugins，这一步 Agent 代劳不了。
npx -y skills add fxp/skillify --skill tavily --agent codex --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill tavily --agent cursor --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill tavily --agent opencode --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill tavily --agent gemini-cli --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill tavily --agent github-copilot --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill tavily --agent trae --yes装到项目的 .trae/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill tavily --agent windsurf --yes装到项目的 .windsurf/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill tavily --agent qwen-code --yes把 --agent 换成你用的 Agent 标识，可以一次写多个。skills CLI 1.5.25 共支持 79 个，例如 qwen-code、kimi-code-cli、trae-cn、qoder、lingma、cline、roo。
或者让 Agent 自己装
读 https://github.com/fxp/skillify/blob/main/skills/tavily/prompt.md 并照它执行装对了的标志：references/ 下有 5 份文档。
装好后，可以这样问你的 Agent
这份 Skill 覆盖的典型任务。点一下复制。
5 类能力
每类能力对应一份 reference，Agent 按任务只打开需要的那份。
网页搜索
POST /search 全部参数、search_depth 四档的费用与内容形态、时间 / 域名 / 语言过滤、keyless 访问
内容抽取与整站爬取
POST /extract 批量抽正文、POST /crawl 整站遍历、POST /map 只拿 URL 清单，以及和 Firecrawl 的选型边界
深度研究
POST /research 创建多步骤研究任务、GET /research/{request_id} 轮询状态、流式 SSE 输出与动态区间计费
SDK / CLI / MCP 接入
Python / JavaScript SDK、tvly CLI、远程与本地 MCP Server、keyless 与 x402 按次付费
错误码与限流
鉴权范围、速率限制分档、Credits 计费总表、HTTP 错误码、GET /usage 与 POST /logs 查用量
当前事实
整理自官方文档（抓取于 2026-09-21），还没有用真实凭证验证。
| 项 | 值 |
|---|---|
| Base URL | https://api.tavily.com；文档站 docs.tavily.com、控制台 app.tavily.com、MCP mcp.tavily.com、x402 x402.tavily.com 都是不同域名，不要混用 |
| 鉴权 | Authorization: Bearer tvly-YOUR_API_KEY；唯一例外是 POST /org-usage，必须用组织owner 本人的个人 key，传团队 / 企业 key 会 403 |
| 最容易选错 | search_depth 四档：basic/fast/ultra-fast 各 1 credit，advanced 2 credits，返回内容形态也不同（整页摘要 vs 重排序分块） |
| Keyless 访问 | header X-Tavily-Access-Mode: keyless，仅 /search、/extract 支持，/crawl//map//research 必须用真实 key |
| 速率限制 | /crawl 创建固定 100 RPM、/research 创建固定 20 RPM，不随开发 / 生产 key 升档；/search//extract//map 才会从 100 跳到 1000 RPM |
照通用经验写容易错的 6 件事
来自官方文档，还没有用真实凭证验证。
- auto_parameters 可能悄悄把请求从 1 credit 升到 2 credit。开启后 Tavily 可能把
search_depth自动升级到advanced，官方只在最佳实践页提了一句；只关心成本可预测性时，auto_parameters和显式设置search_depth二选一，不要两个都不设。 - content 和 raw_content 在 Search 与 Extract/Crawl 里含义相反。Search 里
results[].raw_content默认为null，要显式传include_raw_content: true才有值；Extract/Crawl 里正文字段就叫raw_content且默认返回，跨 endpoint 套用同一套字段语义会出错。 - HTTP 200 不代表全部抽取成功。官方原文："HTTP 200 can have an empty results array when all valid URLs fail during extraction"，
/extract、/crawl必须同时检查results和failed_results两个数组，失败的 URL 从不计费。 - /research 的状态码不按常规 REST 套路走。创建任务成功是
201不是 200；轮询GET /research/{request_id}未完成时返回202，完成和失败都返回200——要判断结果必须读 body 里的status字段，不能只看状态码。 - Crawl 的费用是 Map 部分和 Extract 部分独立叠加的。公式是
Crawl Cost = Mapping Cost + Extraction Cost：instructions只让 mapping 那半从 1 credit/10 页 翻倍到 2 credit/10 页，extract_depth=advanced只让 extraction 那半翻倍，两个开关同时打开费用会叠加，不能线性估算。 - max_results 的默认值文档三处说法不一致。OpenAPI 规范和 Python SDK 参数表都写默认
10，官方 Best Practices 页和 CLI 选项表却写默认5；保守写法是永远显式传max_results，不要依赖默认值。