如果你正在给AI代理写一堆散落的函数或者每次换任务都要改提示词那这套 OpenClaw Skills 的技能体系应该能帮你省下不少周末。OpenClaw Skills 本质上是一个让代理按需调用外部能力的小框架每个技能是一个独立目录声明自己能做什么、输入参数长什么样、输出格式是什么然后由调度器统一管理。它不是什么重型的微服务框架更像给代理装上一套可随时插拔的“工具卡”。我在两个内部项目里用了它之后最大的感受是编写单个技能并不难难的是把大家都在用的约定提前想清楚。1. 为什么我决定给AI代理建立一套技能体系1.1 从一次“提示词失控”说起我手头有个自动化项目一开始只是让代理做三件事整理文档、查天气、发通知。提示词里塞了十几个if分支一开始跑得挺欢。后来需求增加要加一个“批量重命名文件”提示词开始失控代理一会儿把重命名理解成移动文件一会儿又把路径参数传错。问题不在模型本身而是所有功能都混在一段提示词里模型缺少结构化的“能力地图”。这个经历很典型。很多人在做AI代理的时候都从“一段超大提示词”开始初期很爽但功能一多就崩。OpenClaw Skills 的出现就是我当时的解药把每个能力抽成独立技能模块用元数据描述它代理只需要理解“有哪些技能各自干什么”而不用把每个细节都背在提示词里。1.2 技能、工具、插件的边界这里需要先厘清概念。OpenClaw Skills 里的“技能Skill”不是操作系统级插件也不是传统软件的宏命令而是一个有明确输入输出契约的可调用单元。举个生活类比它更像抽屉里的螺丝刀套装而不是一把固定在墙上的电动工具。工具Tool更偏向单个函数比如“获取当前时间”。插件Plugin往往包含一组功能和UI集成。技能Skill则是面向任务封装的可以串联多个工具或函数也可以只做一件事。这样区分的好处是代理选择技能时可以根据任务意图进行匹配而不是在几百个函数里大海捞针。OpenClaw Skills 把技能设计成最小可复用单位你可以单独使用“重命名文件”也可以组合“先扫描文件夹再按规则重命名最后生成报告”组合逻辑写在代理侧的“编排策略”里技能本身不需要知道搭档是谁。1.3 它到底解决了什么核心解决三件事可发现性、可复用性、可容错性。可发现性就是代理能通过技能清单知道有什么可复用性是同一技能可以被不同任务调用可容错性则是在技能内部定义清晰的错误返回格式让代理不至于一失败就装死。这三点听起来简单但真正落地的时候每条背后都有一堆细节。比如可发现性你不仅要写描述还要写参数示例不然模型会忽略掉技能。我见过有人辛辛苦苦写了十几个技能结果代理一个也不用原因就是技能描述写得太含糊代理根本判断不出这个技能是干嘛的。把“用于处理文件”改成“当用户要求按序号批量重命名文件时使用不适用于移动文件或修改文件内容”之后调用率立刻上来了。这种“说明书式”的描述才是代理真正需要的。2. 核心设计拆解让技能像积木一样可拼装2.1 一个技能长什么样清单实现可选依赖一个 OpenClaw Skill 的目录结构可以约定为my-skill/ ├── manifest.json # 技能清单 ├── code.py # 技能实现 └── requirements.txt # 可选依赖这就是三个核心文件。manifest.json放在最前面是为了让调度器不需要加载代码就能了解技能code.py负责真正干活requirements.txt是给运行环境装依赖用的。为什么用独立目录而不是把技能写死在代码里因为在 OpenClaw Skills 的设计里技能目录是“一等公民”它可以被复制、压缩、发送给别人的代理。某次我在一个项目里直接从同事那边拷了一个“图片压缩”技能目录解压后装依赖、注册五分钟就跑了完全不用改代码。这种“目录即技能”的体验是传统函数库很难给的。2.2 输入与输出约定大于配置技能的输入输出定义是整套体系的灵魂。OpenClaw Skills 规定每个技能必须声明一个 JSON Schema 格式的输入参数以及一个固定的输出结构。为什么是 JSON Schema因为它是业界标准工具生态成熟可以自动生成校验逻辑和文档。更重要的是模型对 JSON Schema 的理解能力很强喂给代理的参数示例越具体它的调用准确率越高。比如“批量重命名”技能的输入定义大致是{ type: object, properties: { dir: {type: string, description: 目标目录如 /tmp/files}, pattern: {type: string, description: 新文件名模板支持 {index} 占位符}, dry_run: {type: boolean, description: 只打印结果不实际改名} }, required: [dir, pattern] }这里有一个很容易忽略的点dry_run这种“安全开关”最好做成必须明确传值的布尔类型不要靠默认值。如果你把默认值写成false代理有可能为了省事不传它结果直接改了文件用户连预览都没看到。经验是危险操作要“显式确认”不要“默认关闭”。输出结构同样要固定。我会统一用{ok: true, data: ...}或者{ok: false, error: ...}。这样代理读取结果时只需要判断ok字段不用猜哪个字段是结果。很多新手喜欢自由发挥今天返回success明天返回status代理就被搞晕了。2.3 调度与路由代理怎么找到对的技能调度器的核心逻辑不是什么都管而是维护一个技能注册表并提供两种查找方式按名称精确查找、按语义向量模糊查找。前者适用于代理已经被用户指令明确指向某个技能后者适用于用户自然语言描述需求但没说技能名。实际实现中我会把每个技能的description字段做一次向量化用户指令来的时候算一个 query 向量取 Top-K 候选再让代理从候选里选。这里说个实测数据在某个内部测试里只靠关键字匹配意图识别准确率大概在 74% 左右加上向量检索之后能到 90% 以上。但注意向量检索不是万能的一旦技能描述写得太虚比如“这是一个用于处理文件的技能”模型就会困惑。所以我在项目里定了一条规矩description里必须写清“什么时候该用、什么时候不该用”甚至允许写反例。2.4 安全边界与沙箱不能什么都让模型直接执行技能代码可能是别人的也可能是模型自动生成的所以必须控制权限范围。我的做法是给每个技能定义一个执行身份可以是local普通用户权限、admin需要人工批准或restricted只读操作。再由运行环境负责拦截restricted技能不能写任何文件admin技能在调用前会让用户在接口侧点一下确认。有人觉得这样太麻烦但相信我没有边界的时候你根本不知道一个“整理文件”技能会不会把系统目录当作目标目录给清掉。我建议从第一天就设计好这个机制而不是等出了问题再补。另外我在沙箱里还会限制技能的磁盘访问范围技能只能读自己目录下的临时文件如果要访问外部路径必须由运行时显式授权。这样即使模型被恶意提示词诱导技能也拿不到核心数据。3. 从零写一个 OpenClaw Skill批量文件重命名实战3.1 初始化技能目录先用命令创建目录mkdir -p rename-files cd rename-files然后新建manifest.json。这里不用任何脚手架因为 OpenClaw Skills 的约定本身足够简单。目录名即技能 ID不能有空格推荐用短横线分隔。3.2 写技能实现我把实现写成 Python 脚本接收一个 JSON 格式参数并输出一个 JSON 结果。为了避免模型对“调用什么语言”有困惑OpenClaw Skills 在运行时只要求实现程序暴露一个入口标准输入拿参数标准输出返回结果。# code.py import sys, json, os def run(params): d params[dir] pattern params.get(pattern, {index}) dry_run params.get(dry_run, False) files sorted(os.listdir(d)) changed [] for i, f in enumerate(files, 1): src os.path.join(d, f) if not os.path.isfile(src): continue new_name pattern.replace({index}, str(i).zfill(2)) # 简化保持原扩展名 new_name new_name os.path.splitext(f)[1] dst os.path.join(d, new_name) if dry_run: changed.append({from: f, to: new_name}) else: os.rename(src, dst) changed.append({from: f, to: new_name}) return {ok: True, changed: changed} if __name__ __main__: params json.loads(sys.stdin.read()) try: result run(params) print(json.dumps(result, ensure_asciiFalse)) except Exception as e: print(json.dumps({ok: False, error: str(e)}))这里有个细节输出永远是{ok: true/false, ...}。这是为了让代理读结果时统一判断是否成功。很多技能失败时直接抛异常代理只能看到一行报错完全不知道怎么恢复。用固定的成功/失败标记配合error字段里的具体信息才能让代理做下一步决策。比如目录不存在时os.listdir会抛出异常我的try-except会把错误信息包在error字段里返回。代理看到之后可以自动换个目录再试一次而不是卡死。3.3 写技能清单manifest.json里的字段不多但每个都有讲究{ id: rename-files, version: 0.1.0, title: 批量重命名文件, description: 当用户需要按序号或特定模板批量修改文件名时使用。不要用于移动文件也不要用于修改文件内容。, entry: code.py, input_schema: { type: object, properties: { dir: {type: string, description: 目标目录绝对路径}, pattern: {type: string, description: 模板如 截图-{index}}, dry_run: {type: boolean, description: 是否只预览不执行true 时不会修改文件} }, required: [dir, pattern] }, output_schema: { type: object, properties: { ok: {type: boolean}, changed: {type: array}, error: {type: [string, null]} }, required: [ok] }, permission: local, timeout: 30, tags: [file, rename] }我特别想说一下description和timeout。描述里我特意写了“不要用于移动文件”这就是前面说的反例。模型看到“技能用来重命名”还是不够它可能把mv类的需求也派给这个技能所以我们要主动告诉它边界。timeout设 30 秒是因为这个任务不会太久如果超时代理会收到一个明确的超时错误而不是无限等下去。3.4 本地注册和调试注册到本地 OpenClaw 环境只需要把技能目录放到skills/下面然后执行校验命令。假设 CLI 叫ococ skill validate rename-files这一步会检查 JSON 语法、入口文件是否存在、输入输出 Schema 是否合法。然后运行一个自测echo {dir: /tmp/test, pattern: 文件-{index}, dry_run: true} | oc skill run rename-files我建议dry_run验证一遍确认输出格式符合预期后再关掉dry_run跑一次。这个习惯能节省不少调试时间因为我见过太多人直接对真实文件执行技能结果目录名写错批量改名把文件弄得乱七八糟。3.5 把技能接入代理在代理侧只需要让代理知道技能注册表里有rename-files。OpenClaw Skills 在代理的 System Prompt 中暂存一份技能索引包含每个技能的 ID、描述、参数梗概。等到需要时再加载完整 Schema。这种“先索引、后详情”的延迟加载策略可以避免提示词被所有技能细节撑爆。我自己在项目里的做法是把技能索引描述控制在每条 20 字左右然后让代理在需要时通过内部函数get_skill_detail拿完整 Schema。这样即使注册了上百个技能提示词也依然精简。4. 避坑指南我踩过的6个真实问题4.1 问题速查表这里把常见问题先列出来问题表现可能原因解决办法代理总是选错技能描述太模糊或没有反例重写 description加“不要用于”参数老是传错JSON Schema 缺少示例在 properties 里增加example字段技能运行超时任务规模超出预期设置合理 timeout 并在内部做进度上报共享状态被并发调用污染技能代码使用了全局变量每个请求初始化独立上下文技能返回了失败但代理不处理ok: false后没有建议信息错误信息里给出可操作建议依赖安装失败requirements.txt 版本锁太死放宽版本范围或用最小编号4.2 参数描述太模糊模型总是猜错这个问题的根源是模型不是通过阅读类型定义来理解参数而是通过描述和示例。你只在 schema 里写dir: string是不够的一定要加一个example字段。比如example: /home/user/docs。我在一次测试里发现加了示例后参数填对的比例从 77% 跳到了 94%。这背后的逻辑很朴素对模型来说一个具体例子比一段抽象描述更有价值。就像你让一个人去“买水果”不如说“买两个苹果”效果好。所以写技能的时候把示例参数当成一等公民来对待而不是附注。4.3 技能之间共享状态导致结果漂移我早期在一个数据处理项目里写了一个“全局配置技能”用它去控制后续所有技能的行为。结果发现代理在并发执行多个任务时会出现一个技能改了配置、另一个技能读取到脏数据的情况。后来 OpenClaw Skills 的规范要求每个技能调用都是无状态的要么从输入参数读配置要么显式声明一个上下文对象并在调用链里传递。无状态设计一开始会觉得麻烦但它能避免 80% 的并发和重试问题。技能之间不要偷偷搞共享内存如果一定要共享请通过输入输出传递。这和函数式编程的“纯函数”是同一个道理。每次调用技能时把需要保留的信息作为返回值的一部分带出去下一次调用再作为参数传进来这样整个执行路径都是可追踪的。4.4 长任务没有心跳直接失联有一次我写了个“批量压缩图片”技能处理几千张图片可能要五分钟。结果代理调用后技能进程还在跑但代理那边已经因为超过 timeout 判定失败于是又发起一次重试导致同一批图片被压了两次。这是个典型的“任务超时”场景。解决思路有 3 个一是把大任务拆成多个小批次的技能调用二是在技能内部实现在处理完每张图片后输出一条进度 JSON三是回调推送。我在 OpenClaw Skills 里用的组合方案是把技能设计成“启动异步任务 单独查询进度”两个技能。启动技能返回一个 task_id进度查询技能拿到 task_id 后返回当前状态。这样代理可以轮询而不是干等。4.5 测试时只跑“快乐路径”我发现很多开发者测试技能时只输入正常参数看到返回正确就宣布完成。但代理的真实调用里输入可能千奇百怪目录不存在、权限不足、文件名非法、路径有中文。每个情况都应该在代码里显式处理并返回ok: false加 error 信息。我给自己的技能定了个最低测试标准至少测三种失败场景。一是缺参数二是路径不存在三是有文件被占用。这样代理收到失败后能基于 error 信息做一次“自我修复”比如改路径、换目录而不是直接放弃。4.6 一点心得先写 fail-fast再写功能最后分享一个写 OpenClaw Skill 的私人习惯先写参数校验再写业务逻辑。我会在run函数最前面做一串断言每个输入参数都检查类型和范围。一旦不满足立刻返回{ok: false, error: ...}。这样做的好处是代理能从错误信息里提前知道问题而不是等程序深陷某个循环后崩溃。代码风格上也会更清晰。因为我发现如果先把业务逻辑写出来最后补校验往往会漏掉一些边界条件。反过来先写校验run 函数的业务部分就默认入参是合法的可以大胆往下写。这种 fail-fast 的习惯配合前面说的示例参数和反例描述我用了几个月代理的稳定性和可排查性都提升了一个档次。以前我遇到问题要翻日志现在只要看技能返回的 error 字段就能定位是哪一步出了错。如果让我给刚接触 OpenClaw Skills 的人一个建议那就是别急着堆技能数量先把一个技能从清单、Schema、错误处理到反例描述全部打磨到位再复制这个套路去写下一个。数量解决不了混乱规范才能。
