在智能体开发圈子里skills 这个词最近几乎每天都有人提。可真正上手之后你会发现大多数人说的 skills 还是“给模型写一段更长的提示词”跟工程意义上的“能力包”完全是两码事。我最近正好把一堆散落各处的脚本、命令和临时提示词整理成了一个统一的 Skills 项目——每个技能都由一份“模型能读懂的操作说明”和一段“真正干活的脚本”组成模型负责读说明书、按需调用脚本负责把活干完人负责定义边界和兜底。这篇文章把我整个梳理过程、设计取舍、写描述踩过的坑以及最后沉淀下来的一套做法完整讲一遍。这篇文章主要面向三类人正在做 Agent 应用、想把常见操作封装成能力的开发者喜欢用自动化工具处理文件、数据、网页任务的效率爱好者以及那些已经有了一堆自动化脚本但不知道怎么组织才更可靠的朋友。下面要讲的是真实项目过程不是产品文档所以会有大量的取舍解释和踩坑实录你可以直接照着搭一版。1. 为什么需要一套“Skills”体系1.1 智能体能力碎片化不解决会怎样先说我整理之前的状态各种工具脚本散在目录里有的叫get_weather.py有的叫generate_report.sh还有一堆用了一次就忘的临时命令。每次想让智能体执行一个稍微复杂的任务我都要在对话里重新解释“你得先跑这个脚本、传这几个参数、输出是什么格式、失败的话怎么办”。第一次还行第二次就烦了等到维护三个以上任务时基本处于失控状态。碎片化带来的问题不止是“写提示词麻烦”。你想想如果每个任务都在对话里临时定义那么你无法做测试因为没有一个固定的“接口”可以验证也无法做版本管理因为逻辑散在对话记录里更无法做团队协作因为同事根本不知道你这套“对话约定”长什么样。智能体的能力一旦只存在于上下文里就是一笔无法复核、无法传承的临时资产。这就是 Skills 要解决的第一个问题把“口头约定”变成“工程资产”。一个技能就是一套独立的交付物有目录、有文件、有测试、有版本。模型只是这套资产的调用者而不是定义者。1.2 Skills 体系到底在解决什么问题Skills 解决的核心问题用一句话说让智能体具备“可复用、可测试、可协作”的稳定操作能力。常规的做法是把操作逻辑写在提示词里但提示词是概率性的同样一句“调用脚本处理一下”模型可能在参数上犯迷糊也可能直接跳过脚本自己编一个结果。而技能包把“做什么、怎么做、输出什么”固化成了文件和代码模型的自由度被约束在一个相对确定的边界内。这里面有个很容易被忽略的点Skills 不只是脚本集合它是“说明书 执行器”的组合。说明书是给模型看的决定它什么时候调用、怎么传参数执行器是给系统跑的负责把结果稳定地算出来。两者缺一不可。只有脚本没有说明书模型不知道这个技能的存在只有描述没有脚本那跟提示词没区别。我自己的体会是技能包真正稳定的时刻是模型调用技能的概率变得可预测之后。你会看到它在合适的场景自动触发在不适用的场景果断放弃而不是每次碰运气。1.3 适用场景与边界哪些任务适合封装不是所有任务都适合做成 Skills。我在设计之前先定了一个判断标准这个任务是否有明确的输入、操作步骤和成功标准。如果答案是“有”就可以封装如果任务是开放式的、需要大量自由判断的比如“帮我润色一篇文章”“给我一个创意策划方案”那就不适合。适合封装的典型场景包括文件批量处理重命名、格式转换、归档、定时抓取某个网页或接口的数据、调用第三方 API 做信息查询、固定的代码生成流程比如生成项目骨架、数据清洗与统计分析。这些任务的共同特点是步骤可穷举、输出可校验、异常可处理。不适用的场景也很明显任务定义模糊、需要根据每轮对话重新脑补目标的事情封装成技能反而会限制模型。比如你让智能体“写一个漂亮的营销文案”这个东西没有固定流程也没有统一验收标准硬做成技能只会得到一个僵硬的结果。所以我的建议是第一批先选三个以内最简单、最频繁、边界最清楚的任务跑通整个流程再逐步扩大覆盖范围。2. Skills 项目的整体设计思路2.1 核心组成说明书 执行器一个标准的技能包我通常会分成四个部分技能描述文件、实现脚本、测试用例、示例文件。描述文件解决“模型什么时候用、怎么用”的问题实现脚本解决“活怎么干”的问题测试用例保证每次改动不破坏原有能力示例文件则给模型和开发者一个直观参考。描述文件是技能包的灵魂很多人不重视它觉得脚本写得足够好就行。但实际上模型调度技能的依据几乎全部来自描述文件。脚本写得再健壮如果描述里没有把“何时调用、参数怎么传、输出长什么样”写清楚模型要么不敢用要么乱用。所以我在项目里把描述文件放在目录最顶层命名为SKILL.md一眼就能找到。实现脚本则要遵循一个原则尽量把复杂逻辑放在脚本里简化模型的调用成本。原因也很简单模型对“从外部传入多个复杂参数再拼接结果”这件事的稳定性远不如对“传一个简单参数、拿到一段标准输出”的稳定性。你让模型决定太多细节出错率就会指数级上升。2.2 技能目录的骨架设计与命名规范目录结构看起来是个小事但等你攒了二十个技能之后就会发现命名和摆放方式决定了维护成本。我的推荐目录结构如下skills/ ├── date-query/ # 查询日期、星期、时区 │ ├── SKILL.md │ ├── scripts/ │ │ └── query.py │ ├── tests/ │ │ └── test_query.py │ └── examples/ │ └── basic-usage.json ├── file-organize/ # 按规则整理文件 │ ├── SKILL.md │ ├── scripts/ │ │ ├── organize.py │ │ └── utils.py │ ├── tests/ │ └── examples/ └── README.md命名规范上目录名我统一用小写加连字符的 kebab-case比如file-organize而不是fileOrganize或者整理文件。这样做的好处是在命令行操作时不需要切换输入法在配置系统里也避免大小写冲突。目录名尽量用“动词开头的短语”因为技能本质上是“做某件事”date-query比date更清楚file-organize比files更明确。另外我在每个技能包下都放了一个examples/目录里面存的是典型调用样例输入参数是什么、输出长什么样。这既方便我调试也能在训练模型调用时作为少样本参考。这一步不能省实测下来示例文件是否齐全直接决定了模型第一次调用技能的成功率。2.3 技能描述文件怎么写才能被模型真正理解这是整个 Skills 体系里最值得花时间打磨的部分。写SKILL.md时我始终把自己代入“一个什么都不知道的模型第一次看到这份文件要能独立完成一次调用”的角色。描述文件不是写给人类看的文档是写给模型看的操作手册因此必须同时包含用途说明、使用场景判断、参数定义、执行步骤、输出格式、注意事项这六项内容。一开始我写的第一版描述文件只有一句话“查询文件信息”。结果模型根本不知道什么时候调用参数也不知道该怎么传。后来我改成了结构化写法每个技能的描述文件都包含明确的触发条件和负面排除条件效果立刻好了很多。比如下面这个例子--- name: date_query description: 查询当前日期、星期、时间。用于回答“今天几号”“现在几点”等问题。 when_to_use: 用户询问当前日期、时间、星期、时区转换等时间类问题时使用。 input: timezone: type: string required: false default: Asia/Shanghai description: 时区名称例如 UTC、Asia/Shanghai output: type: text description: 一段人类可读的文本包含日期、星期、时间和时区信息 steps: 1. 执行命令: python scripts/query.py --timezone timezone 2. 将脚本标准输出直接返回给用户 notes: - 不要用于计算两个日期之间相差多少天这类需求请调用 date_calc 技能 - 如果用户未指定时区使用默认值 Asia/Shanghai --- # date_query 查询当前日期和时间的技能。脚本返回 JSON但请将结果转换成自然语言返回给用户。注意里面几个关键点。when_to_use是给模型判断触发条件的越具体越好input的required字段告诉模型哪些参数是必须的避免它自作主张地填一堆默认值notes里的负面约束同样重要它防止模型在错误的场景里调用技能。我在实际项目中加了“不要用于计算日期差”之后误触发率下降得非常明显。2.4 输入输出契约让结果是可预期的输入输出契约这个词听起来很正式实际上就是定义清楚“技能接收什么、返回什么、出错时怎么办”。很多人的脚本只定义了正常返回没定义异常情况模型拿到一个空输出或者乱码时根本不知道发生了什么。我的做法是实现脚本统一输出 JSON 格式正常结果和错误结果都包含status字段。正常时为ok异常时为error并在结果里附加message说明原因。这样模型拿到输出后可以先判断status再进行下一步处理而不是对着一个崩溃的脚本干瞪眼。例如文件整理技能的返回结果统一成下面这种结构{ status: ok, moved: 12, failed: 1, failed_files: [/path/to/bad.txt], detail: 共处理 13 个文件其中 12 个成功1 个因文件名过长失败 }如果出现异常就返回{ status: error, message: 目标目录不存在请先创建或检查路径, code: DIR_NOT_FOUND }这样的契约设计让模型在后续步骤里做判断变得非常轻松成功就继续失败就向用户报告错误或换一种方式处理。而且对于开发者来说调试也方便很多不需要猜脚本到底在哪一步出了问题。3. 从零实现一个可复用的 Skill3.1 场景选择与需求拆解拿我项目里一个真实的技能举例按规则整理下载文件夹。这个任务非常适合封装成 Skill因为规则明确、操作频繁、结果可验证。拆解下来需求包括扫描指定目录下的所有文件根据文件扩展名分类到不同子目录图片放images、文档放docs、压缩包放archives避免覆盖已有文件最后生成一份整理报告。在动手写脚本前我先把输入输出契约想清楚。输入很简单目标目录路径。输出就是前面提到的 JSON 结构。唯一需要额外考虑的是“是否启用模拟运行”我加了一个--dry-run参数让脚本先“假跑”一遍只输出将要移动的文件列表不实际移动。这个参数在调试期非常有用也给了模型一个安全的默认选项。需求拆解这个环节最忌讳的是把规则写死在脚本里。如果“图片归到 images”是写在脚本里的常量那以后用户想改成“图片归到 pics”就得改代码。更好的方式是把规则放在一个 JSON 配置文件里脚本启动时读取配置。这样技能的可复用性就大大提升了换一个场景只需要换配置不需要改逻辑。3.2 编写 SKILL.md 的实操过程拿到拆解后的需求我先写描述文件再写脚本。这个顺序很重要因为描述文件本质上就是需求的“可执行化表达”写清楚描述的过程会逼着你把需求的边界想明白。我在这个技能的SKILL.md里会把触发条件写得很具体--- name: file_organize description: 按扩展名规则整理一个目录中的文件移动到对应分类子目录。 when_to_use: 用户要求“整理某个文件夹”“按类型归档文件”“清理杂乱的下载目录”时使用。 input: directory: type: string required: true description: 要整理的目录绝对路径 dry_run: type: boolean required: false default: true description: 是否仅预览不实际移动文件。建议先传 true 让用户确认后再实际整理 output: type: json description: 包含 status、moved、failed 等字段的 JSON steps: 1. 运行: python scripts/organize.py --directory directory --dry-run dry_run 2. 如果 dry_run 返回的结果符合预期再以 dry_runfalse 运行一次 3. 将返回的 detail 字段整理成自然语言汇报给用户 notes: - 不要处理压缩文件内部的内容只移动文件本身 - 如果目录不存在直接返回错误信息不要创建目录 - 如果出现重名文件自动添加序号后缀 ---写完描述后再写脚本脚本实现时可以确认描述中定义的所有参数都是合理的。这也是一个双向校验的过程。描述文件如果要求传十个参数脚本就得处理十个参数脚本如果突然需要某个额外信息回头再去改描述文件。保持两者一致是整个项目长期运行的前提。3.3 脚本实现鲁棒性比花哨更重要脚本实现不复杂但我很关注两个容易被忽略的点路径安全和异常覆盖。很多第一次写技能的人会在路径上吃亏比如路径里有空格、有中文、有特殊符号。用 Python 的话我统一用pathlib而不是直接拼字符串这样路径处理会安全很多。下面是整理脚本的核心逻辑骨架#!/usr/bin/env python3 import argparse import json import shutil from pathlib import Path RULES { .jpg: images, .png: images, .gif: images, .pdf: docs, .docx: docs, .xlsx: docs, .zip: archives, .tar.gz: archives, .rar: archives, } def organize_directory(directory: Path, dry_run: bool True): if not directory.exists() or not directory.is_dir(): return {status: error, message: 目标目录不存在, code: DIR_NOT_FOUND} moved 0 failed 0 failed_files [] for file in directory.iterdir(): if file.is_dir(): continue matched False for suffix, category in RULES.items(): if file.name.endswith(suffix): target_dir directory / category target_dir.mkdir(exist_okTrue) target_path unique_path(target_dir / file.name) if dry_run: matched True moved 1 break try: shutil.move(str(file), str(target_path)) moved 1 matched True break except Exception as e: failed 1 failed_files.append(str(file)) if not matched: failed 1 failed_files.append(str(file)) return { status: ok, moved: moved, failed: failed, failed_files: failed_files, detail: f共处理 {moved failed} 个文件成功 {moved} 个失败 {failed} 个 } def unique_path(path: Path) - Path: if not path.exists(): return path index 1 while True: candidate path.with_stem(f{path.stem}_{index}) if not candidate.exists(): return candidate index 1 if __name__ __main__: parser argparse.ArgumentParser(descriptionOrganize files by extension) parser.add_argument(--directory, requiredTrue) parser.add_argument(--dry-run, typebool, defaultTrue) args parser.parse_args() result organize_directory(Path(args.directory), args.dry_run) print(json.dumps(result, ensure_asciiFalse))注意unique_path这个函数它解决了重名文件的问题。如果没有这一步脚本遇到重名文件时要么直接覆盖要么抛出异常整个任务就中断了。加上自动加后缀的逻辑之后碰到文件重名可以继续执行模型的整体任务完成率直接上一个台阶。3.4 本地调试与端到端验证技能写完了不要急着接模型先自己在命令行里调一遍。我会构造几个有代表性的目录空目录、全是未分类文件的目录、包含子目录的目录、包含重名文件的目录。每个场景都跑一遍--dry-run true确认输出符合预期后再跑一次--dry-run false检查实际移动结果。调试通过后还要做一个端到端验证让模型根据这个SKILL.md自主调用看它能不能正确理解参数、执行步骤、输出格式。这一步经常会暴露描述文件里的模糊地带。比如我发现模型经常把dry_run参数省略掉然后直接执行整理后来我在描述里把dry_run的默认值改成true并明确写了“建议先预览再实际整理”行为就正常了。端到端验证的另一个作用是检查模型对输出 JSON 的解析能力。如果脚本返回的 JSON 结构嵌套太深模型在后续总结时容易漏掉信息。我的原则是JSON 保持在两层以内关键信息尽量都放在顶层这样模型一眼就能看到核心字段。4. 常见问题与排查技巧实录4.1 描述写得挺全模型就是不调用这是所有人都会遇到的第一道坎。明明描述文件写得清清楚楚脚本也能正常跑模型就是像没看见一样继续用自己臆想的方式处理任务。排查这个问题的第一步是看你的描述里有没有“场景判断”的锚点。如果你的when_to_use只写了“用于处理文件”那模型很难把它和用户的“帮我整理一下桌面”关联起来。更好的写法是给出具体的用户表述示例比如“当用户说‘整理下载文件夹’‘归类图片’‘把桌面搞干净’时”。第二个常见原因是参数太复杂。如果技能需要传五个参数模型计算出每个可靠参数的概率就会下降一旦某个参数不确定它很可能放弃整个技能。解决方法是提供默认值让所有参数都有兜底或者把多个参数封装成一个路径配置。第三个原因则是模型没在历史对话里看到过这个技能的调用示例你可以先在描述里写一段“调用示例”展示标准输入输出。4.2 技能执行报错输出不符合预期脚本报错分两类一类是脚本自身的 Bug另一类是环境问题。自身 Bug 只能靠测试用例去兜环境问题却可以通过一个习惯大幅减少——脚本启动时用绝对路径并在入口处检查依赖。我踩过一次很典型的坑某个技能依赖第三方库平时机器上装着换了一台新机器后没有安装脚本直接崩溃。后来我在所有技能脚本的入口处都加了一个统一的依赖检查函数如果发现缺依赖就返回一个结构化的错误 JSON而不是抛异常。这样模型虽然无法完成任务但至少能把错误信息反馈给用户用户知道下一步去装依赖而不是面对一段完全摸不着头脑的报错。如果输出结构不符合预期比如字段名变了、多了一层嵌套那问题多半出在脚本修改后没有同步更新SKILL.md。我要求自己改脚本后必须同步更新描述里的output部分否则模型拿到的说明就是过时的。4.3 技能包多了之后维护混乱当技能数量超过十个你一定会遇到两类问题一类是技能间功能重叠两个技能可以处理同一个任务另一类是描述里的触发条件写得太宽导致模型选错技能。功能重叠很好解决在开发新技能之前先检索目录如果已有技能能覆盖大部分需求就优先扩展旧技能而不是新建一个。触发条件过宽的问题我会在描述里增加“不要用于……”的负面约束把容易混淆的场景明确排除出去。维护混乱还有一个隐蔽因素命名不规范。目录名、技能名、脚本名如果不一致后期维护时连自己都会困惑。我的命名习惯是目录名file-organize脚本organize.py技能名称file_organize三者保持同一前缀规则统一。4.4 更新不生效与热加载问题模型平台对技能配置往往有缓存你改了描述文件后可能半天之后模型还在用旧版本。最直接的解决办法是更新技能的版本号字段。我在SKILL.md的前置元数据里加了一个version字段每次修改就递增一次。很多平台在检测到版本号变化时会刷新缓存实测这个办法比单纯改内容有效得多。如果版本号也无效说明平台的缓存策略更严格那就只能重启会话或等待缓存过期。另外不要在旧技能上频繁打补丁式修改每一次修改都应该是完整的、可测试的版本更新。我常用的做法是修改内容与版本号一起提交测试通过后再发布避免“改了一半”的状态被模型看到。这里整理了一份我项目里的问题速查表问题现象最可能的原因快速排查方法模型完全不调用技能描述中没有明确的触发条件在when_to_use中加入具体用户说法调用时参数传错参数定义模糊或缺默认值给所有参数设置默认值并在描述里标注 required脚本直接崩溃依赖缺失或路径错误脚本入口增加依赖检查和路径校验输出格式混乱脚本修改后未同步更新描述检查output字段与脚本实际返回是否一致新旧技能混淆触发条件重叠增加负面约束明确各技能边界更新不生效平台缓存递增版本号并重启会话5. 让技能包长期可用测试、版本与迭代5.1 给技能写测试省下的都是时间很多人一开始会跳过技能测试觉得脚本跑一次没问题就够了。但脚本是会被改的描述文件也是会变的每一次改动都可能引入回归问题。写测试并不意味着高大上的 CI/CD哪怕只是一个小脚本也能在长期维护中节省大量时间。我会为每个技能准备一组测试用例和期望结果。比如file-organize测试里我构造了一个临时目录放入各种类型的文件加上一个重名文件然后断言脚本执行后目录结构是否符合预期。测试代码本身不用很复杂python -m pytest skills/file-organize/tests/ -q这个命令我每次修改脚本之后都会跑一遍。如果测试通过我才有信心让模型重新调用这个技能。测试用例也是很好的“文档”新同事或未来的我接手这个技能时只要看测试用例就能快速理解技能的行为边界。5.2 版本管理技能包也需要 Changelog技能包本质上是一个软件工程产物版本管理当然不能少。我采用轻量级的版本管理方式每个技能包目录内维护一个CHANGELOG.md记录每个版本变更内容同时在SKILL.md的元数据中递增version。Git 标签用于记录重大版本日常小改动只需要维护 Changelog 和版本号。版本管理的好处体现在两个场景。其一模型调用出问题时你可以快速定位当前版本回退到上一个稳定版本。其二当多个技能包共享同一个公共函数时版本记录能帮你追踪“上次改公共逻辑后哪些技能受影响”。没有版本管理技能多了以后“改一个坏一片”会变成常态。5.3 迭代经验少而精持续打磨最后说说迭代节奏。我一开始犯过贪多的错误一周内做了十几个技能结果大多数都没用上。后来学乖了聚焦在频率最高、最稳定可靠的三个技能上反复打磨它们包括优化描述措辞、增加异常处理、补充测试用例。技能数量少而精维护成本可控模型的选择准确率也更高。迭代过程中最重要的一条经验是持续收集失败案例。每次模型调用技能出错不管是参数问题、脚本问题还是输出问题都记录下来定期总结然后针对性地修改描述或脚本。这个循环做下来我的技能是“越用越准”而不是“越用越乱”。还有一个小技巧在描述文件里注明“此技能目前已经稳定运行 N 次”这句话对模型没有意义但对你自己的信心维护非常有效——看看调用次数统计你就知道哪些技能值得继续投入哪些应该下线。我个人实际操作下来最大的体会是一个技能能不能被真正用起来关键不在脚本有多复杂而在于描述文件有没有把边界说清楚。我一开始写 Skills 时恨不得一个技能覆盖所有场景结果模型经常在错误的场景里调用它反而产生了一堆不可预期的行为。后来在描述里加上“不适合用于……”之后误触发率降得特别明显。如果你也想搭自己的技能包建议从两三个高频、边界清楚的小技能开始跑通完整流程再扩量。这套体系一旦成型后续新增能力其实就是“写描述、写脚本、补测试”这三件事前期投入会越来越值得。