一份写得好的SKILL.md，能让一个普通的大模型瞬间变成某个领域的专家，而一份写得差的SKILL.md，即使是最强大的模型也会变得笨拙不堪。这不是夸张，而是无数开发者在实践中得出的结论。OpenClaw的核心设计哲学就是一切皆文本，所有的能力都通过纯文本的方式定义，这意味着你写的每一个字，都会直接影响到技能的表现。很多开发者把大量时间花在编写脚本和调试接口上，却忽略了SKILL.md这个最关键的文件，结果就是技能要么触发不准确，要么执行效果差强人意。
SKILL.md不是一份简单的说明书，它是大模型理解这个技能的唯一窗口。大模型没有常识，也没有直觉，它只能严格按照你写的内容去执行。你写得越模糊，它的表现就越不可预测；你写得越具体，它的表现就越稳定。这就像是给一个非常聪明但完全没有经验的实习生写工作指南，你需要把每一个步骤都讲清楚，把每一个边界都划明白，把每一个可能遇到的问题都提前想到。只有这样，这个实习生才能真正帮你分担工作，而不是给你制造更多的麻烦。元数据部分是SKILL.md的灵魂，也是最容易被忽视的部分。很多开发者只是随便填一下名称和描述，就开始写正文了，这是一个致命的错误。元数据决定了技能什么时候会被触发，以及它能在什么样的环境下运行。如果元数据写得不好，技能可能永远不会被调用，或者在不应该被调用的时候被调用，甚至在运行的时候因为缺少依赖而失败。元数据的每一个字段都有其深刻的设计意图，理解这些意图，才能写出真正高质量的元数据。
名称字段不仅仅是一个标识符，它还是大模型理解技能功能的第一个线索。名称应该用动词开头，清晰地描述技能的核心动作，而不是用一个模糊的名词。比如，一个处理PDF的技能，不应该叫"pdf工具"，而应该叫"处理PDF文档"。这样的名称不仅更容易被大模型识别，也更容易被用户理解和记忆。名称应该保持简短，不要超过几个单词，同时要避免使用缩写和专业术语，除非这个术语是这个领域的通用标准。描述字段是元数据中最重要的字段，没有之一。OpenClaw的内核就是通过描述字段来判断什么时候应该调用这个技能。描述字段应该包含两个部分：技能能做什么，以及什么时候应该使用这个技能。很多开发者只写了第一部分，却忽略了第二部分，结果就是技能的触发率非常低。一个好的描述应该是这样的："提取PDF文档中的文本和表格内容。当用户需要从PDF文件中获取信息，或者需要将PDF内容转换为可编辑的文本时使用此技能。"这样的描述清晰地告诉了大模型，在什么样的场景下应该调用这个技能。
版本字段虽然看起来简单，但它是技能生命周期管理的基础。版本号应该遵循语义化版本控制的规则，主版本号表示不兼容的变更，次版本号表示向后兼容的功能新增，修订号表示向后兼容的问题修复。每次更新技能的时候，都应该更新版本号，并且记录变更内容。这样不仅方便用户了解版本差异，也方便开发者自己管理技能的不同版本。如果没有版本号，当技能出现问题的时候，你根本不知道用户使用的是哪个版本，也就无法进行有效的排查和修复。依赖声明是元数据中最容易出错的部分。很多开发者会忘记声明技能需要的二进制文件和环境变量，结果就是技能在自己的电脑上能运行，在别人的电脑上就运行不了。依赖声明应该尽可能地完整和准确，包括所有需要的命令行工具、编程语言运行时和第三方库。如果有多个可选的依赖，可以使用anyBins字段来声明，只要其中一个存在，技能就可以运行。同时，还应该提供详细的安装说明，告诉用户如何安装这些依赖，这样可以大大降低用户的使用门槛。
操作系统字段用来声明技能支持的操作系统。不同的操作系统有不同的命令行工具和文件系统结构，一个在Linux上能运行的技能，可能在Windows上就运行不了。如果你的技能只支持特定的操作系统，一定要在元数据中明确声明，这样OpenClaw就不会在不支持的系统上加载这个技能。如果你的技能是跨平台的，也应该明确声明，这样可以让更多的用户使用你的技能。
表情符号字段虽然是可选的，但它可以大大提升技能的用户体验。一个合适的表情符号可以让技能在列表中更容易被识别，也可以让技能看起来更加友好和生动。表情符号应该和技能的功能相关，比如一个处理图片的技能可以用相机表情，一个处理文档的技能可以用文件表情。不要使用过于复杂或者不常见的表情符号，以免在某些设备上无法正常显示。
正文部分是SKILL.md的主体，它详细描述了技能的使用方法和执行步骤。正文的编写应该遵循渐进式披露的原则，也就是把信息按照重要性和使用频率分成不同的层次，大模型只会在需要的时候才会加载相应层次的信息。这样不仅可以节省token，还可以提高大模型的处理效率。渐进式披露的核心思想是，不要把所有的信息都一次性塞给大模型，而是让它在需要的时候自己去查找。正文的开头应该是一个简短的概述，介绍技能的主要功能和使用场景。这个概述应该和元数据中的描述字段保持一致，但可以更加详细一些。概述的目的是让大模型在调用技能之前，对技能有一个全面的了解。概述之后，应该是详细的使用说明，包括技能的输入参数、输出格式和执行步骤。使用说明应该尽可能地具体和清晰，每一个步骤都应该有明确的动作和预期结果。
执行步骤是正文的核心部分，它告诉大模型应该如何完成这个任务。执行步骤应该按照逻辑顺序排列，从输入解析开始，到数据处理，再到结果输出。每一个步骤都应该是一个独立的动作，不要把多个动作合并到一个步骤里。同时，还应该考虑到各种可能的异常情况，告诉大模型在遇到这些情况的时候应该如何处理。比如，如果输入的文件不存在，应该返回什么样的错误信息；如果API调用失败，应该如何重试。示例是正文部分非常重要的一个组成部分。示例可以帮助大模型更好地理解技能的使用方法和输出格式。示例应该尽可能地真实和具体，覆盖常见的使用场景和边界情况。每个示例都应该包含输入和输出两部分，输入应该是用户可能会说的话，输出应该是技能应该返回的结果。示例不要太复杂，也不要太简单，应该能够准确地反映技能的实际使用情况。
边界情况是很多开发者容易忽略的部分，但它却是决定技能稳定性的关键。边界情况包括输入为空、输入格式错误、依赖缺失、网络超时等等。在编写SKILL.md的时候，应该尽可能地考虑到所有可能的边界情况，并且告诉大模型在遇到这些情况的时候应该如何处理。如果没有处理边界情况，当用户输入一个异常值的时候，技能可能会崩溃，或者返回一个毫无意义的结果，这会严重影响用户体验。输出格式是正文部分另一个非常重要的组成部分。输出格式应该统一和规范，这样不仅方便用户阅读，也方便其他技能调用这个技能的输出。输出应该使用自然语言，避免使用技术术语和专业符号，除非用户明确要求。同时，输出应该尽可能地简洁和清晰，只包含用户需要的信息，不要包含多余的内容。如果输出的内容比较多，可以使用列表或者表格的形式来组织，这样可以让输出更加易读。
技能之间的联动是OpenClaw最强大的功能之一。通过技能联动，你可以把多个简单的技能组合成一个复杂的工作流。在编写SKILL.md的时候，应该考虑到技能的可组合性，让技能的输出可以被其他技能轻松地使用。同时，还应该在正文中说明这个技能可以和哪些其他技能一起使用，以及如何一起使用。这样可以大大提升技能的价值，也可以让用户发现更多的使用场景。测试是技能开发过程中不可或缺的一部分。在发布技能之前，应该进行充分的测试，确保技能在各种情况下都能正常运行。测试不仅要测试正常的使用场景，还要测试边界情况和异常情况。同时，还应该测试技能的触发准确性，确保技能在应该被调用的时候被调用，在不应该被调用的时候不被调用。如果发现问题，应该及时修改SKILL.md，直到技能的表现符合预期。
文档的维护是一个长期的过程。技能发布之后，并不意味着工作就结束了。随着用户的使用，你会收到各种各样的反馈，发现各种各样的问题。你需要根据这些反馈和问题，不断地更新和完善SKILL.md。同时，随着OpenClaw版本的更新，可能会有一些新的特性和变化，你也需要及时更新技能，以适应这些变化。一个好的技能，是需要不断地迭代和优化的。很多开发者在编写SKILL.md的时候，会犯一个常见的错误，就是把它写得像一份技术文档，充满了专业术语和复杂的句子。大模型虽然很聪明，但它更喜欢简单、清晰、直接的语言。在编写SKILL.md的时候，应该使用简单的词汇和短句，避免使用复杂的语法和长句。同时，应该避免使用模糊和歧义的词语，比如"可能"、"大概"、"也许"等等。每一句话都应该有明确的含义，让大模型没有任何误解的余地。
另一个常见的错误是，在SKILL.md中包含了太多的信息。很多开发者觉得，写得越多，大模型就越能理解这个技能。但实际上，信息越多，大模型就越容易混淆，反而会影响技能的表现。正确的做法是，只包含必要的信息，多余的信息应该放到单独的文件中，通过链接的方式引用。这样不仅可以让SKILL.md更加简洁，也可以让大模型更加专注于核心的内容。还有一个常见的错误是，盲目地复制和粘贴网上的模板。很多开发者看到别人的技能写得好，就直接把别人的SKILL.md复制过来，改一改名称和描述就发布了。但每个技能都有自己的特点和使用场景，别人的模板不一定适合你的技能。正确的做法是，先理解SKILL.md的编写原则和底层逻辑，然后根据自己的技能的特点，编写适合自己的SKILL.md。只有这样，才能写出真正高质量的技能文档。
编写高质量的SKILL.md，需要的不仅仅是技术能力，还需要对大模型的工作原理有深刻的理解。你需要知道大模型是如何理解文本的，是如何做出决策的，是如何执行任务的。只有这样，你才能写出大模型能够真正理解和执行的文档。同时，还需要有耐心和细心，不断地测试和优化，直到技能的表现达到最佳状态。OpenClaw的技能生态正在快速发展，越来越多的开发者加入到了技能开发的行列中来。但真正能够写出高质量SKILL.md的开发者并不多。很多开发者只是停留在表面，没有深入理解SKILL.md的本质和编写技巧。如果你能够掌握SKILL.md的编写艺术，你就能够在这个生态中脱颖而出，创造出真正有价值的技能。
