gzh-design-skill: Markdown to WeChat HTML with a Two-Gate Lint Loop

The problem is WeChat's editor, not Markdown

WeChat's article editor is a rich-text field that quietly strips a lot of what a normal web page relies on. The README lists what the generated HTML must avoid: style and script tags, div elements, class and id attributes, position fixed, absolute and sticky, float, media queries, keyframes, display grid, CSS variables, and external fonts. Anything that survives has to be inline, and according to the project every text node is additionally wrapped in a span with a leaf attribute. That is not a stylistic preference, it is a compatibility contract with a specific editor. The target user is someone who already has a finished Markdown draft and wants it to land in the WeChat composer without manually rebuilding headings, code blocks and images by hand. The README is explicit that the skill only typesets and does not write: it is for people with content, not people looking for content.

Where the real work lives: SKILL.md, theme libraries and two scripts

The repository layout shows the split. SKILL.md is the agent entry point and holds the workflow. references/ holds theme-index.md as the single source for the six themes, one theme-*.md component library per theme, common-components.md for cross-theme pieces like code blocks, images and small labels, format-normalize.md for converting docx, pdf or plain text into Markdown, and theme-generator.md for producing a new theme from a sentence or a reference image. scripts/ holds the two validators. assets/ holds a sample article and previews of generated theme blocks, and docs/gallery/ holds a browser preview. The design principle stated in the README is that the typesetting logic lives in the component libraries and scripts rather than in the model, so the same input should produce a consistent result across Claude, GPT, Gemini or domestic models. That claim is architectural, not measured here: nothing in the supplied material reports output diffs across models.

What the skill does to your Markdown before it becomes HTML

The documented pipeline has six steps: pick a theme (the skill recommends one by article type and asks you to confirm, defaulting to 摸鱼绿), read the chosen theme library plus the common increment library, parse the Markdown into headings, sections, bold, highlights, quotes, images, code blocks and lists, assemble HTML from real components in the library, run the validator, then output the clean body plus a preview page with a copy button. Along the way it applies automatic section numbering (with the last chapter rendered as the infinity symbol or three slashes), marks one to three keywords per paragraph with an underline, extracts a pull quote and a table of contents from the body, deduplicates and merges the author signature, and normalizes CJK punctuation to full width while leaving code blocks untouched. The colour rule is stated numerically: the primary colour appears at most five times per article, roughly 90 percent of text uses a neutral grey scale, and colour is decoration only.

Getting it running: three install paths and two commands you will actually repeat

The recommended install is a single command: npx skills add https://github.com/isjiamu/gzh-design-skill. The second path is to ask any agent to find and install the skill, and the README gives the prompt: 请帮我查找并自动安装 https://github.com/isjiamu/gzh-design-skill 这个 skill. The third is a manual clone into the Claude skills directory: git clone https://github.com/isjiamu/gzh-design-skill.git ~/.claude/skills/gzh-design. After that you address the agent in natural language, for example asking it to typeset article.md in 摸鱼绿. The two commands worth memorizing are the validation pair: python3 scripts/component_lint.py . for the source gate over the component libraries, and python3 scripts/validate_gzh_html.py out.html for the product gate over the final HTML. The README states the source gate must reach zero ERROR and the product gate must reach zero ERROR with zero half-width punctuation WARN before delivery. Note the Python 3 dependency: this is not a pure prompt skill, it assumes an interpreter is present.

The two-gate loop is the strongest idea and also the sharpest constraint

The README's stated logic is that a clean source implies a clean product, so the source gate scans the component libraries for anti-patterns such as white-space: pre, dashed boxes around body text, and platform-forbidden constructs, while the product gate scans the generated HTML for banned tags, missing span leaf wrappers, and half-width punctuation. This is the part I would defend. Platform limits are dead rules, and dead rules belong in a deterministic checker rather than in a model's memory. The trade-off is that the loop only protects what the scripts know how to look for. A theme that is visually poor but syntactically clean passes both gates. There is no rendered-output comparison, no screenshot diff, and no accessibility check in the material provided, so the gates catch compliance, not taste. The README points to references/eval-cases.md for the trigger cases and the verifiable loop, which is where I would look first if the gates ever pass something that still looks wrong in the editor.

The theme generator, and what happens when six is not enough

The theme generator is described as taking a one-sentence description or a reference image and producing a new component library that is saved locally for reuse. The repository layout supports this: assets/theme-previews/ is described as holding block-library previews produced by the generator. The practical consequence is that the theme count is not a ceiling, which weakens the usual complaint about preset design systems. It also introduces a maintenance surface that the six shipped themes do not have, because a generated library is your artifact, not the project's, and it will not receive upstream fixes. If you generate a theme, run python3 scripts/component_lint.py . against it before trusting it, since the source gate is the only automated check that will see it.

A genuine limitation: the skill cannot tell you the article reads well

Everything the project enforces is syntactic. Full-width punctuation, inline styles, span leaf wrappers, keyword underline counts, colour frequency caps. None of that is about whether the pull quote you extracted is the right sentence or whether three underlined keywords per paragraph is too many for a dense technical piece. The README presents keyword marking as a feature without a stated upper bound beyond the one-to-three range per paragraph, and in a long tutorial that range may still produce a visually noisy page. The honest position is that the skill removes a mechanical chore and replaces it with a review chore: you still have to look at the preview page before you paste. The copy-button preview exists precisely because the output is meant to be inspected, not trusted blind.

The alternative, and where the difference actually shows

The obvious alternative is a general Markdown-to-HTML converter paired with a CSS theme, the kind you would reach for when publishing to a blog or a static site. The difference is not output quality, it is the constraint model. A general converter emits semantic markup and a stylesheet, which is the right answer for a browser and the wrong answer for the WeChat editor, because the editor strips the stylesheet and much of the markup with it. gzh-design-skill inverts this: it emits no stylesheet at all, inlines everything, and wraps text nodes so that the pasted result keeps its appearance. The cost of that inversion is that the HTML is unpleasant to read, hard to hand-edit, and useless outside WeChat. If your target is a blog, a general converter wins on every axis. If your target is the WeChat composer, the general converter produces something that collapses on paste, and the README's list of forbidden constructs is essentially a description of why.

Licence, maintenance and what to check before you depend on it

The README badge and the badge text both say AGPL-3.0, and the repository metadata reports the licence as NOASSERTION, which usually means GitHub could not match the LICENSE file to a known template. Those two signals disagree, and the supplied material does not resolve it, so read the LICENSE file directly rather than trusting either. If AGPL-3.0 is correct, the network-copyleft clause matters for anyone who modifies the component libraries and serves the output from a hosted tool; that is a legal question for your own counsel, not something this review can settle. On maintenance: the project was pushed in July 2026, v1.0.0 is labelled 联名首发 (a co-branded first release), and the README credits 甲木 and 摸鱼小李 as co-builders, so theme libraries and validation rules are maintained by a small group rather than a foundation. The upgrade path is cheap for the scripts (drop in the new versions and rerun both gates) and expensive for generated themes, which will not track upstream changes. Verify the install path, the licence file, and the Python dependency before you build a publishing routine around it.

Editorial conclusion

Adopt gzh-design-skill if you already write in Markdown and publish to WeChat, and if you are willing to keep Python 3 available because validate_gzh_html.py and component_lint.py are the load-bearing parts, not the themes. Do not adopt it for landing pages, slide decks, image posters, or any non-WeChat target; the README rules all of those out, and the inline-style constraint would make the output worse there, not better. It also will not write your article. Before committing, verify three things yourself: that npx skills add resolves for your agent, that the LICENSE file actually contains AGPL-3.0 text given the repository reports NOASSERTION, and that you accept the AGPL network-copyleft obligation if you plan to modify the theme libraries and expose the result as a service.

Official sources

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