最近在折腾 AI Agent 相关的东西发现很多人在问同一个问题OpenClaw 装好了Agent 也能跑了但总感觉它“啥都不会”——让它写个前端页面只会给你搭个空架子让它做数据分析只会调个describe()。说白了Agent 本身只是个大脑空转的引擎真正让它干活的是 Skills。我一开始也踩了这个坑后来把 OpenClaw 的 Skills 机制彻底啃了一遍自己手写了几个技能又折腾了第三方技能库这才算是把 Agent 从“能聊天”变成了“能干活”。这篇文章就是我这段经验的完整复盘从 Skills 的核心原理、SKILL.md 怎么写、开发到安装的全流程再到我踩过的几个典型报错一次性讲透。这篇文章适合两类人看一是刚装好 OpenClaw 但不知道怎么让 Agent 干实际活儿的新手二是已经在用其他 Agent 工具Claude Code、Codex 这类想迁移技能开发经验的人。我会尽量说人话能给你直接抄作业的地方绝不绕弯子。1. 先想清楚Skills 到底在解决什么问题1.1 Agent 的“外挂大脑”从通用对话到专用能力每个 AI Agent 在刚装好的时候本质上都是一个“什么都会一点但什么都不精”的通用模型。你让它写 Python 它能写但如果你希望它写完代码之后自动跑测试、根据覆盖率报告决定要不要继续改它就懵了——不是模型不行而是模型缺少一套明确的操作流程和领域规则。Skills 解决的就是这个问题。它的核心思路是把某个特定领域的操作流程、判断标准、命令调用方式封装成一个 Markdown 格式的技能包Agent 在遇到对应任务时会把这个技能包的内容注入到对话上下文里然后按照技能包里的指令一步步执行。我自己的理解是Skills 相当于给 Agent 一本“操作手册”。模型本身还是那个模型但有了这本手册它就知道该按什么顺序执行命令、该读哪些文件、该用什么标准判断结果。这跟人类干活是一个道理——一个刚毕业的实习生不是不聪明他是没有把活干好的流程和标准你给他一本 SOP他立刻就能上手。1.2 OpenClaw 的技能加载机制描述匹配与上下文注入OpenClaw 的技能加载机制最关键的环节是“描述匹配”。每个技能包的 SKILL.md 文件里有一段 YAML 格式的 frontmatter其中description字段就是 Agent 判断“该用哪个技能”的依据。当用户提出一个任务时OpenClaw 会把这个任务的内容和所有已安装技能的description做语义匹配。匹配度高的技能会被加载进上下文然后 Agent 开始按技能正文里的指示执行。这也就解释了一个很常见的现象为什么有些技能装上了就没反应十有八九是description写得太笼统或者主题对不上Agent 根本不知道什么时候该调用它。另外要注意OpenClaw 的匹配机制不是简单的关键词匹配而是基于语义的相似度计算。这意味着你不需要在 description 里堆砌大量关键词但你必须把技能的应用场景描述清楚。比如你写“用于处理 CSV 文件”那 Agent 只有在你明确提到 CSV 时才会想到这个技能但你写“当用户需要对表格数据做清洗、格式转换或统计分析时使用”Agent 在遇到各种数据相关任务时都能联想到它。1.3 为什么不用插件或脚本Skills 的设计取舍有的朋友可能会问既然 Skills 能让 Agent 干活那我直接用 Python 脚本包装不行吗我自己也纠结过这个问题但实际对比下来Skills 的优势还是很明确的。脚本解决的是“固定逻辑自动执行”它的问题在于 Agent 不知道“什么时候该调这个脚本”。你得在对话里明确告诉它或者用一套复杂的命令路由机制去触发。Skills 则是“带触发条件的动态指令集”Agent 根据对话内容语义判断该不该用、怎么用而且技能包可以随时增删改不用重启服务。当然Skills 不是万能的。它擅长的是“指导 Agent 如何操作”而不是“替 Agent 完成计算”。如果你的需求是高度确定性的数据处理流程那直接用脚本挂个 API 更高效如果你的需求是让 Agent 在复杂对话场景中自主判断该怎么做那 Skills 是最合适的载体。我自己目前的项目里两者是配合使用的——脚本负责具体执行Skills 负责组织这些脚本的调用顺序和判断条件。2. 开发一个 Skill 的完整规范SKILL.md 拆解2.1 SKILL.md 的结构frontmatter 正文指令一个 Skill 就是一个目录目录的核心是一个名为SKILL.md的 Markdown 文件。这个文件的结构非常清晰分为两大部分YAML frontmatter 和正文指令块。先看 frontmatter它负责描述技能的基本信息。最少需要包含name和description两个字段比如--- name: frontend-design-review description: 当用户需要对前端页面进行设计评审、发现布局或视觉问题时使用。可分析页面截图或 HTML 代码输出具体的修改建议。 ---name是技能的唯一标识建议用短横线连接的小写英文单词不要用空格或中文。description是技能的灵魂我会在后面的小节里专门展开讲怎么写好它。正文部分才是真正的“干货”是 Agent 执行任务时遵循的指令。这里没有严格的语法限制你可以用自然的 Markdown 语言描述步骤、规则和示例。但为了让 Agent 执行得更准确有几个实用建议用有序列表写明操作步骤、用代码块给出期望的输出格式、用引用块标注需要特别注意的坑。我还见过一些复杂的技能包除了 SKILL.md 之外还会带一个assets或scripts子目录里面放着参考图片、模板文件或辅助脚本。OpenClaw 加载技能的时候会把整个目录打包进上下文所以这些附属文件也是可以被 Agent 读取和引用的。2.2 描述怎么写才不被“误调用”我踩过最狠的坑就是 description 写得太泛。最早我写了一个“网页开发助手”description 是“当用户需要前端开发帮助时使用”结果就是所有稍微沾点前端边的问题都会触发它有时候用户只是问个概念它也跑出来要改代码整个对话体验非常割裂。后来我总结了一套 description 的写法公式触发条件 功能概括 典型场景 预期输出。四要素最好都写上尤其是触发条件要尽量具体。比如“当用户提供了一个设计稿截图或一段 HTML/CSS 代码并希望优化页面视觉效果时使用。该技能会分析现有实现输出具体的布局调整建议和代码补丁。”另外有个细节不要在 description 里写“不要用于 XX 场景”。语义匹配模型对否定句的识别效果比较差你写了反而容易造成混淆。正确的做法是只描述你希望它触发的正例场景把边界条件写清楚即可。还有一个经验description 控制在 2-3 句话之间效果最好。太短了信息量不够匹配精度差太长了 Agent 的注意力会被稀释反而抓不住重点。我在几十个技能的实践中发现2-3 句、每句包含一个明确动作的 description 匹配准确率最高。2.3 技能内建命令、环境要求与依赖声明很多技能不是光靠嘴皮子说说就行它需要调用外部工具或脚本。比如一个“代码评审”技能它需要先拉取代码、跑 lint、看测试报告。这时候你就要在 SKILL.md 里明确写出这些操作涉及的命令和预期输出格式让 Agent 能够自主执行并判断结果。我的做法是在技能正文里单独设置一个“执行环境”小节用列表写出所有依赖它的前置条件和命令示例。比如## 执行环境要求 - 需要 git 2.30 以上版本 - 需要 Node.js 18 环境 - 在开始评审之前必须执行 npm install 确保依赖完整 - 测试命令统一使用 npm test输出格式为 JUnit XML 到 test-results/ 目录这样做的好处是 Agent 在执行过程中遇到环境问题时能参考这些信息进行排查而不是凭空猜测。我自己还遇到过一种情况Agent 在执行技能时反复尝试一个根本不存在的命令就是因为技能包没有写明工具版本要求。你把这些信息写清楚Agent 的错误率会大幅下降。关于依赖声明我建议在技能目录下放一个requirements.txt或package.json之类的文件按技能实际使用的语言来定并在 SKILL.md 里显式引用它。OpenClaw 虽然不会自动安装这些依赖但 Agent 在技能执行前会检查这些文件并主动提示用户安装缺失的部分这个机制能省掉很多环境折腾。3. 实操从 0 到 1 开发并安装一个 Skills3.1 环境准备安装 OpenClaw 与技能目录在动手写技能之前先把 OpenClaw 跑起来。如果你用的是 Ubuntu 系统安装过程大致是先把仓库克隆到本地然后运行安装脚本最后用openclaw configure完成 API 密钥和模型配置。这一步不同系统细节会有些差异但整体都不复杂照着官方 README 操作就行。安装完成后你需要确认技能目录的位置。OpenClaw 默认会有一个skills目录你可以在配置里指定它的路径。我的习惯是把技能目录单独放到一个项目仓库里管理这样多个机器之间可以同步也方便备份。# 查看当前配置文件位置 openclaw config show # 修改技能目录路径 openclaw config set skills.path ~/projects/my-skills如果你只是想快速试一下别人的技能OpenClaw 也支持从远程仓库直接安装。命令大致是openclaw skills install repo-url安装完成后技能会出现在你的技能目录里。我用这个方法装过 GitHub 上一些热门的技能包比如 superpower-skills 和 COLA-skills后面我会详细聊这两个包的差异。3.2 手写一个“数学建模数据清洗”技能光说不练假把式我以自己写的一个“数学建模数据清洗”技能为例带你完整走一遍开发流程。这个技能的目标是当用户给出一份 CSV 数据文件并希望对它做清洗和探索性分析时Agent 能按照标准流程处理。首先创建目录和 SKILL.md 文件mkdir -p ~/projects/my-skills/data-cleaning cd ~/projects/my-skills/data-cleaning touch SKILL.md然后写入以下内容--- name: math-model-data-cleaning description: 当用户提供一个 CSV 或 Excel 数据集并希望进行数据清洗、缺失值处理、异常值筛选或基本统计描述时使用。适合数学建模竞赛前的数据准备阶段输出清洗报告和探索性分析图表。 --- # 数学建模数据清洗 ## 任务目标 对给定的数据集进行系统清洗输出一份清洗报告包含 1. 数据基本情况概览行数、列数、类型 2. 缺失值统计与处理方案 3. 异常值检测与处理建议 4. 基础分布可视化 ## 执行步骤 1. 读取数据文件确认编码格式优先尝试 UTF-8失败则尝试 GBK。 2. 使用 df.info() 和 df.describe() 查看结构记录列名与类型。 3. 对缺失比例超过 30% 的列建议删除低于 30% 的列根据业务含义选择均值/中位数/众数填充。 4. 使用 IQR 法则检测数值列的异常值标记但不要直接删除在报告中说明。 5. 绘制所有数值列的直方图和相关性热力图保存到 output/ 目录。 6. 将所有处理步骤写入 cleaning_report.md。 ## 注意事项 - 不要无理由删除整行数据所有删除操作必须在报告中解释原因。 - 日期列统一转换为 datetime 类型避免字符串操作错误。 - 如果数据量超过 100 万行优先使用 polars 而非 pandas。写好之后运行openclaw skills install ~/projects/my-skills/data-cleaning完成安装。这时候你可以在 OpenClaw 里随便给一个 CSV 文件路径说“帮我做一下数据清洗”Agent 就会自动把这个技能加载进来并按流程执行。这个例子看起来简单但里面有几个设计点是刻意安排的一是步骤编号给了 Agent 明确的执行顺序它不会跳过关键环节二是注意事项里写明了“不要无理由删除整行”防止模型凭感觉乱裁数据三是提供了大数据量下的工具切换建议让技能能适配不同的数据规模。3.3 安装第三方技能包superpower-skills、COLA-skills如果你不想从零开始写GitHub 上有现成的技能包可以直接拿来用。我自己实测过几个简单说一下区别和体验。superpower-skills 是往“超级能力”方向做的里面集合了大量面向通用场景的技能——从写代码、写文档到项目管理都有。它的特点是技能数量非常多覆盖面广适合刚开始接触 Skills 的人快速找感觉。缺点是技能多了之后语义匹配可能出现混淆偶尔会调错技能。我的建议是不要一股脑全装挑自己常用的十几个就好。COLA-skills 则是面向“数据分析与科研场景”做的我在做数学建模竞赛的时候用过它的数据分析模块里面有几个技能的质量很高比如“数据探索报告生成”“模型对比试验设计”步骤写得很规范可以直接用在竞赛的前期准备中。它的更新频率也比较高目前我还在持续关注。安装方法基本都一致# 安装 GitHub 仓库 openclaw skills install https://github.com/用户名/仓库名 # 也可以直接安装到指定目录覆盖默认位置 openclaw skills install https://github.com/用户名/仓库名 --path ~/projects/my-skills安装完成后用openclaw skills list检查一下是否成功。如果你打开 SKILL.md 发现格式不完整或 description 写得很随意那这个技能包的效果大概率要大打折扣建议找别的替代。3.4 测试与调试技能调用链路技能装好只是第一步真正让它工作起来需要测试。我的测试方式分三层第一层是基础加载测试。在 OpenClaw 里直接输入“你现在有哪些技能可以处理数据清洗”之类的问题观察 Agent 是否在回复中列出了你期望的技能。如果它绕着说别的东西说明技能根本没被加载检查一下技能目录路径和 SKILL.md 格式。第二层是触发测试。给你技能 descriptions 里提到的典型场景看 Agent 是否会主动使用该技能。注意这里不要用太模糊的说法直接复现 description 里描述的触发条件比如“这里有一个 CSV 文件路径帮我做缺失值分析”。如果 Agent 没有触发最可能的原因是 description 写得不够明确或激活阈值设置过高。第三层是执行链路测试。故意给一个带有边界条件的输入比如空文件、编码错误的文件看 Agent 的技能执行过程是否稳健会不会卡死或报错。这一步最容易暴露技能正文中的指令缺陷比如遗漏了某个可能异常的处理分支——找到了就回去修改 SKILL.md这是个迭代打磨的过程。OpenClaw 有一个对调试特别有用的功能会话日志。当技能执行失败时日志会记录详细的调用上下文和模型输出你可以看到 Agent 到底是在哪一步判断失误的是没识别出触发场景还是正文指令不清晰导致执行出错。查日志比反复猜要有用得多遇到问题先翻日志。4. 常见问题与排查技巧实录4.1 session file locked 超时并发会话的文件锁问题这个报错我在社区里见过不少人问原文大概是agent failed before reply: session file locked (timeout 60000ms)。我一开始遇到也懵了以为是配置坏了后来排查才发现是并发会话导致的文件锁冲突。OpenClaw 在管理会话时会为每个会话创建一个文件用于持久化状态。当你同时打开多个会话窗口或者上一个会话进程没有正常退出时新的会话请求可能会在尝试获取文件锁时等不到锁的释放最终触发 60 秒超时。解决办法很简单确认没有残留的 OpenClaw 进程后找到会话文件目录手动删除锁文件一般是.lock后缀。我这边的情况是同时开了多个终端窗口导致的关掉多余的窗口就恢复了。如果你用的是远程服务器还要检查是不是有多个 http 请求同时触发了同一个会话的写入这种情况可以在 OpenClaw 配置里把会话并发数调低。提示不要在 OpenClaw 还在运行时直接删除锁文件这可能导致会话数据损坏。最稳妥是先退出所有会话进程确认没有残留再清理锁文件。4.2 技能装上了但 Agent“看不见”很多第一次用 OpenClaw 的人都会遇到这个困惑openclaw skills list能看到技能但跟 Agent 对话时它完全没有表现出“学过”这些技能的样子。这个问题的根源大概率是技能目录配置不一致。OpenClaw 配置里可能设置了多个技能路径但skills list显示的是全局搜索的结果Agent 运行时只加载了默认路径下的部分技能。你需要在openclaw config show里确认skills.path的指向然后把技能放进这个目录。另一个常见原因是技能文件大小超限。OpenClaw 对技能包的总大小和 SKILL.md 的 Token 数量是有限制的如果技能包里的附属资源太多比如塞了几十张截图这整个技能可能会被静默跳过。解决办法是把技能包瘦身把不必要的资源移到外部引用。4.3 描述过泛导致的技能误触发前面提到过 description 写得过于笼统会让 Agent 乱调用技能但实际操作中还有一个更隐蔽的问题是“多技能竞争”。当你安装了多个描述相似的技能包Agent 可能会犹豫该用哪个最后选错。我的解决办法是给每个技能增加一个“排除场景”描述但不是说不要写否定句吗这里有个技巧要用肯定的方式描述自己的专属场景同时把你的技能描述做得足够具体让它在语义空间上和其他技能拉开距离。比如你有一个“前端切图”技能就别只说“处理前端任务”要写“当用户提供了设计稿图片并需要切页为 React 组件代码时使用”。这样即使在多技能竞争的场景下匹配度也会明显偏向这个更具体的技能。4.4 技能执行失败后的降级策略技能不是万能的Agent 在执行中可能因为文件不存在、命令报错或数据格式不符合预期而失败。我的经验是在 SKILL.md 里主动设计“失败处理”分支告诉 Agent 遇到哪些情况该继续尝试、哪些情况该停下来向用户求助。我在技能正文里通常这样写## 失败处理 - 如果目标文件不存在先检查文件路径是否是相对路径并尝试从当前工作目录的其他子目录中查找。 - 如果命令执行失败且错误信息与依赖缺失相关尝试运行安装命令后重试一次。 - 如果两次重试仍失败停止操作向用户展示当前遇到的错误信息和已尝试的步骤。这样写的好处是 Agent 不会在死胡同里无限循环它会有一个清晰的“止损点”。我实测过加入失败处理分支后技能执行的整体失败率明显下降用户体验也好很多——毕竟看到一个明确的错误提示总比看它反复试错强。5. 进阶让技能组合与多 Agent 协作5.1 编排多个技能从一个技能调用另一个技能单一技能解决单一任务组合技能才能支撑完整的工作流。OpenClaw 支持在技能正文中引用其他技能一个复杂任务可以被拆解为多个技能的顺序调用。举个例子我想做一个“竞品分析报告”的流程它涉及三件事抓取竞品页面信息、整理数据表格、生成分析文档。我就可以分别写三个技能然后在主技能里用明确的指令串联它们## 执行流程 1. 调用 skill:web-capture 获取竞品页面的完整 HTML 内容和结构数据。 2. 调用 skill:data-organize 将页面数据结构化到表格文件。 3. 调用 skill:analysis-report 基于最终表格生成竞品分析报告。技能编排有两个需要注意的坑。一是技能之间的数据传递要提前约定好文件格式和路径否则后一个技能读不到前一个技能的输出。二是不要过度拆分——如果一个技能内部十几行指令就能搞定的事情硬拆成三个技能反而会增加上下文切换的损耗。我的标准是一个技能最好能独立完成一个有明确产出的任务拆分单元不要小于这个粒度。5.2 外部工具接入Obsidian、Teams 等场景扩展Skills 不只是让 Agent 生成文本它还能让 Agent 指挥其他工具。我自己试过把 OpenClaw 接到 Obsidian 知识库上做法是写了一个技能技能体内定义了如何调用 Obsidian 本地 API 来创建笔记、搜索内容和整理标签。这里的关键在于你需要在 SKILL.md 中把“调用方式”写清楚包括 API 地址、请求格式和鉴权方式。Agent 不会自己知道这些但它会严格按你写的调用手册去操作。同样的原理也可以用在企业通讯工具上比如接入协同办公软件的频道机器人——通过一个定义好的 Webhook 技能Agent 就能向指定频道推送消息或读取指令。接入外部工具时我强烈建议把鉴权信息放进环境变量而不是直接写在 SKILL.md 里。技能内容会被加载进模型上下文存在被日志记录或外泄的风险。我在技能正文里会用${TEAMS_WEBHOOK_URL}这种占位符然后在 OpenClaw 的环境变量里配置实际值Agent 执行时会自动替换。5.3 技能库维护与团队复用技能开发不是一次性的随着使用场景增加你会有越来越多的 SKILL.md 需要维护。我的习惯是把所有技能放在一个 Git 仓库里管理每个技能一个目录主分支保持稳定开发新技能时开分支测试通过后再合并。团队协作时还需要约定命名规范和描述风格。建议强制要求每个技能必须有name、description、适用场景、依赖工具四个关键字段没有这些字段的技能不允许合入主分支。另外技能包里的资源和脚本版本也要跟着 SKILL.md 一起维护不然就会出现“文档说要用新命令但脚本还是旧版”的尴尬情况。我目前还开发了一个小工具用于技能仓库的 CI 检查每次 push 时自动检测 SKILL.md 的 frontmatter 是否完整、description 是否超过 2 句话、目录名是否合法。虽然逻辑很简单但确实帮团队拦住了不少低级错误。最后再分享一个我在多次实践后的体会Skill 的开发是一个持续迭代的过程你不可能第一版就写得很完美。我的流程是先快速写一个“够用”的版本跑通任务然后在真实使用中观察 Agent 的错误和遗漏再回头补充 SKILL.md 的细节。只要你的技能包始终坚持“具体场景 明确步骤 失败处理”这三个原则它就会随着迭代越来越好用Agent 的可信度也会越来越高。 OpenClaw技能开发实战：从SKILL.md到Agent能力扩展
最近在折腾 AI Agent 相关的东西发现很多人在问同一个问题OpenClaw 装好了Agent 也能跑了但总感觉它“啥都不会”——让它写个前端页面只会给你搭个空架子让它做数据分析只会调个describe()。说白了Agent 本身只是个大脑空转的引擎真正让它干活的是 Skills。我一开始也踩了这个坑后来把 OpenClaw 的 Skills 机制彻底啃了一遍自己手写了几个技能又折腾了第三方技能库这才算是把 Agent 从“能聊天”变成了“能干活”。这篇文章就是我这段经验的完整复盘从 Skills 的核心原理、SKILL.md 怎么写、开发到安装的全流程再到我踩过的几个典型报错一次性讲透。这篇文章适合两类人看一是刚装好 OpenClaw 但不知道怎么让 Agent 干实际活儿的新手二是已经在用其他 Agent 工具Claude Code、Codex 这类想迁移技能开发经验的人。我会尽量说人话能给你直接抄作业的地方绝不绕弯子。1. 先想清楚Skills 到底在解决什么问题1.1 Agent 的“外挂大脑”从通用对话到专用能力每个 AI Agent 在刚装好的时候本质上都是一个“什么都会一点但什么都不精”的通用模型。你让它写 Python 它能写但如果你希望它写完代码之后自动跑测试、根据覆盖率报告决定要不要继续改它就懵了——不是模型不行而是模型缺少一套明确的操作流程和领域规则。Skills 解决的就是这个问题。它的核心思路是把某个特定领域的操作流程、判断标准、命令调用方式封装成一个 Markdown 格式的技能包Agent 在遇到对应任务时会把这个技能包的内容注入到对话上下文里然后按照技能包里的指令一步步执行。我自己的理解是Skills 相当于给 Agent 一本“操作手册”。模型本身还是那个模型但有了这本手册它就知道该按什么顺序执行命令、该读哪些文件、该用什么标准判断结果。这跟人类干活是一个道理——一个刚毕业的实习生不是不聪明他是没有把活干好的流程和标准你给他一本 SOP他立刻就能上手。1.2 OpenClaw 的技能加载机制描述匹配与上下文注入OpenClaw 的技能加载机制最关键的环节是“描述匹配”。每个技能包的 SKILL.md 文件里有一段 YAML 格式的 frontmatter其中description字段就是 Agent 判断“该用哪个技能”的依据。当用户提出一个任务时OpenClaw 会把这个任务的内容和所有已安装技能的description做语义匹配。匹配度高的技能会被加载进上下文然后 Agent 开始按技能正文里的指示执行。这也就解释了一个很常见的现象为什么有些技能装上了就没反应十有八九是description写得太笼统或者主题对不上Agent 根本不知道什么时候该调用它。另外要注意OpenClaw 的匹配机制不是简单的关键词匹配而是基于语义的相似度计算。这意味着你不需要在 description 里堆砌大量关键词但你必须把技能的应用场景描述清楚。比如你写“用于处理 CSV 文件”那 Agent 只有在你明确提到 CSV 时才会想到这个技能但你写“当用户需要对表格数据做清洗、格式转换或统计分析时使用”Agent 在遇到各种数据相关任务时都能联想到它。1.3 为什么不用插件或脚本Skills 的设计取舍有的朋友可能会问既然 Skills 能让 Agent 干活那我直接用 Python 脚本包装不行吗我自己也纠结过这个问题但实际对比下来Skills 的优势还是很明确的。脚本解决的是“固定逻辑自动执行”它的问题在于 Agent 不知道“什么时候该调这个脚本”。你得在对话里明确告诉它或者用一套复杂的命令路由机制去触发。Skills 则是“带触发条件的动态指令集”Agent 根据对话内容语义判断该不该用、怎么用而且技能包可以随时增删改不用重启服务。当然Skills 不是万能的。它擅长的是“指导 Agent 如何操作”而不是“替 Agent 完成计算”。如果你的需求是高度确定性的数据处理流程那直接用脚本挂个 API 更高效如果你的需求是让 Agent 在复杂对话场景中自主判断该怎么做那 Skills 是最合适的载体。我自己目前的项目里两者是配合使用的——脚本负责具体执行Skills 负责组织这些脚本的调用顺序和判断条件。2. 开发一个 Skill 的完整规范SKILL.md 拆解2.1 SKILL.md 的结构frontmatter 正文指令一个 Skill 就是一个目录目录的核心是一个名为SKILL.md的 Markdown 文件。这个文件的结构非常清晰分为两大部分YAML frontmatter 和正文指令块。先看 frontmatter它负责描述技能的基本信息。最少需要包含name和description两个字段比如--- name: frontend-design-review description: 当用户需要对前端页面进行设计评审、发现布局或视觉问题时使用。可分析页面截图或 HTML 代码输出具体的修改建议。 ---name是技能的唯一标识建议用短横线连接的小写英文单词不要用空格或中文。description是技能的灵魂我会在后面的小节里专门展开讲怎么写好它。正文部分才是真正的“干货”是 Agent 执行任务时遵循的指令。这里没有严格的语法限制你可以用自然的 Markdown 语言描述步骤、规则和示例。但为了让 Agent 执行得更准确有几个实用建议用有序列表写明操作步骤、用代码块给出期望的输出格式、用引用块标注需要特别注意的坑。我还见过一些复杂的技能包除了 SKILL.md 之外还会带一个assets或scripts子目录里面放着参考图片、模板文件或辅助脚本。OpenClaw 加载技能的时候会把整个目录打包进上下文所以这些附属文件也是可以被 Agent 读取和引用的。2.2 描述怎么写才不被“误调用”我踩过最狠的坑就是 description 写得太泛。最早我写了一个“网页开发助手”description 是“当用户需要前端开发帮助时使用”结果就是所有稍微沾点前端边的问题都会触发它有时候用户只是问个概念它也跑出来要改代码整个对话体验非常割裂。后来我总结了一套 description 的写法公式触发条件 功能概括 典型场景 预期输出。四要素最好都写上尤其是触发条件要尽量具体。比如“当用户提供了一个设计稿截图或一段 HTML/CSS 代码并希望优化页面视觉效果时使用。该技能会分析现有实现输出具体的布局调整建议和代码补丁。”另外有个细节不要在 description 里写“不要用于 XX 场景”。语义匹配模型对否定句的识别效果比较差你写了反而容易造成混淆。正确的做法是只描述你希望它触发的正例场景把边界条件写清楚即可。还有一个经验description 控制在 2-3 句话之间效果最好。太短了信息量不够匹配精度差太长了 Agent 的注意力会被稀释反而抓不住重点。我在几十个技能的实践中发现2-3 句、每句包含一个明确动作的 description 匹配准确率最高。2.3 技能内建命令、环境要求与依赖声明很多技能不是光靠嘴皮子说说就行它需要调用外部工具或脚本。比如一个“代码评审”技能它需要先拉取代码、跑 lint、看测试报告。这时候你就要在 SKILL.md 里明确写出这些操作涉及的命令和预期输出格式让 Agent 能够自主执行并判断结果。我的做法是在技能正文里单独设置一个“执行环境”小节用列表写出所有依赖它的前置条件和命令示例。比如## 执行环境要求 - 需要 git 2.30 以上版本 - 需要 Node.js 18 环境 - 在开始评审之前必须执行 npm install 确保依赖完整 - 测试命令统一使用 npm test输出格式为 JUnit XML 到 test-results/ 目录这样做的好处是 Agent 在执行过程中遇到环境问题时能参考这些信息进行排查而不是凭空猜测。我自己还遇到过一种情况Agent 在执行技能时反复尝试一个根本不存在的命令就是因为技能包没有写明工具版本要求。你把这些信息写清楚Agent 的错误率会大幅下降。关于依赖声明我建议在技能目录下放一个requirements.txt或package.json之类的文件按技能实际使用的语言来定并在 SKILL.md 里显式引用它。OpenClaw 虽然不会自动安装这些依赖但 Agent 在技能执行前会检查这些文件并主动提示用户安装缺失的部分这个机制能省掉很多环境折腾。3. 实操从 0 到 1 开发并安装一个 Skills3.1 环境准备安装 OpenClaw 与技能目录在动手写技能之前先把 OpenClaw 跑起来。如果你用的是 Ubuntu 系统安装过程大致是先把仓库克隆到本地然后运行安装脚本最后用openclaw configure完成 API 密钥和模型配置。这一步不同系统细节会有些差异但整体都不复杂照着官方 README 操作就行。安装完成后你需要确认技能目录的位置。OpenClaw 默认会有一个skills目录你可以在配置里指定它的路径。我的习惯是把技能目录单独放到一个项目仓库里管理这样多个机器之间可以同步也方便备份。# 查看当前配置文件位置 openclaw config show # 修改技能目录路径 openclaw config set skills.path ~/projects/my-skills如果你只是想快速试一下别人的技能OpenClaw 也支持从远程仓库直接安装。命令大致是openclaw skills install repo-url安装完成后技能会出现在你的技能目录里。我用这个方法装过 GitHub 上一些热门的技能包比如 superpower-skills 和 COLA-skills后面我会详细聊这两个包的差异。3.2 手写一个“数学建模数据清洗”技能光说不练假把式我以自己写的一个“数学建模数据清洗”技能为例带你完整走一遍开发流程。这个技能的目标是当用户给出一份 CSV 数据文件并希望对它做清洗和探索性分析时Agent 能按照标准流程处理。首先创建目录和 SKILL.md 文件mkdir -p ~/projects/my-skills/data-cleaning cd ~/projects/my-skills/data-cleaning touch SKILL.md然后写入以下内容--- name: math-model-data-cleaning description: 当用户提供一个 CSV 或 Excel 数据集并希望进行数据清洗、缺失值处理、异常值筛选或基本统计描述时使用。适合数学建模竞赛前的数据准备阶段输出清洗报告和探索性分析图表。 --- # 数学建模数据清洗 ## 任务目标 对给定的数据集进行系统清洗输出一份清洗报告包含 1. 数据基本情况概览行数、列数、类型 2. 缺失值统计与处理方案 3. 异常值检测与处理建议 4. 基础分布可视化 ## 执行步骤 1. 读取数据文件确认编码格式优先尝试 UTF-8失败则尝试 GBK。 2. 使用 df.info() 和 df.describe() 查看结构记录列名与类型。 3. 对缺失比例超过 30% 的列建议删除低于 30% 的列根据业务含义选择均值/中位数/众数填充。 4. 使用 IQR 法则检测数值列的异常值标记但不要直接删除在报告中说明。 5. 绘制所有数值列的直方图和相关性热力图保存到 output/ 目录。 6. 将所有处理步骤写入 cleaning_report.md。 ## 注意事项 - 不要无理由删除整行数据所有删除操作必须在报告中解释原因。 - 日期列统一转换为 datetime 类型避免字符串操作错误。 - 如果数据量超过 100 万行优先使用 polars 而非 pandas。写好之后运行openclaw skills install ~/projects/my-skills/data-cleaning完成安装。这时候你可以在 OpenClaw 里随便给一个 CSV 文件路径说“帮我做一下数据清洗”Agent 就会自动把这个技能加载进来并按流程执行。这个例子看起来简单但里面有几个设计点是刻意安排的一是步骤编号给了 Agent 明确的执行顺序它不会跳过关键环节二是注意事项里写明了“不要无理由删除整行”防止模型凭感觉乱裁数据三是提供了大数据量下的工具切换建议让技能能适配不同的数据规模。3.3 安装第三方技能包superpower-skills、COLA-skills如果你不想从零开始写GitHub 上有现成的技能包可以直接拿来用。我自己实测过几个简单说一下区别和体验。superpower-skills 是往“超级能力”方向做的里面集合了大量面向通用场景的技能——从写代码、写文档到项目管理都有。它的特点是技能数量非常多覆盖面广适合刚开始接触 Skills 的人快速找感觉。缺点是技能多了之后语义匹配可能出现混淆偶尔会调错技能。我的建议是不要一股脑全装挑自己常用的十几个就好。COLA-skills 则是面向“数据分析与科研场景”做的我在做数学建模竞赛的时候用过它的数据分析模块里面有几个技能的质量很高比如“数据探索报告生成”“模型对比试验设计”步骤写得很规范可以直接用在竞赛的前期准备中。它的更新频率也比较高目前我还在持续关注。安装方法基本都一致# 安装 GitHub 仓库 openclaw skills install https://github.com/用户名/仓库名 # 也可以直接安装到指定目录覆盖默认位置 openclaw skills install https://github.com/用户名/仓库名 --path ~/projects/my-skills安装完成后用openclaw skills list检查一下是否成功。如果你打开 SKILL.md 发现格式不完整或 description 写得很随意那这个技能包的效果大概率要大打折扣建议找别的替代。3.4 测试与调试技能调用链路技能装好只是第一步真正让它工作起来需要测试。我的测试方式分三层第一层是基础加载测试。在 OpenClaw 里直接输入“你现在有哪些技能可以处理数据清洗”之类的问题观察 Agent 是否在回复中列出了你期望的技能。如果它绕着说别的东西说明技能根本没被加载检查一下技能目录路径和 SKILL.md 格式。第二层是触发测试。给你技能 descriptions 里提到的典型场景看 Agent 是否会主动使用该技能。注意这里不要用太模糊的说法直接复现 description 里描述的触发条件比如“这里有一个 CSV 文件路径帮我做缺失值分析”。如果 Agent 没有触发最可能的原因是 description 写得不够明确或激活阈值设置过高。第三层是执行链路测试。故意给一个带有边界条件的输入比如空文件、编码错误的文件看 Agent 的技能执行过程是否稳健会不会卡死或报错。这一步最容易暴露技能正文中的指令缺陷比如遗漏了某个可能异常的处理分支——找到了就回去修改 SKILL.md这是个迭代打磨的过程。OpenClaw 有一个对调试特别有用的功能会话日志。当技能执行失败时日志会记录详细的调用上下文和模型输出你可以看到 Agent 到底是在哪一步判断失误的是没识别出触发场景还是正文指令不清晰导致执行出错。查日志比反复猜要有用得多遇到问题先翻日志。4. 常见问题与排查技巧实录4.1 session file locked 超时并发会话的文件锁问题这个报错我在社区里见过不少人问原文大概是agent failed before reply: session file locked (timeout 60000ms)。我一开始遇到也懵了以为是配置坏了后来排查才发现是并发会话导致的文件锁冲突。OpenClaw 在管理会话时会为每个会话创建一个文件用于持久化状态。当你同时打开多个会话窗口或者上一个会话进程没有正常退出时新的会话请求可能会在尝试获取文件锁时等不到锁的释放最终触发 60 秒超时。解决办法很简单确认没有残留的 OpenClaw 进程后找到会话文件目录手动删除锁文件一般是.lock后缀。我这边的情况是同时开了多个终端窗口导致的关掉多余的窗口就恢复了。如果你用的是远程服务器还要检查是不是有多个 http 请求同时触发了同一个会话的写入这种情况可以在 OpenClaw 配置里把会话并发数调低。提示不要在 OpenClaw 还在运行时直接删除锁文件这可能导致会话数据损坏。最稳妥是先退出所有会话进程确认没有残留再清理锁文件。4.2 技能装上了但 Agent“看不见”很多第一次用 OpenClaw 的人都会遇到这个困惑openclaw skills list能看到技能但跟 Agent 对话时它完全没有表现出“学过”这些技能的样子。这个问题的根源大概率是技能目录配置不一致。OpenClaw 配置里可能设置了多个技能路径但skills list显示的是全局搜索的结果Agent 运行时只加载了默认路径下的部分技能。你需要在openclaw config show里确认skills.path的指向然后把技能放进这个目录。另一个常见原因是技能文件大小超限。OpenClaw 对技能包的总大小和 SKILL.md 的 Token 数量是有限制的如果技能包里的附属资源太多比如塞了几十张截图这整个技能可能会被静默跳过。解决办法是把技能包瘦身把不必要的资源移到外部引用。4.3 描述过泛导致的技能误触发前面提到过 description 写得过于笼统会让 Agent 乱调用技能但实际操作中还有一个更隐蔽的问题是“多技能竞争”。当你安装了多个描述相似的技能包Agent 可能会犹豫该用哪个最后选错。我的解决办法是给每个技能增加一个“排除场景”描述但不是说不要写否定句吗这里有个技巧要用肯定的方式描述自己的专属场景同时把你的技能描述做得足够具体让它在语义空间上和其他技能拉开距离。比如你有一个“前端切图”技能就别只说“处理前端任务”要写“当用户提供了设计稿图片并需要切页为 React 组件代码时使用”。这样即使在多技能竞争的场景下匹配度也会明显偏向这个更具体的技能。4.4 技能执行失败后的降级策略技能不是万能的Agent 在执行中可能因为文件不存在、命令报错或数据格式不符合预期而失败。我的经验是在 SKILL.md 里主动设计“失败处理”分支告诉 Agent 遇到哪些情况该继续尝试、哪些情况该停下来向用户求助。我在技能正文里通常这样写## 失败处理 - 如果目标文件不存在先检查文件路径是否是相对路径并尝试从当前工作目录的其他子目录中查找。 - 如果命令执行失败且错误信息与依赖缺失相关尝试运行安装命令后重试一次。 - 如果两次重试仍失败停止操作向用户展示当前遇到的错误信息和已尝试的步骤。这样写的好处是 Agent 不会在死胡同里无限循环它会有一个清晰的“止损点”。我实测过加入失败处理分支后技能执行的整体失败率明显下降用户体验也好很多——毕竟看到一个明确的错误提示总比看它反复试错强。5. 进阶让技能组合与多 Agent 协作5.1 编排多个技能从一个技能调用另一个技能单一技能解决单一任务组合技能才能支撑完整的工作流。OpenClaw 支持在技能正文中引用其他技能一个复杂任务可以被拆解为多个技能的顺序调用。举个例子我想做一个“竞品分析报告”的流程它涉及三件事抓取竞品页面信息、整理数据表格、生成分析文档。我就可以分别写三个技能然后在主技能里用明确的指令串联它们## 执行流程 1. 调用 skill:web-capture 获取竞品页面的完整 HTML 内容和结构数据。 2. 调用 skill:data-organize 将页面数据结构化到表格文件。 3. 调用 skill:analysis-report 基于最终表格生成竞品分析报告。技能编排有两个需要注意的坑。一是技能之间的数据传递要提前约定好文件格式和路径否则后一个技能读不到前一个技能的输出。二是不要过度拆分——如果一个技能内部十几行指令就能搞定的事情硬拆成三个技能反而会增加上下文切换的损耗。我的标准是一个技能最好能独立完成一个有明确产出的任务拆分单元不要小于这个粒度。5.2 外部工具接入Obsidian、Teams 等场景扩展Skills 不只是让 Agent 生成文本它还能让 Agent 指挥其他工具。我自己试过把 OpenClaw 接到 Obsidian 知识库上做法是写了一个技能技能体内定义了如何调用 Obsidian 本地 API 来创建笔记、搜索内容和整理标签。这里的关键在于你需要在 SKILL.md 中把“调用方式”写清楚包括 API 地址、请求格式和鉴权方式。Agent 不会自己知道这些但它会严格按你写的调用手册去操作。同样的原理也可以用在企业通讯工具上比如接入协同办公软件的频道机器人——通过一个定义好的 Webhook 技能Agent 就能向指定频道推送消息或读取指令。接入外部工具时我强烈建议把鉴权信息放进环境变量而不是直接写在 SKILL.md 里。技能内容会被加载进模型上下文存在被日志记录或外泄的风险。我在技能正文里会用${TEAMS_WEBHOOK_URL}这种占位符然后在 OpenClaw 的环境变量里配置实际值Agent 执行时会自动替换。5.3 技能库维护与团队复用技能开发不是一次性的随着使用场景增加你会有越来越多的 SKILL.md 需要维护。我的习惯是把所有技能放在一个 Git 仓库里管理每个技能一个目录主分支保持稳定开发新技能时开分支测试通过后再合并。团队协作时还需要约定命名规范和描述风格。建议强制要求每个技能必须有name、description、适用场景、依赖工具四个关键字段没有这些字段的技能不允许合入主分支。另外技能包里的资源和脚本版本也要跟着 SKILL.md 一起维护不然就会出现“文档说要用新命令但脚本还是旧版”的尴尬情况。我目前还开发了一个小工具用于技能仓库的 CI 检查每次 push 时自动检测 SKILL.md 的 frontmatter 是否完整、description 是否超过 2 句话、目录名是否合法。虽然逻辑很简单但确实帮团队拦住了不少低级错误。最后再分享一个我在多次实践后的体会Skill 的开发是一个持续迭代的过程你不可能第一版就写得很完美。我的流程是先快速写一个“够用”的版本跑通任务然后在真实使用中观察 Agent 的错误和遗漏再回头补充 SKILL.md 的细节。只要你的技能包始终坚持“具体场景 明确步骤 失败处理”这三个原则它就会随着迭代越来越好用Agent 的可信度也会越来越高。