1. 从“skills”这个热词说起它到底是什么最近几个月不管是在技术社区还是开发者群聊里“skills”这个词出现的频率高得离谱。有人把它当成一个工具有人把它当成一套规范还有人把它当成一种新的开发范式。我一开始也懵直到自己动手把整套东西跑通、拆开看了一遍才明白它到底在解决什么问题。简单来说skills 是一套让 AI 智能体Agent具备可复用、可组合、可分发能力的结构化技能包。你可以把它理解成给 AI 装的“插件”或者“技能卡”——每一张卡定义了一件事怎么做、需要什么输入、产出什么结果、依赖哪些工具。Agent 拿到这些技能卡之后就能在特定场景下自动调用而不需要每次从零写提示词。它解决的问题非常实际过去我们让 AI 干活靠的是一大段一大段的提示词写起来累、维护起来更累换一个模型或者换一个场景就得重写。skills 把这种“一次性提示词”变成了“可版本管理的技能模块”谁写的、什么版本、依赖什么、怎么测试全都清清楚楚。这篇文章适合谁看如果你是前端开发者、AI 应用开发者、或者正在折腾 Agent 工作流的人那这篇内容基本就是给你写的。我会从设计思路、核心结构、实操步骤、常见坑四个维度把 skills 这套东西彻底讲透。哪怕你之前只听说过这个词看完也能自己动手写一个能跑的 skill。2. skills 的整体设计与核心思路拆解2.1 为什么需要 skills从“提示词堆砌”到“技能模块化”我先说说自己踩过的坑。早期做 Agent 项目的时候所有的能力都塞在一个巨大的系统提示词里今天加一个“查天气”明天加一个“生成周报”提示词越写越长最后长到模型自己都抓不住重点。更麻烦的是团队里三个人维护同一份提示词改一处冲突三处根本没法协作。skills 的出现本质上是为了解决三个问题复用、组合、分发。复用是指同一个技能可以在不同项目、不同 Agent 之间直接拿来用不用重写。组合是指多个技能可以像搭积木一样拼起来完成复杂任务。分发是指技能可以打包、发布、安装就像 npm 包一样。这三个问题一旦解决Agent 的开发方式就变了——从“写提示词”变成“选技能、配技能、测技能”。这是一个范式级别的转变也是为什么 skills 这个词能火起来的原因。2.2 skills 的核心结构一个技能包里到底装了什么我拆过好几个不同来源的 skill 包结构大同小异核心就三样东西元数据metadata技能的名字、版本、描述、作者、依赖项。这部分决定了技能能不能被正确索引和加载。指令instructions告诉 Agent 这个技能是干什么的、什么时候用、怎么用。通常是一段结构化的自然语言描述但比普通提示词更规范。工具声明tool declarations这个技能需要调用哪些外部工具或 API参数是什么返回什么。这部分是可选的但如果技能需要跟外部系统交互就必须写清楚。有些实现还会加一个测试用例test cases目录用来验证技能在给定输入下能否产出预期输出。这个设计非常关键后面讲实操的时候我会详细说。用一句话概括skill 元数据 指令 工具声明 测试用例。这四样东西凑齐了就是一个完整、可分发、可验证的技能单元。2.3 跟传统提示词工程的区别在哪很多人会问这不就是提示词模板吗有什么区别区别大了。提示词模板是“一段文本”skill 是“一个有生命周期的软件制品”。具体来说维度传统提示词skills复用方式复制粘贴安装引用版本管理靠文件名语义化版本依赖管理无显式声明测试靠人肉试自动化用例分发发文档包管理器组合手动拼接自动编排这个对比表是我自己在项目里总结的不一定全面但能说明核心差异。skills 把提示词从“文本”升级成了“制品”这是本质区别。3. 核心细节解析与实操要点3.1 一个最小可用 skill 的目录结构我拿自己写的一个“生成周报”skill 举例目录结构是这样的weekly-report-skill/ ├── skill.json ├── instructions.md ├── tools.json └── tests/ ├── case-01.json └── case-02.jsonskill.json是元数据长这样{ name: weekly-report, version: 1.0.0, description: 根据本周的提交记录和任务列表生成结构化周报, author: your-name, dependencies: [], entry: instructions.md }instructions.md是指令核心是告诉 Agent 什么时候触发、怎么执行# 周报生成技能 ## 触发条件 当用户提到周报本周总结weekly report时激活。 ## 执行步骤 1. 收集本周的 git commit 记录 2. 收集任务管理系统中的已完成任务 3. 按完成事项/进行中/下周计划三段式组织 4. 输出 Markdown 格式 ## 输出格式 - 完成事项列表每条不超过 50 字 - 进行中列表标注进度百分比 - 下周计划列表按优先级排序tools.json声明依赖{ tools: [ { name: git-log, type: shell, command: git log --since7 days ago --oneline }, { name: task-query, type: http, endpoint: /api/tasks/completed } ] }这个结构看起来简单但每一部分都有讲究。下面我逐个拆。3.2 元数据怎么写才不容易出问题元数据里最容易踩坑的是版本号和依赖声明。版本号我建议严格遵循语义化版本semver也就是主版本.次版本.修订号。为什么因为 skill 被别的项目引用之后你改一个指令可能就会影响下游。主版本变了说明有破坏性变更下游需要主动升级次版本变了说明加了新功能但兼容修订号变了说明只是修了 bug。依赖声明这块我踩过一个坑早期我写了一个 skill 依赖另一个 skill但没写清楚版本范围结果上游 skill 升级之后我的 skill 直接挂了。后来我学乖了依赖一定要写清楚范围比如1.0.0 2.0.0这样上游发 1.x 的时候我能自动拿到发 2.0 的时候我会被拦住逼着我先测试再升级。提示元数据里的 description 不要写得太泛比如“一个有用的技能”这种等于没写。要写清楚“在什么场景下解决什么问题”这样 Agent 在检索技能的时候才能准确匹配。3.3 指令设计的三个关键原则指令是 skill 的灵魂写得好不好直接决定技能能不能用。我总结了三个原则第一触发条件要具体。不要写“当用户需要帮助时”要写“当用户提到 X、Y、Z 关键词或者当前上下文包含 A 条件时”。触发条件越具体误触发的概率越低。第二执行步骤要可执行。每一步都应该是 Agent 能直接做的动作而不是模糊的描述。比如“分析一下数据”就不如“读取 data.csv按日期分组计算每日均值”来得明确。第三输出格式要固定。输出格式固定了下游才能稳定消费。我一般会用 JSON Schema 或者 Markdown 模板来约束输出这样即使模型换了输出结构也不会乱。这三条听起来简单但实际写的时候很容易忘。我的做法是写完指令之后自己扮演 Agent 走一遍看看每一步是不是真的能执行。走不通的地方就是需要改的地方。3.4 工具声明的参数设计工具声明这块核心是把“技能需要什么能力”和“能力怎么实现”解耦。举个例子一个“发送通知”的技能它需要的能力是“发消息”但具体是发邮件、发 Slack、还是发短信不应该写死在技能里。技能只声明“我需要一个 send-message 工具参数是 recipient 和 content”具体用哪个实现由运行环境决定。这样做的好处是技能可以跨环境复用。同一个技能在 A 公司用邮件发在 B 公司用内部 IM 发技能本身不用改。参数设计要注意几点参数名要语义化recipient比to好content比body好必填参数和可选参数要分清参数类型要明确字符串、数字、布尔、数组、对象别含糊如果有默认值写清楚我见过有人把工具声明写成一大坨 JSON几百行根本没法维护。我的建议是能拆就拆一个工具只做一件事参数不超过五个。超过五个就说明这个工具职责太重了该拆。4. 实操过程与核心环节实现4.1 环境准备从零搭建 skill 开发环境先说环境。我目前用的是 Node.js 生态因为大部分 skill 工具链都是 npm 包装起来方便。第一步确认 Node 版本。我实测下来 Node 18 以上比较稳16 也能跑但有些新特性不支持。node -v # 建议 v18.x 或 v20.x第二步初始化项目mkdir my-first-skill cd my-first-skill npm init -y第三步安装 skill 开发工具链。不同平台的工具名不一样我用的是一个通用的 CLInpm install -D skill-cli/core第四步初始化 skill 模板npx skill init这个命令会生成前面说的目录结构你只需要往里填内容就行。注意如果你在公司内网环境npm 源可能需要配置。我一般会先npm config get registry看一下当前源如果是内网源确认一下有没有对应的包。没有的话找运维同步一下别硬装。4.2 写第一个 skill从需求到可运行我拿一个真实需求来演示自动整理会议纪要。需求是这样的用户丢进来一段会议录音转写文本skill 需要提取出“决议事项”“待办任务”“负责人”“截止时间”四个字段输出成结构化 JSON。第一步写元数据{ name: meeting-minutes, version: 1.0.0, description: 从会议转写文本中提取决议、待办、负责人和截止时间, author: your-name, dependencies: [], entry: instructions.md }第二步写指令# 会议纪要提取技能 ## 触发条件 当输入包含会议转写文本或用户提到整理纪要提取待办时激活。 ## 执行步骤 1. 通读全文识别会议中的决议性语句 2. 提取所有待办任务每条任务包含任务描述、负责人、截止时间 3. 如果某条待办缺少负责人或截止时间标记为待确认 4. 按以下 JSON 格式输出 ## 输出格式 { decisions: [决议1, 决议2], todos: [ { task: 任务描述, owner: 负责人或待确认, deadline: 截止时间或待确认 } ] }第三步写测试用例{ input: 本次会议决定采用方案A。张三负责在下周五前完成接口联调。李四跟进用户反馈时间待定。, expected: { decisions: [采用方案A], todos: [ {task: 完成接口联调, owner: 张三, deadline: 下周五}, {task: 跟进用户反馈, owner: 李四, deadline: 待确认} ] } }第四步跑测试npx skill test如果输出跟 expected 一致说明技能基本可用。不一致的话看差异在哪回去改指令。4.3 参数计算与选择怎么定技能的粒度技能粒度是个很微妙的问题。太粗一个技能干十件事复用性差太细一个技能只干一件事组合起来又太碎。我的经验是一个技能对应一个“用户可感知的完整任务”。什么叫用户可感知的完整任务比如“生成周报”是一个完整任务“收集 git 记录”就不是它只是周报的一个子步骤。子步骤应该放在技能内部的执行步骤里而不是单独拆成一个技能。判断标准很简单如果这个技能单独拿出来给用户用用户会觉得“这是个有用的功能”那粒度就对了。如果用户觉得“这只是个中间步骤”那就该合并到上层技能里。我一般会把技能控制在3 到 7 个执行步骤之间。少于 3 步说明太简单可能不值得单独成技能多于 7 步说明太复杂该拆了。4.4 技能组合多个 skill 怎么串起来单个技能能做的事有限真正有价值的是组合。我拿一个实际场景演示自动生成项目周报并发送。这个场景需要三个技能git-summary收集本周提交记录生成摘要weekly-report把摘要和任务列表组织成周报send-notification把周报发出去组合方式有两种串行组合前一个技能的输出作为后一个技能的输入。{ pipeline: [ {skill: git-summary, output: summary}, {skill: weekly-report, input: summary, output: report}, {skill: send-notification, input: report} ] }条件组合根据条件选择不同的技能分支。{ router: { condition: input.type, branches: { weekly: weekly-report, daily: daily-report } } }串行组合适合流程固定的场景条件组合适合需要分支的场景。实际项目里两种经常混用。提示组合的时候一定要注意数据格式的兼容性。前一个技能输出 JSON后一个技能却期望 Markdown这种不匹配是组合失败的最常见原因。我的做法是在每个技能的元数据里明确声明输入输出格式组合之前先做一次格式校验。5. 常见问题与排查技巧实录5.1 技能不触发怎么办这是最高频的问题。技能写好了但 Agent 就是不用。排查思路按顺序来第一检查触发条件。把触发条件里的关键词拿出来看看用户输入里有没有。没有的话要么改触发条件要么确认用户输入是否真的该触发这个技能。第二检查技能是否被正确加载。有些平台需要显式注册技能光有文件不够。看一下加载日志确认技能在列表里。第三检查优先级。如果多个技能都匹配当前输入Agent 可能选了别的。这时候需要调整技能的优先级或者触发条件的特异性。我整理了一个速查表现象可能原因解决方法完全不触发技能未加载检查注册配置偶尔触发触发条件太泛收窄关键词触发但走错分支优先级冲突调整优先级触发后报错依赖缺失检查 dependencies5.2 输出格式不稳定的处理模型输出格式飘是另一个高频问题。明明指令里写了输出 JSON结果模型给你输出一段带解释的文字。我的处理办法有三层第一层指令里强化格式约束。不要只说“输出 JSON”要说“只输出 JSON不要有任何其他文字不要用代码块包裹”。越明确越好。第二层加格式校验。技能执行完之后跑一个校验步骤不符合格式就重试。重试的时候把错误信息带上模型通常第二次就能改对。第三层用结构化输出能力。如果模型支持 JSON mode 或者 function calling优先用这些能力比纯提示词约束靠谱得多。这三层下来格式稳定性基本能到 99% 以上。剩下 1% 是模型本身的随机性接受就好。5.3 依赖冲突与版本管理技能多了之后依赖冲突几乎不可避免。A 技能依赖工具 X 的 1.0B 技能依赖 X 的 2.0两个技能一起用就炸了。我的做法是技能依赖尽量声明宽范围比如1.0.0 3.0.0给运行环境留出选择空间运行环境统一管理工具版本技能不直接锁定版本如果实在冲突把冲突的技能隔离到不同的执行环境里版本管理这块我强烈建议用 lock 文件。每次安装技能的时候生成一份 lock记录所有技能和依赖的确切版本。这样换机器、换环境的时候装出来的东西完全一致不会出现“我这儿能跑你那儿跑不了”的情况。5.4 性能优化技能执行太慢怎么办技能执行慢通常有三个原因一是技能粒度太细组合层数太多。十个技能串起来每个都要加载、解析、执行开销叠加起来很可观。这时候该合并的合并。二是工具调用太频繁。一个技能里调了十次外部 API每次都等网络往返。能批量就批量能缓存就缓存。三是指令太长模型处理慢。指令不是越长越好冗余的描述会拖慢推理。我一般会把指令控制在 500 字以内超过就拆。实测下来一个设计良好的技能从触发到输出延迟应该控制在 2 秒以内。超过 5 秒就要查原因了。5.5 调试技巧怎么快速定位问题调试技能的时候我一般会开三个东西详细日志记录技能加载、触发、执行、输出的每一步中间产物每个步骤的输出都存下来方便对比回放能力把一次失败的执行录下来改完技能之后回放看是否修复这三个东西搭起来之后调试效率能提升好几倍。尤其是回放能力改一次跑一次比手动复现快多了。注意日志里不要记录敏感数据。技能执行过程中可能会碰到用户隐私、密钥之类的信息记录之前先脱敏。这个坑我踩过后来加了脱敏层才解决。6. 技能分发与团队协作的实操经验6.1 技能打包与发布技能写好了怎么分享给团队最土的办法是发文件夹但这样没法管理版本也没法追踪谁用了哪个版本。正规做法是打包发布。打包就是把技能目录打成一个压缩包附带元数据和校验和。发布就是把这个包推到技能仓库里。npx skill pack # 生成 my-skill-1.0.0.tar.gz npx skill publish # 推送到配置的仓库发布之后别人就可以通过名字和版本号安装npx skill install my-skill1.0.0这套流程跟 npm 几乎一样用过 npm 的人上手很快。6.2 团队协作中的技能管理规范团队用技能最容易乱的是命名和版本。我建议定几条规矩技能名用领域-功能格式比如report-weekly、notify-email版本严格 semver破坏性变更必须升主版本每个技能必须有 owner出了问题找得到人技能变更要走 review不能直接推这几条看起来是流程问题但实际执行下来能避免 80% 的协作事故。我见过太多因为技能改名导致下游全挂的案例都是因为没规范。6.3 技能市场与生态现状目前技能的分发渠道主要有几类官方市场、社区仓库、私有仓库。官方市场的技能质量相对有保障但数量有限。社区仓库数量多但质量参差不齐用之前一定要看测试用例和更新记录。私有仓库适合公司内部安全可控。我选技能的时候会看几个指标最近更新时间、测试覆盖率、issue 响应速度、依赖数量。依赖越少越好更新越勤越好测试越全越好。6.4 从个人使用到团队落地的路径最后说说落地路径。我的建议是分三步第一步个人先用起来。自己写几个技能解决自己的重复劳动。这一步的目的是熟悉技能的设计和调试。第二步小范围共享。找两三个同事把技能分享给他们用收集反馈。这一步的目的是验证技能的通用性。第三步团队推广。建立技能仓库定规范做培训。这一步的目的是规模化。每一步之间不要跳跳了容易翻车。我见过有人第一步还没走稳就推全团队结果技能质量不过关大家用了一次就不用了反而打击了积极性。7. 我个人的一些实操体会写了这么多最后分享几个我自己踩坑踩出来的经验。技能不是越多越好。我一开始特别兴奋什么都要写成技能结果技能列表里几十个自己都记不住哪个是哪个。后来砍到十几个核心技能反而用得更顺。技能的价值在于被用不在于被写。测试用例比指令更重要。指令是给模型看的测试用例是给你自己看的。指令写得再漂亮测试不过就是白搭。我现在写技能先写测试用例再写指令这样目标更明确。版本管理要趁早。我第一个技能没管版本改了十几次之后自己都不知道哪个版本是哪个。后来全部重来加上版本管理才理清楚。这个教训挺深刻的。别追求完美先跑起来。技能这东西跑起来比设计完美重要。我见过有人花两周设计一个技能架构结果一行代码没写。先写个能跑的再迭代比什么都强。关注生态但别追新。技能生态变化很快新工具新规范层出不穷。我的做法是关注但不急着追。等一个东西稳定了、有社区验证了再上手。追新追得太紧容易变成小白鼠。这套东西我用了几个月最大的感受是它把 AI 应用开发从“手工作坊”推向了“流水线”。以前每个项目都要重新写提示词现在技能可以复用、可以组合、可以测试。这个转变带来的效率提升是实打实的。如果你还没开始用建议从一个小技能入手比如“整理会议纪要”或者“生成周报”。跑通一个后面的就顺了。