Agent Skill

MagicMD 可以作为 Agent Skill 安装。Skill 不复制转换逻辑；它告诉 Agent 什么时候调用 MagicMD、怎么批量运行、转换后检查哪些文件，以及遇到失败时查看哪些报告。

如果你不想记命令，可以把 MagicMD 当成一个 Agent 能力入口：你只要描述“把这些公开文章变成 Markdown 内容包”，Agent 负责运行 CLI、检查报告，并告诉你哪些结果需要人工复核。

这适合这些场景：

• 让 Agent 批量整理微信公众号、掘金、CSDN 或技术博客文章。
• 在发布流程前先生成 article.md、metadata.json 和 extraction-report.json。
• 让 Agent 根据转换报告判断哪些文章需要人工复核。
• 在 Codex 工作区里把公开文章链接沉淀成可归档、可发布的 Markdown 内容包。

直接复制给 Agent

安装 Skill 后，你可以直接把下面这些话发给 Codex、Claude Code 或其他支持 Skill 的 Agent 工具：

单篇转换：适合你已经有一个公开文章链接，想直接生成 Markdown 内容包。

请用 MagicMD 把这个公开文章链接转换成 Markdown 内容包，并告诉我输出了哪些文件和 warning。

批量整理：适合你已经把多个链接放进 urls.txt，想让 Agent 断点续跑并汇总失败原因。

请读取 urls.txt，用 MagicMD 批量转换到 output/articles，跳过已经存在的内容包，并根据 batch-report.md 汇报失败原因。

环境检查：适合第一次在新机器或新工作区使用，先确认浏览器抓取和平台配置是否可用。

请运行 MagicMD doctor，检查当前工作区是否可以转换微信公众号、掘金、CSDN 和通用文章链接。

发布前复核：适合转换完成后，让 Agent 帮你找出需要人工检查的文章。

请检查这个 MagicMD 输出目录，告诉我哪些文章发布前需要人工复核。

安装 Skill

MagicMD 的可安装 Skill 位于仓库目录 skills/magicmd：

Repository: didilili/MagicMD
Skill path: skills/magicmd

最简单的方式是直接告诉你正在使用的 Agent 工具，例如 Codex、Claude Code 或其他支持 Skill 安装的工具：

请从 GitHub 仓库 didilili/MagicMD 安装 MagicMD Skill，Skill 路径是 skills/magicmd。

安装后，Agent 会看到名为 magicmd 的 Skill。你可以让它处理单条链接，也可以让它读取一个 URL 列表后批量转换。

运行依赖

Skill 本身只定义 Agent 工作流，真正转换仍然调用 MagicMD CLI。

如果环境里已经安装了 MagicMD，Agent 会优先使用：

magicmd doctor
magicmd "https://mp.weixin.qq.com/s/example" -o output/
magicmd batch urls.txt -o output/

如果没有全局安装，Skill 会引导 Agent 使用 PyPI 包：

uvx --from magicmd magicmd doctor
uvx --from magicmd magicmd "https://mp.weixin.qq.com/s/example" -o output/
uvx --from magicmd magicmd batch urls.txt -o output/

Agent 会怎么做

Skill 会让 Agent 按固定流程执行：

1. 环境不明确时先运行 magicmd doctor。
2. 单篇文章使用 magicmd "<url>" -o <output_dir>。
3. 多篇文章使用 magicmd batch <urls.txt> -o <output_dir>。
4. 断点续跑时使用 --skip-existing。
5. 转换后检查 article.md、metadata.json、extraction-report.json。
6. 批量任务检查 batch-report.md 和 batch-report.json。

输出检查

Agent 完成转换后，应该向你汇报：

• 输出目录路径。
• 成功和失败的数量。
• extraction-report.json 或 batch-report.md 里的重要 warning。
• 图片或视频是否已下载到本地。
• 是否遇到 403、登录要求、验证码、视频防盗链或动态资源缺失。
• 下一步建议：可以发布、需要人工复核、需要重试，还是需要保留失败证据。

边界

MagicMD 只处理公开文章页面。Skill 不应该用于绕过登录、付费墙、私有页面、验证码、限流或平台访问控制。

当页面无法公开访问时，Agent 应该保留已经生成的输出包和报告，并把失败阶段、warning、原始链接和必要截图反馈给你，而不是伪装成转换成功。