html-anything 技能模板详解：用 SKILL.md 打造 Spotify Now-Playing 正在播放卡-平芜编程栈

AI 应用
人工智能
AI Agent
AI 写作
媒体生成

【免费下载链接】html-anything

✨ The agentic HTML editor — your local AI agent writes the HTML, you ship it. 🚀 75 Skills × 9 Surfaces (magazine · deck · poster · XHS / tweet · prototype · data report · Hyperframes) 🛡️ Sandboxed preview · 📤 1-click to WeChat / X / Zhihu / HTML / PNG 🔑 Zero API key — Claude Code / Cursor / Codex / Gemini / Copilot / OpenCode / Qwen / Aider.

项目地址：https://gitcode.com/gh_mirrors/ht/html-anything

点击查看免费下载

本文聚焦 html-anything 开源仓库中social-spotify-card这一款技能（Skill）模板，围绕它的定义文档 SKILL.md 展开：它如何用一份纯文本规范驱动 AI Agent 渲染出 Spotify 风格的"正在播放卡"，适用于视频叠加（video overlay）、个人主页（about page）与创作者 hero 场景。读完本文，你将掌握该模板的画布规格、卡片结构、设计令牌、内容映射规则，以及它在 html-anything 中从「技能文件夹」到「AI 生成 HTML」的完整运行链路，并可直接复制其示例输入与示例 HTML 上手使用。

一、Skill 是什么：html-anything 的"文件夹即模板"机制

html-anything 是一套"Agentic HTML 编辑器"：用户把一段 Markdown / 文本内容交给本地 AI Agent，Agent 依据某个技能模板的提示词，输出一份自包含的单文件 HTML。模板不再是一段硬编码在 TS 里的巨型数组，而是每个技能一个文件夹：

next/src/lib/templates/skills/<skill-id>/ SKILL.md — frontmatter（id、场景、标签…）+ 提示词正文 example.md —（可选）示例输入内容 example.html —（可选）预渲染预览，选择器内联展示

这一定位在 loader.ts 的模块注释中写得很清楚：新增一个模板 = 新增一个文件夹，无需改动任何 TS 代码。服务端由/api/templates扫描磁盘返回技能元数据列表，客户端通过 index.ts 的useTemplates()拉取并缓存。social-spotify-card正是这一布局下的典型范例：一份 SKILL.md、一份示例输入 example.md 和一份可直接预览的 example.html。

二、模板定位与 frontmatter 元数据逐项解析

SKILL.md 顶部是一段 YAML frontmatter，它同时服务于选择器展示、搜索与示例加载。字段如下（参考 loader.ts 的SkillFrontmatter类型）：

字段	本模板取值	作用
`name`	`social-spotify-card`	技能 id，即文件夹名，用于 API 路由定位
`zh_name`	`Spotify 正在播放卡`	中文名，选择器默认展示
`en_name`	`Spotify Now-Playing Card`	英文名，locale 为 en 时展示（见 template-picker.tsx）
`emoji`	`🎵`	列表项图标
`description`	`Spotify Now Playing 风格卡…`	单行描述，出现在列表与悬停预览
`category`	`card`	卡片类技能
`scenario`	`personal`	使用场景，对应 scenarios.ts 中`personal`键（个人主页类），选择器按场景分桶过滤
`aspect_hint`	`1280×720 或 600×200`	画布提示，渲染在选择器按钮、列表行与预览弹窗上（template-picker.tsx），提示用户目标尺寸
`featured`	`43`	排序权重，数值越小越靠前（`rankFeatured`见 template-picker.tsx）
`tags`	`["spotify","music","now-playing","card","overlay"]`	搜索关键词，与名称、描述一起参与`matchesQuery`匹配（template-picker.tsx）
`example_id`/`example_name`/`example_format`	`sample-social-spotify-card`/`Spotify Now Playing · Lo-Fi`/`markdown`	示例内容标识、名称与输入格式
`example_tagline`/`example_desc`	`Spotify 经典 dark 卡`/`Lo-Fi Beats · Chillhop 进度条 1:24 / 3:42 + 控制行`	悬停预览弹窗的副标题与描述
`example_source_url`/`example_source_label`	`https://hyperframes.heygen.com/catalog`/`hyperframes · spotify-card`	灵感来源标注，选择器会渲染为外部链接徽章（见 template-picker.tsx）

frontmatter 的解析由 loader 内置的零依赖解析器完成（loader.ts），支持字符串（可带引号）、整数以及单行数组字面量（tags: [...]）。解析出的元数据经fmToMeta映射为SkillMeta，SKILL.md中---分隔符之后的正文则作为提示词 body单独保留，并不会随元数据一起发给浏览器。

三、画布规格：两种目标尺寸

SKILL.md 的【画布】一节定义了两种尺寸，二者对应不同用途：

横版视频叠加：1280×720。卡片居中或左下角浮动，适合作为直播/视频中的 overlay 角标。
紧凑横条 widget：600×200。可嵌入任意 hero 区域，作为个人主页顶部的常驻元素。

aspect_hint: "1280×720 或 600×200"会在选择器界面中直接展示（见 template-picker.tsx），让用户在选中模板前就知道目标画布比例。仓库自带的示例 HTML 实际采用w-[640px]横条卡片、页面背景为min-h-screen深色渐变，处于两种规格之间：既可截取为视频叠加，也可整体嵌入 hero。

四、卡片结构：外框、封面、信息区与 logo

SKILL.md 将卡片拆解为五个可独立描述的区域，这是提示词中最重要的视觉规范，Agent 必须逐项落实：

4.1 外框

圆角12–16px（示例中为rounded-2xl，即 16px）。
背景两种方案：专辑封面色提取的暗渐变（如linear-gradient(135deg, #1e3264 0%, #0d1f3d 100%)），或 Spotify 经典#121212。
边缘 1px subtle border（示例为border:1px solid rgba(255,255,255,0.08)），并配柔和投影。

4.2 左侧专辑封面

严禁外链图片：封面必须用 CSS 渐变 + 大字 monogram（首字母）或抽象几何描绘生成。这是共享设计指令的硬性要求（见下节）。
圆角 6px（rounded-md），尺寸 60–200px 方形（示例为w-44 h-44，176px）。
示例封面由三层渐变叠加而成：两圈径向光晕（粉#ffb1c3、紫#6b46c1）+ 135° 深紫渐变底，再叠上 "Chillhop" 小字标签与 "Lo-Fi Essentials / Spring · 2026" 文字排版（见 example.html）。

4.3 右侧信息区

自上而下依次是：

NOW PLAYING标签：全大写、letter-spacing 0.14em–0.18em、11px、Spotify 绿#1DB954（示例含内联 Spotify 波浪图标）。
歌名/标题：Inter / Spotify Circular，22–28px，weight 700，白色（示例text-2xl font-bold）。
艺人/副标：16px、weight 400、opacity 0.7白色（示例text-white/70）。
进度条：4px 高、圆角、灰底 + 白色 fill（width: 38%），两端时间戳1:24 / 3:42（mono、11px、灰）。示例实现还加了一个位于 38% 处的白色圆点播放头（example.html）。
控制行：⏮ ⏯ ⏭ 三个内联 SVG 图标（24px、白色 fill），shuffle / repeat 图标较小。示例用viewBox="0 0 24 24"的 Material 风格 path 手绘，播放键做成白色圆形按钮 + 黑色三角（example.html）。

4.4 右上角 Spotify logo

内联 SVG：绿色#1DB954圆 + 三道白色波纹。示例直接内嵌了标准 Spotify 图标 path（example.html），同样不依赖外链资源。

4.5 音波动效（可选）

右下角 3 个小 bar 用@keyframes做垂直缩放动画。示例实现为.wave i四个3px宽小条，transform-origin: bottom，1s ease-in-out 无限循环，并通过nth-child依次延迟 0.15s / 0.3s / 0.45s 形成扫波效果（example.html）。关键约束是：动效必须能被prefers-reduced-motion关闭，满足无障碍要求。

五、字体与设计令牌：Spotify 经典 dark mode

SKILL.md 的【字体】与【设计细节】明确了这套卡片的三组设计令牌，也是 Agent 生成时唯一被允许的配色来源：

背景：#121212（Spotify 经典 dark）。
强调色：#1DB954（Spotify 绿，用于 NOW PLAYING 标签、logo、音波条）。
次要文本：#b3b3b3（描述性文字、时间戳）。

字体主选Spotify Circular，fallback 到Inter/Inter Tight，weight 只用 400 / 700 两档；数字与主字体一致，不要大量使用 mono（示例仅在时间戳处用了font-mono以贴合进度条语义）。这与全局共享设计指令（shared.ts）的排版规范一致：英文优先Inter，中文优先Noto Sans SC。

六、内容映射规则：文本输入如何变成卡片

SKILL.md 给定了 Agent 的"输入 → 元素"决策逻辑，这是提示词里最具操作性的部分：

用户输入是文本/标题→ 把"标题"当作歌名、"副标/作者"当作艺人；"时长"在无数据时默认 3:42，进度可估算为某个百分比（示例填 38%，对应 1:24 / 3:42）。
用户输入本身是音乐相关内容（如歌单、播客介绍）→ 直接一一对应：曲名→歌名、创作者→艺人、专辑→封面文字、时长→时间戳。

仓库示例输入 example.md 就是一份音乐类内容：歌名Sunday Afternoon（j'san · evil needle）、进度 1:24 / 3:42、专辑Chillhop Essentials Spring 2026、周听众 2.4M。而示例 HTML 忠实呈现了前三条信息（封面文字取专辑名、副标题取艺人、时间戳取进度），验证了映射规则的实际效果。若输入的是个人介绍，则同样适用：姓名→歌名位置、身份/简介→艺人位置，"时长"这类无来源数据使用默认值即可。

七、共享设计指令：每条技能提示词之上的硬约束

当用户在编辑器中点选该模板并提交内容时，实际发给 Agent 的提示词并非只有 SKILL.md 正文。/api/convert路由会调用 assemblePrompt（route.ts），把 SKILL.md 的 body 与全局设计指令SHARED_DESIGN_DIRECTIVES（shared.ts）拼接，再追加【输入格式】与【用户内容】。

其中有四条与本文模板直接相关、且被 example.html 严格遵循的规则：

禁止使用文件系统工具：HTML 必须作为助手回复正文流式输出，落盘由前端完成；因此示例 HTML 也是可直接双击打开的单一文件。
单文件自包含：<!DOCTYPE html>开头、</html>结尾，head 中通过 CDN 引入 Tailwind v3 Play 与 Google Fonts（示例引入了Inter与Noto Sans SC）。
不引用外部图片 URL：优先 CSS / SVG 内联绘制——这正是 SKILL.md 中"封面用 CSS 渐变 + 文字 logo / 几何描绘"的顶层依据。
内容真实性：必须使用用户真实数据，不得 lorem ipsum——示例 HTML 中的所有文字均来自示例输入。

此外，当用户对同一任务再次编辑时，/api/convert还会走editFromHtml / editFromContent的最小化差异编辑分支（route.ts）：保留原 HTML 的 head、配色与结构，只按新旧内容差异替换文字节点，避免每次重生成导致风格漂移。

八、示例实操：从输入到成品 HTML

完整的"输入 → 产物"链路如下：

输入内容（用户在编辑器粘贴，或从示例加载）：见 example.md。
选择模板：在模板选择器中搜索 "spotify" 即可命中（tags 含 spotify/music/now-playing/card/overlay），选中后按钮上会显示🎵 Spotify 正在播放卡与1280×720 或 600×200的尺寸提示。
悬停预览 / 一键载入：模板携带example.html，选择器悬停时通过/api/templates/:id/example拉取并在 1280×960 的 iframe 中缩放预览（route.ts、template-picker.tsx），点击 "载入" 即可把示例内容与 HTML 一起放进编辑器。
生成与渲染：提交后/api/convert组装提示词（含 SKILL.md body + 共享指令 + 用户内容），Agent 流式返回单文件 HTML，前端捕获 stdout 并渲染在预览面板中。

生产环境的成品即 example.html：Tailwind 工具类完成布局（flex左右分栏、gap-5、items-stretch），内联style承载渐变背景、边框与投影，.wave类承载音波动效，整体约 70 行，未引入任何外部图片。

九、自定义与扩展：把这款卡片改造成自己的技能

social-spotify-card的机制决定了任何人都可以低成本复制改造：

新增一个同族技能：在next/src/lib/templates/skills/下复制文件夹并改名，如social-spotify-mini，修改 frontmatter（id、名称、aspect_hint、tags）与 body 即可；开发模式下 loader 每次请求都会重扫磁盘（loader.ts），无需重启next dev。
调整画布比例：把aspect_hint改为目标值，并在 body 的【画布】中同步更新；例如改成 1080×1080 的方形卡，仅需调整封面尺寸与信息区排布。
替换设计令牌：把#121212/#1DB954/#b3b3b3换成自己的品牌色，即可得到一款"类 Spotify"的播放卡。
通过市场安装：外部技能包安装到~/.html-anything/skills/后，会以pkg-<owner>__<repo>--<originalId>的命名空间 id 合并进同一注册表（见 registry.ts），选择器无需改动即可展示。

十、相关文件速查

模板定义：SKILL.md
示例输入：example.md
示例成品：example.html
技能加载与 frontmatter 解析：loader.ts
全局共享设计指令与提示词组装：shared.ts
转换/生成 API（含 diff-edit）：route.ts
模板选择器（搜索、场景过滤、悬停预览）：template-picker.tsx
场景常量与排序：scenarios.ts

一句话总结：social-spotify-card的 SKILL.md 用一份 50 行不到的规范，完整锁定了"Spotify 正在播放卡"的画布、结构、配色与内容映射规则；它与 html-anything 的共享指令、磁盘加载器和转换 API 协同，让任意本地 AI Agent 都能稳定复现这一经典卡片风格。