1. Skills 的本质与工程化设计1.1 从“对话智能”到“执行智能”最近大半年AI Agent 这个词几乎被聊烂了。从最早只会“你问我答”的对话助手到能自己规划步骤、调用工具、执行脚本的智能体变化非常明显。但接触的团队越多越发现一个共性问题很多人做了一个 Agent 的 Demo能回答几个问题能调一两个 API就认为“跑通了”。真正扔到生产环境问题立刻冒出来——技能文件散落各处模型频繁挑错工具脚本改了没有记录出了故障不知道回滚到哪个版本。说白了Agent 光有脑子不够还得有手。这双手就是技能系统Skills。而让这些技能稳定、可控、可维护地运转就需要一套工程工作流。一个没有 Skills 的 Agent 只能基于预训练知识做“文本推演”本质上和搜索引擎加文本生成的差别不大。一旦接入技能Agent 才真正具备了“读取系统状态、操作文件、调用接口、执行计算”的能力。举个例子让 AI 生成一份周报没有技能时它只能给你一段模板文字有了技能它可以主动运行收集命令、读取 git 提交记录、扫描项目目录文件再把这些真实数据组织成结构化报告。这就是“执行智能”和“对话智能”的分水岭。有人会问为什么不直接在 Prompt 里让 AI 写 Python 代码来完成这些事答案很简单——LLM 当场生成的代码不稳定很容易出现依赖缺失、路径写错、语法出错等问题。与其让模型临场发挥不如把固定操作固化成经过测试的技能脚本。开发者的价值就是把 AI 不可控的“临场发挥”变成可控的“标准动作”。1.2 技能工作流的三条设计原则做技能系统之前先立三条原则。第一条技能要薄逻辑要厚。模型负责理解意图、选择技能、汇总结果脚本负责精确执行。不要把复杂的业务逻辑塞进自然语言描述里那是模型最不擅长的工作方式。数据清洗、文件处理、指标计算这类逻辑全部下沉到脚本模型只保留一个简单的调用入口。第二条一切可复现。技能目录结构必须是固定的每个技能都有明确的名称、描述、参数、测试用例和变更记录。任何人接手一套技能库只要按文档操作就能在本地跑起来。最忌讳的是“一个人写了一套技能走了之后没人能维护”。第三条失败要可控。技能执行失败不能卡死整个 Agent 流程要能识别失败原因、给出明确错误信息、必要时自动重试或回退。一个技能如果失败时只能吐出一段莫名其妙的长英文报错那这种技能就不合格。这三条原则决定了下文所有技术方案的选择方向。1.3 技能边界单体技能与复合技能实际项目里技能最好分两类看待。单体技能只做一件独立的事比如“查询磁盘剩余空间”“批量重命名某个目录下的文件”“读取某个接口的数据并存为 JSON”。这类技能的特点是职责单一、参数少、输出稳定非常适合作为技能库的第一批成员。复合技能则要编排多个步骤比如“生成项目周报”这一件事背后往往要读取 git 提交记录、统计代码变更量、读取项目配置文件、生成 Markdown 文档。如果把这些逻辑全塞进一个技能脚本里脚本会变得又长又笨模型选择一个技能时很难判断它到底适不适用手头的需求参数传递也容易出错。我比较推荐的做法是“小技能 上层编排”。把收集提交记录、统计变更量、渲染模板分别做成三个独立的小技能再让 Agent 的任务层或工作流引擎按顺序调用它们。这样每个技能都可以单独测试、单独复用失败时也能精确定位到具体步骤。刚开始搭技能库时一定要抵挡住做“万能技能”的诱惑。2. 技能目录与配置规范2.1 标准目录结构技能系统想工程化第一步是统一目录结构。目前主流 AI Agent 框架大多采用“一个技能一个目录”的组织方式目录内放说明文件、脚本、资源和测试。一个我常用的标准布局如下skills/ └── weekly-report/ ├── SKILL.md ├── scripts/ │ ├── collect_metrics.py │ └── render_report.py ├── resources/ │ └── report_template.md └── tests/ ├── test_collect_metrics.py └── fixtures/ └── sample_git_log.txtSKILL.md 是这个技能的“说明书”模型靠它理解什么时候该用、参数怎么传。scripts 目录放可执行脚本resources 放模板和静态配置tests 放测试用例和模拟数据。这个结构看似简单但统一之后收益立竿见影新人接手时不用猜自动化工具可以按固定路径扫描技能版本对比也可以精确到文件级。目录命名必须直观比如 report-generator、disk-cleaner不要用 dev_tool_01 这种毫无语义的命名。2.2 SKILL.md 里该写什么SKILL.md 是整个技能系统里最关键的配置文件模型对技能的理解几乎完全来自这份文档。写不好脚本再牛逼也白搭。我一般按下面几个板块组织技能名称必须简洁且唯一通常是“动词-名词”形式比如 generate-weekly-report。功能描述用两到三句话说明这个技能做什么以及它适合哪些场景。参数定义每个参数的类型、必填性、默认值、含义。执行命令模型调用技能时应该执行的命令包含参数模板。示例一个完整的调用示例这是模型参考价值最高的部分。边界与限制什么情况下不要用这个技能能显著减少误用。实际效果参考一份 SKILL.md 的写法--- name: generate-weekly-report description: 生成团队周报。适用于用户要求统计本周工作内容、整理 git 提交记录、或生成项目进展摘要的场景。 parameters: - name: team_name type: string required: true description: 团队名称用于报告标题 - name: since type: date required: false description: 统计起始日期默认本周一 - name: output_dir type: string required: false description: 输出目录默认当前目录 --- 运行以下命令生成周报 python3 scripts/collect_metrics.py --since {{since}} --repo {{repo_path}} python3 scripts/render_report.py --data metrics.json --template resources/report_template.md --output {{output_dir}}/weekly-report.md注意一个细节参数模板用{{since}}这种占位符不要直接写具体日期。模型在调用时会按照上下文替你完成参数填充你传的占位符越规范模型就越知道你期望它做什么。2.3 描述与参数一次写好模型按提示选择技能描述看似只是几句话实际是模型做“技能选择”的最重要依据。我的经验是描述必须写成“用户潜在表达”的样子而不是写成技术文档摘要。比如一个错误示范是“提供文件处理能力”这种描述太宽泛模型根本分不清它和另一个“文件管理技能”有什么差别。更合适的写法是“批量将 CSV 文件转换为 JSON 格式适用于用户上传 CSV 后需要结构化数据的场景”直接点出输入、操作、输出和应用场景。参数定义同样需要精细。必填参数必须标required: true带默认值的参数要写明默认值。类型最好明确是 string、integer 还是 array模型在生成调用时会按类型自动处理。还有一个很容易被忽略的点给每个技能加“不适用场景”或者“边界”说明。比如一个“查询代码仓库信息”的技能明确写一句“如果用户只是要写一段示例代码请勿调用本技能直接回答即可”。看似多此一举实测下来能避免大量误调用。2.4 脚本与资源的组织方式脚本是整个技能的执行核心工程化程度直接影响稳定性。我的建议是脚本必须自包含不要依赖执行时现场安装的包所有第三方依赖写在单独的requirements.txt里并在 README 中注明安装命令。入口设计统一走命令行接口参数用标准的 argparse 或类似方式解析输入输出尽量保持简单结果输出到 stdout错误输出到 stderr退出码为 0 表示成功、非 0 表示失败。复杂结果以 JSON 或 Markdown 格式输出模型读取结构化结果比读取普通文本要准确得多。资源文件只放静态内容比如报告模板、配置文件、示例数据。不能把临时生成的文件放进 resources否则会在版本控制里制造大量噪音。再说一个实操细节脚本文件头要加#!/usr/bin/env python3和# -*- coding: utf-8 -*-并且指定 Python 版本避免不同环境下解释器不一致导致技能执行失败。3. 实操从零搭建一套可用的技能工作流3.1 初始化技能仓库与版本管理动手第一步创建一个 monorepo 风格的技能仓库。这样做的好处是技能与技能之间可以通过相对路径引用公共库版本管理也集中在同一个仓库里。初始化时我会做这几件事mkdir agent-skills cd agent-skills git init mkdir skills touch README.md然后在根目录放一份pyproject.toml声明公共依赖和 Python 版本。每个技能目录内单独保留requirements.txt避免所有技能共享一个依赖清单导致升级时的相互影响。版本管理我使用 git tag。技能达到可发布状态时打一个 tag比如skills-weekly-report-v1.0.0线上服务加载时指定版本范围需要回滚时直接切换到上一个 tag。这个习惯在多人协作时非常关键——你把描述改了一个字可能就改变模型对技能的判断所以任何变更都必须有版本记录。3.2 实现第一个实用技能数据整理用一个实际场景演示技能开发全过程让 Agent 能够在收到 CSV 文件后输出一份清洗后的 JSON 文件和摘要。第一步建立技能目录和脚本。我选择实现一个名为csv-cleaner的技能mkdir -p skills/csv-cleaner/{scripts,resources,tests}第二步编写核心脚本clean_csv.py。脚本逻辑很简单读取 CSV去除重复行填充缺失字段默认值输出 JSON。#!/usr/bin/env python3 import argparse import csv import json import sys from pathlib import Path def main(): parser argparse.ArgumentParser(descriptionClean a CSV file and output JSON.) parser.add_argument(--input, requiredTrue, helpInput CSV file path) parser.add_argument(--output, requiredTrue, helpOutput JSON file path) parser.add_argument(--fill-missing, defaultunknown, helpValue for missing fields) args parser.parse_args() input_path Path(args.input) if not input_path.exists(): print(fERROR: input file {input_path} not found, filesys.stderr) sys.exit(1) rows [] with input_path.open(encodingutf-8) as f: reader csv.DictReader(f) for line in reader: cleaned {k: (v if v else args.fill_missing) for k, v in line.items()} rows.append(cleaned) deduplicated [dict(t) for t in {tuple(r.items()) for r in rows}] with open(args.output, w, encodingutf-8) as f: json.dump({records: deduplicated, total: len(deduplicated)}, f, ensure_asciiFalse, indent2) print(json.dumps({output: str(args.output), total: len(deduplicated)}, ensure_asciiFalse)) if __name__ __main__: main()第三步编写 SKILL.md把技能描述、参数和调用示例写清楚。这一步是整个技能能否被模型正确调用的关键描述里要明确输入是“CSV 文件路径”输出是“JSON 文件路径和记录总数”同时给出一个完整调用示例。第四步本地测试。准备好一个包含重复项的sample.csv运行脚本检查输出 JSON 是否符合预期。这一步千万别省脚本一旦上线模型会以你从未想到的方式调它。3.3 技能加载手动与自动的取舍技能做好之后需要考虑怎么让 Agent 加载它。主流的加载方式有三种。手动加载是固定的你显式配置一个技能列表Agent 每次运行都携带这份列表。优点是行为可预测模型只会在这几个技能里做选择不会乱调用缺点是不够灵活技能数量一多全量携带会消耗大量上下文窗口。自动加载则相反Agent 根据用户的当前请求从一个大的技能库中动态挑选可能相关的技能。优点是灵活缺点是选择有时不靠谱很容易出现“选错技能”的情况尤其在技能描述写得模糊的时候。混合加载是我现在用得最多的方案核心技能常驻长尾技能动态加载。常驻技能数量控制在 5 个以内通常是最高频使用的其他技能放在索引里由模型按需检索。这个方案兼顾了稳定性和灵活性生产环境建议优先复用。3.4 把复杂逻辑下沉到脚本保持技能“薄”刚开始做技能系统的人最容易犯的一个错误是让 Agent 在描述里编写内联代码或者试图用自然语言描述所有逻辑步骤。比如让模型“先检查每一行有没有空值如果为空就填 unknown再去重再转 JSON”这不是技能系统这是靠运气做工程。正确姿势是把这类确定性逻辑全部写进脚本SKILL.md 只描述“你要处理什么输入会得到什么输出怎么调用”。这样模型不需要理解 CSV 去重的细节只负责判断“用户要清理 CSV我应该选 csv-cleaner 技能”。优势非常明显。第一脚本是经过测试的不会像模型现场写代码那样出现语法错误和逻辑漏洞。第二执行结果稳定输入相同输出一定相同便于排查问题。第三token 消耗大大降低模型不再需要在上下文中生成一大段代码。第四脚本可以独立优化比如性能问题、边界问题都只改脚本体不动 SKILL.md 和模型行为。4. 工程化流程测试、发布与监控4.1 技能开发的标准流程技能系统要长期维护必须有一套标准开发流程。我在项目里规定每个技能从需求到上线至少要经过七个环节。需求描述用几句话说明技能要解决什么问题给出两个典型的用户输入示例。编写 SKILL.md 草稿重点是写清楚描述、参数和调用示例先给业务方评审描述是否容易被理解。实现脚本严格遵守统一 CLI 约定输出结构标准化。编写测试覆盖正常流程、边界条件、错误输入。本地联调用小样本对话验证模型能否正确选择并调用该技能。评审与合并至少一名同事评审技能描述和脚本实现。打标签发布按语义化版本打 tag更新技能库索引。这套流程看起来有点重但一旦技能数量超过十个没有流程约束几乎一定会乱。哪怕是一个人维护也要按这个流程走因为你会忘掉自己两个月前写的细节。4.2 测试策略单元测试、集成测试与回放验证技能测试不是“脚本能跑就行”至少要覆盖三层。单元测试只针对脚本用 pytest 直接调用脚本里的函数验证数据处理逻辑。比如clean_csv.py对空值、乱序字段、非法字符的处理是否正确。这些测试跑得飞快每次改代码都要全量跑一遍。集成测试验证“模型调用脚本”这条链路。方式是用一个模拟的用户请求让 Agent 选择技能并执行脚本最后断言输出文件的格式和内容。这种测试适合放到 CI 里每次提交代码后自动跑。回放验证是我近期比较依赖的一种测试方式。把历史真实对话中的技能调用记录存下来包括当时用户的请求、模型选择的技能、传入的参数。技能升级时用同一批请求重新跑一遍对比新旧输出检查有没有行为漂移。这个方法能发现很多稀奇古怪的问题比如你只改了一行描述模型就从选技能 A 变成选技能 B 了。沙箱验证也值得一提。所有需要连接外部系统或真实数据的技能在测试阶段一律在隔离环境中执行用模拟数据和 mock 接口替代真实依赖保证测试不会因为外部故障而失败。4.3 灰度发布与回滚策略技能发布和代码发布一样最忌讳一次性全量上线。我会先在受限环境里加载新版本技能让少量内部会话使用观察调用成功率和输出质量。为什么需要灰度因为技能的“逻辑正确”和“模型正确使用它”是两件完全不同的事。脚本写得再好如果新描述让模型产生了误解线上就会出现大量误调用或拒绝调用。灰度阶段重点观察的是调用次数是否合理、选择是否准确、失败率是否异常。回滚策略我建议做到“一键级别”每个技能发布时保留上一版本的完整目录快照线上加载器支持按 tag 切换版本。出问题时只需要把加载器配置里的版本号改回去然后重新加载技能索引。整个过程应该在五分钟内完成而不是翻 git 历史重新部署。4.4 调用日志与质量评估技能上线之后必须建立监控。裸奔的技能库跟写了代码不提交 git 一个性质。每次技能被调用至少记录以下字段技能名称、触发时间、调用耗时、退出码、错误信息如果有、传入参数摘要、关联的会话 ID、消耗的 token 数。这些日志统一写入结构化存储方便后续按技能维度做聚合分析。我这里有一个简单可用的质量评估指标技能失败率 调用失败次数 / 总调用次数超过 5% 需要立刻排查技能召回率指的是“用户有真实需求时模型是否正确选择了该技能”这个指标没有自动化手段时可以抽样人工审核。日志还有一个重要用途是优化技能描述。翻看日志时会发现模型在某些场景下选错了技能比如用户说的是“处理一下这个 Excel”模型却选中了 csv-cleaner 而不是 excel-processor。这类 case 积累到一定数量就要反向修改 SKILL.md 的描述把这类用户表达写进新技能的描述里或者写进旧技能的“不适用场景”里。5. 常见问题排查实录5.1 技能老是选错或答非所问这个问题的出现概率最高根因往往不在模型而在技能描述。模型不会“记住你心里的预期”它只能根据 SKILL.md 的文本做判断。排查方向按顺序来先确认是不是多个技能描述重叠了。把技能列表中所有 SKILL.md 的描述并排列出来看是否存在“谁都像谁”的情况。比如“整理数据”“处理数据”“转换数据”三个描述放在一起模型能分清才怪。修复方式第一描述里加入典型用户提问的原文比如“当用户说‘帮我把这个 CSV 清理一下’时使用本技能”第二给容易混淆的技能之间增加排除性描述比如在 csv-cleaner 里写“本技能不处理 Excel 文件需要处理 xlsx 请选择 excel-processor”第三简化参数名不要用内部叫法直接用用户能理解的业务术语。改完描述之后一定要做回放测试拿历史对话跑一遍确认选择准确率确实提升而不是靠感觉。5.2 脚本执行失败路径、权限和时间耗尽脚本失败常见的有三类先说路径问题。Agent 执行脚本时的工作目录不一定是技能所在目录你在本地写相对路径能跑线上很可能报“文件找不到”。解决办法是脚本内部用入口文件定位自身目录from pathlib import Path BASE_DIR Path(__file__).resolve().parent.parent然后用BASE_DIR拼接所有资源和输出路径绝不依赖进程当前工作目录。权限问题多发生在读取系统状态或写入特定目录时。技能脚本要提前检查目标目录是否存在、是否可写不行就输出明确错误并退出不要抛一个 Python traceback 让模型试图去猜。超时问题更隐蔽。模型在平台上调用技能通常有超时限制长时间执行的脚本可能直接被平台杀掉。解决办法是脚本内部设置处理超时、分批处理大数据集并且卡住时把执行状态及时写入文件这样即使被杀也能在下次运行时从断点恢复。5.3 技能更新不生效明明改好了 SKILL.md实际测试时发现模型还在用旧版本让人非常抓狂。这类问题先看有没有缓存。很多 Agent 框架会把技能描述在会话启动时固定下来运行中不会重新读取文件改动。修改技能后需要重新加载索引、重启会话或者等待缓存失效。再看版本号有没有变化。如果 git tag 没更新线上加载器可能仍指向旧版本。我的习惯是任何技能变更都同步升级小版本号哪怕只是改了一个字的描述也至少 bump patch 版本。这样排查时能明确分辨“我改的东西有没有被加载到”。实在不行就在技能索引里加一个“最后更新时间”字段日志里也能准确定位当前会话到底加载的是哪一版技能。这个字段很小但在多人协作时能省掉一大半沟通成本。5.4 并发调用时的状态污染技能系统一旦跑真实业务并发调用就躲不开。多个会话同时调用同一个技能如果脚本用了固定临时文件或固定输出路径就会出现文件互相覆盖、数据错乱的问题。解决办法是彻底隔离会话状态。脚本内临时文件一律用tempfile.mkdtemp()创建输出文件名加随机后缀或会话 ID。比如import tempfile import uuid tmp_dir tempfile.mkdtemp(prefixskill-clean-) session_id uuid.uuid4().hex output_path Path(args.output_dir) / fresult_{session_id}.json不要让技能脚本修改任何全局共享目录也不要依赖内存中的全局变量。幂等性也是一个重要指标同一个技能在相同输入下多次执行结果应该完全一致。如果有随机因素要显式固定随机种子并有日志解释。6. 写在最后我的几点体会做技能系统这几个月我最大的体会是AI Agent 的工程化核心不是把模型调得多聪明而是把外部世界变得足够可靠。技能的脚本层就是 Agent 和真实系统之间的“减震器”。你不可能指望模型每次都能写出正确的文件处理代码但你可以写一个经过测试的脚本让它调用几百次。我建议所有刚开始搭技能库的朋友克制住一次做十几个技能的冲动。先挑三个最高频、最底层的操作做成技能把它们做到描述清晰、脚本健壮、测试完备。跑两三个星期之后再用回放数据去优化描述、调整参数慢慢地你的技能库会从“能用”变成“好用”。最后分享一个我认为最有价值的小技巧每个技能在发布时保存一条“实测用例对话”。这条对话记录了三样东西——用户原话、模型正确选择的技能、模型传入的参数。下个版本的维护者打开仓库一眼就能看到这个技能的预期效果比读一万字文档都有用。这个习惯我一直在用也是我能把几十个技能维护下来不翻车的重要原因。