Model or dataset
isjiamu/gzh-design-skill avatar
isjiamu/gzh-design-skill

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

An AI-agent skill that turns Markdown into paste-ready WeChat Official Account article HTML with one click, featuring 6 curated themes, a theme generator, and two-stage validation.

4,382 stars490 forksHTMLNOASSERTION

At a glance

What is it?
An AI-agent skill that turns Markdown into inline-styled HTML for the WeChat article editor. The interesting part is not the six themes, it is the decision to enforce platform limits with Python scripts instead of model discipline.
Who is it for?
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.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository last received commits 25 days ago.
What is it written in?
Mainly HTML, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • isjiamu/gzh-design-skill4,382 ★ · +764
Star history
Repository2026-09-112026-11-15
isjiamu/gzh-design-skill3.6k4.4k

764 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

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.

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. 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's licence badge links to the LICENSE file, and the repository metadata reports the licence as NOASSERTION, which usually means GitHub could not match the LICENSE file to a known template. Read the LICENSE file directly before relying on any particular terms. On maintenance: the last push was in October 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, what the LICENSE file actually permits, given the repository reports NOASSERTION, and whether those terms fit how you plan to modify and use the theme libraries.

Frequently asked questions

What does gzh-design-skill do with my Markdown?

It parses the Markdown, assembles HTML using the component library of the theme you chose, applies automatic chapter numbering and keyword underlining, and produces a document whose styles are all inlined so that pasting it into the article editor does not lose the formatting. A validation script must report no errors before the result is delivered.

Will it write the article for me?

No, and the readme states this in its unsuitable list: the skill only formats and does not write. Its input is Markdown you already have, including from a word processor or document file, which it first normalises into Markdown before formatting.

How do I use a style that is not one of the six themes?

There is a theme generator that takes a description or a reference image, asks for all preferences in one round, produces a full set of component blocks written to a preview file you can view in a browser, and once you confirm it converts them into a standard theme file, registers it in the theme index and lints it to zero errors. After that the new theme is used by name like a built-in one.

Official sources

  1. isjiamu/gzh-design-skill on GitHub
  2. Issues
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/isjiamu-gzh-design-skill.svg)](https://hysenlabs.com/projects/isjiamu-gzh-design-skill)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/isjiamu-gzh-design-skill.svg)](https://hysenlabs.com/projects/isjiamu-gzh-design-skill)

Was this useful?