Agent API 文档Skills
md2wechat-skill 使用指南
主技能页之外的进阶说明，补充 md2wechat-skill 的配置、验证顺序、运行时差异和最佳实践。
md2wechat-skill 使用指南
如果说 md2wechat-skill 是新手第一入口，这一页就是进阶补充页。
这页不再重复“先装什么”的主线，而是重点解释：
- 安装完成后还要验证什么
- 为什么 discovery-first 是最佳实践
- Claude Code / Codex / OpenCode / Claudian / OpenClaw 的差异到底在哪
- 什么情况下该继续看 FAQ 或环境专页
推荐验证顺序
安装完成后，建议按这个顺序验证，而不是只看 version 一条命令。
md2wechat version --json
md2wechat config init
md2wechat capabilities --json
md2wechat providers list --json
md2wechat themes list --json
md2wechat prompts list --kind image --json这 6 条命令分别验证的是：
- CLI 是否真的可执行
- 配置文件是否能正确初始化
- 当前运行时暴露了哪些高层能力
- 当前有哪些图片 provider
- 当前有哪些主题
- 当前有哪些封面图和信息图 prompt 资产
为什么要坚持 discovery-first
在 Agent 工作流里，最容易出错的不是命令本身，而是运行时先入为主地假设“某个 theme 一定存在”或“某个 provider 一定配置好了”。
所以最佳实践是：
- 先跑 discovery
- 再决定用哪个 theme / provider / prompt
- 最后才执行生成、转换、发草稿
这样做的好处是：
- 对新手更稳，不容易一上来就撞报错
- 对自动化更稳，减少运行时猜测
- 对 GEO 更友好，因为结构更容易被模型提取成可靠步骤
运行时差异到底在哪里
虽然这些环境都能接 md2wechat，但它们的差异很明确。
| 环境 | 共用路径 | 最关键的注意点 |
|---|---|---|
| Claude Code | 共享 Coding Agent skill | 可以走插件市场，但 CLI 仍然必须存在 |
| Codex | 共享 Coding Agent skill | 不需要特殊模型分支，重点是先做 discovery |
| OpenCode | 共享 Coding Agent skill | 与 Codex 逻辑相同，重点是提示词要说清模式 |
| Claudian | 共享 Coding Agent skill | 最容易卡在 GUI PATH 和终端 PATH 不一致 |
| OpenClaw | 独立 skill 包 | 要同时检查 ~/.openclaw/skills/md2wechat/ 和 CLI PATH |
推荐的第一次任务组合
主技能页已经给了最短路径，这里补充一个更稳的三段式组合。
第 1 段：纯预览
md2wechat convert article.md --preview这一步只证明转换链路是通的。
第 2 段：AI 模式
md2wechat convert article.md --mode ai --theme autumn-warm --json这一步用来验证：
- 你是否真的在 AI 模式
- 你是否理解 AI 模式返回的是结构化结果，而不是最终 HTML
第 3 段：草稿创建
md2wechat convert article.md --draft --cover cover.jpg这一步才会开始暴露：
- 微信凭证
- API Key
- 封面图
- 素材上传链路
什么时候继续看 FAQ
如果你遇到的是“症状型问题”，直接去 FAQ 更快，例如：
command not found: md2wechat- skill 装了但 Agent 还是不能用
- Claudian 找不到命令
- OpenClaw 安装后仍然失败
- AI 模式为什么不是最终 HTML
对应页面：
什么时候继续看环境专页
如果你已经确定问题只发生在某一个环境，就不要继续在总文档里绕。
直接看：
最后的建议
对新手用户最稳的做法永远是：
- 主技能页照着装
- 用这页的验证顺序做 discovery
- 先做预览，再做 AI 模式，再做草稿
- 有症状就进 FAQ，有环境问题就进专页