最近不少朋友在折腾 Agent 框架里的技能开发群里聊得最多的就是怎么把“能跑通的 Demo”变成“真正好用不翻车的技能”。我手上正好在维护一个基于 openclaw 框架的实用 Skill名字叫 nano-banana-pro。名字看着像玩笑实际是拿来做轻量级文本加工和文件整理的一套技能包。今天把这套东西从设计到落地完整拆一遍包括我踩过的坑、调过的参数、以及最后稳定运行的配置给想搞技能开发的同学一个可以直接抄作业的参考。这个 Skill 解决的核心问题很直接Agent 接到自然语言指令后经常要在本地做一系列确定性操作比如批量重命名、抽取字段、整理格式、生成摘要。如果每次都把任务丢给大模型重新推理速度慢、成本高而且结果不稳定。nano-banana-pro 的思路是把这些高频、重复的“技能动作”固化下来让 Agent 用一套精简的规则加少量大模型调用完成整个流程。适合正在做智能体应用、Prompt 工程或者想把现有工作流改造成 Agent 技能的人参考。1. 先搞清楚这个 Skill 到底解决了什么问题1.1 openclaw 的 Skill 体系是不太一样的实现思路很多人一听到 Skill第一反应是插件或者工作流。实际上在 openclaw 框架里Skill 的定位介于两者之间它比插件更轻没有独立进程和复杂生命周期比工作流更灵活可以直接接收用户的自然语言输入并动态决定执行路径。我理解它本质上是一套“预置好的行为模板”由三部分组成技能描述文件、处理脚本、参数约束。这种设计最大的好处是让 Agent 在不同任务之间切换的成本变得很低。举个例子当我需要处理一批文档时传统的插件方案要安装依赖、配置环境、定义接口整套下来半天过去了。而 Skill 只需要把目录结构和一份 YAML 描述文件写好注册之后就能被 Agent 自动识别和调用。nano-banana-pro 就是按照这个思路来设计的它不负责解决所有问题只把最容易出错、最耗时的“确定性动作”做稳。1.2 nano-banana-pro 的命名与能力边界nano 对应轻量banana 是内部代号pro 表示这是一版带增强能力的生产向版本。整套技能的设计目标只有三个词快速、稳定、低成本。快速指的是从收到指令到完成动作中间不做过多的模型推理稳定指的是同一输入在重复执行时结果差异尽量小低成本指的是能不用大模型的地方就不用能少传 token 就少传。能力边界主要覆盖几个方向批量文件重命名与目录整理按照规则自动分类文本字段抽取从日志、邮件、表格里提取指定信息格式标准化把杂乱的文本转换成 Markdown、JSON 或 CSV轻量摘要生成对较长文本做核心内容压缩不追求文学性表达。这些看起来都不是什么花活但恰恰是日常使用 Agent 时最容易被忽略的细节。很多场景下用户不是要一个惊天动地的智能体而是想把眼前这堆乱麻理顺。1.3 为什么不做成大而全的通用魔板一开始我确实动过念头把摘要、翻译、代码生成、问答都塞进同一个技能里。后来实测下来发现这是个灾难技能描述越长Agent 的意图识别越容易漂移参数越多框架在解析时越容易出错提示词里堆满各种规则模型反而抓不住重点。nano-banana-pro 后来走了一个折中路线核心技能只做三件事但是每一件都做得足够深。如果要扩展其他能力就通过组合多个 Skill 来实现而不是在一个 Skill 里叠加功能。这样做的另一个原因是排障方便。如果技能出了 bug我看到报错日志就能定位到是哪一段逻辑出了问题不用在一大坨代码里翻来翻去。2. 核心细节拆解一个 Skill 的内部结构是怎么组织的2.1 技能描述文件决定了 Agent 能不能认出你在 openclaw 的机制里Agent 先读技能描述文件再决定要不要调用这个技能。所以描述文件写得不好后面的代码就算再漂亮也没用。我的经验是描述要做到“具体而不冗余”既要说清楚这个技能能做什么也要说清楚什么情况下不该调用它。这是 nano-banana-pro 的清单文件示例name: nano-banana-pro version: 2.1.0 description: | 用于完成轻量级文本加工和文件整理任务的技能。 当用户需要批量重命名文件、抽取日志中的关键字段、 将杂乱的文本转换为JSON/CSV、或生成简短摘要时 可以调用本技能。 不适用于代码生成、数学推理、多轮复杂对话等场景。 author: internal license: MIT trigger: keywords: - 重命名 - 整理文件 - 提取字段 - 生成摘要 - 格式化输出这里的 trigger keywords 不是硬匹配而是给 Agent 一个参考信号。真正决定是否调用的还是描述里的语义信息。描述里最后那句话很关键“不适用于什么场景”能有效减少误调用这是我在多轮测试后加上的每次加上之后误触发率都明显下降。2.2 参数定义与解析宁可少也不要多第二个文件是参数约束。很多技能设计者容易在这里犯错恨不得把所有细节都变成参数结果 Agent 在生成参数时反复犹豫、格式出错。nano-banana-pro 只保留了必要的几个参数。parameters: - name: action type: string required: true description: 执行的动作类型可选值为 rename、extract、format、summarize - name: target type: string required: true description: 操作对象可以是文件路径、目录路径或原始文本内容 - name: options type: object required: false description: 附加选项如输出格式、目标目录、字段名称等这里有个小技巧把操作类型明确枚举出来比让模型自由发挥要稳定得多。用户在聊天里说“帮我把这些文件改个名”框架会优先尝试把意图映射到 rename 这个 action 上。如果映射失败就落入兜底分支让模型重新提问而不是瞎猜。参数数量控制在三个以内既降低了模型生成难度也减少了框架解析时的出错概率。2.3 处理脚本的模块划分纯函数和外部动作分开整个技能的核心是一个 Python 模块内部按职责拆成了三层。第一层是意图解析负责把 action 参数映射到具体处理函数第二层是纯逻辑层包括文本处理、格式转换、正则抽取全部设计成无副作用的纯函数方便单元测试第三层是执行层负责文件读写、目录遍历、日志输出所有副作用操作都集中在这一层。这个分层方式帮了我大忙。最开始版本里我把文件操作和文本解析混在一起出 bug 后定位问题特别费劲。后来按纯函数和外部动作分开十几分钟就能定位到问题根因。而且纯函数层可以直接在本地跑测试不需要启动完整的 Agent 框架开发效率提升非常明显。核心处理逻辑片段如下def handle_action(action, target, optionsNone): registry { rename: rename_files, extract: extract_fields, format: format_text, summarize: summarize_text, } handler registry.get(action) if handler is None: raise SkillActionError(f不支持的动作类型: {action}) return handler(target, options or {})每个处理函数都遵循同一个接口输入目标对象和选项字典返回结构化的结果对象。这样做的好处是后续新增动作时只需实现一个新函数然后在 registry 里注册就行不需要改动外层逻辑。2.4 与大模型调用的边界划分nano-banana-pro 一个比较特别的设计是“能不用模型就不用”。四个动作里rename、extract、format 三个都是纯规则驱动的只有 summarize 必须调用大模型。这样设计不是排斥模型而是为了性能和成本。rename、extract 这类操作规则清晰、结果确定用正则和字符串处理就能完成没必要浪费 token 让模型来跑。summarize 涉及语义理解规则搞不定必须上模型。判断标准只有一个这个任务存在“标准答案”吗存在就用规则不存在才用模型。边界划分清楚之后整个技能的平均响应速度比纯模型方案快了两倍不止成本更是降低了一个数量级。3. 从 0 到 1 实操把 nano-banana-pro 跑起来3.1 目录结构与环境准备openclaw 的 Skill 通常放在 skills 目录下每个技能一个独立文件夹。一个标准技能需要以下结构skills/ └── nano-banana-pro/ ├── manifest.yaml ├── params.yaml ├── run.py ├── handlers/ │ ├── rename.py │ ├── extract.py │ ├── format.py │ └── summarize.py └── tests/ ├── test_extract.py └── test_format.py环境方面不需要额外安装复杂依赖Python 3.9 以上标准库基本够用。summarize 功能需要联网调用模型接口所以要在 openclaw 的配置里填好服务商 API Key 和模型名。本地开发调试时可以先用一个轻量模型替代保证功能打通优先。3.2 注册技能的完整流程在 openclaw 框架里技能的注册不是拷贝一份文件就完事。我的操作习惯是三步走。第一步把技能目录放到指定位置。第二步修改框架的主配置文件在 skills 列表里添加 nano-banana-pro 的路径和启用状态。第三步运行框架提供的检查命令比如openclaw skill check nano-banana-pro它会校验描述文件的格式、参数定义是否合法、脚本能否正常导入。注册这一步最容易踩的坑是路径写错。框架对技能目录名和 manifest 中的 name 字段有强校验两者不一致时直接拒绝加载。我一开始把目录命名为 banana-pro但 manifest 里写的是 nano-banana-pro结果检查了半天才发现是名称不匹配。后续我把目录名和技能名保持完全一致再没出过这个问题。3.3 文件重命名动作的完整实现拿最常用的 rename 动作来看核心实现思路。这个动作的目标是根据规则批量重命名文件规则支持日期前缀、序号补零、关键字替换等模式。import re import os from pathlib import Path def rename_files(target, options): path Path(target) if not path.exists(): raise SkillActionError(f目标路径不存在: {target}) pattern options.get(pattern, {date}_{seq:03d}_{name}) files [f for f in path.iterdir() if f.is_file()] files.sort(keylambda f: f.name) results [] for idx, file in enumerate(files, start1): name file.stem ext file.suffix date_part options.get(date, 20250214) new_name pattern.format(datedate_part, seqidx, namename) new_path path / f{new_name}{ext} file.rename(new_path) results.append({old: file.name, new: new_path.name}) return {renamed_count: len(results), files: results}这里有个细节值得注意排序时显式对文件名做了 sort避免不同系统里目录遍历顺序不一致导致重命名结果不稳定。开发环境跑得好好的一到线上顺序就变了这类问题非常隐蔽建议写代码时直接加上排序逻辑。3.4 字段抽取动作的实现细节extract 动作是四个动作里技术含量最高的因为需要平衡规则覆盖率和误抽率。我的实现思路是先定义一组字段解析器每个解析器对应一种模式然后对目标文本逐行匹配。def extract_fields(target, options): fields options.get(fields, [date, level, message]) text load_text(target) result {} for field in fields: if field date: result[field] re.findall( r\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}, text ) elif field level: result[field] re.findall( r\b(INFO|DEBUG|WARNING|ERROR)\b, text ) elif field message: result[field] extract_message_lines(text) return {extracted: result, matched_count: len(text.splitlines())}实际使用中我慢慢发现让调用方把需要的字段名传给技能比在技能里塞满所有可能字段要好得多。一来是控制输出大小二来是减少无关字段的干扰。字段抽取有个很关键的注意事项正则匹配不到时不要静默返回空列表最好在结果里加一个 warning 字段提醒用户“可能存在未匹配的内容”。3.5 摘要生成动作的模型调用封装summarize 是唯一需要通过外部模型接口的能力。在设计时我不是直接把用户文本塞给模型而是先做文本长度检测和分段再按需调用。def summarize_text(target, options): text load_text(target) max_input options.get(max_input, 3000) max_output options.get(max_output, 200) if len(text) max_input: text text[:max_input] truncated True else: truncated False prompt build_summary_prompt(text, max_output) summary call_model(prompt) return {summary: summary, truncated: truncated}build_summary_prompt 里我会明确告诉模型输出格式比如“用三个要点概括核心内容、每条不超过五十字”。加上这层格式约束后输出稳定性提升明显。截断策略也很重要如果不截断长文本会导致 token 消耗暴增而且模型对超长上下文的注意力会分散生成质量反而不如截断后的短文本。4. 实测效果与调优记录从能跑到好用之间差了这几步4.1 测试场景一批量整理下载目录第一轮实测的场景是整理一个塞满各种文件的下载目录里面有一百多个文件命名混乱类型混杂。用 nano-banana-pro 的 rename 动作按“类型-日期-序号”的规则重新命名并分类到不同子目录。实测结果处理一百多个文件耗时不到一秒全部重命名成功无一失败。最让我意外的是整个过程中大模型一次都没参与纯规则就把问题解决了。这让我坚定了一个想法能用规则解决的事情就别让模型抢活。4.2 测试场景二从日志中抽取错误信息第二轮测试是处理一个几百行的服务运行日志目标是提取出所有 ERROR 级别的内容以及对应的时间戳和错误码。这个场景下 extract 动作就派上了用场。第一次测试时遇到一个典型问题日志中夹杂着 INFO 级别的堆栈信息里面也包含了 ERROR 字样导致误抽。后来我在正则匹配里加了一个约束必须是行的起始位置出现 ERROR 才算或者 ERROR 前只能是日期和级别字段。这样调整后误抽率从最初的百分之十五降到了接近零。4.3 token 消耗与响应时间的优化记录这一块是优化空间最大的地方。初始版本里 summarize 动作对三千字的文本平均要消耗两千多个 token响应时间在三秒左右。后来做了三处优化。第一处是文本预压缩。先去掉多余的空行、无意义的符号再用正则提取核心段落砍掉了大约四成的输入 token。第二处是模型选择。简单摘要任务不需要顶级模型换成性价比款模型后速度提升明显质量也没有明显下滑。第三处是输出长度约束强制让模型输出精简内容。优化前后的对比数据指标优化前优化后平均输入 token32001900平均输出 token450210单次耗时3.2 秒1.1 秒成本估算基准约 38%4.4 参数调优心得把经验固化到配置文件里调优过程中的很多发现如果不落地成配置下次重写技能时又会忘掉。我的做法是给 nano-banana-pro 加了一个 config.yaml把那些经过实测有效的参数都写进去比如截断阈值、正则匹配开关、模型温度参数。config.yaml 的核心内容extract: line_boundary_mode: strict enable_warning: true summarize: max_input: 3000 max_output: 200 temperature: 0.3 format: default_output: json rename: sort_files: true这些参数看着不起眼但每一项都是踩过坑之后总结出来的。温度设成 0.3 是为了摘要任务里减少随机性太高会让模型自由发挥太低又显得太死板。strict 边界模式是为了避免之前的误抽问题把匹配规则收紧到行级。5. 常见问题与排查技巧实录5.1 技能没有被框架识别症状是配置好了技能目录运行框架后日志里完全看不到这个技能的加载记录。这个问题我遇到过不止一次原因基本就三样。第一是目录名和技能名不一致牢记目录名必须和 manifest.yaml 里的 name 字段保持一致。第二是 manifest.yaml 文件校验失败建议用工具验证 YAML 格式常见错误是把中文冒号写成英文冒号、缩进用了 Tab。第三是主配置文件里忘了启用该技能部分版本框架默认禁用新加技能。排查思路就是按照这三条逐项检查基本能解决九成问题。5.2 提示词越长效果反而越差这是一个反直觉的结论。我第一次给 summarize 设计提示词时恨不得把所有要求都写进去包括格式、长度、语言风格、禁止事项。结果模型执行效果非常不稳定经常顾此失彼。后来我精简了提示词只保留三个最核心的约束输出格式、输出长度、语言风格。其他因素交给模型自己判断。实测下来效果稳定了不少。长提示词会稀释核心指令的权重模型很难分清哪些是重点。好的提示词应该像简洁的工单而不是一本操作手册。5.3 参数嵌套错误导致功能失效在给 rename 动作传 pattern 参数时我一开始设计得非常灵活允许调用方传一个模板字符串。结果 Agent 生成参数时经常出错比如把模板里的{seq:03d}写成{{seq:03d}}或者干脆不按格式来。这个问题后来通过两级防御解决。第一级在参数解析层加正则校验发现不符合格式的模板直接报错并提示用户。第二级在技能内部做一个模板修正函数把常见的错误变体自动改成正确格式。经过两层处理后这个老问题彻底绝迹了。5.4 上下文过长导致模型调用失败当处理的文本超过模型上下文上限时会直接报错。尤其在 summarize 长文档时最容易出现。我在处理这个问题时没有选择简单截断而是在截断前先删减明显无关的内容。具体做法是先按段落切分文本过滤空白段落和纯符号段落剩下的内容再拼起来。如果仍然超长才做硬截断。这样处理的好处是即使截断也是截掉“次要内容”而不是直接切断文档中间部分。5.5 输出不稳定时的兜底策略在模型调用中加入了重试与降级机制。第一次调用失败或者输出为空时会降低输出要求重新尝试第二次仍然失败就进入本地兜底逻辑返回一个默认的格式化错误提示而不是让用户看到一堆报错堆栈。def call_model_with_fallback(prompt): for attempt in range(2): try: response call_model(prompt) if response and response.strip(): return response except ModelTimeoutError: continue prompt 请用一句话概述核心内容 return 【摘要生成失败】请稍后重试这个兜底看起来技术含量不高却在实际使用中救了多次场。Agent 技能面向的是普通用户体验的稳定性比功能的丰富度重要得多。6. 后续扩展与落地思路nano-banana-pro 目前的版本已经在我日常工作中稳定跑了比较长时间但它的设计从一开始就不是封闭的。后续扩展主要有几个方向。第一个方向是增加更多的动作类型比如格式转换、文件去重、二维码生成这类实用性功能。每个动作仍然遵循纯函数加注册表模式新增成本很低。第二个方向是把配置项开放给调用方比如让 Agent 在对话中动态修改 rename 的模板规则这样用户不需要懂代码也能定制自己的规则。第三个方向是增加结果预览机制在执行文件操作前先输出预期效果让用户确认后再真正执行。每次扩展我都要回头审视一件事技能是否仍然足够精简如果某个新动作涉及大量特殊场景我会考虑另起一个独立技能而不是继续往 nano-banana-pro 里塞。保持技能单一职责后续维护和排障都会轻松很多。这套思路不仅适用于文本整理类技能很多纯工具型的技能都可以按同样的路子来做边界清晰、规则优先、少参数、强校验。照着这个方法落地技能能跑起来的概率会高很多。