Skill Seeker 多文件 HTML 转 Claude Skill 深度解析：以 golden-html-multi 黄金产物为例

人工智能AI 应用AI 技能RAGMCP 服务网页爬虫【免费下载链接】Skill_SeekersConvert documentation websites, GitHub repositories, and PDFs into Claude AI skills with automatic conflict detection项目地址https://gitcode.com/gh_mirrors/sk/Skill_Seekers点击查看免费下载本文以 Skill Seeker 仓库中 tests/golden/phase2/html_multi/SKILL.md 这一黄金基准产物为范例深入讲解项目如何把多个本地 HTML 文档文件一键转换为可直接供 Claude 使用的 SkillSKILL.md references/ 结构覆盖产物文件树、SKILL.md 全部区块的生成逻辑、按源文件分组的分类机制、提取管线以及可复现的验证方法。读完你既能看懂该类 Skill 产物每个字段从何而来也能独立用skill-seekers html命令复现多文件构建。一、golden-html-multi多文件 HTML 构建的黄金基准在 Skill Seeker 中golden黄金测试是一套输出级回归保障机制在 tests/phase2_golden_utils.py 中定义的协议规定任何文档类 Scraper 在重构前先用UPDATE_GOLDENS1 pytest test捕获其完整产物树并提交到 tests/golden/phase2/重构后用同一测试以逐字节比对模式运行任何差异都会导致断言失败从而证明重构前后输出完全一致byte-identical。html_multi正是其中覆盖多文件 HTML 构建路径的基准其产物树为tests/golden/phase2/html_multi/ ├── SKILL.md # 主 Skill 清单 └── references/ ├── index.md # 文档结构索引 ├── golden_html_multi_s1-s2.md # intro 类别Section 1-2来自 intro.html └── golden_html_multi_s3-s4.md # extras 类别Section 3-4来自 extras.html对应测试 test_html_multi_file_matches_golden 明确指出该路径的触发条件与语义当total_files 1时内容按source_file分组并在 SKILL.md 中输出多文件特有的 Source files 元数据行。测试中传入的html_path是一个目录样式的路径fixtures/site这正是把整个站点文档目录一键转 Skill的入口形态。二、从多个 HTML 文件到 Skill 的产物结构2.1 三种分类路径的分工HtmlToSkillConverter.categorize_content 是决定产物形态的核心方法它按来源形态走三条路触发条件分类结果产物示例单文件且html_path指向真实文件1 个以文件 stem 命名的类别golden/html/SKILL.mdpage类别total_files 1目录来源按source_file每个文件一个类别golden/html_multi/intro、extras两个类别未提供html_path且配置了categories关键词按关键词打分归类无命中归入othergolden/html_kw/html_multi走的是第二条categorize_content遍历每个 section 的source_file字段取其 stemintro.html→intro作为类别键同类 section 归入同一pages列表最终生成introSections 1-2与extrasSections 3-4两个类别与 references/index.md 中列出的分类完全一致。2.2 reference 文件命名规则分类文件的命名由reference_filename统一生成格式为{类别stem}_{前缀}{起始编号}-{结束编号}.mdgolden_html_multi_s1-s2.md表示 stem 为golden_html_multi、包含 Section 1 到 2。命名逻辑集中在 DocumentSkillBuilder._reference_filenameSKILL.md 的 Navigation、index.md 的 Categories 与生成器共用同一函数保证三类链接永不漂移源码注释中记为 DOC-07 约束。2.3 多文件特有的元数据与统计Document Information 追加 Source files_write_skill_md_metadata在继承基类输出 Title/Author/Language/Description/Keywords 之后当total_files 1时额外输出**Source files:** 2 HTML files——这正是本 golden 产物中唯一体现多文件字样的信息行。Statistics 追加 HTML Files_write_skill_md_extra_stats在 Documentation Statistics 区块追加- **HTML Files**: 2。index.md 追加文件计数_write_index_statistics额外输出- HTML files processed: 2与作者信息。三、SKILL.md 十区块逐块解读SKILL.md 由 DocumentSkillBuilder._generate_skill_md 生成整体分为 10 个区块逐块对应关系如下3.1 YAML FrontmatterAgent 发现机制的入口--- name: golden-html-multi description: Use when testing the multi-file html build ---name由配置的name字段小写化、_/-/空格替换为-并截断到 64 字符得到description截断到 1024 字符。两者经_frontmatter_value处理只有当值含:#等危险字符或首尾空白时才用 JSON 双引号转义防止类似godot: engine的恶意值破坏 YAML 结构见 document_skill_builder.py#L381-L392。namedescription是 Claude 等 Agent 决定何时调用该 Skill的首个信号。3.2 Document Information源文档元数据输出 Title、Author、Language、Description、Keywords 五个字段配置项见SKILL_MD_METADATA_FIELDShtml_scraper.py#L127-L133。这些值在提取阶段由 _extract_metadata 从title、meta namedescription|author|keywords|generator读取description缺失时回退到 OpenGraph 的og:descriptiontitle回退到og:title再回退到文件名language取自html lang...。多文件模式下_extract_metadata会聚合所有文件的标题到all_titles列表html_scraper.py#L217-L225并在Document Information输出多文件特有行**Source files:** 2 HTML files。3.3 When to Use使用场景清单固定输出 5 条引导语理解概念、查 API、找示例、看教程、探索结构让 Agent 在触发后能快速判断该 Skill 的适用范围。3.4 Section Overview类别分组概览**Total Sections:** 4 **Content Breakdown:** - **intro**: 2 sections - **extras**: 2 sections直接来源于categorize_content的结果intro类别持有 2 个 sectionextras持有 2 个合计 4。它让 Agent 一眼看清文档的整体组织方式。3.5 Key Concepts标题驱动的主题提取_format_key_concepts遍历所有 section 的主标题与子标题h1级别归入Major Topics最多 10 条h2级别归入Subtopics最多 15 条短于 3 字符的标题被过滤。本产物中 Getting Started Guide、Troubleshooting 来自两个h1标题而 Installation Steps、API Usage、Common Errors、Changelog 则是 section 内捕获的h2子标题数据源见 tests/test_phase2_golden_html.py#L19-L107 的 SECTIONS 定义。3.6 Quick Reference模式关键词快速索引_format_patterns_from_content把每个 section 的标题小写化后与关键词表比对命中即记录类型 标题 序号。HTML Scraper 在共享关键词表之上额外扩展了reference与changelog两个 HTML 专有关键词见 html_scraper.py#L126这正是产物中 Changelog 能被识别为独立模式的原因测试注释特别强调该设计用于防止误用基类的基础模式格式化器。产物中 Getting Startedsection 1、API Usage→Usagesection 2、Troubleshootingsection 3、Changelogsection 4四类模式全部命中。3.7 Code Examples质量分排序的示例精选生成逻辑document_skill_builder.py#L443-L472为收集全部代码块 → 按quality_score降序取前 15 → 按语言分组 → 每种语言展示前 5 条。两个细节值得注意质量分由scraper_utils.score_code_quality计算产物中pip install thing得 6.0 分print(hello)得 8.5 分60 行变量赋值的长示例得 9.5 分——得分越高排序越靠前。500 字符截断超过 500 字符的代码在 SKILL.md 中截断并以...结尾完整代码仍在 references 文件中所以long_example()在 SKILL.md 里只展示前 500 字符而在 golden_html_multi_s1-s2.md 中是完整 60 行。3.8 Table Summary前 5 张表的快捷预览按 section 顺序取前 5 张表带表头则渲染为 Markdown 表格每表最多 5 行并标注来源 section。产物中的Option/Default表来自 Getting Started Guide而无表头表a b / c d来自 API Usage则不渲染表头行只展示数据行——这是无表头渲染路径的刻意覆盖。3.9 Documentation Statistics文档体量画像- **Total Sections**: 4 - **Code Blocks**: 3 - **Images/Diagrams**: 2 - **Tables**: 2 - **HTML Files**: 2 ← html 特有 - **Programming Languages**: 2这些数字全部来自提取阶段写入的{name}_extracted.json中间文件total_sections、total_code_blocks、total_images、total_files、languages_detected语言计数经LanguageDetector对无标注代码块做内容级检测后统计html_scraper.py#L254-L275python 2 例、bash 1 例。3.10 Navigation通往 references 的导航**Reference Files:** - references/golden_html_multi_s1-s2.md - intro - references/golden_html_multi_s3-s4.md - extras See references/index.md for complete documentation structure.指引 Agent 从 SKILL.md 继续下钻到完整文档内容。references/index.md 则以- [intro](https://link.gitcode.com/i/4b03ffe92a9bcfcd51e4f6d099c042ff) (2 sections, Sections 1-2)的形式维护类别到文件的映射。四、reference 文件多文件构建的正文载体4.1 内容组织以 golden_html_multi_s1-s2.md 为例每个 section 渲染为** Source: Section 1** *(intro.html)* ← html 特有标注来源文件 ## Getting Started Guide ### Installation Steps #### Verify Setup ← h3 子标题层级自动 1 ... ### Code Examples ← 代码块不截断 ### Tables ← Markdown 表格 ### Images ← [](https://link.gitcode.com/i/cce3e0a05e0a7d8b7f4fcf3396f78643) 链接形式 ### Links ← html 特有链接清单其渲染逻辑见 HtmlToSkillConverter._write_reference_section与基类相比有三处 HTML 特有行为来源文件标注紧邻** Source: Section N**追加*(intro.html)*这是多文件溯源的关键图片以链接形式渲染HTML 提取时图片data恒为空字节不做内嵌展示文本取alt优先、title兜底Request Flow即 alt 为空时回退 title 的产物Links 区块每 section 最多输出 20 条链接javascript:与空锚点 href 在提取阶段即被过滤_extract_link_info。4.2 标题层级推导section 的主标题若为h1在 reference 文件中渲染为##section 内捕获的h3子标题渲染为####——整体下移一级以适配文件首行为类别标题的文档结构。五、提取阶段原始 HTML 如何变成 sections多文件构建的前半程由 extract_html 完成其核心步骤为文件收集_collect_html_files对单文件校验.html/.htm/.xhtml扩展名对目录用rglob递归收集并字母序排序无匹配文件则抛出ValueError。解析与清洗parse_html基于html.parser解析源码注释提及 #96 的宽松回退随后_clean_soup移除script/style/noscript、注释、nav/footer含h1的 header 保留及按 class/id 模式匹配的侧边栏、菜单、面包屑、广告等样板元素。主内容定位_find_main_content按优先级尝试main、article、rolemain、常见 content 类/id 选择器均要求文本长度 50最后回退到文本最长的 div或body。按标题切分_extract_sections遇h1/h2即冲刷前一节h3-h6作为子标题记录进当前节形成带section_number跨文件连续编号、source_file的 section dict。富内容提取代码块支持precode classlanguage-python、pre、独立code仅收长于 30 字符的三种形态语言优先从language-/lang-/code-/highlight-/brush:等 class 前缀识别_detect_language_from_classes缺失时由LanguageDetector兜底。中间产物落盘全部结果写入{name}_extracted.json该文件既是构建阶段的输入也可通过--from-json独立复用。六、复现与验证把多文件构建跑起来6.1 复现黄金产物仓库测试直接用内存中的 SECTIONS 数据驱动构建无需真实 HTML 文件入口为test_html_multi_file_matches_goldenconverter _converter({ name: golden_html_multi, description: Use when testing the multi-file html build, html_path: fixtures/site, # 目录样式路径 → 多文件路径 output_dir: str(tmp_path / skill), }) converter.extracted_data _extracted_data({title: The Web Handbook}, total_files2) assert_matches_golden(build_snapshot(converter), html_multi)total_files2使 SKILL.md 落入多文件分支输出与tests/golden/phase2/html_multi/逐字节比对phase2_golden_utils.py#L30-L65。6.2 命令行实战对真实的多文件文档目录HtmlToSkillConverter的模块文档html_scraper.py#L13-L17给出的用法是# 单文件 skill-seekers html --html-path page.html --name myskill # 多文件目录递归收集所有 .html/.htm/.xhtml skill-seekers html --html-path ./docs/ --name myskill # 复用已提取的中间数据 skill-seekers html --from-json page_extracted.json构建完成后按提示用skill-seekers package skill_dir/打包分发。golden 测试的更新协议为UPDATE_GOLDENS1 pytest tests/test_phase2_golden_html.py仅在有意重构输出时使用平时应保持比对模式。6.3 与单文件产物的对比对比 tests/golden/phase2/html/SKILL.md 可直观看到差异单文件版Section Overview只有- **page**: 4 sections一个类别、Document Information 无 Source files 行、Statistics 显示HTML Files: 1、Navigation 只有一个references/page.md而多文件版则为intro/extras双类别、追加源文件计数。两者仅差一个目录 vs 文件的入参产物形态随之切换——这正是 categorize_content 注释所强调的HTML 的单源快路径必须以路径为真实文件为前提目录来源走多文件分组二者都无法仅靠基类钩子表达故在此覆盖。七、小结从tests/golden/phase2/html_multi/这份黄金产物出发可以看到 Skill Seeker 多文件 HTML 构建的完整链路_collect_html_files收集 →parse_html/_clean_soup/_find_main_content清洗定位 →_extract_sections切分 →extract_html落盘中间 JSON →categorize_content按source_file分组 →DocumentSkillBuilder生成 SKILL.md十区块与 references/分类正文 index 索引。SKILL.md 中Source files、HTML Files、来源文件标注、Links 区块等 HTML 特有细节均由 html_scraper.py 的钩子方法注入并由 golden 测试以逐字节比对的方式锁定确保任何一次重构都不会破坏已发布的产物格式——这也是该仓库文档类 Scraper 输出质量稳定可依赖的根基。赞分享人工智能AI 应用AI 技能RAGMCP 服务网页爬虫【免费下载链接】Skill_SeekersConvert documentation websites, GitHub repositories, and PDFs into Claude AI skills with automatic conflict detection项目地址https://gitcode.com/gh_mirrors/sk/Skill_Seekers点击查看免费下载相关推荐Skill_Seekers 之 Man Page 转 Claude Skill 实战解析以 man_kw 黄金产物与 references/index.md 为例Skill_Seekers 之 Man Page 转 Claude Skill 实战解析以 man_kw 黄金产物与 references/index.md人工智能AI 应用AI 技能RAGMCP 服务网页爬虫Skill Seekers HTML 文档转 Skill 实战从 HTML Scraper 到 golden 基准构建全解析Skill Seekers HTML 文档转 Skill 实战从 HTML Scraper 到 golden 基准构建全解析 本文以仓库中 tests/gol人工智能AI 应用AI 技能RAGMCP 服务网页爬虫Skill_Seekers 多文件 HTML 转 Skill 全流程解析基于 golden_html_multi 黄金基线验证Skill_Seekers 多文件 HTML 转 Skill 全流程解析基于 golden_html_multi 黄金基线验证 本文以 Skill_Seeke人工智能AI 应用AI 技能RAGMCP 服务网页爬虫创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考