1. 从“skills”这个标题说起它到底指什么第一次看到“skills”这个标题很多人会以为是某个泛泛而谈的能力清单或者一份简历上的技能罗列。但结合热搜词里的 Google Cloud、Agent Skills、npx、GKE 这些关键词就能判断出这里说的 skills 不是人力资源语境下的“技能”而是面向 AI Agent 的能力扩展包——一套可安装、可组合、可复用的指令与工具集合用来给智能体赋予特定领域的专业能力。说得再直白一点大模型本身是个“通才”什么都懂一点但落到具体任务上往往不够专精。skills 就是给它外挂的“专业模块”。你装一个“写论文”的 skill它就按学术规范来你装一个“分镜脚本”的 skill它就按影视工业的格式输出你装一个“代码审计”的 skill它就知道该盯哪些漏洞模式。这套机制最早在 Claude 的生态里被大量讨论后来 Codex、Gemini 等平台也陆续跟进形成了各自的 skills 体系。这篇文章适合三类人看一是刚接触 Agent 开发、想搞清楚 skills 到底是什么的开发者二是已经在用各类 AI 编程工具、想通过 skills 提升效率的工程师三是想自己动手写 skill、把团队内部经验沉淀成可复用资产的技术负责人。我会从设计思路讲到实操步骤再到踩坑记录尽量把每个环节的“为什么”说清楚让你看完能直接上手。2. skills 的整体设计与核心思路拆解2.1 为什么需要 skills 这层抽象大模型的能力边界本质上由三样东西决定预训练知识、上下文窗口、以及外部工具的调用能力。预训练知识是固定的你改不了上下文窗口再大也有上限真正能灵活扩展的就是工具调用这一层。但早期的工具调用很原始——你得在 prompt 里写一大堆函数定义模型还不一定按你的格式来。skills 的出现解决了三个痛点。第一是封装性把一组相关的指令、工具定义、示例、约束条件打包成一个独立单元用的时候整体加载不用每次重复描述。第二是可组合性一个任务可以同时挂载多个 skills比如“数据分析”skill 加“可视化”skill 加“报告撰写”skill各司其职。第三是可版本化skills 可以像代码一样做版本管理今天用 v1.2明天升级到 v1.3行为变化可追溯。我打个比方。大模型像一个刚入职的高材生智商很高但不懂你们公司的规矩。skills 就是一本本《岗位操作手册》财务岗看财务手册运维岗看运维手册。手册写得越细新人上手越快出错越少。而且手册可以随时修订不用重新招人。2.2 skills 的典型结构长什么样不同平台的 skills 格式略有差异但核心结构大同小异。一个标准的 skill 通常包含以下几个部分元信息名称、版本、作者、适用平台、依赖项。这部分决定了 skill 怎么被索引和加载。触发条件什么情况下该激活这个 skill。可以是关键词匹配也可以是语义判断还可以是显式调用。指令正文核心的 prompt 内容告诉模型该怎么做、按什么步骤、注意什么禁忌。工具定义这个 skill 需要调用哪些外部函数或 API参数怎么传返回值怎么解析。示例集几个典型的输入输出样例帮模型快速对齐预期格式。约束与边界明确哪些事不能做哪些情况要转人工哪些输出格式必须遵守。以 Claude 的 Agent Skills 为例它采用的就是类似的结构通过一个 manifest 文件声明元信息和依赖通过 markdown 或结构化文本描述指令通过 JSON Schema 定义工具。Google Cloud 那边的 Agent Skills 则更偏向与企业级服务集成比如直接挂载 GKE 集群操作、Cloud Storage 读写等能力。2.3 选型考量自建还是用现成的这是很多人第一个纠结的点。我的建议是分阶段来。起步阶段优先用官方市场和社区现成的 skills比如 Claude 官方市场里那些经过验证的 skill或者 GitHub 上 star 数较高的开源 skill。原因很简单写一个能用的 skill 不难写一个好用的 skill 很难需要大量真实场景的打磨。当现成 skill 满足不了你的特定需求时再考虑自建。自建的触发信号通常有三个一是现有 skill 的输出格式跟你的下游系统对不上二是你的业务领域太垂直社区没人做三是你有敏感数据不能走第三方 skill。自建的时候建议先从最简单的“纯指令型”skill 开始不涉及外部工具调用跑通了再逐步加工具、加示例、加约束。注意不要一上来就追求大而全的 skill。我见过有人写了一个“全能助手”skill塞了几千行指令结果模型反而抓不住重点输出质量还不如不挂 skill。skill 的粒度应该跟任务粒度对齐一个 skill 解决一类问题宁可多写几个小的也不要写一个巨无霸。3. 核心细节解析与实操要点3.1 环境准备npx 与依赖管理大部分 skills 的分发和安装都依赖 Node.js 生态npx 是最常见的入口。你会在各种教程里看到类似npx skills install xxx或npx playwright install这样的命令。这里有个前提本机得先有 Node.js 和 npm。版本建议 Node 18 以上npm 9 以上太老的版本会在依赖解析上出各种奇怪问题。安装 Node 的方式很多Windows 上直接去官网下安装包macOS 用 HomebrewLinux 用包管理器或者 nvm。我个人推荐用 nvm 管理多版本因为不同 skill 可能对 Node 版本有要求nvm 切换起来最方便。装完之后用node -v和npm -v确认一下两个命令都能正常输出版本号才算环境就绪。接下来是 npx 本身。npx 是 npm 5.2 以后自带的工具用来临时执行 npm 包里的命令不用全局安装。但有些 skill 的安装脚本会依赖特定版本的 npx 行为如果遇到诡异报错可以先npm install -g npx更新一下。另外国内网络环境下 npm 源可能比较慢可以换成国内镜像源这个在 npm 官方文档里有详细说明配置一次就行。3.2 skill 的安装路径与目录结构skill 装到哪里这是个容易被忽略但很关键的问题。不同平台的默认路径不一样Claude 系的 skill 通常放在用户目录下的隐藏文件夹里Codex 系的则可能放在项目根目录的.codex或类似目录下。搞清楚路径有两个好处一是方便手动检查和修改 skill 内容二是出问题时知道去哪看日志。典型的 skill 目录结构是这样的skills/ my-skill/ manifest.json instructions.md tools/ schema.json examples/ input1.txt output1.txt README.mdmanifest.json 是入口里面声明了 skill 的名称、版本、入口文件、依赖项。instructions.md 是核心指令。tools 目录放工具定义。examples 目录放示例。README 是给人看的说明。你自己写 skill 的时候建议严格按这个结构来因为很多加载器是按约定找文件的结构不对就加载不了。提示安装完 skill 后先别急着用。打开它的 instructions.md 通读一遍看看它的行为边界跟你预期是否一致。我踩过一次坑装了个“代码优化”skill结果它默认会把所有注释删掉因为它的指令里写了“精简代码”。这种细节不看说明书根本发现不了。3.3 指令正文的写法从模糊到精确skill 好不好用八成取决于指令正文写得怎么样。新手最容易犯的错是写得太模糊比如“帮我写好代码”“输出高质量内容”。模型看到这种指令只能按它自己的理解来结果就是不稳定。好的指令应该具备几个特征。第一是角色明确开头就告诉模型“你是一个资深的 XXX”。第二是步骤清晰把任务拆成有序的几步每步做什么、输出什么写清楚。第三是格式具体输出用 markdown 还是 JSON字段有哪些字段类型是什么给个模板最好。第四是边界明确什么情况该拒绝什么情况该追问什么情况该转人工都要写。举个例子一个“周报生成”skill 的指令可以这样写你是一个帮助工程师整理周报的助手。 输入本周的 git commit 记录、Jira 任务列表、会议纪要。 步骤 1. 按项目维度归类 commit 和任务。 2. 每个项目下列出完成事项、进行中事项、风险事项。 3. 风险事项要标注影响范围和预计解决时间。 输出格式 ## 项目名称 ### 完成 - 事项1关联任务ID ### 进行中 - 事项1进度百分比 ### 风险 - 风险描述 | 影响 | 预计解决时间 约束 - 不要编造未在输入中出现的信息。 - 如果某项目没有任何记录跳过不输出。这种指令模型执行起来就稳得多。你可以把这段直接拿去改改用。3.4 工具定义与参数传递当 skill 需要调用外部能力时就要定义工具。工具定义的核心是 JSON Schema描述函数名、参数、参数类型、是否必填、默认值。这部分跟 OpenAI 的 function calling 格式基本兼容学一次到处能用。参数传递有几个坑要注意。一是类型匹配schema 里写 integer模型传过来字符串就会报错所以指令里要强调类型。二是必填校验必填参数缺失时skill 应该主动追问而不是硬编一个默认值。三是错误处理工具调用失败时skill 要有降级方案比如重试、换工具、或者明确告知用户失败原因。我实测下来工具数量控制在 5 个以内比较稳超过 10 个模型就容易选错工具。如果确实需要很多工具建议拆成多个 skill按场景加载而不是全塞在一个 skill 里。4. 实操过程与核心环节实现4.1 从零写一个 skill 的完整流程假设我们要写一个“API 文档生成”skill输入是代码文件输出是标准格式的 API 文档。完整流程如下。第一步建目录。在 skills 目录下新建api-doc-gen文件夹按前面说的结构建好子目录和文件。第二步写 manifest。声明名称、版本、入口、依赖。依赖这里如果用到 markdown 解析库就写上对应的包名和版本。第三步写指令。核心内容大概是这样你是一个 API 文档生成器输入是源代码输出是 markdown 格式的接口文档。步骤包括解析函数签名、提取注释、识别参数类型、生成示例请求、生成示例响应。输出格式按固定的模板来。约束包括不编造未在代码中出现的参数、注释缺失时标注“待补充”、敏感信息脱敏。第四步加示例。放两组输入输出样例一组是注释完整的一组是注释缺失的让模型知道两种情况分别怎么处理。第五步本地测试。用平台的测试命令加载 skill喂几个真实代码文件看输出是否符合预期。不符合就回去改指令反复几轮。第六步版本化。测试通过后打 tag写 changelog推到团队仓库或官方市场。整个过程快的话半天慢的话两三天主要时间花在指令调优上。4.2 参数计算与选择以超时和重试为例skill 里涉及外部调用时超时和重试参数怎么定很多人是拍脑袋。我给一个基于实践的计算方法。先估算单次调用的 P99 延迟。比如你调一个外部 API实测 100 次P99 是 3 秒。那超时至少设 3 秒的 2 到 3 倍也就是 6 到 9 秒留足余量应对网络抖动。重试次数呢看你的失败容忍度。如果是同步阻塞场景重试 1 到 2 次就够了再多用户等不及。如果是后台异步任务可以重试 3 到 5 次配合指数退避。指数退避的公式是delay base * 2^attemptbase 一般取 1 秒。第一次失败等 1 秒第二次等 2 秒第三次等 4 秒以此类推。这样既能避开瞬时故障又不会把下游打垮。注意重试要区分错误类型。网络超时、5xx 错误可以重试4xx 错误比如参数错误、权限不足重试多少次都没用应该直接失败并报错。这个判断逻辑要写进 skill 的指令里。4.3 与 GKE 等云服务的集成实操热搜词里出现了 GKE说明很多人关心 skill 怎么跟云服务打通。以 GKE 为例一个“集群巡检”skill 大概需要这些能力列出集群、列出节点、查看 Pod 状态、读取事件日志、检查资源配额。实现路径是这样的。先在云平台上创建服务账号授予只读权限巡检不需要写权限最小权限原则。然后拿到凭证文件配置到本地环境。接着在 skill 的工具定义里把 gcloud 或 kubectl 的命令封装成函数。最后在指令里写清楚巡检步骤和输出格式。这里有个实操细节凭证文件不要硬编码在 skill 里而是通过环境变量引用。skill 的 manifest 里声明需要哪些环境变量加载时检查是否配置没配置就提示用户。这样既安全又灵活换环境不用改 skill 代码。巡检的输出建议结构化比如每个检查项输出检查项 | 状态 | 详情状态用 OK/WARN/ERROR 三档。这样后续可以接告警系统WARN 以上就触发通知。4.4 多 skill 协同的编排方式单个 skill 能力有限真实任务往往需要多个 skill 配合。编排方式有两种串行和并行。串行就是一个 skill 的输出作为下一个 skill 的输入。比如“数据抓取”skill 拿到原始数据“数据清洗”skill 处理成规整格式“分析报告”skill 生成结论。串行的关键是接口对齐前一个的输出格式必须符合后一个的输入要求这个要在指令里写死。并行就是多个 skill 同时处理同一份输入最后汇总。比如一份代码同时跑“安全审计”skill 和“性能分析”skill两份报告合并输出。并行的关键是结果合并逻辑冲突时以谁为准要提前定好。我个人的经验是超过三个 skill 的编排就要考虑用工作流引擎来管了纯靠 prompt 编排容易乱。但如果是两三个 skill 的简单场景直接在指令里写清楚调用顺序就行不用上重型工具。5. 常见问题与排查技巧实录5.1 安装类问题速查问题现象可能原因排查方法解决方案npx 命令找不到Node 未安装或 PATH 未配置执行node -v和which npx重装 Node检查环境变量安装卡住不动网络源慢或包体积大加--verbose看卡在哪一步换国内镜像源或手动下载权限报错 EACCES全局目录权限不足看报错路径改 npm 全局目录到用户目录或用 sudo不推荐版本冲突依赖树里有不兼容版本npm ls看依赖树锁定版本或用 pnpm 的严格模式playwright install 失败浏览器二进制下载失败看具体下载哪个组件失败单独下载对应浏览器或设置镜像playwright install 失败是高频问题单独说一下。它失败通常是下载浏览器二进制时网络中断。解决办法是先设置镜像环境变量再重新执行安装。如果还不行就手动下载对应的浏览器包放到缓存目录里再跑安装命令让它跳过下载。5.2 运行类问题排查思路skill 装好了但跑起来不对按这个顺序排查。第一确认 skill 被正确加载。看日志里有没有加载成功的记录或者用平台的 list 命令看已加载的 skill 列表。没加载上后面都白搭。第二确认触发条件命中。有些 skill 是关键词触发的你的输入里没有关键词它就不会激活。改成显式调用试试。第三看指令是否被完整传入。有些平台对指令长度有限制超长会被截断。把指令精简一下或者拆成多个 skill。第四检查工具调用。如果 skill 涉及外部调用看调用有没有发出去、参数对不对、返回是什么。这一步最好有日志没有日志就临时加。第五对比示例。拿 skill 自带的示例输入跑一遍看输出跟示例输出差多少。差太多说明指令有问题差一点说明是边界情况没覆盖。5.3 输出质量不稳定的应对同一个 skill同样的输入两次输出不一样这是大模型的固有特性没法完全消除但可以缓解。降低温度参数。如果平台支持调 temperature调到 0 或 0.1输出会稳定很多。代价是创造性下降但对结构化任务来说是好事。增加输出约束。在指令里明确“必须按以下模板输出不得增删字段”。模板越具体输出越稳定。提供更多示例。示例是最好的锚点。给三到五个高质量示例模型会倾向于模仿示例的格式和风格。分步执行。把一个大任务拆成几个小步骤每步单独调用中间结果落盘。这样每步的输入输出都可控整体稳定性提升明显。提示如果某个 skill 的输出质量始终不达标别死磕。换一个思路把它拆成两个更简单的 skill或者干脆不用 skill直接用精心设计的 prompt。skill 不是万能的它只是工具箱里的一件工具。5.4 安全与权限的避坑要点skill 能调用外部工具就意味着有安全风险。几个必须注意的点。最小权限原则。skill 需要什么权限就给什么权限不要图省事给管理员权限。只读的巡检 skill 就只给读权限绝不给写权限。凭证隔离。API key、token 这些不要写在 skill 文件里用环境变量或密钥管理服务。skill 文件可能会被分享、被提交到仓库硬编码凭证等于泄露。输入校验。skill 接收用户输入时要校验输入内容防止注入类攻击。特别是涉及命令执行的 skill输入必须严格过滤。输出脱敏。skill 输出内容里如果包含敏感信息比如内网 IP、用户手机号要自动脱敏。这个可以在指令里写规则也可以在工具层做后处理。审计日志。skill 的每次调用都记日志包括谁调的、什么时候调的、输入是什么、输出是什么。出问题时能追溯合规检查时能交差。6. 进阶玩法与个人经验分享6.1 把团队经验沉淀成 skill 资产这是我认为 skills 最大的价值所在。团队里总有几个“老法师”他们知道怎么处理各种疑难杂症但这些经验都在脑子里人一走就带走了。把这些经验写成 skill就变成了团队的可复用资产。具体做法是找一个高频且容易出错的场景让老法师口述处理步骤你整理成结构化的指令加上示例和约束做成 skill。然后让团队其他人用收集反馈迭代优化。跑顺了之后这个 skill 就成了团队的标准操作流程。我所在的团队用这种方式沉淀了十几个 skill覆盖代码审查、故障排查、发布检查、文档生成等场景。新人入职第一周就能用这些 skill 干活上手速度比以前快了一倍不止。6.2 skill 的版本管理与灰度发布skill 改动了怎么保证不影响正在用的同学答案是版本管理和灰度发布。版本管理就是每次改动都打 tagmanifest 里写清楚版本号。用户可以选择用哪个版本不强制升级。灰度发布就是新版本先给一小部分人用观察一段时间没问题再全量。具体操作上可以把 skill 仓库分成 stable 和 beta 两个分支。stable 是稳定版beta 是测试版。用户默认拉 stable想尝鲜的拉 beta。发现问题就回滚回滚就是切回上一个 tag几秒钟的事。6.3 我踩过的几个坑坑一指令写太长。我写过一个 3000 字的指令结果模型只记住了开头和结尾中间的关键约束全忽略了。后来拆成三个 skill每个 800 字左右效果好很多。教训是指令要精炼把最重要的放前面次要的放后面。坑二示例给太少。一开始我只给一个示例模型输出格式五花八门。后来加到五个示例覆盖正常、边界、异常三种情况输出立刻稳定了。示例是性价比最高的调优手段。坑三忽略平台差异。同一个 skill在 A 平台跑得好好的换到 B 平台就报错。原因是两个平台对工具定义的 schema 支持不一样。后来我在 manifest 里加了平台标识针对不同平台加载不同的工具定义问题解决。坑四没有错误处理。早期写的 skill 假设一切顺利结果外部 API 一挂整个流程就崩了。后来加了重试、降级、超时健壮性提升明显。写 skill 要像写生产代码一样考虑各种异常情况。6.4 后续可以扩展的方向skill 这套机制还在快速演进有几个方向值得关注。一是自动生成 skill用大模型分析你的操作日志自动提炼出 skill 草稿人工审核后发布。二是skill 市场类似应用商店大家把自己写的 skill 上架按下载量或评分排序形成生态。三是skill 组合编排用可视化工具把多个 skill 连成工作流拖拖拽拽就能搭出一个复杂任务的处理流水线。这些方向有的已经有雏形了有的还在早期。我的建议是先把基础的 skill 写熟、用熟等生态成熟了再跟进新玩法。基础不牢新工具来了也接不住。最后分享一个小技巧每次写完一个 skill先别急着发布自己用一周。一周里遇到的所有问题都记下来改完再发。自己用着别扭的 skill别人用着肯定更别扭。这个习惯帮我省了很多返工的时间。