VibeCoding 帮我验证了"会议纪要整理"这个想法，但要把它做成正式版，我还是得手写——因为要复用公司已有的纪要服务，还要在端侧读写文件。这一篇讲手写 Skill 要碰的那些实在东西。

一、什么时候必须手写

我的判断是三种情况：能力要深度调端侧（比如读写设备文件、操控应用界面）、要复用已有业务接口、逻辑复杂到生成出来的代码不稳。这三条里命中任何一条，手写都比生成靠谱。

反过来说，如果你的能力就是"拿一段文本、处理一下、返回结果"这种标准形态，真没必要手写——生成更快，而且不容易写错格式。

二、工程结构：一个目录，两个必选文件

按官方规范，一个 Skill 就是一个目录，必须包含 SKILL.md 和 module.json 两个文件，其余可选：

• SKILL.md：元数据 + 指令，面向 Agent——它就是第 5 篇说的"被发现"的依据；
• module.json：平台配置，面向运行时框架；
• scripts/：脚本文件（可选），Agent 可执行、读取或修改；
• references/：参考文档（可选），Agent 按需读取；
• assets/：静态资源（可选）。

我自己的分法很清楚：SKILL.md 只写"什么时候叫我、怎么叫我"，具体怎么干写在 scripts 里，业务代码放在你自己的工程里。这样分层，后面改业务逻辑不会动到触发契约。

有个硬约束我踩过：目录名必须与 SKILL.md frontmatter 的 name 字段完全一致，也要和 module 配置里的 skillProfiles[].name 对齐。我第一次因为目录名比 name 多了个后缀，校验直接失败，而报错信息指向的是别的地方，排查了半天才找到。现在我做第一件事就是核对这三处名字。

三、SKILL.md 怎么写

它由 YAML frontmatter + Markdown 正文 两部分组成。

frontmatter 里几个字段有硬校验——不过就直接发布失败：

• name：1–64 字符，只允许小写字母 a-z、数字和连字符；不能以连字符开头或结尾，不能出现连续连字符；必须与目录名一致；
• description：最多 1024 字符，是 Agent 初次筛选 Skill 的关键依据，也是语义匹配的原料；
• compatibility：最多 500 字符，说明环境要求（目标产品、系统包、网络访问等）；
• toolName：能力名，要和 module 对齐。

正文部分按"触发场景 → 能力契约"来写：触发场景列典型话术和不调用的情况（第 5 篇讲过），能力契约说清输入参数、返回结果、以及这件事有什么规矩。

规范里还区分了两种校验：硬校验（字符数、行数）不过就发布失败；软校验（Token 预算）不通过应该修正，除非你有充分理由。我的做法是硬校验项一开始就按上限的七成写，给后续修改留余地—— description 写满 1024 字符，后面想加一句都加不进去。

四、ArkTS 入口脚本只做"参数适配器"

这一点是我吃过亏之后养成的习惯：入口脚本不承载业务逻辑。

它的定位是参数适配器——读取系统注入的参数、做校验、调用你既有的业务接口，然后把业务返回值和运行时异常，分别映射到 SKILL.md 里声明的不同结果分支。

我第一次写的时候图省事，把纪要的处理逻辑直接写在了入口脚本里。后来要复用到另一个场景，发现逻辑和入口的校验、异常映射全缠在一起，拆不动，只能重写一遍。

现在的分法是：业务逻辑放在你自己的业务层，Skill 层只做适配。好处有两个——同一个业务能力换个触发场景就能复用；出问题时你能一眼分清是"匹配错了"还是"业务挂了"。

五、权限与随包发布

要调系统能力，就得在 module 配置里声明对应权限，按第 9 篇要讲的最小必要原则申请——不是必须的权限别要，多要一个就多一道审核风险，也多一分用户不信任。

手写 Skill 是随应用包发布的，所以它绕不开第 2 篇那个硬前置：必须关联一个已经在 AppGallery Connect 上架的应用。这也是为什么我在第 2 篇就让你第一天去建应用——它和 Skill 是同一条链上的前后端。

打包之后不要急着提审，先在真机上跑一遍。下一篇就讲调试——网页调试和真机预览怎么配合，以及我第一次真机调试踩的那个坑。