Skill 写给模型：少占上下文，把易错步骤收成脚本
一份给人看很完整的 Skill，模型经常用不好。来历、版本记录和「专业、全面、注意平衡」都在占上下文，却没有告诉它这次该不该被选中，也没有告诉它哪一步不能写错。
上一篇写的是 Skill 和业务文档、工具定义怎么分工，以及怎样验收「选中了」和「做完了」。这篇只写怎么把一份 Skill 写短、写准。框架来自 hello-agents 的 Extra08，下面是我按这个框架实际取舍时用的规则。
读者是一次新的模型调用
Skill 是一个目录。最少只有 SKILL.md：frontmatter 里的 name 和 description，加上正文。对话开始时，模型只看到名称和描述。描述对上了，才读正文。正文里写的「什么时候使用」，在决定要不要用它的那一刻还没被读到。
所以 description 要同时写两件事：做什么，以及用户会怎么说。例如不是「代码审查技能」，而是「在用户要求审查 diff、查找缺陷或评估改动风险时使用」。文件类型和动作写进描述：新建、修改、批注、导出。
给人看的文件不要放进这个目录。README.md、安装说明、变更日志、测试过程，都是写给下一次打开仓库的人的。模型每次都是重新开始，这些背景不会帮它做对当前任务。
上下文是和别的东西挤在一起的
系统提示、历史、其他 Skill 的名称和描述、用户这次的请求，占的是同一扇窗口。Skill 默认模型已经会写代码、会读报错。只补它没有的信息：这个仓库的目录约定、这个格式里容易写错的字段、必须按顺序执行的命令。
动笔前先问两句。模型是不是本来就知道？这段话值不值得占掉后面的工具结果？能用一个短例子说清的，不要写成一节原则。正文保持在它被触发之后还读得完的长度。细节放到 references/，用到再打开。
「不做什么」通常比「要专业、要有洞察」精确。后面这些词留下的都是可做可不做的空间。禁止项要能检查，并且带上改法：不要在开头用三行重复任务背景；发现缺输入时先问，不要补一组假设继续做。写完可以反过来看：如果一句正面要求能改成「不要做 X」，改完往往更不容易跑偏。
正文用祈使句。写「先读 diff，再列缺陷」，不写「建议可以考虑先了解一下变更」。
三层，不要互相抄
| 层 | 放什么 | 什么时候进上下文 |
|---|---|---|
| 名称和 description | 做什么、用户哪句话该触发 | 每次对话都在 |
SKILL.md 正文 |
步骤、分流、资源放在哪 | 触发之后 |
scripts/、references/、assets/ |
要执行的程序、要查阅的资料、要原样放进产物的模板 | 用到才碰 |
描述写错，Skill 不会被选中，或者不该用的时候被选中。正文写得太长，步骤会被后面的细节盖住。脚本可以执行而不必把源码读进上下文，适合那些做错的方式很多、做对的方式只有一种的操作。
同一段话只放一处。正文里已经有的步骤，不要在 references/ 再贴一遍。参考文件从 SKILL.md 直接链接，不要 A 指向 B、B 再指向 C。超过大约一百行的参考文件，开头放目录。大文件在正文里写明用什么关键词去搜，而不是让模型整篇读完。
assets/ 里的模板、图片、样板代码不是给模型学习的。正文只写路径，以及在哪一步把它们放进输出。
agents/openai.yaml 是界面上的名字、短说明和图标，不改变模型怎么执行。短说明有长度限制，手写容易超。用生成脚本从 frontmatter 产出，SKILL.md 改了就重新生成，不要两处各改各的。
自由度按「做错的代价」来给
多种做法都成立，用文字写启发式。有推荐做法但允许变通，用伪代码或带参数的脚本。顺序固定、格式或长度不能错，就给一个少参数的脚本，让模型填参数而不是重写过程。
写 Skill 本身就是这个光谱。弄清要支持哪些说法、正文怎么组织，自由度高。目录名必须是小写连字符、frontmatter 只能有约定好的字段、短说明必须落在长度范围内，自由度低。让模型手写界面配置，短说明会超长，大小写也不稳。反过来，把每一段的开头和用词都锁死，创作就变成填空。可以规定结构比例，不要规定句子。
适合收成脚本的是：每次结果必须相同的转换、命名规则、格式和长度校验，以及否则就要在正文里反复重写的那段代码。适合留成文字的是：依赖这次上下文、有不止一种合理做法、需要判断取舍的步骤。
skill-creator 把低自由度收成三个脚本，这个分法可以直接照用。init_skill.py 建立目录和带 TODO 的模板，避免从空文件开始漏掉 frontmatter。generate_openai_yaml.py 从名称生成界面文案，并把短说明压进允许的长度。quick_validate.py 检查文件在不在、YAML 能不能解析、name 是不是连字符形式、description 有没有尖括号、frontmatter 有没有多出字段。中间怎么写步骤，留给模型。起点和终点用脚本卡住。
六步，中间可以返工
- 先对齐例子。这个 Skill 要接住哪些说法，不要接住哪些。一次不要问太多。范围说清再往下。
- 把例子里会反复出现的东西列成清单。旋转 PDF 这种操作进
scripts/。每次都要查的表结构进references/。会原样进产物的样板进assets/。 - 新建时跑初始化脚本，不要手搭目录。模板里的 TODO 是留给这次任务填的，示例文件用完就换掉或删掉。
- 先把脚本跑通，再写正文。正文写过程、领域里模型不知道的细节、以及每份资源在哪一步用。不写它显而易见的常识。
- 跑校验。不过就改，改完再跑。
- 拿到真实任务上用。卡住的地方改正文或改资源，再试一次。第一次写完的短说明如果还是「一个有用的技能」，就改成用户能说出口的那件具体的事。
名称用小写、数字和连字符，和目录名一致，优先短的动作短语。需要和某个工具绑在一起时，把工具名放进前缀，例如 gh-address-comments。
Skill 不是把一份人类文档搬进 SKILL.md。它是在一次有限的上下文里，告诉模型何时上场、按什么步骤做、哪些步骤不许自由发挥。