Communitygithub.com

isjiamu/gzh-design-skill

把 Markdown 一键排成可直接粘进公众号编辑器的精致 HTML —— 6 套精选主题 + 主题生成器 + 双关卡校验。An AI-agent skill that turns Markdown into paste-ready WeChat article HTML.

gzh-design-skill 是什么?

gzh-design-skill is a Claude Code agent skill that 把 Markdown 一键排成可直接粘进公众号编辑器的精致 HTML —— 6 套精选主题 + 主题生成器 + 双关卡校验。An AI-agent skill that turns Markdown into paste-ready WeChat article HTML.

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add isjiamu/gzh-design-skill

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

预览

来自技能 README

Alt
gzh-design-skill preview
Alt
gzh-design-skill preview

文档

WeChat Article Formatting Skill

Convert a Markdown article into HTML that can be directly copied and pasted into the WeChat Official Account editor, with formatting preserved after pasting.

The core assets are the theme component libraries under references/ (each theme includes: design variables + full HTML for each component + template skeleton + mapping rules) plus 1 shared incremental library (code blocks / images·GIFs / small tag titles, shared by all themes). The theme list is sourced solely from references/theme-index.md. This SKILL.md only handles the workflow and decisions; all specific HTML code must be taken from the component library — never write it from memory.

Workflow

0. Input & Format Normalization

The user may provide: Markdown text or a .md path (directly proceed to Step 1), .docx, .pdf, .txt/unmarked plain text, or rich web text. Non-Markdown input must first read references/format-normalize.md and follow its rules to convert into a Markdown draft and confirm the structure (docx uses scripts/extract_docx.py, PDF uses Read to read page by page and clean noise, plain text uses heuristic heading inference for structure). If nothing is provided, ask the user.

When the user says "format directly / auto-format / one-click / don't ask," enter full-auto mode: skip structure confirmation and theme selection questions, automatically infer structure, select a theme based on the subject, format and validate, then deliver with a decision explanation (chapter structure, self-generated titles, theme selection rationale).

1. Theme Selection (Auto-Recommendation System)

Read references/theme-index.md (the single source of truth for theme info). Proactively recommend the most fitting theme based on the article's subject, then ask the user to confirm — recommend but don't finalize without asking:

  • User specified a theme in the request → Use it directly, no questions.
  • Subject has a clear match → Single-question confirmation: "Suggest XX (reason), confirm or switch?" Offer the recommendation + 1~2 alternatives + "See all." Subject→theme fit reference (see theme-index "Use Case" column):
    • Tutorial / Review / Checklist / Tool Roundup / Knowledge Organization / Methodology Breakdown (high info density) → Mo Yu Green
    • Deep Analysis / Opinion / Powerful Topic → Red-White Color Scheme
    • Design / Tech Review / Professional Opinion / High-End Brand → Graphite Minimalist Style
    • Zen / Minimalist Life / Deep Essay → Negative Space Zen Style
    • Tool Comparison / Creative Review (ticket visual metaphor) → Mo Yu Ticket Style
    • In-House Notes / Deep Review / Case Study → Olive Notes
  • No clear tendency → Default to the first row in theme-index (Mo Yu Green) as the first recommended item. Use AskUserQuestion to let the user choose from a few options (if more than 4 themes, first group by style and ask about the group, then ask about specific themes within that group).
  • Full-auto mode (user explicitly said "format directly / one-click / don't ask") → Don't ask, automatically select the best-fitting theme or default to the first row, and explain the choice when delivering.
  • User is not satisfied with any existing theme / wants a new style → Follow the "Custom Theme Generation" process (see next section), generate and register it, then return to this step to use it.
  • theme-index is empty → Stop formatting, inform the user that they need to add a theme style first (they can use "Custom Theme Generation").

Only after the user decides on a theme, enter the component matching for that specific theme (Steps 3 and 4: determine article type → select component combinations based on that theme's recipe table).

2. Read Component Libraries (Two Sets)

(1) Based on the theme's "Component Library File" column in theme-index, Read that theme's dedicated component library references/theme-{identifier}.md (contains theme-specific components: intro cards, section titles, body markers, signatures, etc.). (2) Simultaneously Read the shared incremental library references/common-components.md — code blocks, images/GIFs, and small tag titles are shared by all themes; just apply the current theme's primary color.

All subsequent generation is based strictly on these two component libraries; HTML must be taken from them, never written manually.

3. Parse Markdown Structure

ElementIdentification Rule
Article Title# Title or frontmatter title
Opening Intro> Quote block at the very beginning
Section Title## Title
Sub-section### Title
Bold / Highlight / Underline**Text** / ==Text== / <u>Text</u> or ++Text++
Quote Paragraph> Text not at the beginning
Image / GIF![Alt](URL)、![](xxx.gif) (GIFs are treated the same as images)
Code / Command / Prompt``` Fenced code block ```, inline `code`
Horizontal Rule / List---、*** / - Item or 1. Item
TableMarkdown table separated by | (often from docx conversion) → Prefer the theme library's table/card component (use the theme library's mapping rules)

After parsing the structure, determine the article type (use the dominant type, can be composite): Tutorial/How-to Guide, Roundup/Tool Checklist, Opinion/Deep Analysis, Interview/Person Profile, Data Review/Report, Life/Emotional Essay, Case Study. Basis: many steps and commands → Tutorial; many parallel items → Roundup; many quotes and narrative → Interview; many numbers and comparisons → Data; many arguments and reasoning → Opinion.

4. Select Component Combination by Recipe → Assemble HTML

First, consult the selected theme library's "Article Type → Component Combination Recipe" table, and determine this article's core component combination and accent components based on the article type — don't pick components sequentially at random once you have the library; the recipe ensures stable typographic style for articles of the same type. Elements outside the recipe are then supplemented according to the theme library's mapping rule table.

Then, follow the theme library's "Complete Article Template Skeleton" section to assemble, replacing each Markdown element with its corresponding component:

  • Follow the skeleton order of the selected theme library — different themes may have different skeletons; do not reuse skeletons from other themes.
  • Match inline markers semantically to corresponding components in the selected component library (component numbers vary between libraries; always match by semantics, not fixed numbers): **Bold**→bold with theme primary color; ==Highlight==→gradient background highlight; <u>Text</u> or ++Text++→underline; ~~Text~~→highlighter (bottom half-highlight); >Quote→highlighted quote block.
  • Components from the shared incremental library: ``` Code block ``` → 1a dark / 1b light code block, inline `code` → 1c; ![Alt](url) → 2a image (only add caption component if alt text exists), .gif → 2b GIF; Sub-heading/Emphasis that needs highlighting → 3a left vertical bar sub-heading or 3b pill tag, golden sentence → 3d, tip aside → 3e. Priority: first check the theme library's mapping rule table — if that theme has an equivalent semantic component (e.g., its own golden sentence/tip block), use the theme library version for consistent style; only use shared library 3x components when the theme library has no equivalent, and apply the theme's color scheme conversion rules.
  • A single article uses only the components from the selected theme — do not mix components across themes.
  • Emphasis and sub-headings use "small tag / left vertical bar" — do not use dashed borders: To highlight a sub-heading or a section of content, use the left vertical bar sub-heading (3a), pill tag (3b), left vertical bar golden sentence/tip block (3d/3e); do not use a dashed border (dashed border) around a title — that is bulky and overpowers the content.

5. Validation (Mandatory)

After writing the generated HTML to the target file, you must run the validation script. It must report 0 ERRORs for completion:

# Call using the absolute path of the skill root where the script is located. The HTML parameter should also use its actual path (they are usually in different directories).
<SKILL_ROOT>/scripts/validate_gzh_html.py <path/to/generated/.html>

It deterministically checks for platform-prohibited items and <span leaf> wrapping. If it reports ERRORs, go back to Step 4 to fix them; semicolon WARNINGs must also be fixed to 0 before delivery (this is the most common rework point in actual use).

6. Output

Output format: pure <section>…</section> body fragment, starting from the global container. Do NOT wrap with <!DOCTYPE>/<html>/<head>/<body> — the WeChat editor only accepts body fragments; extra document shells will be discarded or interfere with pasting.

  1. Clean body file: Save HTML to the current working directory with filename {original_filename}_formatted_{theme_Chinese_name}({english_identifier}).html (English identifier = theme-index component library filename with theme- prefix and .md suffix removed). This file is used for validation and manual paste fallback.
  2. Preview page with "Copy" button (for one-click copying, avoiding manual select-all):
    <SKILL_ROOT>/scripts/wrap_preview.py <path/to/clean_body.html>
    
    Produces {...}_preview.html — when opened in a browser, there is a "Copy to WeChat" button in the top-right corner. Clicking it copies the rendered rich text to the clipboard (equivalent to Ctrl+A/Ctrl+C), which can then be pasted with Ctrl/⌘+V into the WeChat editor. The button and script are only in the preview wrapper, not inside the copied <section>, so what gets pasted into WeChat is still the clean, compliant body.
  3. Inform the user: Open {...}_preview.html → Click "Copy" in the top-right → Paste in the WeChat editor; also provide the path to the clean body file as a fallback. Attach the validation script conclusion (passed / remaining warnings).

Intelligent Processing During Generation (These are the skill's unique features; must be done)

  1. Automatic Chapter Numbering: Assign 01/02/03… based on the order of ##; if the last chapter is a conclusion/summary type, use the conclusion numbering variant specified by the theme library (e.g., ∞); if the theme library does not specify, continue using numeric numbering.
  2. English Tags: Generate English tags based on the Chinese chapter titles (e.g., 实测→TEST, 教程→TUTORIAL, 总结→SUMMARY, 思考→THOUGHTS…). Use when the theme library has corresponding slots.
  3. Keyword Underlining in Body (Core Feature): For each body paragraph, actively identify 1–3 most important phrases and mark them with the theme's underline CSS (see theme-index). Prioritize core opinions, conclusions, key data, and proper nouns; phrases should be 4–15 characters; if a paragraph has no key points, it's okay to skip. Even if the original text has no bold, actively add underlines — it is the most frequent basic marker.
  4. Intro Quote Keyword Highlighting: Identify core words in the opening golden sentence and mark them with the highlight component.
  5. Table of Contents Extraction: Take the first 3 from all ## headings as guide/table of contents points (when the theme library has a TOC component).
  6. Opening Intro Card Attribution: Based on the article's author or theme — if the article has an attribution, write "— Author Name"; if no clear author, use a short attribution related to the theme or omit it entirely. Do not hardcode "甲木" (the tail signature area also uses {{Author Name}} as a placeholder; see item 7).
  7. Tail Author Signature Area (Self-Fill, Only One at the End): Do not hardcode any name by default; use placeholder signatures for the user to replace with their own.
    • First sentence (Author Introduction): I am {{Author Name}}, {{One-sentence bio, e.g., passionate about sharing AI insights}} — if the user provided their signature or bio in the request/preferences, fill it in directly; if not, keep the {{Author Name}} / {{Bio}} placeholder and remind the user to replace it when delivering.
    • Second sentence (Engagement Prompt, universal, can be kept as-is): If you found today's article valuable, feel free to **Like, Wow, and Share** — see you in the next one!
    • If the original text already has an author signature paragraph at the end (e.g., "I'm XXX…") → directly use the original signature; do not replace with placeholders.
  8. List Conversion: Process according to the theme library's mapping rules; if there is no dedicated list component, convert into indented body paragraphs.
  9. Chinese Full-Width Punctuation: Body punctuation must be full-width (,。!?:;""''()—— …), not half-width , . ! ? : or straight English quotes " '. When generating HTML, directly use curved quotes""'', not straight quotes that are later replaced — straight quotes in the original text should be converted on the spot. Exceptions: Code blocks, inline code, English proper nouns/URLs/code identifiers should remain unchanged.

Visual Hierarchy (3 Levels, Universal Across Themes)

LevelPurposeFrequencyMethod
Anchor LevelStrongest anchor: product names/steps/CTA/core golden sentences≤ 5 times in the entire articleBold with theme primary color, dark background with white text quote
Mark LevelBody keywords, 1–3 per paragraphHigh frequencyUnderline marker
Container LevelQuote blocks, concept tags, long sentence emphasisAs neededLight background quote, highlighter, badge

Platform Red Lines (Core, Full Check by Validation Script)

  • Prohibited: <style>/<script>/<div>, class/id attributes, position:fixed/absolute/sticky, float, @media/@keyframes, display:grid, CSS variables, external fonts/CSS.
  • Required: All styles must be inline style; all text nodes must be wrapped in <span leaf="">Text</span> (otherwise styles are lost after pasting).
  • Allowed: display:flex (limited), linear-gradient, border-radius, box-shadow, <section>/<p>/<span>/<strong>/<img>/<h3>.

Gotchas (Real Formatting Pitfalls)

  • Missing <span leaf> wrapping is the most common fatal error — after pasting into WeChat, styles are lost across the entire block. The validation script in Step 5 is the safety net; don't skip it.
  • Underlining: implement per paragraph, 1–3 phrases per paragraph. Don't underline an entire paragraph (loses focus), and don't miss any paragraphs. Also mark key descriptions in list items.
  • Chapter numbering errors: Strictly follow the order of ##; don't skip numbers. The conclusion numbering variant is only for the final chapter; don't use it in middle chapters.
  • Signature area: only one at the very end: Use fixed copy; do not appear in the middle or multiple times. If the original text already has an author signature / "Like, Wow, Share" paragraph at the end, merge it into this single signature area/CTA card. Don't keep the original paragraph and also generate another one.
  • Forcing image captions: Only generate a caption component when ![Alt](url) actually has alt text; for ![](url) with an empty alt, do not invent a caption.
  • Images adapt, do not stretch: <img> must always have max-width:100%;height:auto;display:block;margin:0 auto — display at the image's own size, centered; large images scale down to container width, small images maintain their original size. Do not use width:100% (which would stretch small images and make them blurry). Only use width:100% for layout elements like tables, cover cards, and flowcharts.
  • Mixing components across themes: An article uses only components from the selected theme + the shared library. Do not borrow components from other themes.
  • Overusing the anchor level: The strongest emphasis should be used ≤ 5 times in the entire article; if everything is bolded, nothing stands out.
  • Missing original content: Each paragraph, each image must be converted; do not skip. Do not add or remove substantial content from the original text.
  • Placeholder images left in: If a signature area/CTA component includes a placeholder card image (e.g., <img src="...name card or guide image URL">), remove the entire line if there is no real image URL. Do not leave placeholders in the final output.
  • Table of contents is a selection, not exhaustive: The preface/TOC component displays a selection of 3 core highlights, not the full chapter list. When there are more than 3 chapters, pick the 3 most important ones. Don't force-feed all or mislead readers into thinking there are only 3 chapters.
  • No dashed borders: To highlight a title/emphasis, use a small tag or left vertical bar (shared library 3a–3e). Do not use border:…dashed around a title. Exception: If the theme library explicitly defines a dashed component (e.g., Mo Yu Green's quote-box quote frame, oneliner-card highlight card), it is a style characteristic of that theme and can be used normally according to the theme library's usage.
  • Punctuation — don't mix half-width: Half-width commas, periods, and straight English quotes " ' in the body must all be changed to full-width. However, maintain original half-width symbols inside code blocks and inline code; do not "full-width-ify" code.
  • Code/Prompt must use code blocks: Code, commands, and prompts in the article must use the shared library's code block component (1a/1b). Do not put them into regular paragraphs or quote blocks, or indentation and monospace will be lost.
  • Code blocks should be compact, avoid large blank spaces: Use shared library 1a/1b's "one line per <p style="margin:0">" method. Never use white-space:pre — it would render indentation before spans and line breaks in the HTML source as large left indentation and blank lines. Only use full-width spaces   for indentation, and control line spacing via line-height:1.6.
  • Center placeholder materials: For [Insert…], pending screen recording/GIF/video/result images, etc., use the shared library's 2c centered material placeholder block (light background with a soft dashed frame + centered icon and description). Do not use left-aligned tip blocks.

Custom Theme Generation (Second Workflow)

When the user wants a new style beyond the built-in themes (saying "generate a new theme / custom style / create a component library based on this reference image," or is unsatisfied with all existing themes), read references/theme-generator.md and strictly follow its process:

  1. Collect Preferences: Theme description is required (or a reference image). Name/ID/five colors/font/three TAGs/rounded corners/shadow can be left empty and auto-completed. Ask all at once; do not ask one field at a time.
  2. Generate Block Library HTML: Execute the [Generation Prompt] at the end of theme-generator.md exactly, producing a complete block library of 45~75 Blocks. Save to assets/theme-previews/{theme-id}.html — all blocks are laid out continuously on one page. The user opens the page in their browser to browse the entire page at once to confirm the style; do not show one block at a time for confirmation.
  3. Convert + Register: After the user confirms the style, convert it to a standard references/theme-{identifier}.md (must add <span leaf=""> wrapping, remove preview IDs, and complete all five sections; see theme-generator.md Step 3 for detailed rules). Register it in theme-index.md, then run component_lint.py until 0 ERRORs.
  4. After delivery, this theme becomes a permanent selectable option, with the same rights as built-in themes.

During the generation phase, the prompt rules take precedence. During the conversion into the theme library phase, the "Platform Red Lines" and "New Theme Specification" sections of this file take precedence (when in conflict, the latter wins, as the theme library directly determines the final formatted output).

New Theme Specification

New themes should be named references/theme-{english_identifier}.md and must include:

  1. Design Variable Reference Table (primary color/light background/dark text/title color/body color/divider color, etc.)
  2. Complete HTML for Each Component (inline styles + <span leaf=""> wrapping, complying with "Platform Red Lines" above)
  3. Complete Article Template Skeleton (component assembly order; if there is a TOC/navigation component, specify its position relative to the cover/intro)
  4. Article Type → Component Combination Recipe Table (core component combination + accent components for each article type; the recipe is key to stable typographic style for that article type)
  5. Markdown → Component Mapping Rule Table

After adding, register a row in references/theme-index.md (Theme Name / Primary Color / Use Case / Component Library File / Body Underline CSS), and run python3 scripts/component_lint.py . to confirm the component library has 0 anti-patterns (0 ERRORs).

Regression test cases for trigger and theme selection can be found in references/eval-cases.md (used for regression checking during maintenance; does not affect single generation).

相关技能