md2wechat-skill

md2wechat-skill is the official Skill entrypoint for using md2wechat inside agent runtimes such as:

• Claude Code
• Codex
• OpenCode
• Claudian inside Obsidian
• OpenClaw

If you remember only one rule, remember this:

install the md2wechat CLI first, then install the md2wechat skill.

Repository:

https://github.com/geekjourneyx/md2wechat-skill

Who this page is for

This page is for:

• people using Claude Code, Codex, or OpenCode who want to convert Markdown into WeChat Official Account HTML
• people who want to use md2wechat inside Obsidian through Claudian
• people who want to install and validate the OpenClaw version
• beginners who want one structured onboarding page instead of jumping across multiple documents

Read this first

Before you install anything, keep these 6 rules in mind:

• npx skills add ... installs the skill only. It does not install the md2wechat CLI.
• md2wechat convert defaults to API mode when --mode is omitted.
• If you want AI mode, pass --mode ai explicitly.
• Do not guess which themes, providers, or prompts exist. Run discovery commands first.
• OpenClaw is a separate path. It does not share the same skill package as Claude Code, Codex, or OpenCode.
• Draft creation and material upload still require WeChat credentials. API mode usually also needs an md2wechat.cn API key.

5-minute quickstart

If you only want the shortest working path, do this in order.

Step 1. Install the CLI

Preferred on macOS:

brew install geekjourneyx/tap/md2wechat

If you already have a stable Go toolchain:

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

If neither path fits, use the pinned installer:

curl -fsSL https://github.com/geekjourneyx/md2wechat-skill/releases/download/v2.0.3/install.sh | bash

If you used the installer, refresh PATH:

export PATH="$HOME/.local/bin:$PATH"

Step 2. Install the skill

Claude Code, Codex, OpenCode, and Claudian share this install command:

npx skills add https://github.com/geekjourneyx/md2wechat-skill --skill md2wechat

Step 3. Verify installation

md2wechat version --json
md2wechat config init
md2wechat capabilities --json

Step 4. Run the first successful task

md2wechat convert article.md --preview

If this works, your main CLI path is already healthy.

Choose your runtime

Claude Code / Codex / OpenCode

These three runtimes should be approached in the same order:

1. install the CLI
2. install the skill
3. run discovery
4. ask the agent to do the real job

Recommended commands:

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

A good prompt to send the agent:

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

Obsidian / Claudian

Claudian uses a Claude Code compatible skill path, so the install order is still:

1. install the CLI
2. install the skill
3. go back to Obsidian and call it there

Recommended commands:

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

Back in Claudian, try either:

/md2wechat

or:

Please use md2wechat to convert the current Markdown note into WeChat HTML and show me a preview first.

If Terminal can find md2wechat but Claudian cannot, check the GUI PATH in:

• Settings
• Environment
• Custom variables

Then add a value like:

PATH=/Users/your-name/.local/bin:existing-path

OpenClaw

OpenClaw is a separate installation path. You need both of these:

• the OpenClaw skill shell under ~/.openclaw/skills/md2wechat/
• the md2wechat CLI available in PATH

Fastest complete install path:

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

Then verify:

md2wechat version --json
md2wechat config init
md2wechat config validate
md2wechat capabilities --json
ls ~/.openclaw/skills/md2wechat/

If you already use ClawHub, you can install the shell with:

npx clawhub@latest install md2wechat

But that usually guarantees only the shell, not the CLI runtime. Check immediately:

command -v md2wechat

What to run first

Do not start with draft creation. Go from simple to sensitive.

1. Preview conversion

md2wechat convert article.md --preview

2. AI mode

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

Important note:

• this is not direct final HTML generation
• it returns structured output for a second model step

3. Draft creation

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

This step usually also requires:

• WeChat AppID
• WeChat Secret
• an md2wechat.cn API key for API-mode workflows
• a valid cover image

Why discovery should happen before execution

md2wechat-skill is designed for agent workflows, and agents fail most often when they assume runtime capabilities instead of checking them.

Before execution, run:

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

This tells you:

• which mode is the default
• which image providers are configured
• which themes exist
• which cover or infographic prompt presets exist

This also improves SEO and GEO value because the page presents a stable, extractable workflow instead of a vague feature list.

Common questions

Why does the agent still say command not found: md2wechat?

Because the skill was installed, but the CLI runtime was not.

Install the CLI first:

brew install geekjourneyx/tap/md2wechat

Then verify:

md2wechat version --json

Why did the agent use API mode when I did not pass --mode?

Because md2wechat convert defaults to API mode when --mode is missing.

To force AI mode:

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

Why does AI mode not return final HTML?

Because AI mode is designed to return structured output for a second model step. It is not the same as direct API conversion.

Why can Terminal find the tool but Claudian cannot?

Because GUI applications often inherit a different PATH. Update Claudian Settings -> Environment -> Custom variables first.

Why does OpenClaw still fail after skill installation?

Because OpenClaw needs both:

• the shell under ~/.openclaw/skills/md2wechat/
• the md2wechat CLI in PATH

If one side is missing, the workflow is still broken.

Why should I run capabilities --json first?

Because it gives the real runtime snapshot. It is more reliable than any remembered feature list.

Where to continue

Once the main path is working, continue here based on your needs:

• md2wechat-skill Guide
• md2wechat-skill FAQ
• Coding Agents
• Claude Code
• Codex
• OpenCode
• Claudian
• OpenClaw