ARTICLE · 1022277
我的第一个 Skills · 让写培训文档不再从零开始
新人要来了 · 技术培训文档从零写 —— 结构乱七八糟 · 每份都是从头想。
那天我停下来 —— 写了一份"怎么写培训文档"。
9 步主流程 + 4 条铁律 + 5 个我踩的坑 —— 从此每份都走这一条流程。
上周三下午 · 老板转来一条消息:"下周有新人报到 · 你给他们培训一下当前项目 · 先出份技术培训文档。"
我打开一份空白文档 · 从"先打开开发环境"写起。
写到一半 —— **我发现自己又在写"先打开 xxx"**。
一份文档写下来 · 结构乱七八糟 —— 有的章节配图 · 有的没图;有的写了"为什么" · 有的没写;FAQ 写了 · 但收官 checklist 忘了。
这不是我第一次这么写技术培训文档 —— 半年下来 · 每次都是从零重来。
那天下午我停下来 —— 我不写技术培训文档了。
**我先写一份 —— "怎么写培训文档"**。
那份东西 · 就是我的第一个 Skills。
一、Skill 是什么
先说清楚 —— Skill 不是某个平台的专属功能。
它是一个通用概念:
把重复流程沉淀成 AI 能直接召回的模板。
各家 AI 助手都有自己的实现:
Claude Code · SKILL.md ChatGPT · Custom GPT Cursor · .cursorrules Cline · Custom Instructions Windsurf · Workflows
概念相同 · 语法不同。
下面我用 Claude Code 的写法举例 —— 用其他工具的读者 · 换语法 · 方法通用。
二、我这个 Skill 长什么样
我给这个 Skill 起名 teach-html —— 一份能教会人的 HTML 教程生成流程。
目录结构:
teach-html/├── SKILL.md (核心 · 定义触发条件 + 主流程 + 铁律)└── references/ (引用文件 · 后面讲坑的时候会说)SKILL.md 分 3 部分:
第 1 部分 · frontmatter · 告诉 AI 什么时候用
---name:teach-htmldescription:>- Use this skill whenever the user asks for a step-by-step how-to tutorial as a single-page HTML document.TRIGGER on:"教程","手把手","培训文档","新人教学"...SKIP when:只要一份markdownREADME·或幻灯片---这一段是 AI 决定"要不要用这个 Skill"的关键。
第 2 部分 · 主流程 · 9 步
从"定位读者"到"收官 checklist" · 9 步顺序不能跳。
第 3 部分 · 铁律 · 4 条
每一份产出都要过 4 条铁律 —— **不过就是"一堵只有作者自己看得懂的墙"**。
三、9 步主流程 · 精讲
9 步不是命令列表 —— 是一份教程 SOP。我挑最容易被跳过的几步讲透:
步骤 1 · 定位读者与场景
一句话说清:读者是谁、已经会什么、在什么设备上读这份文档。
这一句会影响后面所有决定 —— 词汇深浅、截图密度、命令要不要展开解释。哪怕最终不写进 HTML · 也要在草稿最上面先写一行。
步骤 3 · 承诺一个具体终点
一句话:"学完你能 ___"。
必须可验证 —— 一张能对照的截图、一条能核对输出的命令、一个能观察到的行为。
"了解 X" 不算终点。
步骤 7 · 每一步都写"为什么 → 怎么做 → 怎么验证"
为什么:一句话说清这一步为什么存在(不是"接下来我们…" —— 那是过渡词 · 不是理由) 怎么做:命令 · 点击 · 配置 —— 配一张图 怎么验证:做对了应该看到什么;做错了往哪回退一行字讲清楚
每一步 · 无例外。这是 9 步里最贵的一步。
四、4 条铁律 · 每篇必守
主流程管"怎么走" · 铁律管"怎么才不废"。
铁律 A · 先讲为什么 · 再讲怎么做
每章开头先给理由 · 再上命令。文档如果开篇就是"先打开 xxx" —— 废了。
读者不知道这一步跟自己有没有关系 · 就没耐心跟下去。
铁律 B · 每一步能独立验证
没有一步是以"接下来做 X"作为唯一出口的。永远要有办法检查"我做对了吗" —— 截图对比、命令输出、可观察行为 · 三选一。
铁律 C · 图先于字
能用图讲清的 · 就不用文字。文字是兜底 · 不是首选。
之前我写的教程平均每篇 7 张流程图 + 多个 UI 面板示意 —— 密度保持住。
铁律 D · 绝不虚构
所有 FAQ、报错信息、命令输出、版本号 —— 必须来自真实经验。
如果没有真实例子 · 就写"留占位 · 作者补" —— 绝不编一个像模像样的假的。
这是 AI 写文档最容易穿帮的地方。
五、5 个我踩的坑
写完 Skill 我以为一劳永逸 —— 用了几次之后 · 发现了 5 个坑。
坑 1 · references/ 目录里 4 个文件全是空的
SKILL.md 里我引用了 4 个参考文件 —— component-css.md · svg-templates.md · example-outline.md · anti-patterns.md。
但我一个都没写。目录建了 · 文件没建。
AI 加载时不至于失败 · 但它拿不到我说的组件库、模板、样板 —— 生成的文档虽然结构对 · 但每次样式都不一样。
这个坑我踩了几次才反应过来 —— 因为**"目录建了" 让我错以为"东西齐了"**。
坑 2 · TRIGGER 词写太少
一开始 frontmatter 里我只写了"教程"、"手把手"两个词。
结果我跟 AI 说"给新人写一份新员工上手指南" —— 没触发。
补足同义词 —— 培训文档、新人教学、onboarding、walkthrough、how-to、一步步教 · 覆盖你可能说的所有话。
坑 3 · description 太长 · AI 一开始不选
我的 description 写了整整一段话 —— 关键词被稀释了。
AI 决定"要不要用这个 Skill" 是看 description 前 30 字。
改成"一句话讲清 + 大量关键词" —— 前 30 字里要有决定性动词。
坑 4 · 铁律写太多 · AI 只记得前 2 条
第一版我写了 8 条铁律。AI 生成时 · 只稳定遵守前 2 条。
后面 6 条时灵时不灵。
铁律的注意力预算有限 —— 4 条正好 · 挑最重要的 4 条留着 · 其他并入主流程。
坑 5 · 没写"SKIP when"
有一次读者只要一份 markdown README —— AI 也上了 HTML 文档模板。
"SKIP when" 一句话救命 —— "只需一份 markdown README · 或幻灯片 · 或短对话 —— 都不用这个 Skill"。
六、Skill 落地之后 · 我的真实变化
Skill 落地之后 · 我又用它写了几份技术培训文档 —— 但更值钱的不是省了多少时间。
变化 1 · 我不再从零想结构
每份文档打开 —— 9 步顺序摆在那里 走一遍就是一份完整的技术培训文档
变化 2 · 多份文档风格一致
新人不用适应几种不同的教程结构 我自己回来改也不会打架
变化 3 · 我写的时候不再"想到哪写到哪"
每一句我都知道自己在走 9 步里的第几步 卡住的时候 —— 是因为漏了某一步 · 不是"没灵感"
最值钱的一点 —— 半年下来我重复走过的路 · 写下来了一次。
写下来之后 —— 不用再重新走。
七、写在最后
半年造工具的经验里 —— 这是我第一次不是造代码工具 · 而是造流程。
造代码工具 · 是让 AI 帮我干活。
造 Skill · 是我把干活的方法 —— 教给 AI。
一份 Skill 落地之后 · 我的收获不是"少写了多少小时" —— 是把半年下来重复走过的路 · 写下来了一次。
写下来之后 —— 不用再重新走。
八、下期预告
这一篇讲了 ——
Skill 是通用概念 —— 各家 AI 助手都有自己的实现 我的 teach-html Skill 长什么样 —— frontmatter + 9 步 + 4 铁律 9 步主流程精讲 —— 定位读者 · 承诺终点 · 每步三段套路 4 条铁律 —— 先讲为什么 · 每步能验证 · 图先于字 · 绝不虚构 5 个我踩的坑 —— 从空目录到 TRIGGER 词到 SKIP when
下周同一时间 ——
《实时性能监测 · 三合一时序图那些看不出的卡顿》
三条曲线单独看都合格 —— 用户还是嫌卡 卡顿藏在三条曲线联合的那一刻 三种误判 + 5 项审批 checklist
关注公众号「小谈AI智舱」· 下周不见不散。
写在最后
用 AI 让工程师少加班 · 让工程师从"干活的人"变成"造工具的人" · 是我们的核心命题。