web-to-markdown

web-to-markdown skill 概览

web-to-markdown 是一个边界非常清晰的格式转换技能，核心用途是通过本地安装的 web2md CLI，把在线网页转换成干净、可携带的 Markdown。它的价值不在于“总结网页内容”，而在于“用真实浏览器渲染页面，提取文章或文档主体，再把结果转成可复用的 Markdown”。正因为如此，它特别适合处理依赖 JavaScript 渲染的页面、文档站、博客文章、需要交互渲染才能通过的受限流程，以及那些简单 HTTP 抓取远远不够的归档场景。

web-to-markdown 最适合哪些人

这个 web-to-markdown skill 最适合以下需求的用户：

• 将一个或多个 URL 转成可读的 Markdown
• 处理依赖客户端 JavaScript 的页面
• 把内容保存成文件，供后续分析或复用
• 提取类似文章的主体内容，而不是抓取页面上的所有元素

如果你的真实目标是“拿到我已经能在浏览器里打开的页面主体内容”，那这个 skill 会比泛化的 prompt 更对路。

web-to-markdown 有什么不同

它真正的差异点在于这条处理链路：

• 通过本地 Chromium 系浏览器使用 Puppeteer
• 使用 Readability 提取主体内容
• 使用 Turndown 转换为 Markdown

这套组合面向的是“已经渲染出来的内容”，而不是原始 HTML。实际效果上，这意味着 web-to-markdown 能处理很多普通 fetch 类工具会失败、或者只能拿到不完整内容的页面。

这个严格触发门槛很重要

这个 skill 有一个不常见但非常关键的限制：只有当用户明确点名要求使用它时，才能触发，比如写出 use the skill web-to-markdown 这样的表达。只要没有这个显式触发语，就不应该调用该 skill。对目录用户来说，这意味着采用门槛并不高，但调用时必须遵守这个规则。

web-to-markdown 真正解决的任务是什么

大多数用户并不是在找“一个浏览器自动化技能”。他们真正想要的通常是这些结果之一：

• “把这篇文章转成我能保存的 Markdown。”
• “把这个文档页转成 Markdown，哪怕它是前端渲染的。”
• “把一批 URL 批量处理成 .md 文件。”
• “先在真实浏览器里打开页面，让我完成登录或验证，再把内容保存下来。”

这才是 web-to-markdown 真正优化的使用场景。

什么时候不该选 web-to-markdown

遇到以下情况就不要选 web-to-markdown：

• 你只需要快速摘要，不需要 Markdown 输出
• 普通 HTTP 抓取已经能干净拿到内容
• 你需要完整爬虫或站点级抓取
• 你想要基于 Playwright 的自动化；这个 skill 明确依赖的是 web2md，不是其他浏览器栈

如何使用 web-to-markdown skill

首次使用前先确认安装上下文

可以把 web-to-markdown 看成两层依赖：

1. agent 环境中的这个 skill 本身
2. 可正常运行的本地 web2md CLI，以及一款可用的 Chromium 系浏览器

一个实用的安装方式是：

npx skills add softaworks/agent-toolkit --skill web-to-markdown

仓库地址在：
https://github.com/softaworks/agent-toolkit/tree/main/skills/web-to-markdown

但光把 skill 加进去还不够。如果你的机器无法运行 web2md，或者无法启动 Chrome/Chromium/Brave/Edge，这个 skill 依然没法真正工作。这个“本地浏览器必须可用”的要求，往往是最该优先排查的接入阻碍。

先读这两个文件

这个 skill 体量不大，最推荐的阅读顺序是：

1. skills/web-to-markdown/SKILL.md
2. skills/web-to-markdown/README.md

SKILL.md 主要用来确认触发规则、必需输入以及整体工作流。README.md 则更适合用来核对官方预期用法，比如 JS 渲染页面、交互模式以及批量转换等场景。

web-to-markdown 需要什么输入

为了让 web-to-markdown 更稳定地工作，建议明确提供：

• 一个 url 或 URL 列表
• 输出方式：
  • 用 --print 打印到 stdout
  • 用 --out ./file.md 写入单个文件
  • 用 --out ./some-dir/ 输出到目录
• 需要时再补充浏览器控制参数：
  • 如果浏览器自动检测失败，使用 --chrome-path <path>
  • 如果页面有登录墙、同意弹窗或人工验证，使用 --interactive

如果你不明确说明输出行为，agent 就只能猜。这个不必要的模糊点，往往也是最容易提前说清楚的一项。

web-to-markdown 的精确触发要求

这个 web-to-markdown skill 只有在用户明确写出类似下面的话时才应该触发：

• use the skill web-to-markdown ...
• use a skill web-to-markdown ...

如果你是在测试这个 skill，直接把名字写出来。这个要求不是仓库层面的“礼貌规范”，而是执行逻辑的一部分。

把模糊请求改写成高质量 prompt

弱请求：

• convert this page

强请求：

• use the skill web-to-markdown to convert https://example.com/article to Markdown and save it to ./notes/article.md

更好的写法：

• use the skill web-to-markdown to convert these 5 docs URLs to Markdown, save them in ./docs-md/, and use interactive mode if a consent screen appears

好的 prompt 能显著降低失败率，因为它会直接告诉 skill：

• 要处理哪些页面
• 输出要写到哪里
• 是否可能需要浏览器交互
• 这是一次性任务，还是批量任务

值得直接提出的常用命令模式

web-to-markdown 常见且实用的用法包括：

• 单页输出到终端：--print
• 单页保存到文件：--out ./page.md
• 多页输出到文件夹：--out ./pages/
• 难处理页面配合可见浏览器：--interactive
• 显式指定浏览器可执行文件路径：--chrome-path <path>

相比“帮我抓这个网站”这种范围过大的开放式请求，仓库里给出的这些模式更贴合这个 skill 的设计边界，也更容易得到稳定结果。

处理单个页面的最佳工作流

一个成功率很高的流程通常是：

1. 先确认用户明确调用了 web-to-markdown
2. 收集 URL
3. 决定是打印输出还是保存到文件
4. 只有在页面确实需要人工辅助时才启用 --interactive
5. 检查 Markdown 结果里是否缺段落、是否夹带过多导航噪音
6. 如果提取不完整，再用更合适的浏览器设置重跑一次

这通常比一开始就把 prompt 设计得过于复杂更高效。

批量处理多个 URL 的最佳工作流

做批量任务时，建议这样走：

1. 把 URL 列表一次性交给 skill
2. 选择目录作为输出目标
3. 预期保存到文件夹时，文件名通常会基于页面标题生成
4. 先抽查几个输出结果，再扩大到大批量运行

批量处理的主要价值是统一性；最大的风险则是默认认为同一站点的所有页面模板都能被同样好地提取。

常见的本地环境阻碍

大多数 web-to-markdown 安装失败，问题不在 prompt，而在本地环境：

• web2md 没有安装，或者不在 PATH 上
• 本地没有可用的受支持浏览器
• 浏览器自动检测失败，需要手动传入 --chrome-path
• 页面必须打开可见浏览器并进行人工交互

如果你想快速判断是否值得接入，建议先拿一个公开文章页和一个 JS 较重的页面做测试，再决定是否用于正式工作流。

对输出质量的合理预期

web-to-markdown 的目标是“干净的主体内容 Markdown”，不是对原网页做像素级还原。也就是说：

• 文章正文和文档主体通常能较好保留下来
• 页头、页脚、广告和页面外壳一般会被弱化
• 一些特殊组件、应用壳层和嵌入式工具未必能转换得很整齐

对归档和分析来说，这种取舍通常是加分项；但在安装前就知道这一点，会更容易判断它是否适合你的需求。

web-to-markdown skill 常见问题

web-to-markdown 比普通 prompt 更好吗？

如果你的真实需求是“把已经渲染完成的页面转成 Markdown”，答案是肯定的。泛化 prompt 可以讨论一个 URL，但它并不会天然帮你打开浏览器、等待 JavaScript 执行、提取可读主体并输出 Markdown。web-to-markdown 的价值就在于，它把这条流程真正落成可执行能力。

web-to-markdown 适合新手吗？

适合，前提是你的任务本身比较简单：一个 URL、一个输出文件、页面结构也比较直白。新手真正容易卡住的通常是本地环境，不是这个 skill 的设计本身。只要你能运行本地浏览器自动化 CLI，这个 skill 的上手难度并不高。

web-to-markdown 能处理重 JavaScript 页面吗？

这正是它存在的主要原因之一。它通过 Puppeteer 调用本地真实浏览器，因此相较于原始 fetch 路线，更适合处理依赖 JS 渲染的页面。

web-to-markdown 能绕过登录或验证页面吗？

有时可以，方式是配合 --interactive。仓库里明确支持一种模式：显示 Chrome 窗口并暂停，让用户完成必须的人类操作。这对于受保护或半受保护页面来说，是非常实际的优势。

什么时候不应该使用 web-to-markdown skill？

以下情况不建议使用：

• 用户没有明确要求 web-to-markdown
• 简单抓取页面就已经能完成任务
• 你需要对页面多个结构化区域做复杂抓取
• 你希望走非浏览器的转换路径

这个 skill 很专注，而这种专注恰恰是它的优势，不是缺点。

它支持任意浏览器吗？

文档里明确适配的是 Chromium 系浏览器，例如 Chrome、Chromium、Brave 或 Edge，底层通过 puppeteer-core 调用。如果自动检测失败，就要准备手动提供浏览器路径。

web-to-markdown 只能用来处理文章吗？

不是。文章是最容易匹配的场景，但 web-to-markdown 同样适合文档页，以及其他“主体内容提取”模型成立的内容型页面。对于仪表盘或高交互应用，它就没那么理想了。

如何改进 web-to-markdown skill 的使用效果

给 web-to-markdown 明确的输出指令

更好的请求不应该只是“convert this URL”，而应该明确成：

• print it
• save it to ./tmp/page.md
• save all results under ./exports/

这样可以去掉猜测空间，也更容易让第一次运行就符合你的工作流。

只有在页面确实需要时才用交互模式

--interactive 对同意弹窗、登录流程和验证提示很有用，但它更慢，也更难自动化。面对普通公开页面，尽量不要默认开启；而对于明确被阻挡的页面，与其盲目重试，不如尽早启用它。

尽早测试浏览器检测

如果第一次运行连浏览器都拉不起来，不要一直改 prompt。应该先修正执行环境：

• 确认机器上确实有 Chromium 系浏览器
• 必要时传入 --chrome-path <path>

对很多用户来说，这是最关键的一条 web-to-markdown 安装建议。

大规模铺开前先选有代表性的页面测试

在一口气转换几百个 URL 之前，先测试：

• 一个简单的文章页
• 一个 JS 渲染页面
• 一个有同意弹窗或登录阻碍的页面

这样你判断的是这个 skill 是否适合你真实面对的网站组合，而不是只对理想样例有效。

用页面级约束增强 prompt

如果你知道某个页面比较棘手，就直接说出来：

• use the skill web-to-markdown on this docs page; it renders client-side, save to ./docs/intro.md
• use the skill web-to-markdown on this member page with interactive mode because I need to pass a verification screen first

这种上下文补充，对执行质量的提升，往往比堆砌泛泛措辞更明显。

先验证第一份 Markdown 结果，再迭代

拿到第一份输出后，重点检查：

• 主体内容有没有被抓到
• 导航和模板化内容是不是混进来太多
• 页面是不是只渲染了一部分
• 文件名或目录输出行为是否符合预期

然后基于问题重新运行，并加上更合适的控制参数。web-to-markdown 往往通过一次有针对性的重试就能明显改善，而不是靠长篇试探式 prompt。

认清 web-to-markdown 的主要失败模式

常见失败模式包括：

• 没有显式触发短语，因此这个 skill 根本不该运行
• 本地浏览器启动有问题
• 页面需要可见交互
• 页面“主体内容”对 Readability 来说并不明确
• 用户想要的是整站抓取，但这个 skill 擅长的是页面转换

越早识别这些问题，越容易判断是继续使用 web-to-markdown，还是该换工具。

按 web-to-markdown 的输出标准来设定预期

当你的成功标准是以下这些时，web-to-markdown 通常表现最好：

• 干净、可读的 Markdown
• 主体内容优先于页面外壳
• 适合笔记、归档、分析或后续 AI 处理的可移植输出

如果你的成功标准是“保留页面的每一个布局细节”，那这个 skill 就不是合适工具。让预期和设计目标对齐，是提升结果最快的方法。