gzh-design-skill:3.8k 星公众号排版 Skill,Markdown 一键转成不掉格式的 HTML

把 Markdown 文章排成能直接粘进微信公众号编辑器的 HTML,中途不掉一次格式,这是 gzh-design-skill 做的事。它是一个给 AI Agent 用的排版 Skill,在 GitHub 上已收获约 3.8k stars,采用 AGPL-3.0 协议,由甲木和摸鱼小李共同维护。

在公众号后台粘过外部内容的人都知道后果:AI 生成的 HTML 再好看,粘进去样式大概率被过滤得只剩纯文本。公众号对外来内容有一套严格的白名单,<style>、<script> 标签不认,class 和 id 属性不认,position:fixed 这类定位、grid 布局、CSS 变量、外部字体也都不认。gzh-design-skill 的做法是把这些限制直接写进组件库:所有样式内联,文字用 <span leaf=""> 包裹,再交给校验脚本把关,模型只负责内容层面的判断。

gzh-design-skill 摸鱼绿主题排出的文章效果:绿色主色,带封面卡片、目录卡片、章节编号和关键词下划线

六套内置主题

主题决定了整篇文章的观感。项目内置六套主题,各有分工:

主题	主色	适用场景
摸鱼绿(默认)	`#059669`	教程、测评、清单、工具盘点,卡片多、信息密度高
红白色系	`#DC2626`	深度分析、观点文,经典编辑风
石墨极简风	`#52525B`	设计、科技评论、专业观点
留白禅意风	`#4A5D52`	禅意、极简生活、随笔,留白最多
摸鱼票据风	`#059669`	工具对比、创意评测,带票据视觉隐喻
橄榄手记	`#1e1f23`	内刊手记、案例复盘,编辑部质感

如果六套都不合适,还有主题生成器:用一句话描述气质(比如「黑白杂志、克莱因蓝点睛、衬线字体」),或者丢一张参考图,Agent 会按流程生成一套 45 到 75 个区块的新主题库,登记进主题索引、通过 lint 检查后,和内置主题享有同等地位。

排版时它做了什么

排版的活儿不只有换颜色。装配 HTML 的过程中,Agent 会按组件库的规则处理一揽子细节:

章节自动编号:正文小节按序号编排,不用手写「一、二、三」
关键词下划线:核心概念加下划线强调,一段内高亮不超过两种
引言卡与目录:开头自动生成引言卡,长文配目录卡片
代码块、图片、GIF:按公众号支持的写法包装
中文标点规范化:半角标点统一转全角,校验脚本会盯着这一项

克制用色是贯穿始终的原则:主色在全文出现不超过 5 处,九成左右的文字交给灰阶承担。这也是成稿耐看的原因之一。

安装

三种方式任选:

bash

# 方式一:npx 一行安装(推荐)
npx skills add https://github.com/isjiamu/gzh-design-skill

# 方式二:让 Agent 自己装,对它说——
# "请帮我查找并自动安装 https://github.com/isjiamu/gzh-design-skill 这个 skill"

# 方式三:手动 clone
git clone https://github.com/isjiamu/gzh-design-skill.git ~/.claude/skills/gzh-design

更新时重跑安装命令,或者进安装目录 git pull。

快速开始

装好后对 Agent 说一句话就行:

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

Agent 内部会走六步工作流:选主题、读组件库、解析 Markdown、装配 HTML、跑校验、输出产物。最后拿到的是两样东西:一份干净的正文 HTML,一个带「复制」按钮的预览页。点复制,粘进公众号编辑器,格式原样保留。

双关卡校验:格式不靠模型自觉

这个项目最值得学的设计,是把死规则从模型手里拿走,交给脚本:

bash

# 源头关:扫描组件库自身的反模式
python3 scripts/component_lint.py .

# 产物关:扫描最终 HTML 是否合规
python3 scripts/validate_gzh_html.py out.html

源头关卡检查组件库里的 white-space:pre、正文四周虚线框等会触发平台过滤的写法;产物关卡检查禁用标签、<span leaf> 包裹是否到位、半角标点是否清零。两关都是 0 ERROR 才允许交付。逻辑很直接:源头干净,产物必然干净。

不挑模型也是同理。排版逻辑都在组件库和脚本里,Claude、GPT、Gemini,以及 DeepSeek、Kimi、通义千问、智谱 GLM 这些国产模型,跑出来的效果一致。Claude Code、Codex、Cursor 等任何能读 Skill 目录的 Agent 都能用。

使用示例

场景一:多套主题对比。拿不准哪套主题合适,就批量各排一遍:

用这几套主题各排一遍这篇

场景二:一句话生成新主题:

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

场景三:以参考图定基调:

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

适合与不适合

适合的场景:观点长文、教程、测评、知识整理、访谈、数据报告,Markdown、Word、PDF 来源都行。

不适合的:普通网页、PPT、海报这类非公众号产物,以及代写文章。它只管排版,写作还是你自己的事。

项目链接

GitHub 仓库:isjiamu/gzh-design-skill
协议:AGPL-3.0(署名、衍生品开源,SaaS 使用同样须开源)
作者:甲木 × 摸鱼小李