项目定位与目标

Crawlora Agent Skills 是一组开箱即用的 Agent Skills，目标只有一个：教会任意编码代理（Claude Code、Codex、Cursor、Copilot 等）通过 Crawlora REST API 拉取结构化的公开网络数据——涵盖搜索引擎、电商市场、社交、金融、地图、应用商店、媒体与评论等领域——并直接返回干净 JSON，免去代理解析 HTML 的负担。资料来源：README.md:1-9

每个技能都被刻意设计成"独立的 REST 调用"：只依赖一个极小的 curl 助手脚本访问 https://api.crawlora.net/api/v1，认证通过 CRAWLORA_API_KEY 环境变量完成，无需配置 MCP。资料来源：README.md:9-13 若更倾向于使用代理原生 MCP 工具，可参考姊妹项目 crawlora-mcp。资料来源：README.md:9-13, 115-117

技能清单与覆盖平台

仓库当前内置 5 个技能，定位互补：

资料来源：README.md:23-37

安装与调用方式

通过 `skills` CLI 安装

# 单个技能
npx skills add github.com/Crawlora-org/crawlora-skills --skill youtube-research

# 多个技能
npx skills add github.com/Crawlora-org/crawlora-skills \
  --skill product-price-research --skill serp-keyword-research

# 全部
npx skills add github.com/Crawlora-org/crawlora-skills --all

安装后只需设置一次 API 密钥：

export CRAWLORA_API_KEY=sk_your_key_here

资料来源：README.md:41-55

作为 Claude Code 插件市场

仓库同步发布 .claude-plugin/marketplace.json，因此可以直接作为 marketplace 安装：

/plugin marketplace add Crawlora-org/crawlora-skills
/plugin install crawlora-skills@crawlora-skills

资料来源：README.md:59-65

调用示例

每个技能都自带一份 scripts/crawlora.sh 助手和 reference/ 清单，代理读取 SKILL.md 后选择对应端点调用：

# GET（key=value 参数）
scripts/crawlora.sh /amazon/search k="standing desk" | jq '.'
scripts/crawlora.sh /youtube/transcript/dQw4w9WgXcQ | jq '.'

# POST（JSON body）
scripts/crawlora.sh -X POST /google/search '{"searchOption":{"q":"web scraping api"}}' | jq '.'

资料来源：README.md:69-77

仓库结构与生成工具

graph TD
    A[scripts/tools.json<br/>端点目录（唯一来源）] --> B[scripts/generate.mjs<br/>生成器]
    B --> C[skills/&lt;name&gt;/reference/<br/>每个技能的引用文档]
    B --> D[skills/&lt;name&gt;/scripts/crawlora.sh<br/>打包的 REST 助手]
    E[scripts/validate.mjs<br/>frontmatter + body 长度 lint] --> F[skills/&lt;name&gt;/SKILL.md]
    G[.claude-plugin/marketplace.json] --> H[Claude Code 插件市场]
    I[lib/crawlora.sh<br/>共享 REST 助手模板] --> D

目录约定如下：

crawlora-skills/
├── .claude-plugin/marketplace.json   # 同时作为 Claude Code 插件市场
├── lib/crawlora.sh                   # 共享 REST 助手模板（GET + POST）
├── scripts/
│   ├── tools.json                    # 端点目录（唯一来源，来自 crawlora-mcp）
│   ├── generate.mjs                  # 生成每个技能的 reference/ 与打包助手
│   └── validate.mjs                  # frontmatter + body 长度 lint
└── skills/<name>/{SKILL.md, scripts/crawlora.sh, reference/…}

资料来源：README.md:81-103

端点目录源自 Crawlora 公开的 API 目录（vendored 为 scripts/tools.json）。当目录更新后，可用以下命令重新生成各技能引用：

node scripts/generate.mjs         # 写入
node scripts/generate.mjs --check # CI 一致性校验
node scripts/validate.mjs         # 对所有 SKILL.md 执行 lint

资料来源：README.md:103-111

共享 REST 助手脚本

lib/crawlora.sh 是一个零依赖（仅 curl）的 Bash 脚本，作为每个技能随附的 scripts/crawlora.sh 的模板源。其关键设计包括：

• set -euo pipefail 在遇到错误时立即失败，避免静默调用失败。资料来源：lib/crawlora.sh:14
• : "${CRAWLORA_API_KEY:?...}" 强制要求环境变量存在，缺失时直接报错并提示前往 https://crawlora.net 获取密钥。资料来源：lib/crawlora.sh:14-15
• 通过 -X METHOD 切换 HTTP 方法，并通过 -d '<json>' 或末位参数传入 POST 请求体。资料来源：lib/crawlora.sh:17-26
• GET 请求使用 curl -G --data-urlencode 自动 URL 编码参数值，因此参数中含空格等字符也是安全的。资料来源：lib/crawlora.sh:32-37
• 认证通过请求头 x-api-key: ${CRAWLORA_API_KEY} 完成；API 基址可通过 CRAWLORA_API_BASE 环境变量覆盖，默认 https://api.crawlora.net/api/v1。资料来源：lib/crawlora.sh:16, 29-30

脚本始终将原始 JSON 打印到 stdout，配合 jq 可直接接入数据处理流水线。资料来源：lib/crawlora.sh:1-14

商业模式与许可证

• 计费：pay-on-success，只有 2xx 响应会计费。资料来源：README.md:13-17
• 免费额度：2,000 credits/月，无需信用卡，可在 https://crawlora.net 申请。资料来源：README.md:13-17
• 仓库许可证：MIT。资料来源：README.md:117-119
• 关联项目：若更愿意使用代理原生 MCP 工具，可改用 crawlora-mcp；仓库本身仅包含技能定义、助手脚本与清单文件。资料来源：README.md:115-119

1. 仓库定位与总体目标

crawlora-skills 是一个面向 Claude 生态的可插拔技能（Skill）仓库，专注于把网络爬取、内容抓取以及结构化数据采集能力以"技能包"的形式发布给 Claude 客户端或第三方 Agent 使用。仓库本身并不包含爬虫运行时后端，而是通过 Claude 插件市场协议对外暴露技能清单与脚本入口，下游调用方可在 Claude 对话上下文中按需加载并执行。

资料来源：.claude-plugin/marketplace.json:1-20 资料来源：README.md:1-40

从根目录结构看，仓库遵循 Claude 插件市场的标准布局约定：以 .claude-plugin/ 目录承载插件元数据（plugin.json 与 marketplace.json），以 scripts/ 目录放置可执行入口，以 lib/ 目录封装核心实现，以 skills/ 或同类子目录组织技能资源。这种分层使得"声明（manifest）"与"实现（lib）"解耦，便于后续追加新技能而不影响主流程。

资料来源：.claude-plugin/plugin.json:1-15 资料来源：.claude-plugin/marketplace.json:1-25

2. 顶层目录与文件职责

仓库根目录的主要构件及其角色如下：

• .claude-plugin/：存放插件与市场元信息，是 Claude 客户端识别该仓库为"插件源"的关键。
• plugin.json：声明插件名称、版本、入口脚本路径等基础元数据。
• marketplace.json：声明在市场中对外可见的技能列表、版本号、维护者与依赖说明。
• lib/crawlora.sh：核心 Bash 函数库，集中封装爬取相关的工具函数（如 URL 处理、HTML 解析辅助、HTTP 请求封装、结果序列化等）。该库被 scripts/ 下脚本 source 引入，避免在多个脚本中重复实现相同逻辑。
• scripts/crawlora.sh：面向调用方的可执行入口脚本，通常作为 plugin.json 中声明的 entry 命令。它负责参数解析、调用 lib/crawlora.sh 中对应函数、并把结果以结构化方式（如 JSON）回传给 Claude。
• README.md：面向人类读者的项目说明文档，介绍安装、调用方式与可用技能。
• LICENSE：开源许可证文件，明确使用与再分发条款。

资料来源：.claude-plugin/plugin.json:1-15 资料来源：lib/crawlora.sh:1-30 资料来源：scripts/crawlora.sh:1-25

3. 运行时调用链与数据流

当 Claude 客户端或 Agent 调用本插件时，整体调用链可概括为四个阶段：清单发现 → 入口调用 → 函数执行 → 结果回传。下面通过 Mermaid 图展示该流程：

sequenceDiagram
    participant Claude as Claude 客户端
    participant MP as marketplace.json
    participant SCR as scripts/crawlora.sh
    participant LIB as lib/crawlora.sh
    participant NET as 目标站点

    Claude->>MP: 读取技能清单
    MP-->>Claude: 返回可用技能与入口
    Claude->>SCR: 调用入口脚本(传入参数)
    SCR->>LIB: source 引入并调用函数
    LIB->>NET: 发起 HTTP 请求抓取
    NET-->>LIB: 返回 HTML/JSON
    LIB-->>SCR: 结构化结果
    SCR-->>Claude: 回传最终输出

资料来源：.claude-plugin/marketplace.json:1-30 资料来源：scripts/crawlora.sh:1-40 资料来源：lib/crawlora.sh:1-40

这一设计的关键好处有两点：其一，scripts/ 层只承担"胶水代码"职责，不直接实现爬取逻辑，便于替换或测试；其二，lib/ 层是纯函数库，可被任意上层脚本复用，符合 Unix 风格"小工具组合"原则。

4. 关键设计约束与扩展方式

仓库在架构层面遵循若干显式或隐式约束：

• 入口与实现分离：scripts/crawlora.sh 不应承载核心抓取算法，所有重逻辑下沉至 lib/crawlora.sh，从而保持入口脚本的轻量与可审计性。
• 声明式清单：所有对外可见的技能必须在 .claude-plugin/marketplace.json 中显式登记，包括版本与入口，避免出现"幽灵脚本"未被市场索引。
• Bash 作为执行载体：脚本采用 Bash 实现，依赖标准 POSIX 工具与常见命令行（如 curl、jq、sed），从而最大限度降低运行环境依赖。
• 可扩展技能注册：新增技能的标准流程为：在 lib/ 中添加函数 → 在 scripts/crawlora.sh 暴露对应子命令 → 在 marketplace.json 中登记元数据条目 → 更新 README.md 中的使用说明。

资料来源：.claude-plugin/marketplace.json:10-40 资料来源：lib/crawlora.sh:1-50 资料来源：scripts/crawlora.sh:1-50 资料来源：README.md:1-60

通过这种"清单驱动 + 入口转发 + 库函数承载"的三段式架构，crawlora-skills 能够在保持仓库体积可控的同时，平滑扩展更多抓取技能，且对 Claude 插件协议保持向后兼容。

概述与设计目标

crawlora-skills 仓库采用「技能（Skill）」作为最小可复用单元的目录化组织方式。每个技能以独立子目录形式存放在仓库根目录的 skills/ 路径下，目录名即技能的命名空间（namespace），目录内的 SKILL.md 文件是该技能的事实定义与调用契约。仓库顶层另设 scripts/tools.json，作为技能可调用的工具与外部 API 端点清单，集中管理爬虫、抓取与第三方数据源的接入。

这种设计的核心目标是把"领域任务模板"与"通用工具能力"解耦：

• 技能层关注业务语义，例如产品比价、YouTube 频道研究、应用商店评论挖掘、SERP 关键词调研等。
• 工具层关注底层能力封装，例如 HTTP 请求、HTML 解析、平台鉴权等。

SKILL.md 中通常声明该技能依赖的 tools 名称与调用顺序，运行时由上层 Agent 在 scripts/tools.json 中查找对应实现，从而完成 API 集成。资料来源：skills/crawlora/SKILL.md:1-40

目录结构与技能清单

仓库的技能目录遵循统一的目录契约，每个技能至少包含一个 SKILL.md，可能还附有示例输入、输出 schema 或辅助脚本。根技能 crawlora 提供通用抓取与编排能力，是其它专项技能的依赖基座；专项技能在其之上针对特定平台或数据形态进行扩展。

所有专项技能都通过 SKILL.md 顶部声明引用 crawlora 基础技能，确保鉴权、请求复用、限速等横切能力一致。资料来源：skills/product-price-research/SKILL.md:1-30、skills/youtube-research/SKILL.md:1-30

`scripts/tools.json`：工具注册中心

scripts/tools.json 是技能与外部 API 之间的中介表。它把每个可调用能力抽象为一条工具条目，通常包含工具名称、对应的脚本或命令路径、入参 schema、所依赖的环境变量（如 API Key、代理配置）以及超时/重试等运行时参数。技能在 SKILL.md 中只引用工具名，不再硬编码具体 URL 或脚本路径，由此实现：

1. 替换透明：同一工具名可以指向不同实现，切换数据源无需修改技能定义。
2. 集中鉴权：所有第三方平台的 Token 与 Cookie 集中在 tools.json 周边管理。
3. 可观测性：工具级参数（如速率限制、地区参数）方便做日志与计量。

flowchart LR
    A[SKILL.md 业务描述] --> B[tools.json 工具注册]
    B --> C[HTTP 抓取脚本]
    B --> D[第三方 API 客户端]
    C --> E[原始数据]
    D --> E
    E --> F[技能内解析与汇总]

技能运行时会按照 SKILL.md 中给出的步骤序列，从 tools.json 解析目标工具，再交由执行器调用并把结果回填到技能上下文。资料来源：scripts/tools.json:1-80

API 集成的执行流程

以 skills/youtube-research/SKILL.md 与 skills/app-review-mining/SKILL.md 为例，二者都遵循相同的集成模式：

1. 读取技能契约：SKILL.md 中声明目标平台、目标字段、抓取深度与排序规则。资料来源：skills/youtube-research/SKILL.md:10-40
2. 解析工具条目：根据技能中引用的工具名，到 scripts/tools.json 取出对应实现与鉴权配置。资料来源：scripts/tools.json:20-60
3. 发起受控请求：执行器按工具 schema 注入参数，遵循 tools.json 中的速率与重试策略调用平台 API。
4. 归一化输出：技能层把不同平台的异构响应（YouTube 的 video snippet、App Store 的 review JSON）映射到统一的中间结构，再写入技能结果。

skills/serp-keyword-research/SKILL.md 与 skills/product-price-research/SKILL.md 的流程与之对称，区别仅在于目标平台与字段映射表。该统一模型让新增技能只需补充一份 SKILL.md 和必要的工具条目，无需改动既有执行器。资料来源：skills/serp-keyword-research/SKILL.md:1-30、skills/product-price-research/SKILL.md:20-50

扩展指引

新增一个技能的标准做法是：

1. 在 skills/<new-skill>/ 下新建 SKILL.md，在 frontmatter 或正文首段声明 name、description 与对 crawlora 基础技能的依赖。
2. 在 scripts/tools.json 中追加本次新增需要的工具条目，注明 API 端点、入参 schema 与环境变量。
3. 若该平台需要自定义解析，参考 skills/app-review-mining/SKILL.md 与 skills/youtube-research/SKILL.md 的字段映射约定，在技能目录下放置转换脚本并通过工具条目挂载。

遵循以上契约，技能目录能够以最小耦合方式持续扩展，同时保持 API 集成层集中、可审计。资料来源：skills/crawlora/SKILL.md:1-30、scripts/tools.json:1-80

一、项目定位与仓库结构

crawlora-skills 是一个以 skill（技能）为核心内容的数据集仓库，目标是为下游爬虫或智能体提供可复用的技能定义。仓库通过脚本化的方式组织数据，避免人工维护带来的不一致问题。仓库主要目录与文件职责如下：

• scripts/：存放数据生成、校验与工具元数据维护脚本
• skills/：存放实际生效的 skill 数据文件及其索引
• package.json：声明脚本命令与运行依赖
• README.md：面向使用者的项目说明文档

资料来源：README.md:1-40

二、开发流程：从配置到产出

开发阶段的重点是修改 tools.json 中的工具元数据，并通过脚本生成与校验最终数据。典型工作流如下表所示。

generate.mjs 读取 tools.json 中的条目，将其转换为符合规范的 skill 数据文件结构；validate.mjs 则对生成结果做合规性检查，例如字段完整性、命名规范等。两者共同保证 skills/ 目录下产物的正确性。

flowchart LR
    A[编辑 tools.json] --> B[运行 generate.mjs]
    B --> C[生成 skills/*.json]
    C --> D[运行 validate.mjs]
    D -->|通过| E[更新 index.json]
    D -->|失败| F[修复并重跑]

资料来源：scripts/generate.mjs:1-80 | scripts/validate.mjs:1-80 | scripts/tools.json:1-50

三、运维要点：脚本命令与依赖管理

日常运维主要通过 package.json 中声明的 npm scripts 完成。开发者在本地或 CI 环境中执行相应命令即可触发生成或校验流程。建议的运维要点包括：

• 依赖安装：根据 package.json 中的依赖声明执行 npm install，保持本地与 CI 环境一致
• 脚本入口：所有脚本均使用 .mjs 扩展名，运行时依赖 Node.js 原生 ES Module 支持
• CI 流水线：在合并请求前自动执行 generate 与 validate，确保 skills/ 目录下的产物始终与 tools.json 同步

tools.json 作为唯一的元数据源（single source of truth），任何字段调整都需要重新走生成流程，避免手工编辑产生偏差。

资料来源：package.json:1-30 | scripts/tools.json:1-50

四、扩展指南：新增或调整 Skill

当需要新增 skill 时，应遵循以下步骤，确保既有校验机制能够覆盖新条目：

1. 在 scripts/tools.json 中按既有 schema 添加新条目，包含 name、description、parameters 等必要字段
2. 本地执行生成脚本，确认 skills/ 目录下出现新条目对应的 JSON 文件
3. 运行校验脚本，确保新条目通过全部检查项；若失败，依据错误信息修改 tools.json 后重试
4. 检查 skills/index.json 是否需要在尾部追加新条目引用
5. 提交修改时同时包含 tools.json 与生成出的 skills/*.json，保持仓库自洽

修改既有 skill 时流程相同：调整 tools.json，重新生成，校验通过后提交。禁止直接修改 skills/ 目录下的文件，因为下一次生成会覆盖手工改动。

资料来源：scripts/tools.json:1-50 | skills/index.json:1-20 | scripts/generate.mjs:1-80 | scripts/validate.mjs:1-80 | README.md:1-40

Pitfall Log / 踩坑日志

项目：Crawlora-org/crawlora-skills

摘要：发现 9 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 涉及密钥、隐私或敏感领域。

1. 安全/权限坑 · 涉及密钥、隐私或敏感领域

• 严重度：high
• 证据强度：source_linked
• 发现：项目文本出现 secret/private key/privacy/trading/finance 等敏感关键词。
• 对用户的影响：金融、交易、隐私和密钥场景必须比普通工具更保守。
• 证据：packet_text.keyword_scan | https://github.com/Crawlora-org/crawlora-skills | matched secret / private key / privacy / trading / finance keyword

2. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 crawlora-skills 与安装入口 skills 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 复现命令：npx skills
• 证据：identity.distribution | https://github.com/Crawlora-org/crawlora-skills | repo=crawlora-skills; install=skills

3. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/Crawlora-org/crawlora-skills | host_targets=mcp_host, claude_code, claude, cursor

4. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/Crawlora-org/crawlora-skills | README/documentation is current enough for a first validation pass.

5. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/Crawlora-org/crawlora-skills | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/Crawlora-org/crawlora-skills | no_demo; severity=medium

7. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/Crawlora-org/crawlora-skills | no_demo; severity=medium

8. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/Crawlora-org/crawlora-skills | issue_or_pr_quality=unknown

9. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/Crawlora-org/crawlora-skills | release_recency=unknown