Skill Seekers Skill Builder 实战指南：在 Claude Code 中把任意知识源一键构建为 AI Skill

• 人工智能
• AI 应用
• AI 技能
• RAG
• MCP 服务
• 网页爬虫

导读

skill-builder是 Skill Seekers 项目随 Claude Code 插件分发的一个 Agent Skill（位于 distribution/claude-plugin/skills/skill-builder/SKILL.md）。它把"文档网站、GitHub 仓库、PDF、视频、本地代码库 → 可供 LLM 直接消费的 AI Skill"这条完整流水线封装成了 Claude 可自动调用的能力：底层依赖 Skill Seekers MCP Server 提供的约 40 个工具，并在 MCP 未连接时提供同等的 CLI 兜底路径。读完本文，你将掌握：如何安装并连接 MCP 环境、如何让 Claude 自动识别 8 类知识源、如何按 7 步推荐工作流完成从抓取到发布的全过程，以及每个 MCP 工具与 CLI 命令的真实参数与底层实现位置。

Skill Builder 是什么

Skill Builder 是一份面向 Claude 的"技能说明书"（Agent Skill）。它不包含抓取逻辑本身，而是充当调度层：

• 识别用户意图：当用户说"把 React 文档做成一个 skill""抓取 Flask 仓库并打包给 OpenAI""导出到 Chroma 向量库"时，Claude 读取本 Skill 的检测规则，决定调用哪个 MCP 工具；
• 编排流水线：源类型检测 → 配置生成/拉取 → 规模预估 → 抓取 → AI 增强 → 打包 → 向量库导出；
• 降级策略：如果 MCP 工具不可用，Skill 明确要求"使用文件底部的 CLI 兜底，而不是停下"（原文：do not stop）。

在插件体系中的位置见 distribution/claude-plugin/README.md：插件自带 MCP Server、三个斜杠命令（/skill-seekers:create-skill、/skill-seekers:sync-config、/skill-seekers:install-skill）以及本 Skill。安装插件后，Skill Builder 对 Claude 自动可用。

环境准备：安装与连接 MCP

Skill Builder 文档给出的前置条件只有两步：

1. 安装包（含 MCP 依赖）：

pip install "skill-seekers[mcp]"

2. 连接 MCP Server，按安装方式二选一：
   • 以 Skill Seekers 插件形式安装：无需手动注册，插件自带的.mcp.json会自动拉起服务器（但仍需完成第 1 步安装 Python 包）；
   • 独立安装（例如手动把 skill 复制到~/.claude/skills/）：需手动注册一次：

claude mcp add skill-seekers -- python -m skill_seekers.mcp.server_fastmcp

判断是否连接成功：如果scrape_docs、package_skill等工具没有出现在 Claude 的工具列表中，说明服务器未连接。此时应向用户说明上面两步，并立即转用 CLI 兜底方案（见下文"CLI 兜底"一节）。

MCP 服务器入口为skill_seekers.mcp.server_fastmcp（FastMCP 实现），其工具实现按功能拆分在 src/skill_seekers/mcp/tools/ 目录下，包括config_tools.py（配置管理）、scraping_tools.py（抓取）、packaging_tools.py（打包/上传/增强/安装）、splitting_tools.py（拆分/路由）、vector_db_tools.py（向量库导出）、source_tools.py（配置源管理）等模块，最终在 tools/init.py 统一注册导出。

何时使用 Skill Builder

按 Skill 文档，当用户出现以下任一诉求时应当激活本技能：

• 想从文档网站、GitHub 仓库、PDF、视频或其他来源创建 AI Skill；
• 需要把文档转换成适合 LLM 消费的格式；
• 想用最新源文档更新或同步已有 Skill；
• 需要把 Skill 导出到向量数据库（Weaviate、Chroma、FAISS、Qdrant）；
• 询问任何关于"为 AI 抓取、转换、打包文档"的问题。

这也对应了插件的三种典型用法：create-skill（创建）、sync-config（同步配置）、install-skill（端到端安装），以及"直接用自然语言向 Claude 描述意图"的方式。

源类型自动检测

Skill 文档给出了一张核心的"输入模式 → 源类型 → 工具"映射表，这是整个流水线的入口：

检测逻辑在源码层面有两处印证：

• CLI 侧：create_command.py 的帮助文本完整罗列了同一套自动检测规则：URL/域名 → 网页抓取、owner/repo→ GitHub 分析、./path→ 本地代码库、file.pdf→ PDF 提取、file.docx/file.epub→ Word/EPUB 提取、youtube.com/.../file.mp4→ 视频提取、file.json→ 多源配置；
• MCP 侧：scraping_tools.py 中scrape_generic_tool内置了 10 种泛化源类型（jupyter、html、openapi、asciidoc、pptx、word、confluence、notion、rss、manpage、chat），并维护了每种类型到转换器配置键的映射（如jupyter → notebook_path、confluence → export_path），URL 型源（confluence/notion/rss/openapi）则使用base_url/page_id/feed_url/spec_url等键。

需要说明的是：scrape_docs工具本身也具备格式自动判定能力——scrape_docs_tool 会读取配置 JSON，若包含sources数组则走Unified（多源）格式，否则按base_url/repo/pdf_path/directory等键推断 legacy 单源类型并路由到对应转换器。

推荐工作流（7 步）

Skill 文档定义了从输入到产出的标准流水线：

1. 检测源类型：根据用户输入判定；
2. 生成或拉取配置：需要时使用generate_config或fetch_config；
3. 预估规模：文档站点用estimate_pages；
4. 抓取源：使用对应的抓取工具；
5. 增强：用户需要 AI 能力提升时用enhance_skill；
6. 打包：用package_skill面向目标平台打包；
7. 导出向量库：按需使用export_to_*系列工具。

这条流水线与源码中的调用链一一对应：

• 步骤 2 的generate_config实现于 config_tools.py，默认生成 Unified 格式配置（sources数组），并内置保守默认值：max_pages=100、rate_limit=0.5s，默认选择器为main_content: "article"、title: "h1"、code_blocks: "pre code"；fetch_config支持三种模式（注册表命名源 > 直接 Git URL > API），实现在 source_tools.py；
• 步骤 3 的estimate_pages_tool（scraping_tools.py）以max_discovery（默认 1000）为上限做快速预估，unlimited=True或max_discovery=-1时进入无上限发现模式；
• 步骤 4 的抓取工具统一通过get_converter(source_type, config)创建转换器并进程内执行（_run_converter），日志实时回传；
• 步骤 6 的package_skill_tool（packaging_tools.py）在target="auto"时通过AgentClient.detect_default_target()自动探测目标平台。

MCP 工具详解

Skill 文档将约 40 个工具分为四组，下面结合源码补全每个工具的真实参数与默认值。

配置管理（Config Management）

generate_config生成的配置可直接与仓库中的现成示例对照——例如 configs/react.json 就是一个典型的 Unified 配置：顶层含name、description、version、merge_mode: "rule-based"，sources数组内同时挂载documentation（base_url: "https://react.dev/"、选择器、url_patterns排除/blog/、categories分类、rate_limit: 0.5）与github（repo: "facebook/react"、code_analysis_depth: "deep"、max_issues: 100）两类源，展示出"文档 + 代码"融合构建 Skill 的形态。

抓取（Scraping，按源类型选用）

• scrape_docs：文档站点抓取。支持unlimited（解除页数限制，会创建临时配置）、dry_run（预览不落盘）、skip_scrape（跳过抓取、复用缓存）、merge_mode（覆盖 Unified 配置的合并模式）等参数；
• scrape_github：GitHub 仓库抓取。提取 README、Issues、Changelog、Releases 与代码结构；参数含repo/config_path、name、description、token、no_issues/no_changelog/no_releases、max_issues（默认 100）、scrape_only；
• scrape_pdf：PDF 抓取，三种输入方式：config_path、直接pdf_path+name、或from_json从已提取的 JSON 重建；
• scrape_video：视频转写（YouTube/Vimeo/本地文件）。参数最丰富：url/video_file/playlist、languages、visual（逐帧画面提取）、whisper_model（默认 base）、visual_interval（默认 5s）、visual_min_gap（默认 2s）、visual_similarity（默认 0.95）、vision_ocr、start_time/end_time、setup（自动检测 GPU 并安装视觉提取依赖）；
• scrape_codebase：本地代码库分析。directory必填，depth（surface/deep/full，默认 deep）、enhance_level（0-3，0 关闭 AI 增强，3 为全量增强）、languages、file_patterns，以及一组skip_*开关（默认所有功能开启：API 参考、依赖图、设计模式、测试示例、How-to 指南、配置模式、文档提取）；
• scrape_generic：泛化源。source_type必填（jupyter/html/openapi/asciidoc/pptx/word/confluence/notion/rss/manpage/chat），配合path或url与name。

后处理（Post-processing）

其中install_skill_tool（packaging_tools.py）是流水线的"一键版"：它依次调用fetch_config_tool、scrape_docs_tool、enhance_skill_local.py、package_skill_tool、upload_skill_tool，并输出各阶段完成清单与产物路径。其上传阶段依赖平台环境变量（如ANTHROPIC_API_KEY、GOOGLE_API_KEY、OPENAI_API_KEY），未设置时跳过上传并给出手动上传指引。

高级（Advanced）

• detect_patterns：在代码中检测设计模式（Singleton、Factory、Observer、Strategy、Decorator、Builder、Adapter、Command、Template Method、Chain of Responsibility），支持 10 种语言，参数file/directory、depth、json；
• extract_test_examples：从测试文件提取真实 API 用法示例（实例化、方法调用、配置、fixture 与多步工作流），Python 使用 AST 深度分析，其余语言正则分析；参数language、min_confidence（默认 0.5）、max_per_file（默认 10）；
• build_how_to_guides：基于test_examples.json生成分步教学指南，支持 4 种分组策略（ai-tutorial-group、file-path、test-name、complexity）与no_ai开关；
• split_config：拆分超大配置（如 1 万页以上的文档站按 5000 页/份切分，Unified 配置按源类型拆分），strategy可选 auto/none/source/category/router/size，实现在 splitting_tools.py；
• export_to_weaviate/export_to_chroma/export_to_faiss/export_to_qdrant：把 Skill 目录导出为对应向量库的 JSON 包（含 schema、objects、config），实现在 vector_db_tools.py，每个工具还会输出一段可复制的 Python 上传/查询示例代码。

CLI 兜底（MCP Server 未连接时）

Skill 文档强调：MCP 工具不可用绝不意味着流程中断。同一套流水线可从命令行执行（需pip install skill-seekers）：

skill-seekers create <source> # 自动检测：URL、owner/repo、./path、file.pdf、视频链接…… skill-seekers package <skill_dir> --target claude # 目标平台可为 gemini/openai/langchain/chroma/...

关键语义：

• create一步完成"检测 → 抓取 → 构建"；加--enhance-level 0可跳过 AI 增强；
• 命令结束后，读取生成的SKILL.md并向用户总结产物内容。

create子命令的实现位于 create_command.py，除了自动检测外还提供一套实用的辅助能力：

• 三档预设-p：quick（约 1-2 分钟，基础功能）、standard（约 5-10 分钟，推荐）、comprehensive（约 20-60 分钟，全功能）；
• 渐进式帮助：--help-web、--help-github、--help-local、--help-pdf、--help-word、--help-epub、--help-video、--help-config、--help-advanced、--help-all，按源类型分组展开 13→120+ 个参数，避免一次性输出全部选项；
• 常见组合：skill-seekers create <source> -p quick、skill-seekers create <source> -p standard --enhance-level 2、skill-seekers create <source> --chunk-for-rag（面向 RAG 的分块）。

此外，skill-seekers package支持--target指定 21+ 个 LLM 平台（适配器实现在 src/skill_seekers/cli/adaptors/），MCP 的package_skill_tool与 CLI 走的是同一套get_adaptor适配器机制。

完整实战示例

结合插件用法与上述工具链，一次典型的"React 文档 → Claude Skill"会话如下：

# 1. 安装（MCP 模式） pip install "skill-seekers[mcp]" # 2. 连接 MCP（独立安装场景） claude mcp add skill-seekers -- python -m skill_seekers.mcp.server_fastmcp # 3. 在 Claude 中发起请求 # "把 https://react.dev 做成一个 Claude skill" # 4. 内部自动执行的步骤（等价于如下命令） skill-seekers create configs/react.json -p standard --enhance-level 2 skill-seekers package output/react --target claude

若 MCP 未连接，直接用 CLI 兜底：

skill-seekers create https://react.dev -p standard skill-seekers package output/react --target claude

之后读取生成的output/react/SKILL.md向用户汇报：Skill 名称、覆盖的文档范围、增强内容与打包产物路径。若需要进一步接入 RAG，可继续调用export_to_chroma等工具将同一份 Skill 目录导出为向量库格式。

排查与最佳实践

1. 工具列表中看不到scrape_docs/package_skill：说明 MCP Server 未连接。按"环境准备"一节重新执行安装与注册两步，期间用 CLI 兜底继续任务；
2. 大站点抓取超时/页数过多：先用estimate_pages预估规模，再决定是否使用split_config（按 5000 页/份切分）或将max_pages调低；确需全量抓取时再用unlimited=true；
3. 自动上传失败：package_skill与install_skill仅在检测到平台 API Key 时才上传，未设置环境变量（如ANTHROPIC_API_KEY）时会优雅跳过并提示手动上传，不会中断打包；
4. 产物质量：install_skill将 AI 增强设为强制阶段，因为文档声称增强能带来明显的质量提升（质量分从 3/10 提升到 9/10，见 packaging_tools.py 的说明）；package_skill在交互式终端外会自动跳过质量检查对话框，适合自动化场景；
5. 复用与同步：generate_config生成的配置保存在configs/目录，可手工微调后复用；插件还提供sync_config命令（MCP 侧为sync_config_tool，见 sync_config_tools.py）用于让既有配置与线上文档保持同步。

结语

Skill Builder 的价值在于把 Skill Seekers 的完整工程能力（8 类源检测、多源 Unified 配置、AI 增强、21+ 平台打包、4 种向量库导出）收敛为 Claude 里一段可自主决策的技能说明：检测、编排、降级三者齐备，且每条指令都能在 src/skill_seekers/mcp/tools/ 与 src/skill_seekers/cli/ 的源码中找到对应的实现依据。对于希望让 Agent 自主完成"知识源 → AI Skill"闭环的团队，这份 Skill 与配套的 MCP Server 提供了开箱即用的参考实现。

• 人工智能
• AI 应用
• AI 技能
• RAG
• MCP 服务
• 网页爬虫