Skip to content

zach22-1999/generic-skills / skills/zach-md-html

zach-md-html

Verified

已降级的 Markdown→HTML 兼容转换器。仅当用户明确要求“使用 zach-md-html”、或明确说“不要重组内容,只把现成 Markdown 机械转换成 HTML/套用旧主题”时使用。不要因为用户只说“输出成 HTML”“生成 HTML 报告”“把日常报告做成 HTML”“数据报告/交付报告”而触发;这些任务应由模型从原始资料直接组织并生成自包含 HTML。此 Skill 不负责数据可视化、工作面、自由设计、万物转 md、html 转 md 或 md 转 docx。

references/workspace-five-principles.md

View on GitHub
# Thariq 工作面 5 条原则(中文化)

> 这是 zach-md-html 工作面档 / 自由设计师档的设计指南。
> 源头:[Thariq · The unreasonable effectiveness of HTML](https://thariqs.github.io/html-effectiveness/) — Anthropic Claude Code 工程负责人的论述:HTML 不再只是「美化的 markdown」,而是可以让信息从「线性叙述」变成「空间化、可交互的工作面」。
> 5 条原则是工作面档 / 自由设计师档与"美化阅读型"的根本分界。

---

## 1. 空间 > 顺序

**问题**:markdown / 阅读型 HTML 把所有信息线性铺陈,读者必须在脑中维持上下文。
**解法**:把可并列的信息**同框并列**——读者一眼对比,不再读完一段再翻下一段。

**典型应用**:
- 方案对比(A / B / C 三列 side-by-side,行级别对齐 trade-off)
- 计划面板(timeline 横向 + 风险表 + 数据流图三个区域同框)
- annotated PR(diff 主区 + 右栏批注同视)
- 概念解释(live 图示 + 旁注 + 术语表 hover 同视)

**反例**:把对比写成「方案 A 的优点是 1)... 2)... 3)... 缺点是 4)... 方案 B 的优点是 1)... 2)...」——读者读到 B 时已经忘了 A 的细节。

---

## 2. 交互 > 静态

**问题**:静态文字描述「这里有 3 种模式 / 这里有 5 个步骤 / 这里有 N 个变量」,读者必须脑补每种模式 / 每个步骤 / 每个变量值的产物。
**解法**:把可切换 / 可调节的内容做成**轻交互组件**,读者点 / 滑 / 折一下,立刻看到结果。

**允许的交互**(见 `js-interaction-allowlist.md`):
- `<details>` 折叠展开
- tab 切换(多代码示例、多状态、多视图)
- 简单 slider 调参(CSS 动画 / SVG 变换)
- copy-to-clipboard 按钮
- 本地筛选 / 排序(不连后端)

**反例**:用 React + 网络请求做"模拟登录"——超出 skill 边界,且不稳定。

---

## 3. 视觉编码 > 文字描述

**问题**:「这是 P0 严重 bug」「这是周一 14:02 发生的」「这块模块依赖另外两块」——用文字描述需要读者逐字解码。
**解法**:把这类「带结构」的信息用**颜色 / 形状 / 位置 / 大小**视觉编码。

**典型应用**:
- severity → 红黄绿色条
- 时间 → 竖向 timeline 的位置
- 重要度 → 字号大小(KPI 周报)
- 依赖关系 → 箭头 / 连线 / 缩进层级
- 状态 → 色块(done / wip / blocked)

**反例**:把「严重程度 P0」「时间 14:02」做成行内文字 — 浪费 HTML 的视觉表达力。

**警告**:视觉编码 ≠ 花哨。严格遵守 `anti-ai-slop.md` 的色板和排版底线——空间化绝不是紫渐变或赛博霓虹的借口。

---

## 4. 动手验证 > 阅读

**问题**:「点击这里会发生 X」「滑动这个会调整 Y」「这种交互体感是 Z」——文字描述的交互体感和真实体验差距很大。
**解法**:能让读者**真正点 / 滑 / 拖**的,就不要描述。

**典型应用**:
- 动画沙盒(slider 调 easing / duration,实时看到运动曲线)
- prototype flow(4 屏可点击跳转)
- prompt tuner(左输入右实时渲染)
- feature flag editor(toggle 实时看 diff)

**边界**:在 zach-md-html 框架内,所有交互必须**纯前端、无网络请求、本地状态**。复杂的真交互该用 web-artifacts-builder 或 frontend-design。

---

## 5. 导出回路

**问题**:传统美化的 HTML 是「死的」——读完就结束,下一次 AI agent 处理时还要重新提供 md 源。
**解法**:每个工作面产物都自带「**复制为 markdown / 复制为表格 / 导出为 X**」按钮,让 HTML 同时是「人看的工作面」和「机器可读的源」。

**核心要求**(所有 workspace 和 free-design 产物必须满足):
- 右下角固定一个「复制为 markdown」按钮,点击后剪贴板里是干净的 md 源
- 如有结构化数据(kanban 状态、表格行 / 列),也支持复制为 markdown 表格
- 不依赖任何外部 JS 库(剪贴板用 `navigator.clipboard.writeText`)

**反例**:可读但不可复制的产物 — 等于一次性烟花,第二次复用要从头来。

---

## 5 原则与 md 是源的协同

这 5 条原则**不与「md 是源」的方法论冲突**——而是它的进一步实现:

| 原则 | 与「md 是源」的关系 |
|------|---------------------|
| 空间 > 顺序 | md 的章节 / 列表结构是源,工作面只是把它**空间化呈现** |
| 交互 > 静态 | md 是冷源,HTML 工作面是热壳,cold→hot→cold 循环可以重复 |
| 视觉编码 | severity / 时间 / 状态 等在 md 里是字段,HTML 把字段视觉化 |
| 动手验证 | md 的数字 / 参数在 HTML 里可调,调完产物变更 md 数字 |
| 导出回路 | HTML 工作面**永远能回到 md**,闭环 |

「md 是源」+ 5 原则 = 工作面是 md 的**视觉空间化、交互化、视觉编码化、可调可导出的呈现层**。

---

## 一句话总结

**美化阅读把 md 渲染得稍微好看一点;工作面把 md 变成可空间扫描 / 可点滑 / 可视觉解码 / 可动手 / 可回流的工作场。**

> 当你的内容里有"对比 / 时间线 / 计划 / 评审 / 状态切换 / 调参 / 多步流程 / 结构化数据" — 就该走工作面档,不是阅读型档。
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall