gzh-design-skill: an AI-agent skill that turns Markdown into paste-ready WeChat article HTML

The narrow problem gzh-design-skill solves

Pasting formatted text into the WeChat official account editor is where most of the work disappears. The platform strips or ignores a long list of CSS constructs, so a page that looks correct in a browser can collapse once it lands in the editor. gzh-design-skill targets exactly that gap: the README says it turns Markdown into HTML whose styles are fully inline and whose text nodes are wrapped in `<span leaf="">`, so the formatting survives the paste.

The audience is narrow and stated plainly. The README lists the suitable cases as opinion and analysis pieces, tutorials, tool roundups, methodology write-ups, interviews, data reviews, essays and case studies, converted from Markdown, Word, PDF or plain text. The unsuitable list is just as explicit: ordinary web pages and landing pages, slide decks, pure image posters and social cards, typesetting for platforms other than WeChat, and ghostwriting. The README is blunt that the skill only lays out text and does not write it, so a Markdown file has to exist first.

That boundary matters more than the feature list. This is not a general HTML generator with a WeChat mode bolted on. It is a single-purpose pipeline, and the repository is organised around that single purpose.

How the skill pipeline works, from SKILL.md to the preview page

The entry point is `SKILL.md`, described in the README as the main workflow document and the agent's entry point. The workflow has six steps: choose a theme, read the component library, parse the Markdown, assemble the HTML, validate, and output.

The component libraries live under `references/`. There is a `theme-index.md` that the README calls the single source for the six themes' primary colours, use cases and underline colours, six `theme-*.md` files such as `theme-moyu-green.md`, a `common-components.md` for cross-theme increments like code blocks, images and small labels, a `format-normalize.md` for converting docx, PDF and plain text into Markdown, and `theme-generator.md` for producing new themes from a description or a reference image.

Assembly is where the design philosophy shows. The README states that the skill pulls real components out of the chosen theme library rather than inventing markup, and that it applies automatic chapter numbering, keyword underlines, full-width Chinese punctuation, an extracted quote card and table of contents, and a merged author signature. Punctuation normalisation is scoped: body text is converted to full-width, code blocks are left alone.

The output is two artefacts. One is clean body HTML. The other is a preview page carrying a copy button, so the reader opens it in a browser, clicks copy, and pastes into the WeChat editor without a manual select-all. The README describes the platform constraints the generated HTML obeys: no `<style>`, `<script>` or `<div>`, no `class` or `id`, no `position:fixed/absolute/sticky`, no `float`, no `@media` or `@keyframes`, no `display:grid`, no CSS variables and no external fonts. Those rules are enforced by scripts, not by the model remembering them.

Installing gzh-design-skill and running a first article

The README gives three installation routes. The recommended one is a single npx command:

npx skills add https://github.com/isjiamu/gzh-design-skill

The second route is to ask any agent to find and install the repository itself, which the README says will clone it into the appropriate skills directory. The third is a manual clone into the Claude Code skills path:

git clone https://github.com/isjiamu/gzh-design-skill.git ~/.claude/skills/gzh-design

After installation, the README's example instruction to the agent is a single sentence naming the theme and the input file:

> 用摸鱼绿把这篇文章排成公众号 HTML：`article.md`

In English that reads: use the moyu-green theme to lay this article out as WeChat HTML, from `article.md`. The agent then reads the theme library, parses the Markdown, assembles the HTML and runs the product-side validator. The README states that the validator must reach zero ERROR before delivery.

If you change the component library or the workflow, the README describes a two-gate loop to catch regressions. The source gate scans the component library for anti-patterns, and the product gate scans the final HTML for compliance:

python3 scripts/component_lint.py .            # 源头关：扫组件库反模式
python3 scripts/validate_gzh_html.py out.html  # 产物关：扫最终 HTML 合规

The README says the source gate checks for `white-space:pre`, dashed boxes around body text and banned platform constructs, and must report zero ERROR. The product gate checks banned tags, `<span leaf>` wrapping and half-width punctuation, and must report zero ERROR and zero half-width WARN. Both scripts are plain Python 3 and are invoked directly, so no build step or package install is implied by the README.

What the two validation gates actually check, and what they do not

The interesting claim in this repository is the division of labour. The README states the logic as: clean source implies clean output. Platform restrictions are treated as dead rules and pushed down into `component_lint.py` and `validate_gzh_html.py`, leaving the model to make content judgements.

That is a real architectural choice, and it has a consequence the README does not dwell on. The scripts check structure and punctuation. They cannot tell whether the chosen theme suits the article, whether a keyword underline landed on the right phrase, or whether an extracted quote card represents the piece fairly. Those remain model decisions, and the README's own framing admits it: the model does content judgement. So the two gates raise the floor on mechanical compliance and do nothing for editorial quality.

The README also states that the source gate must report zero ERROR, which means a theme author who introduces a banned construct gets a hard stop rather than a warning. That is stricter than most lint setups and will surprise anyone extending the component libraries. The `references/eval-cases.md` file is described as holding trigger cases and the verifiable loop, so the intended workflow for a new theme or component is to add cases there rather than to eyeball the output.

Limits, wrong-tool cases and the licence question

The README's own unsuitable list is the first limitation: no ordinary web pages, no slides, no image posters, no non-WeChat platforms, no ghostwriting. If your destination is a blog, a newsletter or a static site, the inline-style constraint that makes WeChat work becomes dead weight in the markup.

The second limitation is the theme count. Six themes ship, and the README positions the theme generator as the answer when those are not enough. A generated theme is not the same as a maintained one: the README says generated component libraries are saved locally for reuse, which means the quality bar and the upkeep of that theme are yours, not the project's.

The third is the repository's own state. The last push was on 2026-07-08, and the most recent release is v1.0.0 from 2026-07-06, so the project has not moved in roughly two months. Nothing in the repository is archived, but a reader should treat the current theme set and scripts as the state of the art rather than expect frequent additions.

On licensing, the README carries an AGPL-3.0 badge and links to a `LICENSE` file, while the repository metadata reports NOASSERTION. Those two signals disagree about the exact terms, so anyone planning to redistribute the skill, or to build a hosted service on top of it, should read the `LICENSE` file itself. This is a factual discrepancy to resolve, not legal advice, and the AGPL family generally imposes source-availability obligations that a permissive licence would not.

How it differs from a browser-based Markdown-to-WeChat converter

The obvious alternative is a web tool where you paste Markdown, pick a style and copy the rendered result. Those tools generally ship a fixed set of templates and run the conversion in the browser, and they are the right answer if you want a one-off conversion with no agent involved.

The difference here is where the rules live. In a browser converter the platform restrictions are baked into the renderer by its authors. In gzh-design-skill they are written down as checks in `component_lint.py` and `validate_gzh_html.py` and shipped alongside the themes, so the same rules apply whether the HTML was assembled by Claude, Codex or Cursor. The README makes this explicit as a design goal: the layout logic sits in the component libraries and scripts rather than in a particular model, so switching models does not change the output.

That portability is the actual product. A converter gives you a result. This gives you a result plus a repeatable way to check it, and a documented path to add a theme when the six do not fit. The cost is that you need an agent that can read files and run Python, and you need to keep the component library and the scripts in sync. A converter asks nothing of you beyond a browser tab.

Who this fits, and what to check before adopting

The fit is specific: you publish long-form articles through the WeChat official account editor, you already write in Markdown or can normalise from Word and PDF, and you run an agent such as Claude Code, Codex or Cursor that can read the skill directory and execute Python 3. Under those conditions the six themes plus the two gates give you a predictable output floor, and the preview page's copy button removes the manual select-all step.

The misfit is equally specific. If you need a landing page, a deck, a poster or typesetting for another platform, the README says to use a different skill, and the inline-style approach will actively get in your way. If you want the tool to write the article, it will not; the README states it only lays out text.

Before committing, verify three things against your own material. Run `python3 scripts/component_lint.py .` on a fresh clone to confirm the shipped component libraries pass their own source gate. Then run `python3 scripts/validate_gzh_html.py out.html` on a real article and check that the half-width punctuation warnings are zero, since that is the noisiest check. Finally, open the generated preview page, click copy, and paste into the WeChat editor to confirm the inline styles survive on the current platform. If all three hold, the pipeline is doing what the README claims.

Editorial conclusion

Adopt it if you publish long-form Chinese articles through the WeChat editor and already write in Markdown; the six themes and the two validation scripts give you a repeatable output floor. Skip it if you need a landing page, a PPT, a poster, or non-WeChat typesetting, and note that it does not write articles for you. Before trusting it, run python3 scripts/component_lint.py . and python3 scripts/validate_gzh_html.py out.html on your own article and confirm both report zero ERROR, then paste the result into the WeChat editor to see whether the inline styles survive.

Frequently asked questions

Official sources

1. isjiamu/gzh-design-skill on GitHub
2. Issues
3. Project website
4. README
5. Releases