自建 Agent 技能写了改、改了写，我干脆定了一条规范

最近一直在折腾 Agent 的技能（Skill），先后自建了好几个：给本地技能和规则做 GitHub 备份的、往 GitCode 仓库提 Issue 的。前几个技能来回返工，改到第三版才消停。问题不是不会写，是每次写都靠现场发挥，没有一套固定的章法。后来把华为云市场的官方 skill-creator 翻出来，发现人家的结构规范才是主干——命名规矩、三级加载、校验脚本都是现成的。我就干了一件事：拿官方规范打底，再把我自己环境里踩出来的坑叠上去，整合成一份 skill-creation-guide，之后新建技能都照它走。

先说最核心的那个机制：技能是「三级渐进披露」，这也是官方 skill 规范的地基。平时只有文件头那几行（name 和 description）常驻在 Agent 上下文里；等到真的触发到这类任务，正文才整段加载进来；至于 scripts、references 这些辅助文件，是 Agent 用到时才去读的。这个机制直接决定了一条铁律：「什么时候该触发」必须写进 description。我第一版就把触发条件写在正文里，结果技能根本没被触发——正文不加载，写什么都是白写。

命名有硬校验：只能小写字母、数字、连字符，目录名必须和 SKILL.md 里的 name 一致，文件名必须全大写 SKILL.md，违反直接停。这些规矩不用自己发明，就来自官方 skill-creator 的结构规范，跑一下它附带的 quick_validate.py 就知道：frontmatter 缺 metadata 字段时，直接报「Missing required field in frontmatter: metadata」。

官方给的是骨架，真正让技能好用的是后两条写作纪律，都是血泪：

不许编造命令和参数。 技能里写的每个工具名、每个参数、每条报错原文，必须来自真实跑过的东西。编一个没验证的参数，轻则技能当场失效，重则误导后续所有会话。

变体拆到 references。 一个技能支持好几种情况时，正文只留主流程和选择指引，每种变体的操作细节拆成独立参考文件按需加载——这才是三级渐进披露的用武之地。

写完不等于能用。在 CodeArts 里注册：往 UserSkillStatus.txt 加一行「名字=true」，不注册就是废的；再跑官方校验脚本；脚本类技能还得拿样本数据真实运行一次，调用工具类的把工具名和参数逐个核对。这步我也栽过：写完没跑校验，上线才发现 frontmatter 缺版本号。

放一份我自己踩出来的失败模式清单，当反面教材：

1. description 写太泛（比如「处理各种文档」）——这种描述要么啥事都触发，要么啥事都不触发
2. 触发条件写在正文里而不是 description
3. 焦点太大，把技能写成了百科全书——一个技能只干一件具体的事
4. SKILL.md 里引用了根本没创建的文件
5. 忘了注册，文件躺在磁盘上但从没生效
6. 涉及 PowerShell 的引用文本用了英文双引号，直接 ParserError

定完这份规范，我再造技能基本是流水线了：一句话说清做什么 → 收集几个真实使用场景 → 列出要固化的脚本和参考文件 → 批准后开写 → 校验 → 真实跑一遍。看着繁琐，但至少不用再为同一个坑改第三遍。