# https://github.com/Crawlora-org/crawlora-skills 项目说明书 生成时间：2026-07-19 07:05:57 UTC ## 目录 - [Crawlora Agent Skills 项目概览](#page-1) - [系统架构与仓库结构](#page-2) - [技能目录与 API 集成](#page-3) - [开发、运维与扩展指南](#page-4) ## Crawlora Agent Skills 项目概览 ### 相关页面 相关主题：[系统架构与仓库结构](#page-2), [技能目录与 API 集成](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Crawlora-org/crawlora-skills/blob/main/README.md) - [lib/crawlora.sh](https://github.com/Crawlora-org/crawlora-skills/blob/main/lib/crawlora.sh) - [.claude-plugin/marketplace.json](https://github.com/Crawlora-org/crawlora-skills/blob/main/.claude-plugin/marketplace.json) - [scripts/tools.json](https://github.com/Crawlora-org/crawlora-skills/blob/main/scripts/tools.json) - [scripts/generate.mjs](https://github.com/Crawlora-org/crawlora-skills/blob/main/scripts/generate.mjs) - [scripts/validate.mjs](https://github.com/Crawlora-org/crawlora-skills/blob/main/scripts/validate.mjs)
# Crawlora Agent Skills 项目概览 ## 项目定位与目标 Crawlora Agent Skills 是一组开箱即用的 [Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)，目标只有一个：教会任意编码代理（Claude Code、Codex、Cursor、Copilot 等）通过 [Crawlora](https://crawlora.net) 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`](https://github.com/Crawlora-org/crawlora-mcp)。资料来源：[README.md:9-13, 115-117]() ## 技能清单与覆盖平台 仓库当前内置 5 个技能，定位互补： | 技能 | 主要能力 | 覆盖平台 | |---|---|---| | [`crawlora`](skills/crawlora) | 总览目录技能，可访问任意 733 个 Crawlora 端点；包含认证、计费与完整目录说明 | 全部 61 个平台 | | [`product-price-research`](skills/product-price-research) | 商品搜索、比价、商家与市场评论 | Amazon、eBay、Shopify、Shop.app | | [`youtube-research`](skills/youtube-research) | 视频字幕、评论、频道元数据与搜索（无需 `yt-dlp`） | YouTube | | [`app-review-mining`](skills/app-review-mining) | 应用详情、评论、评分、榜单与相似应用（ASO） | App Store、Google Play | | [`serp-keyword-research`](skills/serp-keyword-research) | SERP 快照、自动补全关键词、谷歌趋势 | Google、Bing、Brave、Google Trends | 资料来源：[README.md:23-37]() ## 安装与调用方式 ### 通过 `skills` CLI 安装 ```bash # 单个技能 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 密钥： ```bash export CRAWLORA_API_KEY=sk_your_key_here ``` 资料来源：[README.md:41-55]() ### 作为 Claude Code 插件市场 仓库同步发布 [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json)，因此可以直接作为 marketplace 安装： ```text /plugin marketplace add Crawlora-org/crawlora-skills /plugin install crawlora-skills@crawlora-skills ``` 资料来源：[README.md:59-65]() ### 调用示例 每个技能都自带一份 `scripts/crawlora.sh` 助手和 `reference/` 清单，代理读取 `SKILL.md` 后选择对应端点调用： ```bash # 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]() ## 仓库结构与生成工具 ```mermaid graph TD A[scripts/tools.json
端点目录（唯一来源）] --> B[scripts/generate.mjs
生成器] B --> C[skills/<name>/reference/
每个技能的引用文档] B --> D[skills/<name>/scripts/crawlora.sh
打包的 REST 助手] E[scripts/validate.mjs
frontmatter + body 长度 lint] --> F[skills/<name>/SKILL.md] G[.claude-plugin/marketplace.json] --> H[Claude Code 插件市场] I[lib/crawlora.sh
共享 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//{SKILL.md, scripts/crawlora.sh, reference/…} ``` 资料来源：[README.md:81-103]() 端点目录源自 Crawlora 公开的 API 目录（vendored 为 `scripts/tools.json`）。当目录更新后，可用以下命令重新生成各技能引用： ```bash 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 ''` 或末位参数传入 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`](https://github.com/Crawlora-org/crawlora-mcp)；仓库本身仅包含技能定义、助手脚本与清单文件。资料来源：[README.md:115-119]() --- ## 系统架构与仓库结构 ### 相关页面 相关主题：[Crawlora Agent Skills 项目概览](#page-1), [技能目录与 API 集成](#page-3), [开发、运维与扩展指南](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [.claude-plugin/marketplace.json](https://github.com/Crawlora-org/crawlora-skills/blob/main/.claude-plugin/marketplace.json) - [lib/crawlora.sh](https://github.com/Crawlora-org/crawlora-skills/blob/main/lib/crawlora.sh) - [scripts/crawlora.sh](https://github.com/Crawlora-org/crawlora-skills/blob/main/scripts/crawlora.sh) - [.claude-plugin/plugin.json](https://github.com/Crawlora-org/crawlora-skills/blob/main/.claude-plugin/plugin.json) - [README.md](https://github.com/Crawlora-org/crawlora-skills/blob/main/README.md) - [LICENSE](https://github.com/Crawlora-org/crawlora-skills/blob/main/LICENSE)
# 系统架构与仓库结构 ## 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 图展示该流程： ```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 插件协议保持向后兼容。 --- ## 技能目录与 API 集成 ### 相关页面 相关主题：[Crawlora Agent Skills 项目概览](#page-1), [系统架构与仓库结构](#page-2), [开发、运维与扩展指南](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [scripts/tools.json](https://github.com/Crawlora-org/crawlora-skills/blob/main/scripts/tools.json) - [skills/crawlora/SKILL.md](https://github.com/Crawlora-org/crawlora-skills/blob/main/skills/crawlora/SKILL.md) - [skills/product-price-research/SKILL.md](https://github.com/Crawlora-org/crawlora-skills/blob/main/skills/product-price-research/SKILL.md) - [skills/youtube-research/SKILL.md](https://github.com/Crawlora-org/crawlora-skills/blob/main/skills/youtube-research/SKILL.md) - [skills/app-review-mining/SKILL.md](https://github.com/Crawlora-org/crawlora-skills/blob/main/skills/app-review-mining/SKILL.md) - [skills/serp-keyword-research/SKILL.md](https://github.com/Crawlora-org/crawlora-skills/blob/main/skills/serp-keyword-research/SKILL.md)
# 技能目录与 API 集成 ## 概述与设计目标 `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` 提供通用抓取与编排能力，是其它专项技能的依赖基座；专项技能在其之上针对特定平台或数据形态进行扩展。 | 技能路径 | 业务定位 | 典型 API / 数据源 | | --- | --- | --- | | `skills/crawlora/` | 通用抓取与技能编排入口 | 内部 crawlora 接口 | | `skills/product-price-research/` | 商品价格调研 | 电商平台搜索/详情 API | | `skills/youtube-research/` | YouTube 频道与视频研究 | YouTube Data API | | `skills/app-review-mining/` | 应用商店评论挖掘 | App Store / Google Play 抓取接口 | | `skills/serp-keyword-research/` | 搜索结果页关键词研究 | SERP 抓取与第三方 SEO API | 所有专项技能都通过 `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. **可观测性**：工具级参数（如速率限制、地区参数）方便做日志与计量。 ```mermaid 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//` 下新建 `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]() --- ## 开发、运维与扩展指南 ### 相关页面 相关主题：[系统架构与仓库结构](#page-2), [技能目录与 API 集成](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [scripts/generate.mjs](https://github.com/Crawlora-org/crawlora-skills/blob/main/scripts/generate.mjs) - [scripts/validate.mjs](https://github.com/Crawlora-org/crawlora-skills/blob/main/scripts/validate.mjs) - [scripts/tools.json](https://github.com/Crawlora-org/crawlora-skills/blob/main/scripts/tools.json) - [package.json](https://github.com/Crawlora-org/crawlora-skills/blob/main/package.json) - [README.md](https://github.com/Crawlora-org/crawlora-skills/blob/main/README.md) - [skills/index.json](https://github.com/Crawlora-org/crawlora-skills/blob/main/skills/index.json)
# 开发、运维与扩展指南 本页面向希望参与 `crawlora-skills` 项目开发、部署与功能扩展的工程师，系统说明仓库的结构、脚本职责、日常运维要点以及如何新增或调整 skill 条目。 ## 一、项目定位与仓库结构 `crawlora-skills` 是一个以 skill（技能）为核心内容的数据集仓库，目标是为下游爬虫或智能体提供可复用的技能定义。仓库通过脚本化的方式组织数据，避免人工维护带来的不一致问题。仓库主要目录与文件职责如下： - `scripts/`：存放数据生成、校验与工具元数据维护脚本 - `skills/`：存放实际生效的 skill 数据文件及其索引 - `package.json`：声明脚本命令与运行依赖 - `README.md`：面向使用者的项目说明文档 资料来源：[README.md:1-40]() ## 二、开发流程：从配置到产出 开发阶段的重点是修改 `tools.json` 中的工具元数据，并通过脚本生成与校验最终数据。典型工作流如下表所示。 | 步骤 | 操作 | 入口文件 | 输出 | |------|------|----------|------| | 1 | 修改工具元数据 | `scripts/tools.json` | 配置更新 | | 2 | 生成 skill 数据 | `scripts/generate.mjs` | `skills/*.json` | | 3 | 校验数据一致性 | `scripts/validate.mjs` | 通过/失败报告 | | 4 | 同步索引 | `skills/index.json` | 索引文件 | `generate.mjs` 读取 `tools.json` 中的条目，将其转换为符合规范的 skill 数据文件结构；`validate.mjs` 则对生成结果做合规性检查，例如字段完整性、命名规范等。两者共同保证 `skills/` 目录下产物的正确性。 ```mermaid 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]() --- --- ## Doramagic 踩坑日志 项目：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