1. 从“skills”这个标题说起它到底指什么第一次看到“skills”这个标题很多人会以为是某个泛泛而谈的能力清单或者一份简历上的技能罗列。但结合热词里的 Google Cloud、Agent Skills、npx、GKE 这些词方向就很清楚了——这里说的 skills是围绕 AI Agent智能体构建的一套可插拔能力模块。简单讲它把“让 Agent 会做某件事”这件事从写死在提示词里变成了像装软件包一样可以安装、卸载、组合、复用的独立单元。我接触这套东西的起点是看到社区里有人用npx一条命令就把一个 skill 装进本地环境然后 Agent 立刻多了一项能力比如自动做代码审查、自动生成分镜脚本、自动跑一遍漏洞扫描。那种感觉确实像“打开新世界”——因为它把过去需要反复调提示词、反复贴上下文的工作收敛成了一个标准化的包。这篇文章适合三类人看一是已经在用 Claude、Codex 这类 Agent 工具想让它们干更多具体活的人二是想自己开发 skill 并分发给别人的人三是团队里负责把 Agent 能力工程化、平台化的人。我会从设计思路讲到实操细节再到踩坑排查尽量把每一步为什么这么做都讲清楚。核心关键词 skills、Agent Skills、npx、Google Cloud、GKE 会自然贯穿全文不堆砌。需要先说明一点skills 目前没有唯一官方标准不同平台Claude 生态、Codex 生态、Google Cloud 的 Agent 体系实现细节有差异。下面讲的是基于常见实践归纳出的通用模型具体到某个平台时我会标注差异。你把它当成一套“方法论 可抄作业的步骤”来用而不是当成某个产品的说明书。2. skills 的整体设计与思路拆解2.1 为什么要把能力拆成 skill过去让 Agent 做一件复杂的事主流做法是把所有要求塞进一个超长提示词角色设定、输出格式、工具调用规则、边界条件全堆在一起。这个做法在任务单一的时候能用但一旦任务变多提示词就会膨胀到难以维护。改一个格式要求可能影响另一个任务的输出想复用某段逻辑只能复制粘贴。skills 的核心思路是“关注点分离”。一个 skill 只负责一类能力它有自己的描述、触发条件、执行逻辑和依赖声明。Agent 在运行时根据当前任务去匹配、加载对应的 skill。这样做的好处很直接能力可以独立迭代A skill 升级不影响 B skill能力可以组合一个复杂任务由多个 skill 串起来完成能力可以分发别人写好你直接装。打个生活化的比方以前的提示词像是一本把所有菜谱写在一起的手抄本想加一道菜就得重抄整本skills 像是把每道菜做成独立的料理包需要哪道拆哪道还能自由拼桌。这个类比基本能解释为什么社区对 skills 这么兴奋。2.2 一个 skill 通常由哪些部分组成虽然各平台格式不完全一样但一个完整的 skill 一般包含这几块元信息metadata名称、版本、作者、一句话描述。描述很关键Agent 靠它判断“这个任务该不该用这个 skill”。触发条件trigger什么情况下激活。可以是关键词匹配也可以是语义匹配还可以是显式调用。指令主体instructions告诉 Agent 具体怎么做相当于这个 skill 内部的提示词。工具与依赖tools / dependencies需要调用哪些外部工具、需要哪些运行时环境。比如要跑浏览器自动化就依赖 Playwright要访问云资源就依赖对应的 SDK。输入输出契约I/O schema输入什么参数、输出什么结构。这一块决定了 skill 能不能被稳定组合。我见过不少人写 skill 只写指令主体忽略 I/O 契约结果两个 skill 想串起来时对不上只能靠人工在中间转一道。这是很典型的坑后面排查章节会细说。2.3 方案选型本地装还是云端跑热词里同时出现了 npx 和 GKE这其实对应了两种部署思路。本地装npx 方式适合个人开发者和小团队。npx是 Node 生态里的包执行器它能直接从仓库拉取并运行一个包不需要你先全局安装。用它来装 skill好处是快、轻、隔离性好——每个 skill 在自己的依赖环境里跑不会污染全局。缺点是依赖本机环境换台机器就得重装团队协作时环境一致性难保证。云端跑GKE 方式适合需要规模化、需要多人共享、需要稳定算力的场景。把 skill 的执行环境容器化部署到 Kubernetes 集群上Agent 通过接口调用。好处是环境统一、可扩缩容、可观测。缺点是重搭一套的成本不低个人玩没必要。我的建议是先用 npx 在本地把 skill 跑通、把逻辑调对确认有价值之后再考虑往云端迁。不要一上来就上集群那是给自己找麻烦。选型的判断标准就一条——你现在是“验证想法”还是“交付服务”。验证想法用本地交付服务用云端。3. 核心细节解析与实操要点3.1 skill 的目录结构长什么样一个规范的 skill 目录我一般会组织成这样my-skill/ ├── skill.json # 元信息与 I/O 契约 ├── instructions.md # 指令主体 ├── tools/ # 工具封装 │ └── index.js ├── package.json # 依赖声明 └── README.md # 使用说明skill.json是整个 skill 的入口Agent 先读它再决定要不要加载后面的内容。这个设计的好处是“轻量探测”——不用把整个 skill 加载进来就能判断相关性节省上下文。instructions.md用 Markdown 写是因为 Markdown 对模型友好结构清晰模型容易解析出步骤和约束。我试过用纯文本和 JSON 写指令效果都不如 Markdown尤其是涉及多步骤流程时Markdown 的标题和列表能帮模型建立层次感。3.2 元信息怎么写才容易被正确触发元信息里最容易被写坏的是description字段。很多人写成“这是一个用于处理数据的 skill”这种描述等于没写Agent 根本判断不出什么时候该用它。好的描述要包含三个要素做什么、什么场景用、有什么限制。举个例子差的写法description: 代码审查工具好的写法description: 对 Git 暂存区的改动做静态审查检查空指针、资源泄漏、命名规范。适用于提交前的自检不适用于架构级评审。第二种写法里“Git 暂存区”限定了输入来源“空指针、资源泄漏、命名规范”说明了检查范围“提交前自检”点明了使用时机“不适用于架构级评审”划清了边界。Agent 拿到这样的描述匹配准确率会高很多。注意description 不要写得太长一般控制在 100 字以内。太长会占用上下文而且模型抓重点反而变难。把详细说明放到 instructions 里。3.3 指令主体的写法把模型当新人带写 instructions 的时候我习惯把模型当成一个刚入职、能力很强但完全不了解你业务的新人。你要告诉他目标是什么、步骤分几步、每步的输入输出是什么、遇到异常怎么办、什么情况必须停下来问人。一个常见的错误是写得太抽象。比如“请仔细分析代码质量”模型不知道“仔细”是什么标准。改成“逐行检查对每个函数判断是否存在未释放的文件句柄若存在则在输出中列出函数名和行号”就具体多了。另一个错误是步骤之间没有衔接。比如第一步输出一个列表第二步却要求“基于上面的结果继续处理”但没说清楚列表的格式。模型只能猜猜错就崩。所以每一步的输出格式都要显式定义最好给个示例。3.4 依赖管理npx 装 skill 时最容易出问题的地方用 npx 装 skill本质是拉一个 Node 包下来跑。这里最容易出问题的就是依赖。热词里有个“npx playwright install 失败”这是非常典型的场景——skill 依赖 Playwright 做浏览器自动化但 Playwright 需要下载浏览器二进制这一步经常因为网络或权限问题失败。处理这类问题的思路是把依赖分成“包依赖”和“运行时依赖”两类。包依赖由 npm 管运行时依赖比如浏览器二进制、系统库要单独处理。在 skill 的 README 里明确写清楚需要哪些运行时依赖以及怎么装。不要假设用户环境里已经有。我一般会在 skill 里加一个preflight检查脚本启动时先检查关键依赖在不在不在就给出明确的安装提示而不是等到执行到一半才报错。这个习惯能省掉大量“为什么跑不通”的沟通成本。4. 实操过程与核心环节实现4.1 从零写一个 skill 的完整流程假设我要写一个“自动生成分镜脚本”的 skill热词里有“分镜 skills 下载”说明这个需求真实存在。完整流程如下。第一步定义能力边界。这个 skill 只做一件事——把一段文字描述转成结构化的分镜列表每个分镜包含镜号、画面描述、时长、运镜方式。它不负责生成图片不负责配音那些是别的 skill 的事。边界清晰后面才好组合。第二步写 skill.json。元信息里描述清楚触发场景I/O 契约定义输入是文本、输出是 JSON 数组。{ name: storyboard-generator, version: 1.0.0, description: 把文字脚本转成结构化分镜列表含镜号、画面、时长、运镜。适用于短视频前期策划不适用于成片剪辑。, input: { type: object, properties: { script: { type: string }, maxShots: { type: number, default: 20 } }, required: [script] }, output: { type: array, items: { type: object, properties: { shotNo: { type: number }, scene: { type: string }, duration: { type: number }, camera: { type: string } } } } }第三步写 instructions.md。把生成规则讲清楚。比如“每个分镜时长控制在 2 到 5 秒”“运镜方式从固定、推、拉、摇、移里选”“总时长不超过 maxShots 乘以 5 秒”。规则越具体输出越稳定。第四步本地测试。用 npx 把 skill 挂到本地 Agent 环境喂几段不同风格的脚本看输出是否符合契约。重点测边界情况脚本特别短怎么办、特别长怎么办、包含对话怎么办。第五步打包分发。确认稳定后发布到包仓库别人就能用 npx 装了。4.2 参数选择maxShots 为什么默认 20这个默认值不是随便定的。短视频平台常见时长是 60 到 90 秒单个分镜平均 3 到 4 秒算下来大概 15 到 25 个分镜。取 20 作为默认值覆盖大多数场景。如果用户做的是长视频可以显式传更大的值。这种“基于真实场景反推默认值”的做法比拍脑袋定一个 10 或者 100 要靠谱。写 skill 的时候凡是涉及数值参数都问自己一句这个值在真实使用场景里对应什么算一遍再定。4.3 把 skill 部署到 GKE 的关键步骤如果确实需要云端部署大致步骤是这样容器化给 skill 写 Dockerfile把运行时依赖Node、Playwright 浏览器等都装进镜像。基础镜像选轻量的比如 node:20-slim。定义服务接口skill 在云端要以服务形式暴露通常包一层 HTTP 接口接收输入、返回输出。写 K8s 部署文件Deployment 定义副本数和资源限制Service 定义访问入口。资源限制很重要Playwright 这类依赖吃内存limit 给太小会被 OOM kill。配置健康检查liveness 和 readiness 探针都要配否则流量会打到还没准备好的 Pod 上。灰度发布新版本先放一个小比例流量观察没问题再全量。这里有个经验云端跑 skill最大的成本不是算力是调试。本地能直接看日志、打断点云端只能靠日志和指标。所以我的做法是本地把逻辑调到 95% 稳定再上云云端只解决“规模”和“共享”两个问题不指望在云端调逻辑。5. 常见问题与排查技巧实录5.1 skill 装了但 Agent 不触发这是最高频的问题。原因通常有三个描述不匹配、触发条件太严、优先级被别的 skill 抢了。排查顺序先看 description 是否覆盖了用户实际会说的表达。用户说“帮我看看这段代码有没有问题”你的描述写的是“静态代码审查”语义上能匹配但如果描述写的是“AST 分析”就可能匹配不上。其次看触发条件如果设了必须包含特定关键词用户没说这个词就不会触发。最后看是不是有另一个 skill 的描述更贴合把机会抢走了。解决办法把 description 改得更贴近自然语言减少硬性关键词依赖必要时给 skill 加显式调用别名。5.2 npx 安装时报依赖缺失典型报错是找不到某个二进制或某个系统库。前面提过根因是运行时依赖没装。排查时先看报错里提到的具体文件或命令然后确认它在不在 PATH 里。Playwright 的浏览器二进制默认装在用户目录下的缓存里如果换了用户或清了缓存就会丢。速查表如下现象可能原因处理方式找不到浏览器可执行文件浏览器二进制未下载重跑安装命令确认缓存目录可写权限拒绝缓存目录权限不对修正目录权限或换安装路径网络超时下载源不可达配置镜像源或离线安装版本不匹配包版本与二进制版本不一致锁定版本统一升级5.3 skill 之间组合时数据对不上两个 skill 串联前一个输出 JSON后一个期望 YAML中间就断了。这类问题的根源是 I/O 契约没对齐。解决办法是在设计阶段就统一数据格式我一般全用 JSON因为模型对 JSON 的生成和解析都最稳。如果已经出现了对不上加一个转换层别去改两个 skill 的内部逻辑。转换层单独做成一个小 skill职责单一也好维护。5.4 输出不稳定同样的输入结果差异大模型输出有随机性这是客观事实。降低波动的办法把 instructions 里的规则写得更硬能枚举的就枚举别用“等等”“之类”这种开放词在 I/O 契约里加校验输出不符合结构就重试把温度参数调低如果平台支持。我实测下来把规则从“输出合适的分镜”改成“输出恰好 N 个分镜每个分镜时长在 2 到 5 秒之间”稳定性提升非常明显。模糊的形容词是稳定性的天敌。5.5 踩过的坑别把 skill 写成万能工具我早期写过一个 skill想让它同时处理代码审查、文档生成、测试用例编写三件事。结果描述写不清触发混乱输出格式在三种任务间来回横跳最后没法用。后来拆成三个独立 skill每个都稳定了。这个教训很值钱一个 skill 只做一件事。想覆盖多个场景就写多个 skill让 Agent 去组合。拆开之后不仅稳定还更容易复用——别人只需要文档生成就只装那一个。6. skills 生态的扩展玩法与个人体会6.1 从“用别人的”到“写自己的”社区里已经有大量现成 skill 可以下载覆盖代码、写作、设计、安全测试等方向。刚开始用的时候直接装现成的最快。但用着用着你会发现通用 skill 总有些地方不贴合你的具体流程。这时候就该动手改或者自己写。我的路径是先装三个同类 skill 对比看它们各自怎么定义描述、怎么组织指令然后取长补短写一个自己的。这个过程本身就是最好的学习。写 skill 的能力本质是把“你脑子里的隐性流程”显性化成模型能执行的步骤这个能力在 Agent 时代会越来越值钱。6.2 团队内共享 skill 的注意事项团队共享 skill最大的挑战不是技术是版本和约定。我的做法是给 skill 定语义化版本号破坏性变更必须升大版本建一个内部索引记录每个 skill 的用途、负责人、当前版本新 skill 上线前必须过一遍 I/O 契约检查。还有一点共享的 skill 要写清楚“不适用场景”。很多人只写能干什么不写不能干什么结果别人在不合适的场景用了出了问题还以为是 skill 的 bug。把边界写清楚是对使用者的尊重也是对自己的保护。6.3 我个人在实际操作中的体会折腾 skills 这段时间最大的感受是它把 Agent 从“一个什么都懂一点但什么都不精的通才”变成了“一个可以按需装配专业能力的平台”。这个转变的意义比单个 skill 好不好用大得多。如果让我给刚入门的人一句建议那就是别急着写复杂的 skill先写一个只做一件小事的把它从描述到输出全部打磨顺跑通整个“写—装—用—改”的循环。这个循环跑通了后面写多复杂的都不慌。我见过太多人一上来就想写个大而全的结果卡在依赖装不上、触发不生效这些基础问题上热情很快就耗没了。另外遇到装不上的依赖、触发不了的情况先别怀疑自己的 skill 逻辑八成是环境或描述的问题。按排查章节的顺序过一遍基本都能定位。skills 这东西门槛在“跑通第一个”跑通之后就是复制和组合的事了。