手把手写第一个 Skill
系列入口：如何使用 Agent。前置：Skill 的内部结构。
一、第一步也是最关键的一步：选对场景
不是什么都值得做成 Skill。第一个 Skill 强烈建议选一个你反复在做、流程相对固定、每次做法差不多的事。好的候选：提交前自查、写提交信息、给某类文件补文档、按固定清单做发版检查。
避开两类场景：一次性的临时任务（做成 Skill 没复用价值），以及高度依赖临场判断、没有稳定流程的事（写出来也很快失效）。判断标准一句话：这件事你是不是已经手工重复了好几次，而且步骤能列成清单？ 是，就适合。
我们以「提交前自查」为例走一遍。
为了帮你判断手头的事适不适合，给你一组直接对照的候选：
- 很适合：每次发版都要走一遍的固定检查清单、给某类文件统一补文档头、按固定口径整理会议纪要、把需求描述整理成统一格式——它们重复、稳定、可列清单。
- 不适合：「帮我做一次这个季度的专项分析」（一次性）、「处理各种突发线上问题」（每次差异大、强依赖临场判断）、「想清楚我们明年技术方向」（没有稳定流程）。
如果你暂时找不到明显候选，一个小技巧是回顾最近一两周，哪件事让你产生过「怎么又要做一遍」的感觉，往往那就是第一个 Skill 的好来源。不必追求选一个「最重要」的场景，第一次更该选一个「小而稳、容易跑通」的，先把完整流程练一遍，价值感会在做第二个、第三个时体现出来。选对场景这一步看似简单，却是新手最容易失败的地方——场景选错，后面指令写得再好也用不起来或很快过期。
二、第二步：写入口文件
新建 precommit-check/SKILL.md，先写 frontmatter，重点打磨 description：
---
name: precommit-check
description: 在用户准备 git commit / 提交代码前，对暂存改动做提交前自查，检查是否遗留调试代码、是否有明显逻辑/边界问题、测试是否通过，并建议一条规范的提交信息。当用户说「准备提交」「帮我 commit」「提交前检查」时使用。
---注意描述里同时写清了做什么和什么时候触发，这直接决定后面触发准不准。
然后写精简的核心指令：
# 提交前自查
按以下顺序检查当前暂存改动：
1. 运行 `git diff --cached`，列出实际改动的文件。
2. 检查是否遗留：console.log/print 调试语句、被注释掉的大段代码、TODO。
3. 检查明显问题：边界条件、空值处理、被误删的代码。
4. 运行项目测试；不通过则停止，不建议提交。
5. 全部通过后，根据改动建议一条符合约定式提交的信息。
输出格式：先给「发现的问题」清单（无则写「无」），再给建议的提交信息。指令短、步骤清，细节先不堆。
三、第三步：为易错环节加示例
新手写 Skill 最容易漏的就是示例，而示例恰恰能显著提升稳定性。对最容易出错的地方，直接给范例。比如在文件里补：
## 提交信息示例
- 正确：`fix(auth): 修正 token 过期后未跳转登录页的问题`
- 错误：`修改了代码`（太笼统）、`fix bug!!!!!!!!`（不规范）示例让模型对「好的产出长什么样」有具体锚点。如果内容较多，把长示例放进 references/，入口里用路径引用即可（渐进式披露）。
挑示例也有讲究，不是越多越好。一是优先给「边界容易错」的对照，好与坏并排，比只给正面例子更能帮它划清线。二是示例要贴近你真实会遇到的情况，用你项目里实际出现过的说法和格式，而不是教科书式的泛例。三是少量高质量示例胜过大量重复示例——三五个有代表性的正反例通常足够，堆太多反而占空间、稀释重点。
一个常见误区是把示例当成步骤的重复：步骤讲「怎么做」，示例给「做成后好坏长什么样」，两者职责不同。如果你发现示例只是把步骤换个说法再写一遍，那它提供的额外锚点很有限。真正有用的示例，应该针对你在实际中观察到的、模型容易犯的具体错误——这也是为什么建议你先用几次、观察它哪里容易跑偏，再回头补针对性的示例。把示例和真实失败点对应起来，是 Skill 迭代最有效的方式之一。
四、第四步：验证触发，别写完就算
把 Skill 放到客户端能识别的位置，然后用正反两类任务测试：
- 该触发的：「我准备提交了，帮我看下」「帮我 commit」——确认它调用了 precommit-check。
- 不该触发的：「解释一下这个函数」「重构这个模块」——确认它没有误触发。
触发不准，就回去调 description：误触发说明描述太宽，漏触发说明场景没写全。这是个快速迭代的过程，第一轮能做到「该用时基本会用」就很好。
但验证不能只看「触不触发」，还要看「触发后做得对不对」。建议在真实或模拟场景下检查三层：
- 触发准：该用时调用、不该用时不干扰（前面正反任务已覆盖）。
- 执行对：它是否按步骤走、有没有跳过检查或自行发挥？可以故意在暂存区留一个
console.log，看它能不能抓到——抓不到，说明指令或示例还要加强。 - 输出合：最终格式是不是你要的（先问题清单、再提交信息），建议的提交信息是否规范具体。
这种「故意埋一个已知问题、看它能否发现」的办法特别有效，因为它给了你客观的判断标准，而不是凭「看起来挺完整」验收。如果它漏了你埋的点，就回去强化对应步骤或示例，再测。第一次做不必追求零遗漏，但建议至少保证「最常见的问题能被稳定发现」。把 Skill 当成一个需要测试的小产品，而不是写完就交付的一段文字，这是从「写了」到「好用」的关键认知，后面讲测试与迭代会进一步展开。
| 环节 | 要点 |
|---|---|
| 选场景 | 重复、流程稳定、能列清单 |
| description | 写清做什么 + 何时触发 |
| 指令 | 精简步骤 + 明确输出格式 |
| 示例 | 给易错环节具体范例 |
| 验证 | 正反任务都测，反复调描述 |
五、一次完整的操作记录：从建目录到验收
为了让你照着就能复现，这里把「提交前自查」这个 Skill 从零到验证的完整操作再走一遍，并说明每步在确认什么。
1. 建立目录与入口。 在工具约定的技能目录下新建 precommit-check/SKILL.md。先只写 frontmatter（名称 + 带触发场景的描述），此时你确认的是「这个 Skill 解决什么、何时被调用」。
2. 补主干指令。 写入检查步骤：查看暂存改动 → 检查调试残留 → 检查明显逻辑问题 → 跑测试 → 建议提交信息，并明确输出格式。你确认的是「每次调用都要走的稳定流程」，且步骤可执行、无歧义。
3. 加关键示例。 补充规范与不规范的提交信息对照，给模型一个具体锚点。你确认的是「最容易跑偏的产出有了好坏标准」。
4. 放置并让工具识别。 确认目录位置、命名正确，必要时重新加载。你确认的是「Skill 能被发现」，这是后面一切验证的前提。
5. 触发测试。 分别发「我准备提交了，帮我看下」（应触发）和「解释一下这个函数」（不应触发），观察行为。你确认的是「触发边界基本准确」；不准就回描述调整。
6. 执行测试。 故意在暂改动里留一条调试语句，再发起检查，看它能否报告出来；并确认输出顺序和提交信息建议符合预期。你确认的是「它不仅被调用、而且真的有用」。
这六步构成了一个完整的小闭环：先建、再写、配示例、确认被识别、测触发、测执行。第一次严格走一遍，你会非常清楚每个环节的作用；等熟练后，其中很多步骤会在几分钟内自然完成。
需要特别说明的是第 6 步的价值。新手常停在「触发成功」就认为 Skill 写好了，但一个能被调用、却发现不了问题的 Skill 反而是危险的——它会给你虚假的安全感。只有通过「埋已知问题看能否抓到」这种客观验证，你才知道它的真实能力边界。把这个习惯从第一个 Skill 就建立起来，后面所有 Skill 的质量都会更有保障。
如果在某一步反复失败，不要带着问题继续往后堆内容，而应回到那一步解决——比如确认不了「被识别」，就先别测触发；触发都不准，就先别测执行。这种分层验证的思路，和排查 Agent 其他问题是一致的：让每一层在被验证可靠后，再进入下一层。
六、把第一个 Skill 用好的几个建议
写完只是开始，让它真正发挥作用还有几个小建议：一是在真实工作里刻意用几次，观察它在实际场景中的表现，往往会发现当初没考虑到的情况；二是每次发现它漏判或误判，就顺手更新一次，让 Skill 随使用持续变好；三是不要过早追求通用化，先让它在你当前的具体场景里稳定，再考虑抽象成更通用的版本。Skill 是用出来、迭代出来的，不是一次写成的。
七、第一次最容易卡住的地方
把新手实操中的高频卡点和处理列出来，对号入座：
- Skill 放好了却不被识别。 检查目录位置、文件命名是否符合当前工具约定（通常入口必须叫
SKILL.md并放在对应技能目录下），部分工具需要重启或重新加载。 - 一次都不触发。 多半是描述里场景写得太窄、或没列出真实说法。回头补充用户实际会说的几种意图。
- 动不动就触发。 描述太宽泛，收紧边界，明确只在特定场景调用。
- 触发了但不按步骤做。 检查主干是否清晰、有没有歧义；关键环节用示例锚定，确定性动作考虑下沉成脚本。
- 改了描述但行为没变。 确认会话是否重新加载了 Skill，必要时新开会话再测，避免旧缓存干扰判断。
遇到任何卡点，记住一个原则：先用最小场景验证「它能不能被触发」，再逐步加复杂度，不要在还没确认基础链路时就往里堆很多内容，否则出了问题很难定位是结构、描述还是指令的问题。
八、写完第一个之后
跑通第一个 Skill，你其实已经掌握了通用套路。接下来可以自然延伸：用同一方法把第二、第三个重复流程沉淀下来；当某个 Skill 内容变多，再学习用资源文件做渐进式披露；当你希望团队共用，再了解打包与分享。这些都是后面专题的内容，现在只要先把「选场景 → 写入口 → 加示例 → 验证触发」这个最小闭环练熟即可。
九、常见问题
Q：第一个 Skill 大概写多久、写多复杂算正常？ 第一次包括摸索，控制在很小的范围，一个场景、几条步骤即可，目标是跑通闭环而不是一次做全。等套路熟了，简单 Skill 往往十几分钟就能写好。
Q：我需要会写脚本才能做 Skill 吗？ 不需要。很多实用 Skill 只有触发描述和文字步骤。脚本是在你需要「确定性、可重复动作」时才引入的可选项，不是第一个 Skill 的必需品。
Q：怎么确认我不是在把简单事情复杂化？ 回头问一句：这件事我是不是确实重复做过、Skill 是否明显比每次手动交代省心？如果只是一次性、或 Skill 比任务本身还难维护，就不值得。Skill 服务于复用。
Q：写好的 Skill 只能自己用吗？ 可以自己用，也可以后续打包分享给团队或发布，后面会专门讲分享与市场。第一次先在自己工作里验证价值，再考虑共享。
Q：如果用着发现流程本身改了怎么办？ 直接更新 Skill。它承载的是「当前做法」，流程演进时让它同步更新，必要时标注变更。过时的 Skill 和过期规则一样会误导，定期让它贴合现状即可。
Q：怎么判断该把内容放进入口还是资源文件？ 看频率与普适性：每次调用都要用的主干放进入口，只在特定情况用的细节放资源文件。拿不准时先放资源、入口引用，避免入口一开始就臃肿。
Q：第一个 Skill 失败了会不会说明我不适合用？ 完全不会。触发不准、漏判都很正常，本就是靠迭代修正的。把它当学习闭环，改一两轮往往就有明显改善，关键是先动手做出第一个。
十、写给第一次尝试的你：降低心理门槛
如果你一直迟迟没有动手，这里再帮你把门槛降到最低。你完全不需要先把 Skill 的所有概念、脚本写法、分发方式学完，那反而会成为拖延的理由。你真正要做的只是一件很小的事：挑一个本周重复做过、步骤能用五六条说清的小事，把「什么时候用、按什么顺序做、产出长什么样」写进一个 SKILL.md，然后真的让它跑一次。 仅此而已，脚本、模板、参考文档都可以以后再说。
第一次的产出不完美是正常且应该预期的。你会在真实使用中发现它哪里漏了、哪里理解偏了，而这正是迭代的输入。把第一次的目标从「写出完美 Skill」改成「跑通一个最小闭环并观察一次真实表现」，压力会小很多，也更容易真正开始。很多人卡住，不是能力问题，而是把第一个 Skill 的目标定得太大、太追求完善。
等你看着这件小事真的被自动完成、并且自己只需稍微修正时，你会获得一种非常实在的掌控感——原来我可以把一类工作「教」给工具，并让它反复为我所用。这个体验的价值远大于读十篇教程，也是继续做第二个、第三个 Skill 最好的动力。所以，与其继续准备，不如现在就挑那件最小的事动手，这也是这篇教程最想推动你跨出的一步。
总结
写第一个 Skill 别贪大：选一件你反复做的固定流程，把触发条件和精简步骤写进 SKILL.md、给关键环节配示例，再用正反任务验证触发——跑通这一个，你就掌握了后面写几十个 Skill 的通用套路。