让 AI 输出更美的 HTML：html-skill-effectiveness 技能包全解析

AI 每天都在生成海量的 Markdown，但有多少是你真正"看进去"的？

本文从一个实际痛点出发，带你一步步了解为什么 HTML 能替代 Markdown 成为更好的 AI 输出载体，以及我们如何通过一个 Skill 包让这件事变得简单、可复用、可落地。

目录

1. 痛点：AI 输出为什么总是"扫一眼就跳过"？

你有没有这样的体验——

让 AI 对比三套技术方案，它给你列了三个列表，每个列表标题下面几个"优点/缺点"，排成一长串。你知道信息都在那里，但要真的看进去——在心里把三套方案拉平对比、判断哪套更适合自己的场景——却需要费不少脑子。

这不是 AI 的问题，是输出载体的问题。

AI 默认输出 Markdown，而 Markdown 的本质是线性文本。它擅长的是「顺序叙述」，不擅长的是「空间表达」——也就是那些需要靠视觉布局才能更快理解的信息：

• 三套方案的横向对比
• 一段代码的增删变化
• 一条数据流的走向
• 一堆指标中哪个好、哪个差

这些信息，用 Markdown 写出来都能读，但读起来不痛快。

2. 根本原因：Markdown 的三大局限

为了让问题更具体，我们拆解一下 Markdown 在信息表达上的三个先天不足：

2.1 没有空间布局

Markdown 是线性的，从上到下排列。但人脑处理信息的方式不是线性的——我们靠空间关系来理解结构。

2.2 没有图表能力

趋势、对比、分布——这些信息在 Markdown 里只能靠数字表格来表达。而人眼对图形的识别速度比文字快几个数量级。

| 月份 | 销售额 |
|——|——–|
| 1月 | 120K |
| 2月 | 135K |
| 3月 | 145K |

一个 3 月的销售额是上涨还是下跌？你得读数字比较。换成柱状图，一眼就知道。

2.3 完全没有交互

Markdown 是纯静态文本。你不能：

• ❌ 拖拽一个卡片到"已完成"列
• ❌ 滑动滑块看参数变化
• ❌ 点击步骤按钮逐步学习
• ❌ 切换 Tab 查看不同的代码视角

这些能力在一个 AI 输出的文档中本可以存在——因为浏览器原生支持。

3. 解决方案：用 HTML 替代 Markdown

既然浏览器就在那里，为什么不直接让 AI 输出 HTML？

HTML 能做到的事情，Markdown 完全做不到：

但问题来了——AI 默认不会生成好看的 HTML。

让 AI 写 HTML 不难，但让它写出有设计系统、有视觉层次、有交互逻辑的 HTML，需要一套清晰的规则和模板。这就是 html-skill-effectiveness 存在的意义。

3.1 项目简介

html-skill-effectiveness 是一个面向 AI Agent（OpenClaw / Claude）的 Skill 技能包。它通过一份 SKILL.md 文件，教会 AI 如何输出自包含、零依赖、单文件的高质量 HTML 页面。

一句话：把 AI 聊天的输出，从"能看"变成"好看"。

GitHub 地址：https://github.com/YardonYan/html-skill-effectiveness

3.2 文件结构

html-skill-effectiveness/
├── SKILL.md # 核心技能定义（AI 读取的指令）
├── README.md # 项目文档
├── LICENSE.txt # Apache 2.0
├── BLOG.md # 本文
├── indexxxxxxx_en.html # 英文展示页（含 20+ 示例）
├── indexxxxxxx_zh.html # 中文展示页
└── references/
├── pattern-examples.md # 代码片段参考
└── complete-examples.md # 完整示例

4. 设计系统：让每个页面都有一个"好看的底子"

好看不是碰运气的。每一个好看的 HTML 页面，背后都有一套设计系统——一组有共识的颜色、字体、间距规则。

这个 Skill 预置了一套完整的设计令牌：

4.1 配色体系

:root {
–ivory: #FAF9F5; /* 页面背景 —— 暖白不刺眼 */
–slate: #141413; /* 正文标题 —— 近乎黑色但有温度 */
–clay: #D97757; /* 强调色 —— 赤陶红，温暖醒目 */
–oat: #E3DACC; /* 次级强调 —— 燕麦色 */
–olive: #788C5D; /* 成功/正向 —— 橄榄绿 */
–rust: #B04A3F; /* 错误/破坏性 —— 锈红色 */
–sky: #6A8CAF; /* 信息/中性 —— 天蓝色 */
}

为什么选这些颜色？因为暖调。纯黑 #000 + 纯白 #FFF 给人"文档"的感觉，而 ivory（米白）+ clay（赤陶）的搭配让页面读起来像一本精装杂志，而不是技术手册。

4.2 字体层级

:root {
–serif: ui-serif, Georgia, "Times New Roman", serif;
–sans: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
–mono: ui-monospace, "SF Mono", Menlo, Monaco, monospace;
}

4.3 间距与圆角

–radius-panel: 12px; /* 卡片圆角 */
–radius-row: 8px; /* 内部元素圆角 */
–radius-pill: 999px; /* 标签药丸圆角 */
–border: 1.5px solid var(–g300);

这些值不是随意选的——12px 圆角刚好给卡片一种"精致但不圆滑"的感觉；1.5px 边框比常见的 1px 粗一点，在暖色背景上更有存在感。

5. 11 种设计模式：覆盖 AI 输出的大部分场景

有了设计系统还远远不够，我们需要知道在什么场景下用什么结构。Skill 定义了 11 种模式，每一种对应一个常见的 AI 输出场景。

下面逐一展开，每种模式都会给出：场景说明、Markdown 写法、HTML 改写代码、💡 关键差异。

5.1 🔄 并列对比（Side-by-Side Comparison）

场景：技术选型、方案对比、设计选项

Markdown 写法：

## 方案对比

### 方案 A：客户端渲染
优点：导航快、交互丰富
缺点：首屏慢、SEO 差

### 方案 B：静态生成（推荐）
优点：加载快、SEO 好、成本低
缺点：构建时间长

HTML 改造后：

<div class="grid" style="display:grid;grid-template-columns:repeat(3,1fr);gap:24px">
<div class="card">
<span class="badge">方案 A</span>
<h3>客户端渲染</h3>
<ul class="pros"><li>✅ 导航快</li><li>✅ 交互丰富</li></ul>
<ul class="cons"><li>❌ 首屏慢</li><li>❌ SEO 差</li></ul>
</div>
<div class="card best">
<span class="badge" style="background:#141413;color:#FAF9F5">★ 推荐</span>
<h3>静态生成</h3>
<ul class="pros"><li>✅ 加载快</li><li>✅ SEO 好</li><li>✅ 成本低</li></ul>
<ul class="cons"><li>❌ 构建时间长</li></ul>
</div>
</div>

HTML显示为：

对应 CSS：

.card {
background: #fff;
border: 1.5px solid var(–g300);
border-radius: 14px;
padding: 28px;
transition: transform 150ms ease, box-shadow 150ms ease;
}
.card:hover {
transform: translateY(-3px);
box-shadow: 0 10px 30px rgba(20,20,19,.10);
}
.pros li::before { content: "✓ "; color: var(–olive); }
.cons li::before { content: "✗ "; color: var(–rust); }

💡 关键差异：Markdown 用列表做对比，读者需要在心里"对齐"三个方案的优缺点。HTML 用并排卡片让推荐方案自动突出，悬停还有微妙动效——信息获取速度提升一个数量级。

5.2 📝 代码审查（Annotated Diff / Code Review）

场景：PR 评审、代码变更前后对比

Markdown 写法：

– const token = jwt.sign(payload, secret)
+ const token = jwt.sign(payload, secret, { expiresIn: '1h' })

HTML 改造后：

<div class="diff-block">
<div class="diff-line del">
<span class="ln">10</span>
– const token = jwt.sign(payload, secret)
</div>
<div class="diff-line add">
<span class="ln">10</span>
+ const token = jwt.sign(payload, secret, { expiresIn: '1h' })
</div>
</div>
<span class="severity critical">CRITICAL</span>
<span> 缺少 TTL，安全风险</span>

HTML显示为：

对应 CSS：

.diff-line.add {
background: #F0F7EC;
border-left: 3px solid var(–olive);
}
.diff-line.del {
background: #FDF2F0;
border-left: 3px solid var(–rust);
}
.severity.critical { background: var(–rust); color: #fff; padding: 2px 8px; border-radius: 999px; font-size: 10px; }
.severity.warn { background: var(–clay); color: #fff; }
.severity.note { background: var(–olive); color: #fff; }

💡 关键差异：Diff 本质上是空间信息——删除用红色背景 + 左边框，新增用绿色背景 + 左边框。不读正文、只看颜色也知道改了哪、改了什么。再加上彩色严重性标签，评审效率大幅提升。

5.3 🏗️ 架构图（Module Map / Architecture Diagram）

场景：系统架构、模块依赖、数据流

Markdown 写法：

AuthService 依赖 UserService 和 TokenManager，TokenManager 依赖 UserDB。

HTML 改造后：

<svg viewBox="0 0 400 300">
<defs>
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
<path d="M0,0 L0,6 L9,3 z" fill="#D1CFC5"/>
</marker>
</defs>
<rect x="140" y="20" width="120" height="40" rx="6"
fill="#fff" stroke="#D97757" stroke-width="1.5"/>
<text x="200" y="45" text-anchor="middle" font-family="monospace" font-size="12">AuthService</text>
<rect x="140" y="100" width="120" height="40" rx="6"
fill="#fff" stroke="#788C5D" stroke-width="1.5"/>
<text x="200" y="125" text-anchor="middle" font-family="monospace" font-size="12">UserService</text>
<line x1="200" y1="60" x2="200" y2="98"
stroke="#D1CFC5" stroke-width="1.5" marker-end="url(#arrow)"/>
</svg>

HTML显示为：

交互 tooltip：

document.querySelectorAll('.node').forEach(node => {
node.addEventListener('click', () => {
const data = detailData[node.dataset.step];
document.getElementById('panel').innerHTML = `<h3>${data.title}</h3><p>${data.desc}</p>`;
});
});

💡 关键差异：架构是图不是文。SVG 箭头 + 彩色方框让依赖关系一目了然，点击节点还能展开详情。

5.4 🎨 设计系统展示（Living Design System）

场景：品牌色板、组件库、设计令牌

.swatch-grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(120px, 1fr));
gap: 16px;
}
.swatch { border-radius: 8px; overflow: hidden; border: 1.5px solid #D1CFC5; }
.swatch .color { height: 80px; }
.swatch .label { padding: 10px 12px; background: #fff; font-family: monospace; font-size: 12px; }

<div class="swatch-grid">
<div class="swatch"><div class="color" style="background:#D97757"></div><div class="label">–clay: #D97757</div></div>
<div class="swatch"><div class="color" style="background:#788C5D"></div><div class="label">–olive: #788C5D</div></div>
<div class="swatch"><div class="color" style="background:#B04A3F"></div><div class="label">–rust: #B04A3F</div></div>
</div>

HTML显示为：

💡 关键差异：颜色需要被看到。一个 80px 高的色块传达的信息量远大于一行 #D97757 文本。

5.5 📽️ 演示文稿（Slide Deck）

场景：汇报分享、技术分享

body { scroll-snap-type: y mandatory; overflow-x: hidden; }
.slide {
width: 100vw;
height: 100vh;
scroll-snap-align: start;
display: flex;
align-items: center;
justify-content: center;
padding: 8vh 6vw;
}
.slide.invert { background: #141413; color: #FAF9F5; }

键盘导航：

document.addEventListener('keydown', (e) => {
const slides = document.querySelectorAll('.slide');
const current = Math.round(window.scrollY / window.innerHeight);
if (e.key === 'ArrowDown')
slides[Math.min(current + 1, slides.length – 1)]?.scrollIntoView();
if (e.key === 'ArrowUp')
slides[Math.max(current – 1, 0)]?.scrollIntoView();
});

HTML显示为：

💡 关键差异：好的演示需要舞台感——全屏沉浸 + 翻页动效 + 进度指示器。scroll-snap 让 HTML 页面拥有 PPT 级别的体验。

5.6 📖 交互式讲解（Interactive Explainer）

场景：教学、概念讲解、教程

可折叠区块：

<details class="deep-dive">
<summary>什么是 TTL？</summary>
<div class="content">
<p>TTL（Time To Live）是缓存条目在过期前保持有效的时长。</p>
</div>
</details>

details.deep-dive {
border: 1.5px solid var(–g300);
border-radius: 12px;
padding: 16px 20px;
margin-bottom: 12px;
}
details[open] summary::before { transform: rotate(90deg); }

交互式滑块：

<input type="range" min="10" max="300" value="60" id="ttlSlider">
<div class="output" id="result">缓存 60s 后过期，命中率约 85%</div>

<script>
document.getElementById('ttlSlider').addEventListener('input', (e) => {
const v = e.target.value;
const hitRate = Math.min(95, 50 + (v / 10)).toFixed(0);
document.getElementById('result').textContent = `缓存 ${v}s 后过期，命中率约 ${hitRate}%`;
});
</script>

HTML显示为：

💡 关键差异：学习需要渐进式展示——折叠 让读者自己控制节奏，滑块让抽象的 TTL 概念变得可操作、可感受。

5.7 📊 状态报告（Status / Incident Report）

场景：周报、事故复盘、进度追踪

健康状态药丸：

.health {
display: inline-flex;
align-items: center;
gap: 6px;
font-family: var(–mono);
font-size: 11px;
text-transform: uppercase;
letter-spacing: 0.06em;
padding: 4px 10px;
border-radius: 999px;
}
.health::before { content: ""; width: 6px; height: 6px; border-radius: 50%; }
.health.on-track { background: #E8F0E0; color: #788C5D; }
.health.on-track::before { background: #788C5D; }
.health.at-risk { background: #F5E8E4; color: #B85C3E; }
.health.at-risk::before { background: #D97757; }
.health.blocked { background: #F5E8E4; color: #B04A3F; }
.health.blocked::before { background: #B04A3F; }

<span class="health on-track">On Track</span>
<span class="health at-risk">At Risk</span>

CSS 迷你柱状图：

.bar-chart {
display: flex;
align-items: flex-end;
gap: 8px;
height: 120px;
}
.bar { flex: 1; border-radius: 4px 4px 0 0; min-height: 4px; }
.bar.done { background: #788C5D; }
.bar.in-progress { background: #D97757; }
.bar.planned { background: #D1CFC5; }

HTML显示为：

💡 关键差异：状态需要颜色。绿色=正常，黄色=有风险，红色=阻塞——不读文字，只看药丸颜色也知道项目的健康状况。

5.8 🔀 流程图（Flowchart / Process Diagram）

场景：部署流程、决策树、工作流

<svg viewBox="0 0 400 300">
<g class="node" data-step="build" cursor="pointer">
<rect x="140" y="20" width="120" height="40" rx="6"
fill="#fff" stroke="#D1CFC5" stroke-width="1.5"/>
<text x="200" y="45" text-anchor="middle" font-family="monospace" font-size="12">Build</text>
</g>
<g class="node" data-step="test" cursor="pointer">
<rect x="140" y="100" width="120" height="40" rx="6"
fill="#fff" stroke="#D1CFC5" stroke-width="1.5"/>
<text x="200" y="125" text-anchor="middle" font-family="monospace" font-size="12">Test</text>
</g>
<line x1="200" y1="60" x2="200" y2="98"
stroke="#D1CFC5" stroke-width="1.5" marker-end="url(#arrow)"/>
</svg>

HTML显示为：

💡 关键差异：流程需要被看到——箭头方向 + 节点位置本身就是信息，比数字列表直观得多。

5.9 🎨 SVG 插画（SVG Illustration Sheet）

场景：博客配图、图标集、示意图

svg.figure .st { stroke: #87867F; fill: none; stroke-width: 2.5; }
svg.figure .cl { fill: #D97757; }
svg.figure .ol { fill: #788C5D; }

HTML显示为：

优势：零依赖、无限缩放、hover 反馈、可直接复制 SVG 代码用于其他场景。

5.10 🎮 自定义编辑器（Custom Editor / Triage Board）

场景：问题分类、配置面板、Prompt 调优

HTML5 拖拽核心：

card.draggable = true;
card.addEventListener('dragstart', (e) => {
e.dataTransfer.setData('text/plain', card.dataset.id);
});

column.addEventListener('dragover', (e) => e.preventDefault());
column.addEventListener('drop', (e) => {
const id = e.dataTransfer.getData('text/plain');
const card = document.querySelector(`[data-id="${id}"]`);
column.appendChild(card);
});

导出功能：

function exportMarkdown() {
let md = '';
document.querySelectorAll('.column').forEach(col => {
md += `## ${col.dataset.name}\\n\\n`;
col.querySelectorAll('.card').forEach(card => {
md += `– ${card.querySelector('.title').textContent}\\n`;
});
md += '\\n';
});
navigator.clipboard.writeText(md);
}

HTML显示为：

💡 关键差异：配置需要操作——拖拽排序 + 开关按钮让用户感受到控制力，而不是被动阅读。

5.11 📈 数据仪表板（Dashboard / Data Display）

场景：监控面板、KPI 追踪

<div class="metric">
<div class="value">99.9%</div>
<div class="delta up">↑ 0.2%</div>
<div class="sparkline">
<div class="bar" style="height:30%"></div>
<div class="bar" style="height:45%"></div>
<div class="bar" style="height:60%"></div>
<div class="bar" style="height:90%"></div>
</div>
</div>

.metric .value { font-family: var(–serif); font-size: 42px; font-weight: 500; color: var(–slate); }
.metric .delta.up { color: var(–olive); }
.metric .delta.down { color: var(–rust); }
.sparkline { display: flex; align-items: flex-end; gap: 3px; height: 40px; margin-top: 16px; }
.sparkline .bar { flex: 1; background: var(–g200); border-radius: 2px 2px 0 0; }
.sparkline .bar:last-child { background: var(–clay); }

HTML显示为：

💡 关键差异：监控需要实时感——大号数字 + 迷你趋势线 + 颜色编码，让人在极短时间内掌握数据状态。

6. 实战展示：20 个真实办公场景

本开源项目展示页（indexxxxxxx_en.html）中集成了 20 个真实工作场景的左右对比演示，覆盖 9 大领域：

6.1 卡片结构

每个示例的布局：

┌──────────────────────────────────┐
│ 卡片标题 + 副标题 │
├──────────────┬───────────────────┤
│ 📄 Markdown │ 🎨 HTML │
│ 灰色背景 │ 白色背景+真实样式 │
│ 纯文本展示 │ 交互式渲染效果 │
├──────────────┴───────────────────┤
│ 💡 关键差异：一句话总结 │
└──────────────────────────────────┘

6.2 双主题切换

展示页内置两种配色方案，一键切换：

document.getElementById('themeToggle').addEventListener('click', function() {
const isDark = document.documentElement.getAttribute('data-theme') === 'dark';
document.documentElement.setAttribute('data-theme', isDark ? 'light' : 'dark');
this.textContent = isDark ? 'Claude Code' : 'VS Code';
});

7. 安装与使用

7.1 OpenClaw 用户

# 找到 skills 目录
openclaw config get workspace.skills.dir

# 复制 skill 文件夹
cp -r html-skill-effectiveness /path/to/skills/

7.2 Claude.ai / Claude Code 用户

7.3 触发关键词

安装后，对 AI 说以下任一短语会自动激活技能：

• “生个 HTML 状态报告”
• “用 HTML 展示这三套方案的对比”
• “做个交互式讲解器，教 XXX 概念”
• “画一张部署流程图”
• “做个监控仪表板”
• “把这堆 Markdown 变成好看的 HTML”

8. 最佳实践与避坑指南

✅ 应该做

❌ 绝对不要做

9. 总结与获取

什么时候该用 HTML 替代 Markdown？

适合用 HTML 的场景（Skill 自动识别）：

• ✅ 需要对比多个选项 → 并列卡片
• ✅ 需要展示代码变化 → Diff 高亮
• ✅ 需要表达空间关系 → SVG 架构图
• ✅ 需要输入交互 → 表单、滑块、拖拽
• ✅ 需要呈现数据趋势 → 图表、Sparkline
• ✅ 需要分页展示 → 幻灯片
• ✅ 需要分级展示 → 折叠面板

不适合用 HTML 的场景（不要滥用）：

• ❌ 纯文本文档（备忘录、笔记）
• ❌ 数据库导出（CSV 更适合）
• ❌ API 文档（结构化文档更好）

技术栈总结

获取方式

# 克隆仓库
git clone git@github.com:YardonYan/html-skill-effectiveness.git

# 或直接下载 ZIP
# https://github.com/YardonYan/html-skill-effectiveness/releases

“Trade documents people skim for documents people actually read.”

这个 Skill 的使命是：让 AI 的每一次输出，都变成你真正愿意读、愿意看、愿意交互的作品。

作者：Yardon · 2026年5月 · Apache 2.0 License

相关链接

• GitHub 仓库
• 开源项目：The Unreasonable Effectiveness of HTML
• Anthropic frontend-design skill