gzh-design-skill README

The project's README from github.com/isjiamu/gzh-design-skill. As one markdown file: README.md.

🤝 本项目由 甲木 × 「摸鱼小李」 联名共建 —— 排版组件、主题设计与质量标准凝聚了两人的公众号实践与共同打磨,特别感谢小李。

gzh-design-skill · 公众号排版技能

把 Markdown 一键排成可直接粘贴进微信公众号编辑器的精致 HTML

6 套精选主题 + 主题生成器 · 代码块/图片/GIF · 自动章节编号与关键词标记 · 双关卡质量校验

License: AGPL-3.0 Claude Code Themes PRs Welcome Agents

English | 中文


一个给 AI Agent(Claude Code / Codex / Cursor 等)用的公众号排版 Skill。你写完 Markdown,它按你选的主题,生成样式全内联、粘贴到公众号编辑器不掉格式的 HTML——自动编章节号、标关键词下划线、配引言卡与目录、处理代码块和图片、合并作者签名,并用脚本确定性地兜住公众号平台的各种限制。

✨ 核心特性

👀 效果预览

6 套主题各排同一篇长文(真实长图,含配图、引言卡、编号章节、金句、名词旁注等完整组件):


摸鱼绿(默认)

红白色系

橄榄手记

石墨极简风

留白禅意风

摸鱼票据风

📚 6 套完整长图 → docs/all-themes.md | 克隆后浏览器打开 docs/gallery/index.html 可看可交互的完整 HTML。

✅ 适合 / ❌ 不适合

✅ 适合:观点/深度分析 · 教程/操作指南 · 测评/工具盘点 · 知识整理/方法论 · 访谈/人物特稿 · 数据复盘/报告 · 生活/情感随笔 · 案例实战 —— 把 Markdown / Word / PDF / 纯文本长文,一键排成可直接粘进公众号编辑器的 HTML;也能按描述或参考图生成自定义主题。

❌ 不适合:普通网页/落地页(用前端 skill)· PPT(用 PPT skill)· 纯图片海报/社交卡片(用社交卡片类 skill)· 非公众号平台的排版 · 代写文章(本 skill 只排版、不写作——先有 Markdown 再用它)。

🗂 常见使用场景

你的内容 推荐怎么排
观点 / 深度长文 红白 或 石墨极简;关键词下划线 + 金句引用 + 居中金句
产品测评 / 工具盘点 摸鱼绿 或 摸鱼票据;step/tool-label + 卡片,按配方表走
教程 / 操作指南 摸鱼绿;step-label + 代码块 + 编号列表
数据复盘 / 年度报告 摸鱼绿 或 橄榄手记;数据卡 + 表格
禅意 / 极简随笔 留白禅意;大留白 + 居中衬线引用
内刊 / 深度评测 / 案例复盘 橄榄手记;编者按 + 分节 + 暗色摘要框
Word / PDF 稿转公众号 先自动格式归一化 → 再按题材选主题
想要现成之外的风格 主题生成器:一句话或参考图现造一套

🎨 6 套精选主题

覆盖绝大多数公众号题材,每套都打磨到「拿来即用」:

主题 适合
摸鱼绿(默认) 教程、测评、清单、工具盘点(卡片丰富、信息密度高)
红白色系 深度分析、观点、力量感话题(经典编辑风)
石墨极简风 设计、科技评论、专业观点、高端品牌
留白禅意风 禅意、极简生活、深度随笔(呼吸感最强)
摸鱼票据风 工具对比、创意评测(票据视觉隐喻)
橄榄手记 内刊手记、深度评测、案例复盘(编辑部内刊质感)

主色、下划线色值等完整速查表见文末 附录;不够用就让 AI 生成新主题。

🚀 快速开始

方式一:一行安装(推荐)

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

方式二:让 AI 自己装

对任意 Agent(Claude Code / Codex / Cursor 等)说一句:

请帮我查找并自动安装 https://github.com/isjiamu/gzh-design-skill 这个 skill

它会自行 clone 到对应的 skills 目录并接入。

方式三:手动 clone

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

装好后,直接对 Agent 说:

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

💬 交流群

扫码加入官方企业微信交流群(活码自动邀请入群,一起交流公众号排版 & Agent Skills 玩法):

企业微信交流群二维码

扫码失效?加作者微信 zuiyn_soul(备注「gzh-design」)拉你进群。

📖 使用流程

  1. 选主题 — 按题材自动推荐最契合的主题并请你一步确认(默认摸鱼绿);也可直接指定,或让 AI 生成新主题。
  2. 读组件库 — 读所选主题库 + 通用增量库(代码块/图片/小标签)。
  3. 解析 Markdown — 识别标题、章节、加粗、高亮、引用、图片、代码块、列表。
  4. 装配 HTML — 用组件库里的真实组件拼装,落实编号、下划线、全角、签名。
  5. 校验 — 跑 validate_gzh_html.py,ERROR 清零才交付。
  6. 输出 — 生成干净正文 + 带「复制」按钮的预览页;浏览器打开预览页点右上角「复制到公众号」,再去编辑器粘贴即可(免手动全选)。

🧩 公众号平台限制(已内置兜底)

生成的 HTML 严格遵守:禁 <style>/<script>/<div>、class/id、position:fixed/absolute/sticky、float、@media/@keyframes、display:grid、CSS 变量、外部字体;样式全部内联;所有文字用 <span leaf=""> 包裹。这些由校验脚本确定性检查,而非靠模型自觉。

🔁 可验证循环

改组件库或工作流后,用双关卡闭环防回归:

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

💡 为什么这么设计

📁 目录结构

gzh-design/
├── SKILL.md                    # 排版工作流主文档(Agent 入口)
├── references/
│   ├── theme-index.md          # 6 套主题索引(主色/适用/下划线,单一来源)
│   ├── theme-*.md              # 6 套主题组件库(theme-moyu-green.md 等)
│   ├── theme-generator.md      # 主题生成器(按描述/参考图生成新主题)
│   ├── common-components.md    # 跨主题通用增量组件(代码块/图片/小标签)
│   ├── format-normalize.md     # 格式归一化(docx/pdf/纯文本 → Markdown)
│   └── eval-cases.md           # 触发用例 + 可验证循环
├── scripts/
│   ├── validate_gzh_html.py    # 产物合规校验
│   └── component_lint.py       # 组件库源头检查
├── assets/
│   ├── sample-article.md       # 演示输入
│   └── theme-previews/         # 主题生成器产出的区块库预览
└── docs/gallery/               # 主题浏览器预览

🎯 设计原则

🧠 方法论:不止 6 套,自己造主题

主题生成:一句话 / 一张参考图,现造一套新主题

内置 6 套不够用时不必等更新——让 AI 现造一套。背后是 references/theme-generator.md 定义的第二条工作流:

  1. 收集偏好(一次问全,不逐条追问):主题描述必填(或给参考图),名称 / 主色 / 背景 / 正文色 / 强调色 / 装饰色 / 字体 / 圆角 / 阴影 / 适用场景可留空自动补全。
  2. 生成区块库:AI 产出 45~75 个区块的完整 HTML 组件库,存到 assets/theme-previews/{id}.html,浏览器整页一次浏览确认风格(不逐块问)。
  3. 转标准主题库 + 登记:确认后转成 references/theme-{id}.md(补 <span leaf>、补齐五章节:变量表 / 组件 / 骨架 / 配方表 / 映射表),登记进 theme-index,跑 component_lint.py 到 0 ERROR。
  4. 即刻同权:之后排版和内置主题完全一样,直接说「用 XX 主题排这篇」。

怎么触发:

按「黑白杂志、克莱因蓝点睛、衬线字体」的气质,给公众号排版生成一套新主题

按这张参考图(附图)做一套公众号排版组件库

仓库里 assets/theme-previews/theme-mono-blue-editorial.html 就是这样生成的一套「墨蓝刊读风」样例。

颜色搭配:一套可复制的配色结构,AI 自动生成协调色板

每套主题的视觉都建立在一张设计变量色板上——配色不是拍脑袋,而是固定的角色分工:

角色 作用 取色思路
主色 章节编号、锚点强调、封面点睛 一个有辨识度的品牌色(#059669 emerald / #DC2626 正红 …)
浅底 / 浅边框 卡片背景、引用块、标签底 主色同色系的极浅色(主色 + 大量白)
点睛高亮色 每段 1~2 处黄底 / 渐变高亮 与主色冷暖对比的第二色(绿配黄)
中性灰阶 正文 / 标题 / 辅助 / 分割线 #111827 → #9CA3AF 一套灰阶,承担 90% 的文字
下划线标记色 正文关键词逐段标记 主色的浅色版(#A7F3D0 / #FECACA),温和不抢戏

克制三原则:① 主色只在锚点出现(全文 ≤5 处);② 大面积白底 + 灰阶,彩色只点缀;③ 一段内高亮 ≤2 种。

让 AI 自动配:只给一个主色或一句气质描述,主题生成器就据此推导整套协调色板——浅底、边框、高亮、灰阶、下划线色自动生成并保证可读对比度:

以 #7C9EB2 雾蓝为主色,生成一套清新旅行随笔风的公众号主题

🗺 Roadmap

❓ FAQ

Q:粘贴到公众号后样式会掉吗? A:不会。所有样式内联、文字 <span leaf=""> 包裹,这正是校验脚本强制的重点。

Q:能自己加主题吗? A:两种方式。① 让 AI 生成:说「按这个风格 / 这张图生成一套公众号主题」,它会走 references/theme-generator.md 的流程生成组件库、登记并复用。② 手写贡献:照 CONTRIBUTING.md 的「新增一套主题风格」,跑通可验证循环即可提 PR。

Q:只能在 Claude Code 用吗? A:不限。任何能读取 Skill 目录的 Agent(Codex / Cursor 等)都能用,工作流在 SKILL.md。

Q:对模型有要求吗?国产模型行不行? A:不挑模型,国内外模型都能跑出一致效果。排版逻辑全部沉淀在组件库和校验脚本里,不依赖某家模型的特殊能力——Claude、GPT、Gemini,以及 DeepSeek、Kimi、通义千问、智谱 GLM 等国产模型都可以。模型只负责按规则填充内容,硬约束由校验脚本确定性兜底,所以换模型不会导致排版走样。

Q:能一次出多套主题对比吗? A:能。说「用这几套主题各排一遍这篇」即可批量生成多套供你挑。

Q:怎么更新到最新版? A:重新跑 npx skills add https://github.com/isjiamu/gzh-design-skill,或到安装目录 git pull。

Q:Agent 写出来不合规怎么办? A:跑 scripts/validate_gzh_html.py,报 ERROR 就回到装配步骤修;两关全绿才交付,仍有问题欢迎开 Issue。

📋 完整主题速查表

主色 主题 适用
#059669 摸鱼绿(默认) 教程、测评、清单、工具盘点
#DC2626 红白色系 深度分析、观点、力量感话题
#52525B 石墨极简风 设计、科技评论、专业观点、高端品牌
#4A5D52 留白禅意风 禅意、极简生活、深度随笔
#059669 摸鱼票据风 工具对比、创意评测(票据视觉隐喻)
#1e1f23 橄榄手记 内刊手记、深度评测、案例复盘

每套主题的英文标识、组件库文件、下划线 CSS 见 references/theme-index.md。 需要别的风格?让 AI 用 主题生成器 现生成一套。

⭐ Star History

如果这个项目帮到了你,点个 Star 支持一下~

Star History Chart

🤝 贡献

欢迎新主题、修复与文档改进,请先读 CONTRIBUTING.md。

📄 License

AGPL-3.0 © 2026 甲木 × 摸鱼小李

本项目采用 GNU AGPL-3.0 协议,要点:

  1. 必须署名 — 保留版权与联名署名声明
  2. 衍生品必须开源 — 任何修改版本、Fork、二次分发,必须以 AGPL-3.0(或兼容协议)公开发布,提供完整源代码
  3. 网络服务也要开源 — 即使只是把修改版本部署成 SaaS / Web 服务给别人用而不分发代码,也要公开源代码(这是 AGPL 区别于 GPL 的核心)
  4. 不允许闭源、专有化、仅付费分发

完整条款见 LICENSE。

🤝 欢迎 AI Agent 厂商、模型厂商共创:想把 gzh-design 集成进产品、或基于它做深度共建,我们很欢迎——共创协议请联系甲木。

🙏 致谢


<img src="http

gzh-design-skill (isjiamu/gzh-design-skill)

Searching Database…

What is this?It is an AI-agent skill that converts a Markdown article into paste-ready HTML for the WeChat official account (公众号) editor, using one of 6 polished themes so formatting does not break when pasted.
Is this a standalone app, or something my AI coding agent uses?It is a Skill folder (SKILL.md plus theme/component references and validation scripts) that an AI agent like Claude Code, Codex, or Cursor reads and executes; it has no GUI of its own.
Which AI agents and models does it work with?Any agent that can read a skill directory works (Claude Code, Codex, Cursor and others), and any model including Claude, GPT, Gemini, DeepSeek, Kimi, Qwen or GLM, since all formatting logic lives in the component library and validation scripts rather than the model itself.
Can I use it for regular web pages or PPTs too?No — it is purpose-built only for WeChat official account articles; for landing pages, slides, or social cards you need a different skill, and it only formats existing Markdown, it does not write the content for you.
How does it guarantee the pasted formatting will not break in the WeChat editor?All styles are fully inlined and every text node is wrapped in span tags, specifically avoiding tags, classes, position/float/grid CSS and other constructs the WeChat editor strips out.
Does it just pick one fixed look, or can I get a custom theme?Beyond the 6 built-in themes, a theme generator can create a brand-new component library from a one-line style description or a reference image, which is then saved locally and reused like any built-in theme.
How does it make sure the output is actually correct?It runs a two-stage check: componentlint.py validates the theme component library itself, and validategzhhtml.py validates the final HTML output; both must report zero errors before delivery.
What kind of content is it designed for?It targets long-form WeChat official account content like opinion pieces, tutorials, product reviews, knowledge summaries, interviews, and data recaps, each mapped to a recommended theme and component recipe.
Creator
isjiamu
Size
0.2 MB
Stars
4K
Age
3mo
Commits · 90 Days