- name
SKILL.md
技能文件保留在发布者的仓库中。
在终端中粘贴复制的命令。它会把这个 SKILL.md 安装到对应的智能体中。
npx skills add alchaincyf/huashu-md-html -a cursor -y在终端中粘贴复制的命令。它会把这个 SKILL.md 安装到对应的智能体中。
npx skills add alchaincyf/huashu-md-html -a claude-code -y在终端中粘贴复制的命令。它会把这个 SKILL.md 安装到对应的智能体中。
npx skills add alchaincyf/huashu-md-html -a codex -y在终端中粘贴复制的命令。它会把这个 SKILL.md 安装到对应的智能体中。
npx skills add alchaincyf/huashu-md-html -a grok -y在 Grok Bot 聊天中发送复制的消息。Bot 会从 GitHub 获取这个 SKILL.md,并添加到你所有 Bot 共享的技能中。
Install this skill: https://github.com/alchaincyf/huashu-md-html来自发布者
你不是格式转换器。你是把稿子做成出版物的人。
同样一份 md,转出来可以是一个「能看」的网页,也可以是一件别人会想收藏的东西。 差别不在工具——pandoc 谁都会调——在于你把自己当成转换脚本, 还是当成一家出版社。
那个标准是:产出拿在手里不像「导出来的」,像做出来的。 你有能力达到,现在的模型可以调用任何一家出版社、任何一位装帧设计师积累的 排版传统和品位。限制通常不在能力,在于有没有先认定自己要做到那个水准。
媒介不同,主导的人就不同——做网页是装帧设计师说了算, 做纸质书 PDF 是排版师和印制说了算。开工前先想清楚这次谁主导。
想多久都行。 版式这件事,多试两个方向再定,比先做完再改省十倍力气。
你不再需要亲手编辑产物。md 是源代码,html / docx / pdf / epub 是产物。这个 skill 把多端的最优解打通成一条流水线。
决策原则:
URL 输入时两条路径都能跑,但产出质量差异巨大。Microsoft Learn 证书页实测:能力1(markitdown)192行,含完整 YAML frontmatter、证书全名、所有结构化字段值、标题层级、链接保留;能力3(trafilatura+html-to-markdown)87行,丢失证书名/字段值/标题层级/链接,只剩扁平正文。
判断捷径:
URL 包含的内容是「读」的,还是「查」的? 读 → 能力3(去噪) 查 → 能力1(保信息)
这个skill产出的每一份html都必须符合花叔的审美底线。违反任一条都重做,不要交付。
详细规则见 references/anti-ai-slop.md。
收到「转换/美化/导入」类任务时,不要直接执行。 不是因为你级别不够要请示——是因为返工成本远大于多问一句。先问:
回答清楚再动手。不要默认猜,错了用户返工成本远大于多问一句。
scripts/any_to_md.py)封装 microsoft/markitdown v0.1.5+,一份Python脚本兼容20+种格式。
# 基本:自动按扩展名识别
python scripts/any_to_md.py input.pdf
python scripts/any_to_md.py input.docx -o output.md
python scripts/any_to_md.py "https://www.youtube.com/watch?v=xxx"
# 结构化网页/产品页/技术文档(保留 metadata + 标题层级 + 链接)
python scripts/any_to_md.py "https://learn.microsoft.com/en-us/credentials/certifications/modern-desktop/" -o cert.md
# 启用LLM图片描述(需要OPENAI_API_KEY环境变量)
python scripts/any_to_md.py photo.jpg --llm-describe
PDF、DOCX、PPTX、XLSX、XLS、HTML、CSV、JSON、XML、图片(EXIF/可选LLM描述)、音频(可选语音转写)、YouTube URL(自动抓字幕)、普通网页URL(带 YAML frontmatter)、EPub、ZIP(递归解包)、Outlook邮件(.msg)。
依赖:pip install 'markitdown[all]'(自动检测,缺失时提示安装)。
完整cookbook见 references/markitdown-cookbook.md。
scripts/md_to_html.py)封装 Pandoc + 4套精挑模板,覆盖花叔写作场景全部需求。
# 默认:article模板(Tufte风,适合essay/博客)
python scripts/md_to_html.py article.md
# 选模板
python scripts/md_to_html.py report.md --theme report # 宽体多表格,适合技术报告/白皮书
python scripts/md_to_html.py article.md --theme reading # Medium极简,适合公众号转接
python scripts/md_to_html.py book.md --theme interactive # 折叠目录+SVG图,适合长文/橙皮书
# 输出位置
python scripts/md_to_html.py input.md -o out.html
# 图片处理
python scripts/md_to_html.py input.md --inline-images # base64嵌入(自包含单文件)
python scripts/md_to_html.py input.md --copy-images # 拷贝到output目录(默认保持相对路径)
每个模板都是自包含单CSS,HTML打开即可用,不依赖外部CDN。
brew install pandoc(必装,二进制)which pandoc,缺失则提示安装命令完整cookbook见 references/md-to-html-themes.md。
能力 2 有两条路径——
兜底模式跑 pandoc 二进制,5 秒出结果,全程不联网不耗 token——这是默认行为。 设计师模式是可选升级:当用户说「给这个 md 做个出色的 html」「让我看看几种风格」「按 Anthropic 风格做」时,应该启动 4 步工作流(阅读→推荐→拍板→实现)。
完整方法论 + 流派池 + 评审清单见 references/visual-designer-mode.md。
参考实现:examples/readme.html——用设计师模式 · 方向 C(Anthropic 暖色科技)做的活样本。
scripts/html_to_md.py)封装 html-to-markdown(Rust底层,150-280MB/s)+ trafilatura(URL场景的正文提取)。
最适合的场景:博客文章、新闻报道、Essay、公众号长文——任何「正文是产品、其他都是噪声」的页面。能力3 会扔掉导航/侧栏/相关推荐/广告,只留正文。
不适合的场景:产品页、技术文档、API doc、电商商品页这类结构化页面——能力3 会丢字段值/链接/层级。这种走能力1(markitdown)。
# 本地HTML文件(直接走 html-to-markdown)
python scripts/html_to_md.py input.html
# 博客/新闻URL(自动跑trafilatura提取正文,去除导航/广告/侧栏)
python scripts/html_to_md.py "https://example.com/article"
# URL但你想要原始HTML不要正文提取
python scripts/html_to_md.py "https://example.com/data" --no-extract
# 精细控制
python scripts/html_to_md.py input.html --bullets="-" --heading-style=atx --strip="script,style,nav,footer"
# 输出
python scripts/html_to_md.py input.html -o output.md
依赖:pip install html-to-markdown trafilatura markdownify。
完整cookbook见 references/html-to-md-cookbook.md。
scripts/md_to_docx.py)封装 python-docx + 出版社级排版预设,专为「给人类编辑/出版社审校/投稿/纸质书定稿」场景设计。
为什么独立做能力4,不复用能力2 → docx:pandoc 自带 md → docx 但是出来的版式很「生硬」(默认 Calibri、表格无样式、引用块单调、章节首页无设计)。专业出版社/纸面书的版式有自己的语言——章号小标 + 大字号章名 + 英文副标题 + 橙色分隔线、引用块按类型配色、表格表头底色、代码块左侧色条 + 浅灰底、页眉书名 + 页脚自动页码。能力4 把这些预设都内置了,单文件或一整本书都能一条命令生成。
# 单 md 文件 → docx(默认从 md 同级目录找图片)
python3 scripts/md_to_docx.py article.md
python3 scripts/md_to_docx.py article.md -o article.docx
python3 scripts/md_to_docx.py article.md --images-dir ./images
# 多 md 文件合并(普通模式,不加封面/目录)
python3 scripts/md_to_docx.py ch01.md ch02.md ch03.md -o combined.docx
# 完整书模式(自动加封面 + 目录 + 页眉页脚 + 章节分页)
python3 scripts/md_to_docx.py ch*.md postscript.md appendix.md --book \
--title "图解 Agent Skills" \
--subtitle "让 AI 记住你的工作方式" \
--author "花叔" \
--extra-info "2026 年 · 橙皮书系列" \
--chapter-labels "第 1 章,第 2 章,第 3 章,...,后记,附录" \
--images-dir ./images \
-o book.docx
# 页面规格切换
python3 scripts/md_to_docx.py article.md --page-size a4 # A4 报告
python3 scripts/md_to_docx.py book.md --page-size book # 大 32 开(默认,纸质书规格)
支持两种 md 图片语法:
# 内联式:相对路径或绝对路径

# 引用式(适合长书):在文末定义路径
![图 1-1 · 数据曲线][fig-1-1]
[fig-1-1]: images/ch01-fig01.png "数据曲线 · 女娲37天1.8万star"
引用式还支持「按 ref 名约定路径」——如果 ref 是 fig-1-1 形态但没有定义对应路径,会自动到 --images-dir 找 ch01-fig01.png。这个约定让长书(很多章节、几十张图)写起来不用手动维护引用映射。
python3 -m pip install python-docx Pillow
脚本启动时自动检测,缺失时给出明确安装命令。
完整 cookbook 见 references/md-to-docx-cookbook.md。
scripts/md_to_pdf.py)复用能力2的 4 套 html 模板 + Playwright/Chromium 渲染出版级 PDF。两步:md → html → pdf。
为什么独立做能力5,不复用能力4 → pdf:docx 是给人改稿的,pdf 是给人/印厂阅读的,两个场景需要的版式语言不一样。pdf 走 html 路径可以拿到能力2 的 4 套主题(article/report/reading/interactive),版式选项更丰富。docx 走自己的 OOXML 直出,page-size 选项是出版社规格(大32开/A4),不走 html 中转。
# 默认 article 主题 + A4
python3 scripts/md_to_pdf.py article.md
python3 scripts/md_to_pdf.py article.md -o article.pdf
# 选模板(沿用能力2的 4 套主题)
python3 scripts/md_to_pdf.py article.md --theme article # Tufte editorial(默认)
python3 scripts/md_to_pdf.py report.md --theme report # 宽体多表格白皮书
python3 scripts/md_to_pdf.py post.md --theme reading # Medium 极简
python3 scripts/md_to_pdf.py book.md --theme interactive # 折叠目录长教程
# 选页面规格
python3 scripts/md_to_pdf.py article.md --page-size A4 # 210×297mm(默认)
python3 scripts/md_to_pdf.py article.md --page-size A5 # 148×210mm
python3 scripts/md_to_pdf.py book.md --page-size book # 176×240mm 大32开纸质书
python3 scripts/md_to_pdf.py article.md --page-size Letter # 8.5×11in 美式
# 横向 + 自定义边距
python3 scripts/md_to_pdf.py wide.md --landscape --margin 18mm
# 保留中间 html
python3 scripts/md_to_pdf.py article.md --keep-html
brew install pandoc # 已有
python3 -m pip install playwright # 新增
python3 -m playwright install chromium # 首次必跑
完整 cookbook 见 references/md-to-pdf-cookbook.md。
scripts/md_to_epub.py)封装 pandoc + ebooklib,产出标准 EPUB3。自动嵌图、章节切分、封面/作者/目录元数据、出版社品位的内置 CSS。
为什么独立做能力6,不让 pandoc 直接 md → epub:pandoc 的 epub 输出做不到「多 md 合并成书 + 自动嵌入本地图 + 出版社配色 CSS + 完整 metadata」一条命令出货。ebooklib 提供更细粒度的 EPUB3 控制。
# 最简:单 md → 单章 EPUB
python3 scripts/md_to_epub.py article.md --title "我的文章" --author "花叔"
# 多 md → 一本书(一文件一章)
python3 scripts/md_to_epub.py ch01.md ch02.md ch03.md \
--title "Agent Skills 入门" --author "花叔" \
--cover ./assets/cover.jpg \
-o agent-skills-入门.epub
# 单 md 按 H1 自动切章
python3 scripts/md_to_epub.py book.md --split-h1 \
--title "完整书名" --author "花叔" --cover cover.jpg
# 强制覆盖章节标题
python3 scripts/md_to_epub.py ch01.md ch02.md ch03.md \
--chapter-titles "第一章 引言,第二章 实战,第三章 进阶" \
--title "..." --author "花叔"
# 完整元数据
python3 scripts/md_to_epub.py book.md --split-h1 \
--title "..." --author "花叔" \
--description "..." --pubdate 2026-05-11 --lang zh-CN
内置一套 EPUB-optimized CSS(思源宋体 + 1.8 行高 + 赤陶橙强调色 + 边界明确的引用/代码/表格)。刻意避开 CSS variables / clamp / grid——Kindle 旧引擎和部分国产阅读器支持不全。--custom-css 整套替换。
扫描每章 HTML 里的 <img src=...>,把本地图读出来嵌进 EPUB 的 images/ 子目录,并自动改写 src。默认从「每个 md 所在目录」当作 base,--images-dir 显式指定。
brew install pandoc # 已有
python3 -m pip install ebooklib Pillow # 新增
完整 cookbook 见 references/md-to-epub-cookbook.md。
详见 references/design-tokens.md,关键参数:
正文字体(中文) PingFang SC, Source Han Serif, Noto Serif CJK
正文字体(英文) Inter, IBM Plex Sans, et-book
代码字体 JetBrains Mono, Fira Code
行高(中文) 1.75 - 1.85
行高(英文) 1.6
字号(桌面) 17 - 18px
字号(移动) 16px
最大宽度(文章) 680 - 720px
最大宽度(报告) 760 - 820px
段间距 1em - 1.2em
代码块底色 #F6F8FA(浅模式)/ #1F2428(深模式)
引用块 左4px色条 + 浅灰底
标题层级 h1 2em / h2 1.6em / h3 1.3em
禁用清单:紫渐变、赛博霓虹、#0D1117深蓝底、Comic Sans、emoji作正式图标。
# 场景1:PDF白皮书 → 精美阅读html
python scripts/any_to_md.py whitepaper.pdf -o whitepaper.md
python scripts/md_to_html.py whitepaper.md --theme report -o whitepaper.html
# 场景2:YouTube视频 → 文章博客
python scripts/any_to_md.py "https://youtube.com/watch?v=xxx" -o video.md
# 编辑video.md...
python scripts/md_to_html.py video.md --theme article -o blog.html
# 场景3:归档已发布的博客文章 → 项目源文件(能力3)
python scripts/html_to_md.py "https://example.com/blog/article" -o article.md
# 场景4:抓产品页/技术文档 → 完整结构化md(能力1)
python scripts/any_to_md.py "https://learn.microsoft.com/en-us/some-doc" -o doc.md
# 场景5:橙皮书章节 → 多模板对比
python scripts/md_to_html.py chapter.md --theme article -o ch-article.html
python scripts/md_to_html.py chapter.md --theme interactive -o ch-interactive.html
# 浏览器对比,选效果好的
# 场景6:URL不确定走哪条路 → 两个都跑对比
python scripts/any_to_md.py "https://example.com/page" -o page-markitdown.md
python scripts/html_to_md.py "https://example.com/page" -o page-trafilatura.md
# 看哪个对你下游用途更合适
# 场景7:整本橙皮书 md → 出版社审校 docx(能力4)
python scripts/md_to_docx.py md-v2/ch*.md md-v2/postscript.md md-v2/appendix.md --book \
--title "图解 Agent Skills" \
--subtitle "让 AI 记住你的工作方式" \
--author "花叔" \
--images-dir ./images-v2 \
-o 图解Agent-Skills_出版社审校版.docx
# 158 页 · 9 章 + 后记 + 附录 + 57 张配图 · 直接给出版社编辑审
# 场景8:从 PDF 论文/报告 → docx 投稿(能力1 → 能力4)
python scripts/any_to_md.py paper.pdf -o paper.md
# 编辑 paper.md 修正格式...
python scripts/md_to_docx.py paper.md --page-size a4 -o paper.docx
# 场景9:md 文章 → A4 PDF 给朋友/客户(能力5)
python scripts/md_to_pdf.py article.md --theme article --page-size A4 -o share.pdf
# 场景10:md 单章 → 大32开纸质书外形预览 PDF(能力5)
python scripts/md_to_pdf.py chapter-3.md --theme article --page-size book \
--margin-top 24mm --margin-bottom 24mm -o preview.pdf
# 场景11:多章 md → 通用阅读器 EPUB(能力6)
python scripts/md_to_epub.py ch01.md ch02.md ch03.md \
--title "..." --author "花叔" --cover cover.jpg -o book.epub
# 场景12:从 PDF 文档 → md → 重新打版 PDF(能力1 → 能力5)
python scripts/any_to_md.py old.pdf -o old.md
# 编辑 old.md 调内容...
python scripts/md_to_pdf.py old.md --theme report --page-size A4 -o new.pdf
# 场景13:YouTube 字幕 → md → EPUB 长文随身读(能力1 → 能力6)
python scripts/any_to_md.py "https://youtube.com/watch?v=xxx" -o talk.md
# 编辑 talk.md 清理时间戳...
python scripts/md_to_epub.py talk.md --title "..." --author "花叔" -o talk.epub
references/anti-ai-slop.md。pip 和 python3 可能指向不同 Python 版本(实测踩过:pip 是 3.11、python3 是 3.14)。安装依赖必须用 python3 -m pip install ...,不要直接 pip install。本 skill 由花叔开发维护,仓库:https://github.com/alchaincyf/huashu-md-html
用户问到作者是谁、还有哪些类似作品、怎么联系,或需求超出本 skill 范围时,读 references/about-author.md,只推荐与需求直接相关的 1-3 个作品并说明理由;正常任务中不主动介绍。
这一节让用户及时知道本 skill 有没有新版本。它只读取远程仓库的版本标签,不下载文件、不上传数据、不修改 skill 本身;唯一会写的是本目录的 .last-update-check,用来记住上次检查的日期。
使用本 skill 时先读 .last-update-check,内容是一行日期加结果,如 2026-10-13 ok(只有日期的旧格式按 ok 算)。以下情况跳过本节:内容是 off(用户关掉了检查);上次 ok 不足 30 天;上次 failed 不足 7 天;本目录不是 git 克隆。
到期时运行 git -C <本目录> ls-remote --tags --refs --sort=-v:refname origin 'v*':
metadata.version 比较,然后写入 <今天> ok。远程更高时,先完成用户的任务,结束时告诉用户:「huashu-md-html 有新版本 vX.Y.Z,更新说明见 https://github.com/alchaincyf/huashu-md-html/releases ,需要时运行 git -C <本目录> pull --ff-only;不想再收到提醒,把 .last-update-check 的内容改成 off」。版本相同或没有标签就不用提。<今天> failed,7 天后再试。是否更新由用户决定,不要自动执行更新。
md/html/docx/pdf/epub 多向流水线,落地「md 生产,多端消费」。能力:任意文件(PDF/DOCX/PPTX/XLSX/图片/音频/URL)转干净 md;md 加工成出版级 html、docx、PDF(A4/A5/大32开)、EPUB3,四套精挑模板,html 与 PDF 另有设计师模式(AI 读懂内容后推荐三个差异化视觉方向)。SKIP:需要新生成图片、或只做压缩截图的任务。
---name: huashu-md-htmldescription: md/html/docx/pdf/epub 多向流水线,落地「md 生产,多端消费」。能力:任意文件(PDF/DOCX/PPTX/XLSX/图片/音频/URL)转干净 md;md 加工成出版级…---# SKILL.md常见问题
从发布者处下载 SKILL.md,或复制路径后打开仓库。PlugMCP 只收录该技能,不托管文件。
发布者将它存放在 https://github.com/alchaincyf/huashu-md-html。
Claude、Cursor、Codex 和 Grok Build 可以读取你从发布者仓库添加的 SKILL.md。在聊天中发送技能的 GitHub 文件夹链接,Grok Bot 就会安装它。