md2wechat-skill 使用指南：安装顺序、第一次调用与 Agent 最该先做什么

如果你只记住 md2wechat-skill 的一条规则，那就记住这一条：

先装 CLI，再装 skill。

这一条能帮你避开 Claude Code、Codex、OpenCode、Claudian 里大多数最浪费时间的坑。

md2wechat-skill 到底是什么

md2wechat-skill 不是单纯再包一层微信 API。

它本质上是一个面向 Agent 运行时的分发层。也就是说，这个项目同时在做两件事：

• 把 md2wechat 工作流整理成 Agent 更容易调用的形态
• 给 Agent 一个比“复制几条命令”更稳定的调用顺序

很多失败其实并不发生在 Markdown 转换那一步，而是更早：

• CLI 没装
• 运行时猜错默认模式
• 没做 discovery 就假设主题和 provider 一定存在
• 把 Coding Agent 路径和 OpenClaw 路径混在一起

实际安装顺序应该是什么

对于 Claude Code、Codex、OpenCode、Claudian，最稳的路径是：

brew install geekjourneyx/tap/md2wechat
npx skills add https://github.com/geekjourneyx/md2wechat-skill --skill md2wechat
md2wechat version --json
md2wechat capabilities --json

如果你不用 Homebrew，还有两种常见替代方式：

go install github.com/geekjourneyx/md2wechat-skill/cmd/md2wechat@v2.0.3

或者：

curl -fsSL https://github.com/geekjourneyx/md2wechat-skill/releases/download/v2.0.3/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"

重点不是你用了哪种安装器，重点是顺序。

npx skills add 只会安装 skill 定义，不会把 md2wechat 二进制放进你的 PATH。

为什么一定要先做 discovery

上游文档里最值得保留的一条原则，就是 discovery-first。

在 Agent 真正选择 provider、theme 或 prompt 模板之前，先问 CLI 当前到底支持什么：

md2wechat capabilities --json
md2wechat providers list --json
md2wechat themes list --json
md2wechat prompts list --kind image --json

这样能避免一连串错误假设。

它回答的是：

• 运行时有没有真正装好
• 默认模式是什么
• 当前配置了哪些图片 provider
• 当前有哪些主题和 prompt preset

对 Agent 工作流来说，这比“凭记忆猜”安全太多了。

第一次成功调用应该跑什么

完成安装和 discovery 之后，第一次成功任务应该尽量朴素：

md2wechat convert article.md --preview

这一步只是证明 CLI 主路径是通的。

接下来再往上加：

AI 模式：

md2wechat convert article.md --mode ai --theme autumn-warm --json

创建草稿：

md2wechat convert article.md --draft --cover cover.jpg

这三步的意义不一样：

• 预览说明 CLI 路径正常
• AI 模式说明结构化主题输出正常
• 创建草稿说明你连微信凭证和封面图链路也打通了

最浪费时间的几个错误

1. 装了 skill，没装 CLI

这是最常见的一种。

运行时看起来像是“已经接上了”，但第一条真正执行命令就会报 command not found: md2wechat。

这不是内容问题，也不是主题问题，而是 runtime 缺失。

2. 忘了 API 模式才是默认值

如果你执行：

md2wechat convert article.md

那默认就是 API 模式，除非你显式加 --mode ai。

这点很关键，因为 AI 模式不是“更漂亮的同一个结果”，而是给第二步模型使用的结构化输出。

3. 把 OpenClaw 当成同一路径

它不是。

OpenClaw 用的是独立 skill 包和独立安装逻辑，应该和共享的 Coding Agent 路径分开理解、分开写、分开装。

4. 跳过能力发现

很多人一上来就想直接用高级主题，或者直接生成封面图。

但稳妥顺序还是：

md2wechat capabilities --json

这一个命令能避免非常多的误判。

可以直接发给任意 Coding Agent 的提示词

如果你不想自己手敲命令，可以直接发：

请先安装 md2wechat CLI，再安装 md2wechat skill，验证 version 和 capabilities，所有命令成功后再结束。

然后再发：

请先运行 md2wechat capabilities --json，再把 article.md 转成公众号 HTML，并给我一个预览版本。

这样 Agent 必须先证明 runtime 是通的，再去承诺后面的输出。

接下来该看哪里

如果你主要在 Coding Agent 里用，继续看：

• Coding Agents 总览
• Claude Code
• Codex
• OpenCode

如果你是具体环境问题，继续看：

• Claudian
• OpenClaw

如果你想保留一页更短的参考文档，也可以直接收藏：

• md2wechat-skill 使用指南