从0到1写出高质量Skill，先设计触发，再设计流程

从0到1写出高质量Skill，先设计触发，再设计流程从0到1写出高质量Skill，先设计触发，再设计流程 Modified May 30 能用脚本解决的，就别让模型硬想写Skill时，还有一个分水岭。有些事情适合写进Markdown，让Agent理解原则。有些事情更适合放进 scripts ，让代码稳定执行。比如统计字数、扫描目录、校验JSON、转换文件格式、生成图表、检查链接。这些任务交给模型做，既浪费上下文，也容易出错。放进脚本以后，Skill只需要告诉Agent什么时候运行、如何解释结果、失败时怎么处理。这也是跨平台Skill的关键。 Claude Code和Codex支持的工具名、权限模型、路径习惯并不完全一样。如果你在正文里写死某个平台的工具名，迁移时就容易断。更稳的写法，是用能力描述来表达需求，把确定性逻辑沉到脚本里。不要写： Code block Plain Text Copy 使用Bash工具检索所有文件，再通过Read工具查看每条检索结果。可以改成： Code block Plain Text Copy 在项目文件中检索匹配的内容模式。若有配套脚本，请在技能目录下运行该脚本，并使用其结构化输出结果。这句话少了平台绑定，多了迁移空间。脚本也不要变成黑盒。一个好脚本至少要做到三点：输入清楚，输出结构化，失败码明确。这样 Agent看到结果以后，不需要猜。对于复杂Skill，我建议用一个很朴素的分工： Markdown负责判断和流程。脚本负责计算和校验。 references负责长资料。 assets负责模板和示例。这样写出来的Skill会更像一个小工具包，而不是一篇长提示词。第一个版本别追求完整，要先跑一次压力场景 Skill的第一个版本，不应该追求完美。它应该能暴露问题。很多人写完Skill以后，只用一个最顺的请求测试。比如帮我写一篇文章、帮我审查代码、帮我整理会议纪要。如果这个请求刚好命中，输出看起来不错，就以为 Skill 成功了。这不够。高质量Skill至少要测三类场景。第一，标准场景。用户说得很清楚，素材齐全，任务边界明确。它用来验证Skill的主流程能不能跑通。第二，缺口场景。用户只给了半截信息，比如没有目标读者、没有文件路径、没有输出格式。它用来验证Agent会不会在缺关键信息时乱猜。第三，诱惑场景。用户催得很急，或者要求跳过验证，或者让Agent直接给结论。它用来验证Skill 的质量门槛能不能顶住压力。一个代码审查Skill，如果只在干净PR上表现好，价值有限。更该测试的场景是：PR很大、测试缺失、用户催着合并时，它还会不会坚持列风险。一个写作Skill，如果只会在完整brief下写得漂亮，也不够。更该测试的场景是：素材碎、热点乱、事实未核验时，它会不会先降级表达，避免把不确定信息写死。这就是我喜欢把Skill当成小型产品来做的原因。写出来只是第一步。能不能在真实压力下不走形，才是它值不值得长期使用的判断。 0到1的最小闭环把上面的东西收束成一个闭环，其实只有六步。第一步，选一个重复任务。不要从我想写一个万能Skill开始。先选一件反复出现、每次都要解释、失败模式稳定的任务。第二步，写任务卡。写清触发、输入、输出、失败信号。任务卡越清楚，后面的 SKILL.md 越不会膨胀。第三步，写 description。把用户可能说的话放前面，把边界写清楚，把不该触发的场景排除掉。description是入口，不是宣传文案。第四步，写最小正文。只写进入条件、工作步骤、质量门槛、退出标准。不要把所有背景知识塞进去，长资料放到references，确定性动作放到scripts。第五步，跑三类测试。标准场景看能不能跑通，缺口场景看会不会乱猜，诱惑场景看能不能守住质量线。第六步，改触发，再改流程。如果Skill没被想起，优先改description。如果被想起但做错，改正文。如果每次都要算同一件事，写脚本。如果资料太长，拆reference。这里有个很反常识的经验：很多Skill失败，不是流程写少了，而是入口写弱了。 Agent先看入口，再决定要不要读正文。入口错，正文再好也没有机会发挥。真正的好Skill，是让Agent少猜如果只能带走一句话，我希望是这句：好Skill的价值，是让Agent少猜。少猜什么时候该用。少猜下一步做什么。少猜什么结果算完成。少猜遇到异常该继续、该降级，还是该停下来问人。 Claude Code、Codex这些智能体越来越像工作环境里的操作系统。Skill则是你给这个系统安装的工作处方。写得好，它会把你的经验变成稳定能力；写得差，它只会变成另一段占上下文的噪音。所以，下次你想从0开始写一个 Skill，别急着打开编辑器。先拿纸写下四句话：它替我重复哪件事。用户会怎么说出这件事。它最后必须交付什么。它在哪些情况下必须停下来。这四句话写明白， SKILL.md 只是落地形式。写不明白，再多规则也救不了它。好 Skill 的价值，是让Agent 少猜。能用脚本解决的，就别让模型硬想写Skill时，还有一个分水岭。有些事情适合写进Markdown，让Agent理解原则。有些事情更适合放进 scripts ，让代码稳定执行。比如统计字数、扫描目录、校验JSON、转换文件格式、生成图表、检查链接。这些任务交给模型做，既浪费上下文，也容易出错。放进脚本以后，Skill只需要告诉Agent什么时候运行、如何解释结果、失败时怎么处理。这也是跨平台Skill的关键。 Claude Code和Codex支持的工具名、权限模型、路径习惯并不完全一样。如果你在正文里写死某个平台的工具名，迁移时就容易断。更稳的写法，是用能力描述来表达需求，把确定性逻辑沉到脚本里。不要写：可以改成：这句话少了平台绑定，多了迁移空间。脚本也不要变成黑盒。一个好脚本至少要做到三点：输入清楚，输出结构化，失败码明确。这样 Agent看到结果以后，不需要猜。对于复杂Skill，我建议用一个很朴素的分工： Markdown负责判断和流程。脚本负责计算和校验。 references负责长资料。 assets负责模板和示例。这样写出来的Skill会更像一个小工具包，而不是一篇长提示词。第一个版本别追求完整，要先跑一次压力场景 Skill的第一个版本，不应该追求完美。它应该能暴露问题。很多人写完Skill以后，只用一个最顺的请求测试。比如帮我写一篇文章、帮我审查代码、帮我整理会议纪要。如果这个请求刚好命中，输出看起来不错，就以为 Skill 成功了。这不够。高质量Skill至少要测三类场景。第一，标准场景。用户说得很清楚，素材齐全，任务边界明确。它用来验证Skill的主流程能不能跑通。第二，缺口场景。用户只给了半截信息，比如没有目标读者、没有文件路径、没有输出格式。它用来验证Agent会不会在缺关键信息时乱猜。第三，诱惑场景。用户催得很急，或者要求跳过验证，或者让Agent直接给结论。它用来验证Skill 的质量门槛能不能顶住压力。一个代码审查Skill，如果只在干净PR上表现好，价值有限。更该测试的场景是：PR很大、测试缺失、用户催着合并时，它还会不会坚持列风险。一个写作Skill，如果只会在完整brief下写得漂亮，也不够。更该测试的场景是：素材碎、热点乱、事实未核验时，它会不会先降级表达，避免把不确定信息写死。这就是我喜欢把Skill当成小型产品来做的原因。写出来只是第一步。能不能在真实压力下不走形，才是它值不值得长期使用的判断。 0到1的最小闭环把上面的东西收束成一个闭环，其实只有六步。第一步，选一个重复任务。不要从我想写一个万能Skill开始。先选一件反复出现、每次都要解释、失败模式稳定的任务。第二步，写任务卡。写清触发、输入、输出、失败信号。任务卡越清楚，后面的 SKILL.md 越不会膨胀。第三步，写 description。把用户可能说的话放前面，把边界写清楚，把不该触发的场景排除掉。description是入口，不是宣传文案。第四步，写最小正文。只写进入条件、工作步骤、质量门槛、退出标准。不要把所有背景知识塞进去，长资料放到references，确定性动作放到scripts。第五步，跑三类测试。标准场景看能不能跑通，缺口场景看会不会乱猜，诱惑场景看能不能守住质量线。第六步，改触发，再改流程。如果Skill没被想起，优先改description。如果被想起但做错，改正文。如果每次都要算同一件事，写脚本。如果资料太长，拆reference。这里有个很反常识的经验：很多Skill失败，不是流程写少了，而是入口写弱了。 Agent先看入口，再决定要不要读正文。入口错，正文再好也没有机会发挥。真正的好Skill，是让Agent少猜如果只能带走一句话，我希望是这句：好Skill的价值，是让Agent少猜。少猜什么时候该用。少猜下一步做什么。少猜什么结果算完成。少猜遇到异常该继续、该降级，还是该停下来问人。 Claude Code、Codex这些智能体越来越像工作环境里的操作系统。Skill则是你给这个系统安装的工作处方。写得好，它会把你的经验变成稳定能力；写得差，它只会变成另一段占上下文的噪音。所以，下次你想从0开始写一个 Skill，别急着打开编辑器。先拿纸写下四句话：它替我重复哪件事。用户会怎么说出这件事。它最后必须交付什么。它在哪些情况下必须停下来。这四句话写明白， SKILL.md 只是落地形式。写不明白，再多规则也救不了它。好 Skill 的价值，是让Agent 少猜。 🔗 原文链接： https://mp.weixin.qq.com/s/81qygaKd... https://mp.weixin.qq.com/s/81qygaKd... 原创三栖有话说三栖有话说三栖有话说2026年5月29日 08:00 四川很多人第一次写Skill，会做一件很自然、也很容易出问题的事。打开 SKILL.md ，开始往里面塞规则。背景写一点，步骤写一堆，注意事项再补十几条。写完以后很有成就感，像是终于把自己的经验封装给了Agent。然后一用，尴尬来了。该触发时没触发，没该触发时乱触发。触发以后读了一大段，还是漏步骤。迁移到另一个Agent 里，原来能跑的命令突然失效。再修几轮，Skill从一页纸长成一份小论文。我的判断是，问题通常不在你写得不够多。问题出在你把Skill当成文档来写了。高质量Skill更像一张工作处方。它要先判断什么症状该用，再告诉Agent做哪几步，最后规定怎样才算完成。对Claude Code、Codex这类智能体来说，Skill的第一价值不是知识量，而是把一件重复任务变成可触发、可执行、可验证的工作流。所以，从0到1写Skill，第一步不是写正文。第一步是设计触发。先问一句，它到底替你重复哪件事 Skill最怕从概念开始。比如我要写一个数据分析Skill、我要写一个写作Skill、我要写一个代码审查Skill。这些说法都太大。Agent看到以后，可能不知道什么时候该用，也不知道用了以后到底要交付什么。一个高质量Skill的起点，应该是一件你已经重复做过多次、并且每次都要反复交代的任务。更好的问题是：我每次都要提醒Agent做哪几步。我每次都要纠正它漏掉什么。我每次都希望它用同一种格式交付什么结果。比如数据分析不是一个好起点。把一份销售CSV清洗、分组、找异常、输出三条业务判断，才是一个可以封装的Skill。写作也不是一个好起点。把一个AI热点整理成公众号长文，并且必须先核验事实、再写正文、最后做质量复审，才像一个工作流。这里有一个很实用的判断标准：如果你无法用一句话说清这个Skill的交付物，它还不该被写成 Skill。因为Agent不缺泛泛的建议，它缺的是稳定的工作路线。Skill 不是知识仓库，也不是提示词收藏夹，它应该解决一种可重复的卡点。我建议先写一张任务卡。这张卡写清楚以后，你再打开SKILL.md 。Claude Code也是类似思路，Skill 的描述会帮助 Claude 判断什么时候应用它。这意味着， description 不是给人类看的简介。它是Agent的分诊台。分诊台不用讲完整治疗方案。它要在几秒钟内判断：这个请求该不该进这个科室。写Skill也是一样，description最重要的任务是让Agent在正确时机想起你。一个常见坏写法是：这句话看起来没错，但对Agent几乎没用。better太空，articles太宽，什么时候触发也不明确。更好的写法应该像这样：这里有三个关键动作。第一，写用户会怎么说。撰写、润色、审核、公众号文章这些词让Agent更容易匹配真实请求。第二，写适用边界。AI产品、研究、工具、行业趋势，是这个Skill的领地。第三，写不该触发的场景。短社交帖和闲聊不该进来，能减少误触发。 Codex官方文档还提醒了一点：当Skill很多时，描述可能被缩短，所以关键用例和触发词要放在前面。也就是说，description的前半截必须能独立工作。这就是高质量Skill的第一道门槛：读完description，Agent应该知道三件事。何时用，何时不用，用它要交付什么。正文只写Agent不知道、但必须遵守的事很多Skill变臃肿，是因为作者不信任模型。于是把每一步都写得很细，把每个常识都解释一遍，把每个可能性都预先塞进去。结果是，Agent读到一份看似完整、实际很难抓重点的说明书。高质量Skill的正文应该克制。默认Agent已经会读文件、会调用工具、会总结、会写Markdown。你只需要补它不知道、但这项任务必须遵守的东西。我会把正文拆成四块。第一块，进入条件。告诉Agent开始前要确认什么。例如是否有输入素材，是否需要读取指定文件，是否需要先问用户补充信息。进入条件的价值，是防止Agent 一上来就写。第二块，工作步骤。步骤不要写成百科目录，而要写成可执行路线。比如先核验事实，再确定主张，再生成正文，再做复审。每一步都要有产物，不要只写分析一下、优化一下、检查一下。第三块，质量门槛。这是Skill和普通提示词的差别。普通提示词经常只告诉Agent做什么，Skill 要告诉它做到什么程度才算过关。比如无事实错误、输出包含引用、必须运行测试、必须列出风险、必须保留用户原有意图。第四块，退出标准。 Agent很容易完成一个看起来像结果的东西，然后停下。退出标准要告诉它最后必须交付什么：文件路径、摘要、测试结果、失败原因，还是下一步建议。一个最小骨架可以这样写：这份骨架不炫，但很稳。它把Agent从会做，大幅推进到会收尾。