md2wechat-skill Guide: Installation, First Run, and What Agents Should Do First

If you only remember one thing about md2wechat-skill, remember this:

install the CLI first, then install the skill.

That single rule removes most of the confusion people hit in Claude Code, Codex, OpenCode, and Claudian.

What md2wechat-skill actually is

md2wechat-skill is not just another WeChat API wrapper.

It is a distribution layer for agent runtimes that already understand reusable skills. That means the project does two jobs at the same time:

• it exposes the md2wechat workflow in an agent-friendly shape
• it gives agents a more reliable calling pattern than a loose set of copied shell commands

That matters because most failures are not really about Markdown conversion. They happen earlier:

• the CLI is missing
• the runtime guesses the wrong mode
• the runtime assumes a theme or provider exists without checking
• users mix up the Coding Agent path with the OpenClaw path

The practical install order

For Claude Code, Codex, OpenCode, and Claudian, the stable path is:

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

If you do not use Homebrew, the next two choices are:

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

or:

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

The important part is not the installer brand. The important part is the install order.

npx skills add only installs the skill definition. It does not place the md2wechat binary into your PATH.

Why discovery should always happen before execution

One of the clearest ideas in the upstream docs is the discovery-first rule.

Before the agent chooses a provider, theme, or prompt template, it should ask the CLI what is actually available:

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

That avoids a long chain of bad assumptions.

It answers:

• is the runtime installed correctly
• which mode is the default
• which image providers are configured
• which themes and prompt presets exist right now

For agent workflows, that is far safer than relying on memory.

The first workflow that should succeed

Once installation and discovery are done, the first successful task should be boring:

md2wechat convert article.md --preview

That proves the basic CLI path works.

Then you can move to the next layers:

AI mode:

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

Draft creation:

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

The split matters:

• preview confirms the CLI path
• AI mode confirms structured themed output
• draft creation confirms you also have WeChat credentials and cover handling in place

The mistakes that waste the most time

1. Installing the skill but not the CLI

This is the most common one.

The runtime sees the skill and looks healthy, but the first real command fails with command not found: md2wechat.

That is not a content problem. It is not a theme problem. It is a missing runtime problem.

2. Forgetting that API mode is the default

If you call:

md2wechat convert article.md

you are in API mode unless you explicitly add --mode ai.

This matters because AI mode does not behave like direct API conversion. It produces structured output for a second model step.

3. Treating OpenClaw as if it shared the same path

It does not.

OpenClaw uses a separate skill package and its own skill directory. The Coding Agent route and the OpenClaw route should be documented and installed separately.

4. Skipping capability checks

Many people want to jump straight to “use the premium theme” or “generate the cover”.

But the stable move is still:

md2wechat capabilities --json

That one command prevents a surprising number of misfires.

A good prompt to send any Coding Agent

If you do not want to manually type commands yourself, send a prompt like this:

Please install md2wechat CLI first, then install the md2wechat skill, verify version and capabilities, and stop only after every command succeeds.

After that, use:

Run md2wechat capabilities --json first, then convert article.md into WeChat HTML and show me the preview.

This keeps the agent honest. It must prove the runtime exists before it starts promising output.

Where to continue

If your main runtime is a Coding Agent, continue with:

• Coding Agents
• Claude Code
• Codex
• OpenCode

If your path is environment-specific, continue with:

• Claudian
• OpenClaw

And if you want the compact reference form, keep the docs page nearby:

• md2wechat-skill Guide