前言¶
做数据分析、竞品调研或 RAG 资料准备时，Agent 往往需要「先拿到网页正文，再总结或入库」。手写 requests + 解析 HTML 能跑通，但搜索、整站爬取、反爬和格式清洗会占掉大量对话轮次。Firecrawl 本身是面向 AI 的 Web 数据 API；在 SkillHub 上，@user_b22a52ba/firecrawl 把调用方式、端点和示例代码整理成 Agent 可遵循的 SKILL.md，让模型在合适场景下按同一套约定去调 API。
下面介绍这个 Skill 的定位、能力与安装方式。
这是什么¶
Firecrawl Agent Skill（版本 2.0.0，坐标 @user_b22a52ba/firecrawl）是社区来源（community）的 data-analysis 类技能，简介为：Firecrawl Web 数据 API 技能，用于大规模搜索、抓取和与网络交互，将网页转化为干净的 Markdown 或结构化数据。
它在 SkillHub 由发布者 user_b22a52ba 维护；页面标注作者为 xiayutian。技能标签包含 requires_api_key=true，实际调用依赖 Firecrawl 的 API Key，而不是本地无密钥爬取。
核心功能¶
Skill 文档将 Firecrawl 能力归纳为与 https://api.firecrawl.dev 对应的 REST 接口（认证为 Authorization: Bearer <API_KEY>）：
| 能力 | 端点 | 说明 |
|---|---|---|
| Scrape | POST /v2/scrape |
单页抓取，可输出 Markdown、HTML、截图、链接等 |
| Search | POST /v2/search |
互联网搜索，返回带摘要/内容的结果列表 |
| Map | POST /v2/map |
列出站点内可抓取 URL（站点地图） |
| Crawl | POST /v2/crawl |
整站异步爬取，需用任务 ID 轮询状态 |
| Monitor | POST /v2/monitor |
监控网页或站点变化 |
此外，Skill 说明可通过 Scrape 请求的 extract 字段做结构化提取（自然语言 prompt，可选 JSON Schema），与「单页抓取」共用 /v2/scrape。
触发场景在 SKILL 中有明确描述：用户提到 Firecrawl、网页抓取、站点地图、整站爬取、网页监控，或提供 API Key 要求抓取/搜索时，Agent 应加载该技能并按文档调用。
安装与启用¶
方式一：让 Agent 按 SkillHub 指引安装¶
SkillHub 页面给出的提示为：根据 SkillHub 安装文档 安装 @user_b22a52ba/firecrawl。
方式二：SkillHub CLI¶
先确认本机是否已有 CLI：
command -v skillhub && skillhub --version
未安装时可按官方文档执行（完整安装示例）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
安装技能时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 且可能不被识别。Firecrawl 的安装命令为：
skillhub install @user_b22a52ba/firecrawl --dir <skills 目录>
常见客户端 skills 路径（摘自 SkillHub 安装文档）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下的.agents/skills/
装好后需按你所用客户端的要求重启或刷新，使新 Skill 生效。
API Key 配置¶
Skill 要求通过环境变量传入密钥：
export FIRECRAWL_API_KEY="你的_Firecrawl_API_Key"
不要在脚本或仓库里硬编码 Key；Firecrawl 为付费 API（文档注明有免费额度），每次调用消耗 credits。
典型用法¶
Skill 内提供可复用的 Python 调用模板：从环境变量读取 FIRECRAWL_API_KEY，BASE_URL 为 https://api.firecrawl.dev。
抓取单页为 Markdown（默认 formats 为 ["markdown"]）：
import os
import requests
FIRECRAWL_API_KEY = os.environ.get("FIRECRAWL_API_KEY", "")
BASE_URL = "https://api.firecrawl.dev"
HEADERS = {
"Authorization": f"Bearer {FIRECRAWL_API_KEY}",
"Content-Type": "application/json"
}
payload = {"url": "https://example.com", "formats": ["markdown"]}
resp = requests.post(f"{BASE_URL}/v2/scrape", headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()
print(resp.json())
搜索再深入：文档建议先用 Search 定位 URL，再对目标页 Scrape；整站场景可先 Map 看结构，再设定 Crawl 的 maxDepth 与 limit。Crawl 提交后返回任务 id，需请求 GET /v2/crawl/{id} 轮询结果。
结构化提取：对 /v2/scrape 传入 extract.prompt（及可选 extract.schema），从页面抽出字段，超时建议 60–90 秒。
成功时 Scrape 类响应在 Skill 中描述为 success + data（含 markdown、metadata 等）；Search 返回 data 数组，元素含 url、title、markdown、score 等字段。
适用场景与注意¶
适合谁：需要在 Agent 对话里稳定完成「搜网页 → 拉正文 → 转 Markdown / 结构化 JSON」的开发者；已持有或愿意申请 Firecrawl API Key 的团队。
限制与坑：
- 必须配置
FIRECRAWL_API_KEY，Skill 不会替代账号与计费。 - Crawl 为异步，不能只发 POST 就假定结果已就绪。
- 反爬站点可能仍失败或返回被混淆的正文，Skill 明确不保证 100% 成功。
- 控制
formats与请求范围，避免不必要的 credits 消耗。
SkillHub 侧当前统计（以页面抓取资料为准）：评分 100000，下载 2828，分类 data-analysis。
结尾¶
Firecrawl Skill 把 Firecrawl Web API 的端点、认证和 Python 示例收敛进一份 SKILL.md，方便 Cursor、Claude Code、Codex 等客户端在抓取与搜索场景下行为一致。安装与详情见 SkillHub：
- 技能页：https://www.skillhub.cn/skills/user_b22a52ba/firecrawl
- API 入口：https://api.skillhub.cn/user_b22a52ba/firecrawl
