我之前做了一个叫 kz-skill-creator 的 Skill，用来帮我把 Skill 的结构、流程边界和检查方式整理清楚。简单说，它想解决的是：AI 技能开发时容易结构混乱、边界不清、后期难验证的问题，让一个 Skill 更稳定，执行时更符合预期，也更方便长期维护。
这篇文章想讲的，不是“Skill 的技术原理”，也不是一篇特别硬的工程规范。更准确一点说，它是一份使用笔记：如果你已经有一个想做成 Skill 的想法，可以怎么借助 kz-skill-creator，把它一步步整理清楚。
为了不空讲，我会用一个小例子来演示：在 Trae Work 里创建一个叫 kz-html 的 HTML 可视化报告 Skill。这个 Skill 的目标很简单，就是把文章、方案、流程说明、复盘报告这类内容，整理成一份可以打开、可以演示、可以截图的 HTML 页面。
这里不用先懂所有术语。后面出现 workflow、references、validate 这些词，我都会尽量用人话解释。你可以先把它当成一次“边做边看”的练习。
先看两张效果图，会更直观。
第一张是没有使用专门 Skill 时的默认生成结果：
第二张是使用 kz-html 后的效果：
先看这次要做什么
这个新 Skill 就叫 kz-html。
它要帮我们做的事，是把一类内容整理成 HTML 可视化报告。很多内容平时用 Markdown 写着还算清楚，但一拿给别人看，就会显得有点散。
这时候，HTML 报告就有用：可以分区、可以放表格、可以加流程图，也方便截图。
这个任务背后，其实有一条稳定流程：
-
先读懂材料。
-
再判断它更适合做成哪一类 HTML。
-
想清楚页面要怎么组织。
-
生成一个单文件 HTML。
-
打开浏览器检查效果。
-
最后补截图或交付说明。
如果每次都临时写 Prompt，当然也能做。但只要这件事以后会反复出现，就值得考虑沉淀成 Skill。
kz-skill-creator 的作用，就在这里。它不是只帮你写一个 SKILL.md 文件，而是帮你把这件事从“一个模糊想法”整理成“一个能被反复使用的流程”。
下面这张表可以当成路线图，不用背，只要知道后面大概会按这个顺序走：
| 这一段在讲什么 | 在 kz-skill-creator 里对应什么 |
放到这个例子里就是 |
|---|---|---|
| 需求沟通 | 创建流程里的前置确认 | 先问清输入、输出、谁来看、做到什么算完成 |
| 拆业务流程 | business-to-workflow-mapping.md |
先区分“用户会触发的 workflow”和“每条路里都会做的步骤” |
| 组合成 Skill | 规划工作流边界和资源分工 | 先做一个主入口，再按通用页、图解页、计划页、报告页等类型分流 |
| 实现 | 初始化和编辑 Skill | 在 Trae Work 里建目录、写 design.md 和 SKILL.md |
| 检查优化 | 验证、评测、迭代 | 跑检查，打开页面看效果，记录问题 |
| 版本管理 | 版本与验证规则 | 每次修改都留下版本号和修改原因 |
这张表看起来有点像工程流程，但别被吓到。实际做的时候，就是一步一步把事情说清楚。
需求沟通：先把目标问明白
很多 Skill 后面不好用，不是因为写得不够长，而是开始时没问清楚。
所以第一步，不是打开 SKILL.md，而是先做一点需求沟通。这个沟通可以很轻，不需要开会，也不需要写很正式的文档。你只要让 AI 帮你顺手过一遍这些问题就行。
| 可以先问什么 | 这个例子里可以怎么答 |
|---|---|
| 这个 Skill 想稳定完成什么事？ | 把内容材料整理成可浏览、可截图、可交付的 HTML 页面或报告 |
| 用户通常会怎么说？ | “帮我把这份内容做成 HTML 可视化报告” |
| 输入一般有哪些？ | 文章、方案、流程说明、复盘内容、设计偏好、交付要求 |
| 输出是什么？ | 一个单文件 HTML，必要时附检查说明和截图 |
| 做到什么程度算完成？ | 页面能打开，结构清楚，关键信息没丢，截图可读 |
| 这个 Skill 大概复杂吗？ | 偏复杂。如果只做报告页，可以按中等起步；如果要覆盖多种 HTML 产物，就按复杂 Skill 处理 |
这一步对应 kz-skill-creator 里的“统一确认进入条件与关键问题”，以及“用具体示例理解目标对象，并判断复杂度”。
听起来像流程，其实就是把脑子里的想法倒出来。
如果只说：
生成一个好看的 HTML 报告。
AI 当然也会做，但它要猜很多东西。好看是什么？给谁看？必须保留哪些内容？要不要暗色模式？要不要截图？要不要检查文字溢出？
稍微说具体一点，就稳很多：
读取用户提供的内容材料，判断它更适合做成通用信息页、图解页、计划页、报告页还是交互小工具。产物默认是单文件 HTML，交付前要检查文字溢出、暗色模式、响应式和截图可读性。
这段不一定要写进最终 SKILL.md，但很适合先放进 references/design.md。它就像草稿纸，帮你在正式写 Skill 前，把目标先放平。
业务流程：把一件大事拆成几段
接下来会遇到一个词：workflow。
如果你没有技术背景，可以先别管它的英文。简单理解，workflow 就是“一段可以反复执行的小流程”。
不过这里要稍微分清两层。
一层是用户真的会单独提出的事，比如“做一个报告页”“做一个架构图页面”“检查这个 HTML 有没有问题”。这种更适合叫 workflow。
另一层是每个 workflow 里都会做的动作，比如读材料、规划结构、写 HTML、打开浏览器检查。这些更像内部步骤，不一定要单独拆成 workflow。
比如“生成 HTML 报告”听起来是一件事，但真做起来，里面确实有好几步：
- 先看用户给了哪些材料。
- 再决定报告结构。
- 然后写 HTML。
- 最后打开浏览器检查。
这些步骤很重要，但它们不一定都是 workflow。
kz-skill-creator 里 business-to-workflow-mapping.md 真正想提醒你的，是不要一上来就把所有步骤堆成一段话。先看看真实业务是怎么走的，再决定哪些是用户入口，哪些只是执行过程。
对 kz-html 来说，更自然的拆法是按“最后要交付什么类型的 HTML”来拆：
| workflow | 用户大概会怎么说 | 最后产物 |
|---|---|---|
| HTML 可视化主入口 | “帮我做成 HTML 可视化页面” | 先判断应该走哪条分支 |
| 通用内容可视化页 | “把这篇内容做成展示页 / 解释页” | 信息结构清楚的单页 HTML |
| 图解 / 架构 / 流程可视化 | “做个架构图 / 流程图 / 系统关系图” | 更偏图解的 HTML 页面，图形优先 |
| 计划 / 方案可视化 | “把实施方案做成计划页” | 时间线、阶段、任务、风险 |
| 报告 / 复盘可视化 | “做一份汇报页 / 复盘页” | 结论、指标、时间线、关键发现 |
| 交互原型 / 小工具 | “做个能点的 Demo / 调参器” | 带少量交互的单文件 HTML |
每个创建类 workflow 里面，再共用一套生产步骤：
理解输入 -> 提炼信息结构 -> 选择视觉模式 -> 实现单文件 HTML -> 浏览器验收 -> 修复回环
这样拆有个好处：主 Skill 不会被某一种页面绑死。今天做报告页，明天做图解页，后天检查已有 HTML，入口还是同一个 kz-html。
当然，第一版不用把上面所有分支都写满。为了降低负担，可以先做一个更小的版本：
- 一个 HTML 可视化主入口。
- 一个报告 / 复盘可视化 workflow。
- 一个验收与修复 workflow。
后面真实使用时，如果发现“图解页”经常被单独触发，再补上图解 workflow。这样就不会一开始写得太重，也不会把后面扩展的路堵死。
比较好用的判断方式还是那句：如果这件事以后经常被单独触发，有清楚的输入和输出，也可能反复复用，那它才更适合成为一个 workflow。
组合方式：别把所有东西都塞进 SKILL.md
拆完流程以后，就要决定：这些内容放在哪里。
这一步很容易走偏。很多人会觉得，既然是 Skill，那就把所有东西都写进 SKILL.md。背景、示例、注意事项、模板、检查规则，全放进去，看起来最完整。
但实际用起来，主文档越长，Agent 反而越难抓住重点。
主 SKILL.md 不需要当百科。它只要回答几个关键问题：
- 用户怎么说时应该触发这个 Skill？
- 触发后怎么判断该走哪类 HTML workflow？
- 有哪些所有分支都必须遵守的硬规则？
- 做完怎么检查？
- 如果需要更多细节，去读哪个文件？
比如单文件交付、默认不需要构建步骤、暗色模式、响应式、浏览器验收，这些属于硬规则，适合在主入口里提醒。至于页面风格、视觉模式、验收细节和样例，可以放到 references/ 里。这样主文档轻一点，后面维护也轻一点。
这些内容，kz-skill-creator 会引导你一步步补齐。真正落到文件里之前，还是要看一眼边界和取舍是否符合你的场景。
实现：先搭一个能跑的最小版本
到了实现阶段，不用一开始就追求“完整”。可以先完成一个简单版本，跑起来再说。
后面如果发现“视觉模式选择”需要更多解释，就把它放进 references/visual-patterns.md。
如果发现“浏览器验收”每次都重复做同一批检查，再把清单沉淀到 references/acceptance-checklist.md，或者补一个脚本。
先让最小版本跑起来，再慢慢补。
语义化标签：不是装专业，是减少误会
kz-skill-creator 很强调语义化标签。比如 @工作流、@步骤、@动作、@验证点。
这几个词看起来有点技术，但作用很朴素：少让 Agent 猜。
普通写法可能是：
先看看用户要什么页面，然后生成 HTML，最后检查一下。
人看得懂，但 Agent 要猜很多东西。怎么判断页面类型？生成到什么程度？检查什么？怎么判断检查通过？
换成结构化写法，意思就清楚很多：
### @步骤1: 判断 HTML 类型
<!-- @类型: 决策步骤 -->
<!-- @优先级: 必须 -->
<!-- @验证点: 已选择正确的 HTML 可视化 workflow -->
<!-- @验证方式: 用户意图、输入内容和目标产物一致 -->
<!-- @ID: step-route-html-type -->
- @动作: 根据用户原话判断是通用页、图解页、计划页、报告页还是交互小工具。
- @动作: 如果用户只说“做成 HTML 可视化”，先根据内容和交付场景推断最合适类型。
- @动作: 如果不同类型会导致页面差异很大，再集中问一个澄清问题。
你可以把它想成路标。
@工作流 告诉它现在走哪条路，@步骤 告诉它走到哪一步，@动作 告诉它具体做什么，@验证点 告诉它做完要看什么。
对人来说，这些标签像清单。对 Agent 来说，它们像导航。
检查与优化：先跑稳，再慢慢加评测
Skill 写完第一版，不代表它已经稳定。
但也不用一上来就做很重的评测。对很多人来说，第一轮先人工检查就够了。
可以先看这些：
| 检查项 | 看什么 |
|---|---|
| 触发条件 | 用户怎么说时应该用这个 Skill |
| 主入口 | 是否能判断通用页、图解页、计划页、报告页、交互小工具和检查修复 |
| 主流程 | 是否能看出每个 workflow 内部先做什么、再做什么 |
| 标签 | 是否有 @工作流、@步骤、@动作、@验证点 |
| 资源分层 | 长说明是不是放到了 references/ |
| 硬规则 | 是否默认单文件、无构建步骤、支持暗色模式和响应式 |
| HTML 结果 | 页面能不能打开，文字有没有溢出，元素有没有重叠，截图是否可读 |
| 交互状态 | 如果有按钮、切换或调参，状态是否真的可验证 |
| 版本记录 | 修改有没有留下版本号和说明 |
如果你使用 kz-skill-creator 创建技能，它会引导你跑验证、整理问题，并把需要修复的地方列出来。实际结果还是要结合你的场景再确认一遍。
HTML 报告类 Skill 还要多一步：打开浏览器看一眼。很多问题，光看 Markdown 看不出来，比如文字压到一起、暗色模式看不清、移动端横向滚动、按钮点了没反应，或者截图里信息太小。
如果页面里有图解，优先检查节点层级和连线关系。如果页面里有交互，别只看按钮在不在，还要看点了之后状态有没有变化。
等 Skill 用过几次，最有价值的优化通常来自真实问题。比如页面在移动端溢出、暗色模式看不清、图解节点太乱，这些都可以反过来写进规则。
我在使用 kz-html 时遇到这些问题：
- 移动端有文字溢出
- 暗色模式下部分文字看不清
- 图解页面节点层级不够清楚
请帮我优化 kz-html Skill。
等它跑过几次真实任务，再考虑更完整的评测。kz-skill-creator 里有一条评测路线：
这条路线很有用，一般跑完会生成一份详细的评估报告，只要让 kz-skill-creator 把主要问题修复即可。
如果优化效果还不理想，可以继续补充问题，再让 kz-skill-creator 做一轮调整。改完之后，再跑一次评测看看效果有没有变好。
版本管理：给未来的自己留条线
最后说版本。
这一块看起来最像形式主义，但真的很有用。Skill 一旦开始复用，就会不断改：今天补一个触发条件，明天调整一个流程，后天增加一个检查点。
如果没有版本记录，过一段时间再回头看，很难知道哪次改动改变了行为。
kz-skill-creator 的要求很简单：每次修改 SKILL.md、references/、scripts/ 或 assets/，同步更新三处。
- YAML frontmatter 里的
version。 - 标题下方的版本信息。
- 文末
## 版本历史里的首条记录。
比如：
---
name: kz-html
description: 当用户需要把内容材料整理成 HTML 可视化报告时使用。
version: 0.2.0
---
# HTML 可视化报告 Skill
> **版本**: v0.2.0
## 版本历史
- **v0.2.0** (2026-07-07) - 增加浏览器检查步骤，要求交付前检查文字溢出、暗色模式和截图可读性。
- **v0.1.0** (2026-07-07) - 初始版本，支持生成 HTML 可视化报告。
版本历史不用写得很正式。重点是写清楚“为什么改”。
“优化 Skill”这种记录太模糊。以后回看时，你不知道它到底优化了什么。
写成下面这样就清楚多了：
增加浏览器检查步骤，要求交付前检查文字溢出、暗色模式和截图可读性。
这句话能帮你想起来：这次改动是为了让 HTML 报告交付更稳。
最后留一张小清单
如果你也想用 kz-skill-creator 创建一个 Skill，可以照着这张清单慢慢过，不用一次做到满分。
| 阶段 | 问自己 |
|---|---|
| 需求沟通 | 这个 Skill 到底解决什么稳定任务？输入、输出、完成标准是什么？ |
| 复杂度判断 | 它是轻量、中等还是复杂？有没有多阶段产物或检查点？ |
| workflow 拆分 | 哪些是用户会单独触发的入口？哪些只是每条路里都会做的普通步骤？ |
| 组合 Skill | 主 SKILL.md 放什么？references/、scripts/、assets/ 各放什么？ |
| 实现 | 最小版是否已经能触发、能执行、能检查？ |
| 语义化标签 | 关键步骤有没有 @动作、@验证点、@验证方式？ |
| 检查优化 | 是否跑过 validate，或至少人工检查过一次？ |
| 版本管理 | 修改有没有同步版本号和版本历史？ |
如果是很轻的 Skill，可以少写一点。
如果是中等复杂度的 Skill，至少把 workflow 和检查讲清楚。
如果它以后会长期复用、多人使用，或者经常返工，再考虑补完整的映射表、决策矩阵、验收清单和评测闭环。
不用把 Skill 一次写到完美，长期使用中不断积累的经验教训才会让 skill 更有价值。
先把需求说清楚，再拆流程；先做一个能跑的版本，再慢慢补检查和版本记录。这样用 kz-skill-creator，会轻松很多，也更容易坚持维护。