★ FEATURED ARTICLE 1. 从“skills”这个标题说起它到底指什么第一次看到“skills”这个标题很多人会以为是泛泛而谈的“技能”二字没什么信息量。但结合热词里反复出现的 Google Cloud、Agent Skills、npx、GKE、claude agent skills、codex skills 这些词基本可以锁定它讨论的是智能体技能体系——也就是给 AI Agent 挂载可复用能力模块的那套机制。简单说就是让一个只会聊天的模型变成能真正动手干活的“数字员工”。它解决的问题很具体模型本身是通用的但具体业务需要它查数据库、调接口、跑脚本、生成报告、操作云资源。如果每次都靠一段超长提示词硬塞既不稳定也不可维护。Agent Skills 的思路是把这些能力拆成一个个独立、可描述、可加载的“技能包”按需挂载、按需调用。适合谁来参考一是正在做 AI 应用落地的开发者二是想把重复工作自动化的运维和数据分析人员三是想理解这套机制到底怎么跑起来的技术爱好者。我接触这套东西的起点是看到热词里“claude agent skills: a first principles deep dive”和“codex skills”同时出现。这说明它不是某一家独有的概念而是正在形成一种跨平台的通用范式。下面我按自己的理解把这套体系从设计思路到落地实操完整拆一遍。2. 技能体系的整体设计与思路拆解2.1 为什么要把能力拆成“技能”而不是写死提示词最直接的原因是上下文窗口的稀缺性。一个 Agent 如果同时挂载几十个能力每个能力的说明、参数、示例都塞进系统提示里token 消耗会迅速膨胀而且模型在长上下文里对细节的注意力会下降。我实测过一个场景把五个工具的完整说明写进提示词模型调用正确率还能维持在九成以上写到十二个工具时正确率掉到七成左右经常张冠李戴。技能化拆分的逻辑是把“能力描述”和“能力实现”分离。描述部分保持精简只在需要时加载实现部分放在外部由运行时按需调用。这就像公司里不是把所有人的岗位说明书都贴在墙上而是有一本通讯录需要找谁再翻到那一页。好处有三个上下文占用可控、技能可以独立迭代、不同项目之间能复用。2.2 技能包的核心结构长什么样一个标准的技能包我见过的实现基本都包含这几块元数据名称、版本、描述、触发条件、参数定义输入输出的 schema、执行逻辑脚本或接口调用、示例给模型看的调用样例。元数据里的描述最关键它决定了模型在什么情况下会想到用这个技能。描述写得太窄模型该用的时候想不起来写得太宽又会误触发。参数定义我建议用 JSON Schema 来写因为主流模型对 JSON Schema 的理解最稳定。执行逻辑可以是本地脚本、HTTP 接口、也可以是云函数。示例部分不要省两三个正例加一个反例能显著提升调用准确率。我踩过的坑是早期图省事只写描述不写示例结果模型经常把参数名拼错或者把可选参数当成必填。2.3 跨平台复用的现实考量热词里同时出现 Google Cloud、GKE、npx说明这套技能体系不是绑死在某个模型上的。npx 是 Node 生态的包执行器意味着技能可以做成 npm 包分发GKE 是容器编排意味着技能可以容器化部署。这种设计的好处是同一个技能包既能在本地开发环境跑也能推到云端给生产环境的 Agent 用。我自己的做法是技能的核心逻辑写成一个独立的可执行单元外面套一层适配层。适配层负责把不同平台传来的参数转成统一格式再把结果转回去。这样换平台时只改适配层核心逻辑不动。这个思路在热词“agent skills测试”里也能得到印证——测试的重点往往不是逻辑本身而是适配层在不同平台下的行为一致性。3. 核心细节解析与实操要点3.1 技能描述文件的写法与避坑描述文件是模型决定“用不用这个技能”的唯一依据写法上有几个硬性经验。第一动词开头比如“查询”“生成”“转换”不要用“用于查询”这种被动表述。第二明确边界写清楚什么情况下用、什么情况下不用。第三控制长度我一般把描述压在 80 到 120 个字符之间太短说不清太长模型抓不住重点。一个反面例子是我早期写的“这个技能可以处理数据。”模型看到这句话完全不知道什么时候该调用。改成“将 CSV 文件转换为 JSON 格式适用于结构化数据导入场景”之后调用准确率明显上升。另外描述里不要出现歧义词汇比如“可能”“大概”“也许”这些词会让模型犹豫。注意描述文件里的触发条件不要和别的技能重叠。我有一次两个技能都写了“处理文本”结果模型在两个之间反复横跳最后哪个都没调对。后来把其中一个改成“处理纯文本”另一个改成“处理带格式的富文本”问题就解决了。3.2 参数 schema 的设计细节参数 schema 我建议遵循几个原则。必填参数尽量少能设默认值的就设默认值。参数名用下划线命名法和大多数编程语言的习惯保持一致。类型要写清楚字符串、数字、布尔、数组、对象不要用 any 这种模糊类型。对于枚举类型的参数一定要把可选值列全。我见过一个技能参数叫“格式”描述里只写了“输出格式”没列可选值结果模型自己编了一个“pdf”传进去而实际只支持 json 和 csv。后来我把枚举值写进 schema并在描述里也重复一遍这类错误就基本消失了。还有一个细节是参数之间的依赖关系。比如某个参数只有在另一个参数为特定值时才需要传。这种依赖关系要在描述里写清楚或者在执行逻辑里做校验并返回明确的错误信息。模型看到错误信息后往往能自我纠正。3.3 执行逻辑的健壮性设计执行逻辑最容易出问题的地方是异常处理。技能被调用时输入不一定完全符合预期网络可能超时外部接口可能返回错误。我的做法是所有外部调用都加超时所有可能失败的地方都返回结构化的错误信息而不是直接抛异常。结构化错误信息要包含三部分错误类型、错误原因、建议的修正方式。比如“参数格式错误日期应为 YYYY-MM-DD 格式收到的是 2024/01/01请转换后重试。”模型拿到这种信息很多时候能自己改对再调一次。如果只返回一个“Error”模型就懵了。另外执行逻辑要幂等。同一个请求调两次结果应该一致不能产生副作用。这在重试场景下特别重要。我有个技能是往数据库写记录早期没做幂等网络抖动重试了一次结果写了两条重复数据。后来加了唯一键约束问题才解决。3.4 技能加载与卸载的时机技能不是越多越好。我实测下来同时挂载的技能数量控制在 8 到 12 个之间比较合适。超过这个数模型的调用准确率会下降。所以需要根据当前任务动态加载和卸载技能。加载时机一般是在任务开始前根据任务类型预判需要哪些技能。卸载时机是在任务完成后或者切换到不相关的子任务时。有些运行时支持按需加载就是模型先看到一个技能列表决定用哪个再加载详细描述。这种方式上下文占用更小但多了一次交互往返。提示如果你的运行时支持技能分组把相关的技能放在一组里按组加载。比如“数据处理组”“文件操作组”“网络请求组”。这样比单个加载效率高也比全部加载省上下文。4. 实操过程与核心环节实现4.1 从零搭建一个最小可用技能我拿一个实际做过的例子来演示一个“查询天气”的技能。虽然简单但涵盖了完整流程。第一步建目录结构。我习惯这样组织skills/ weather-query/ skill.json index.js examples/ basic.json第二步写skill.json{ name: weather-query, version: 1.0.0, description: 查询指定城市当前天气返回温度和天气状况, parameters: { type: object, properties: { city: { type: string, description: 城市名称如北京、上海 }, unit: { type: string, enum: [celsius, fahrenheit], default: celsius, description: 温度单位 } }, required: [city] } }第三步写执行逻辑index.jsconst axios require(axios); module.exports async function(params) { const { city, unit celsius } params; if (!city || typeof city ! string) { return { error: INVALID_PARAM, message: city 参数必须是非空字符串, suggestion: 请提供有效的城市名称 }; } try { const resp await axios.get(https://api.example.com/weather, { params: { city, unit }, timeout: 5000 }); return { city: resp.data.city, temperature: resp.data.temp, condition: resp.data.condition, unit }; } catch (e) { return { error: UPSTREAM_ERROR, message: e.message, suggestion: 请稍后重试或检查城市名称是否正确 }; } };第四步写示例文件examples/basic.json{ input: { city: 北京, unit: celsius }, output: { city: 北京, temperature: 25, condition: 晴, unit: celsius } }这个最小技能跑通之后再往上加功能就简单了。4.2 用 npx 做本地测试与分发热词里“npx playwright install失败”和“claude mcpservers npx”都指向同一个点npx 是这套生态里常用的执行和分发工具。我本地测试技能时习惯用 npx 直接跑不用先全局安装。比如测试上面那个技能npx skills-run ./skills/weather-query --input {city:上海}如果要把技能分发出去可以做成 npm 包。在package.json里加一个bin字段指向入口文件。别人用npx your-skill-name就能直接跑。这种方式的好处是版本管理清晰依赖也自动处理。注意npx 执行时会先检查本地有没有这个包没有才去远程拉。如果你在开发过程中改了代码但没改版本号npx 可能用的是缓存里的旧版本。我踩过这个坑调试了半天发现跑的是旧代码。解决办法是加--force参数强制重新拉取或者直接用本地路径。4.3 部署到云端与 GKE 集成技能在本地跑通之后下一步往往是部署到云端让生产环境的 Agent 调用。热词里的 GKE 就是常见的容器化部署方案。我的做法是把技能包打成一个 Docker 镜像里面包含运行时和技能代码。然后写一个简单的 HTTP 服务接收参数、调用技能、返回结果。这个服务推到 GKE 上通过 Service 暴露出来。Dockerfile 大概长这样FROM node:18-slim WORKDIR /app COPY package*.json ./ RUN npm install --production COPY . . EXPOSE 8080 CMD [node, server.js]server.js里起一个 HTTP 服务把请求体转成技能参数调用技能再把结果返回。部署到 GKE 时注意配置好资源限制和健康检查。技能服务一般内存占用不大但如果有并发调用CPU 要留够。我实测下来一个轻量技能服务256MB 内存加 0.25 核 CPU 就能跑得不错。但如果技能里有大量计算或者外部调用就要相应调高。健康检查的路径设成/health返回 200 就行。4.4 技能编排与组合调用单个技能能做的事有限真正有价值的是把多个技能组合起来。比如一个“生成周报”的任务可能需要查询数据库技能、统计汇总技能、生成图表技能、写文件技能。这四个技能按顺序调用前一个的输出作为后一个的输入。编排有两种方式。一种是硬编码在代码里写死调用顺序。这种方式简单直接但不够灵活。另一种是让模型自己编排把可用技能列表给模型让它决定调用顺序和参数传递。这种方式灵活但对模型的规划能力要求高。我一般混合使用主流程硬编码确保稳定子流程让模型自己选技能保留灵活性。比如周报任务的主流程是固定的四步但“统计汇总”这一步具体用哪个技能让模型根据数据特点自己决定。5. 常见问题与排查技巧实录5.1 技能不被调用或调用错误这是最常见的问题。排查思路我整理成一个表现象可能原因排查方法解决方式技能完全不被调用描述太窄或太模糊检查描述是否包含任务关键词重写描述加入同义词调用了错误的技能多个技能描述重叠对比各技能描述明确边界消除重叠参数传错schema 不清晰检查参数类型和枚举补全 schema加示例调用后无返回执行逻辑异常查看日志加异常处理和结构化错误我遇到最多的是描述问题。有一次一个“发送邮件”的技能一直不被调用后来发现描述写的是“发送通知”而模型理解的通知是站内信。把描述改成“发送电子邮件”之后立刻就正常了。5.2 npx 安装失败的排查热词里专门提到“npx playwright install失败”说明这是个高频问题。npx 安装失败通常有几个原因网络问题、权限问题、Node 版本不兼容、缓存损坏。排查顺序我一般是先看 Node 版本node -v确认在 16 以上再看网络能不能访问 npm 源然后清缓存npm cache clean --force最后看权限是不是需要 sudo。大部分情况清缓存就能解决。如果是在 CI 环境里失败还要检查环境变量和代理配置。有些 CI 默认不装某些系统依赖需要手动补上。我遇到过一次是缺少libgbm这个库装上就好了。5.3 技能执行超时与重试技能执行超时原因可能是外部接口慢、计算量大、或者死循环。我的做法是所有外部调用设超时一般 5 到 10 秒计算密集型的技能设更长的超时但要有上限死循环靠代码审查和单元测试来防。重试策略要谨慎。不是所有失败都适合重试。网络超时可以重试参数错误重试也没用。我一般只对超时和 5xx 错误重试重试次数不超过 3 次每次间隔递增。提示重试的时候要确保技能是幂等的。如果不是重试可能产生副作用。我有个写文件的技能早期没做幂等重试时把文件写了两遍内容重复了。后来改成先检查文件是否存在存在就覆盖问题才解决。5.4 技能版本管理与兼容性技能更新后旧版本的调用方可能不兼容。我的做法是版本号遵循语义化版本主版本号变化表示不兼容次版本号变化表示新增功能修订号变化表示修复 bug。调用方可以指定版本范围比如^1.0.0表示接受 1.x.x 的所有版本。另外技能包里要保留变更日志写清楚每个版本改了什么。这样调用方升级时能快速判断影响。我见过一个团队技能更新后没通知调用方结果生产环境直接挂了。后来他们加了变更日志和升级通知机制问题才没再出现。6. 技能生态的扩展与个人实践体会6.1 从单技能到技能市场当技能数量多起来之后自然就需要一个地方来管理和分发。热词里的“skills下载平台有哪些”“skills大全”“skills推荐”都指向这个需求。我自己的做法是先在团队内部建一个私有技能仓库用 Git 管理每个技能一个目录配一个索引文件。索引文件里记录技能名称、版本、描述、作者、依赖。新成员加入时先看索引找到需要的技能直接拉下来用。这种方式比口头传递靠谱得多。等团队规模再大一些可以做一个简单的 Web 界面支持搜索和预览。对外分发的话npm 是一个选择但要注意技能包里不要包含敏感信息。我一般会在发布前跑一遍检查确认没有硬编码的密钥、没有内部地址、没有测试数据。6.2 技能测试的自动化热词里“agent skills测试”是个关键点。技能测试不能只靠手动要自动化。我的做法是每个技能配一组测试用例覆盖正常输入、边界输入、异常输入。测试用例用 JSON 文件描述跑测试时自动加载、执行、比对结果。测试用例的格式我一般这样写{ name: 正常查询, input: { city: 北京 }, expect: { city: 北京, temperature: number } }expect里可以写具体值也可以写类型。写类型的好处是结果会变化时测试不会误报。比如温度每天都不一样写具体值就没法测了。自动化测试跑在 CI 里每次提交代码都跑一遍。这样能及早发现问题避免把坏掉的技能发布出去。6.3 我个人踩过的几个坑第一个坑是技能描述写得太技术化。我早期写描述喜欢用专业术语比如“执行 HTTP GET 请求并解析 JSON 响应”。模型看到这种描述不知道什么时候该用。后来改成“获取网页内容并提取其中的数据”调用率立刻上去了。模型是给普通人用的描述也要用普通人能懂的话。第二个坑是参数默认值设得不对。有个技能的单位参数默认设成了华氏度结果国内用户调用时经常得到奇怪的结果。后来把默认值改成摄氏度问题就没了。默认值要符合大多数使用场景不能按开发者的个人习惯来。第三个坑是技能之间共享状态。我早期设计时让多个技能共享一个全局变量来传递数据。结果并发调用时数据串了A 任务的数据被 B 任务覆盖了。后来改成每个调用独立传参不共享状态问题才解决。技能应该是无状态的状态由调用方管理。6.4 后续可以扩展的方向这套技能体系跑通之后能扩展的方向不少。一个是技能组合模板把常用的技能组合固化下来一键调用。比如“数据导入”模板包含读取、清洗、入库三个技能用户不用自己编排。另一个是技能性能监控记录每个技能的调用次数、成功率、平均耗时。这些数据能帮助判断哪些技能需要优化哪些技能可以下线。我目前是用简单的日志加统计脚本来做后面可以考虑接入更专业的监控系统。还有一个方向是技能权限控制。不是所有技能都适合所有人调用有些技能涉及敏感操作需要加权限校验。这个可以在技能执行前加一层检查根据调用方身份决定是否放行。最后分享一个小技巧技能描述里可以加一些“触发词”就是用户可能会说的词。比如天气技能里加上“气温”“冷热”“下雨”这样用户用不同说法时模型都能匹配到。这个技巧在热词“find skills”的场景下特别有用能提高技能的发现率。
阅读完成 · 觉得有帮助？
