1. 从skills这个模糊词说起它到底指什么第一次看到skills这个标题加上项目正文和关键词全是空的我其实是有点懵的。但结合热搜词里那一串——Google Cloud、Agent Skills、npx、GKE、claude agent skills、codex skills、skills开发、skills安装包——基本可以锁定这里说的不是泛泛的技能概念而是AI Agent 生态里的 Skills 机制也就是给智能体挂载可复用能力模块的那套东西。打个比方。大模型本身像一个刚毕业的高材生脑子好使但没进过具体岗位。你让它写代码它也能写让它查数据库它也能查但每次都要你从头把背景、规范、工具用法讲一遍效率极低。Skills 就是给这个高材生配的一本岗位操作手册加一套工具箱手册告诉它遇到什么场景该走什么流程工具箱给它现成的脚本、模板、API 封装。挂上 Skills 之后同一个模型在特定任务上的表现会稳定很多因为它不用每次即兴发挥了。这套机制目前主要活跃在几个地方Claude 的 Agent Skills、Codex 的 skills 体系、以及围绕 Google Cloud / GKE 做云上 Agent 部署时用到的技能包。热搜里出现的npx、npx playwright install失败、claude mcpservers npx这些说明大量 Skills 是通过 npm 生态分发和安装的MCP Server 又是 Skills 调用外部工具的常见通道。所以这篇东西适合谁看三类人一是刚听说 Agent Skills、想搞清楚它和普通 prompt / function calling 有什么区别的开发者二是已经在用 Claude 或 Codex想自己写 skills 提升日常效率的人三是需要在云环境比如 GKE里批量部署和管理 skills 的工程团队。我会从概念、结构、开发、安装、踩坑、云上落地几个角度把它讲透尽量让你看完能直接动手。2. Agent Skills 和普通 Prompt、Function Calling 的本质区别2.1 为什么多写点提示词解决不了问题很多人第一反应是我提示词写详细点不就行了搞什么 Skills我一开始也这么想直到我把同一个复杂任务用两种方式各跑了二十遍。纯提示词方案的问题在于上下文漂移。你写了两千字的规范模型在前几轮还记得聊到第十轮、上下文被各种中间结果塞满之后它就开始忘了——该走的校验步骤跳过了该用的工具想不起来用了。这不是模型笨是注意力被稀释了。而且提示词是软约束模型可以合理地把你的要求理解偏。Skills 的核心价值是把软约束变成硬结构。一个 Skill 通常包含三部分元数据名称、描述、触发条件、指令正文Markdown 写的操作流程、可执行资源脚本、模板、参考文档。模型在需要的时候按需加载而不是一股脑塞进上下文。这就像查手册——你不会把整本手册背下来而是遇到问题时翻到对应那一页。2.2 Skills 与 Function Calling 的分工Function Calling 解决的是模型怎么调用一个具体函数的问题它是单次、原子的给模型一个工具定义模型决定调不调、传什么参数。但真实任务往往是多步骤的、有条件的、需要判断的。Skills 更像是编排层。一个 Skill 内部可以描述第一步先读配置文件第二步根据配置决定用哪个工具第三步校验输出格式第四步失败时怎么重试。它可以把多个 Function Calling 串起来还能带上领域知识和判断逻辑。热搜里agent tool agent skills这个词很说明问题——工具是工具技能是技能技能负责什么时候用哪个工具、怎么组合。2.3 一张表看清三者边界维度纯 PromptFunction CallingAgent Skills本质自然语言指令结构化工具调用可复用能力模块加载方式全量塞入上下文按需注册按需加载渐进披露复用性复制粘贴需重新定义打包分发跨项目复用适合场景一次性任务单点工具调用多步骤、有规范的复杂流程典型载体对话JSON SchemaMarkdown 脚本 资源理解这张表后面所有实操你都不会迷路。我见过太多人把 Skills 当成高级提示词来写结果写出来的东西又长又乱模型反而不爱用。记住Skill 是给模型看的操作手册不是给你自己看的备忘录。3. 一个 Skill 的解剖目录结构、元数据与渐进披露3.1 标准目录长什么样虽然不同平台Claude、Codex、各家 Agent 框架细节有差异但一个规范的 Skill 目录结构高度趋同基本是这样my-skill/ ├── SKILL.md # 核心元数据 指令正文 ├── scripts/ # 可执行脚本 │ ├── validate.py │ └── fetch.sh ├── references/ # 参考文档按需读取 │ └── api-spec.md └── assets/ # 模板、静态资源 └── report-template.mdSKILL.md是入口也是最重要的文件。它的头部是 YAML 格式的元数据frontmatter下面才是正文。这个设计的关键在于渐进披露Progressive Disclosure模型启动时只加载所有 Skill 的元数据名称描述几十个 token只有当它判断某个 Skill 相关时才去读完整的SKILL.md再需要时才去读references/里的细节。3.2 元数据怎么写才会被触发元数据里最关键的是name和description。description直接决定模型会不会在合适的时候想起你。我踩过的坑是一开始把描述写得很官方比如用于处理数据相关任务结果模型几乎从不触发它因为太模糊了。正确的写法是把触发场景写具体甚至把用户可能说的原话写进去。比如--- name: gke-deploy-checker description: 当用户需要检查 GKE 集群部署配置、排查 Pod 启动失败、验证 YAML 清单合法性时使用。适用于 kubectl apply 报错、镜像拉取失败、资源配额不足等场景。 ---你看描述里带了具体场景词GKE、Pod、YAML、kubectl模型在做语义匹配时命中率高得多。这是纯经验文档里不会强调但你写十个 Skill 之后就会明白描述的重要性。3.3 正文指令的写法像写给新人不像写给机器正文部分我建议用步骤化 判断分支的结构。不要写成散文模型对有序步骤的执行稳定性明显更高。一个典型的正文骨架## 使用流程 1. 先读取项目根目录的 config.yaml确认目标环境。 2. 如果环境是 production执行前必须输出变更摘要并等待确认。 3. 运行 scripts/validate.py 做静态校验。 4. 校验失败时读取 references/error-codes.md 对照错误码给出修复建议。 5. 校验通过后执行部署并采集 30 秒日志确认无 CrashLoopBackOff。注意第 2 步和第 4 步——带条件的判断和失败时的兜底这才是 Skill 比 prompt 强的地方。很多人写 Skill 只写顺利路径一遇到异常模型就抓瞎等于白写。提示正文里引用脚本和参考文档时用相对路径并且明确说明何时读取。模型不会主动去翻你没提到的文件。4. 从零开发一个可用的 Skill完整实操链路4.1 先想清楚这个 Skill 解决哪一类重复劳动开发 Skill 最大的误区是贪大求全。我见过有人想写一个万能运维 Skill结果里面塞了二十个流程模型每次加载都要读几千 token触发还特别不准。正确做法是一个 Skill 只干一件事但把这件事干到极致。判断标准很简单如果这个任务你每周要重复做三次以上且步骤相对固定就值得做成 Skill。比如生成周报、检查 PR 的代码规范、把 Figma 导出的分镜整理成规范格式热搜里那个分镜skills就是这个思路。4.2 手写第一个 SKILL.md假设我们要做一个代码审查 Skill。先建目录再写文件mkdir -p code-review-skill/scripts cd code-review-skill touch SKILL.mdSKILL.md内容--- name: code-review-helper description: 当用户提交代码片段或 PR 链接需要审查时使用。覆盖命名规范、边界条件、错误处理、性能隐患四类检查项。 --- ## 审查流程 1. 通读代码先判断语言和框架选择对应的检查清单。 2. 按以下四类逐项检查每类至少给出一条具体意见 - 命名规范变量、函数、类名是否表意清晰 - 边界条件空值、越界、并发、超时是否处理 - 错误处理异常是否被吞掉是否有兜底 - 性能隐患循环内查询、重复计算、内存泄漏 3. 输出格式先给结论通过/需修改再列问题每条问题附修改建议。 4. 如果代码超过 300 行先读 references/review-checklist.md 做系统化检查。写完这个一个最小可用 Skill 就成了。你会发现它没有任何魔法就是把一个资深工程师脑子里的检查流程显式化了。4.3 加脚本让 Skill 真正能动手光有指令还不够真正的效率提升来自脚本。比如加一个自动统计代码复杂度的脚本# scripts/complexity.py import sys import ast def count_branches(tree): count 0 for node in ast.walk(tree): if isinstance(node, (ast.If, ast.For, ast.While, ast.Try)): count 1 return count if __name__ __main__: path sys.argv[1] with open(path, encodingutf-8) as f: tree ast.parse(f.read()) print(f分支数量: {count_branches(tree)})然后在SKILL.md里加一句第 2 步之前先运行python scripts/complexity.py 文件路径分支数超过 15 时重点提示可维护性风险。 这样 Skill 就从会说话变成会干活了。4.4 本地测试别跳过这一步写完直接扔进生产环境是大忌。我的做法是准备一组回归用例五个典型输入两个边界输入一个异常输入。每次改完 Skill 都跑一遍看触发是否准确、步骤是否被完整执行。测试时重点观察三件事一是触发率该触发时有没有触发二是步骤完成度有没有跳步三是输出稳定性同样输入多次运行结果是否一致。第三点最能暴露问题——如果结果飘忽多半是正文指令有歧义。5. 安装与分发npx、MCP Server 与那些绕不开的坑5.1 npx 为什么成了 Skills 分发的默认姿势热搜里npx、claude mcpservers npx、npx playwright install失败反复出现说明现在大量 Skills 和 MCP Server 都走 npm 分发。原因很实际npm 生态成熟npx可以免安装直接运行跨平台版本管理也方便。典型安装命令长这样npx some-org/skill-installer add code-review-helper或者针对 MCP Servernpx -y modelcontextprotocol/server-filesystem /path/to/dir-y参数是自动确认脚本化部署时必加否则会卡在交互提示上。5.2npx playwright install失败到底卡在哪这个报错在热搜里出现频率极高我帮人排查过不下十次根因基本就三类第一类网络下载超时。Playwright 安装时会去下载浏览器二进制包体积几百 MB网络不稳就断。解决办法是设置镜像源或提前把浏览器包缓存到本地。可以配置环境变量指向国内镜像export PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright npx playwright install chromium第二类权限问题。在 CI 容器或受限环境里默认安装路径没有写权限。指定一个可写目录即可export PLAYWRIGHT_BROWSERS_PATH$HOME/.cache/ms-playwright npx playwright install第三类系统依赖缺失。Linux 上缺libnss3、libatk之类的库浏览器装上了也起不来。Debian 系可以npx playwright install-deps排查顺序建议是先看报错是下载失败还是启动失败前者查网络和路径后者查系统依赖。别一上来就重装浪费时间。5.3 MCP Server 与 Skill 的配合关系MCPModel Context ProtocolServer 负责把外部能力文件系统、数据库、浏览器暴露给模型Skill 负责告诉模型什么时候、按什么顺序用这些能力。两者是互补的。配置 MCP Server 通常是在客户端的配置文件里加一段{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /data] } } }配好之后Skill 的正文里就可以直接引用这些能力比如使用 filesystem 工具读取 /data 下的日志文件。这里有个坑MCP Server 启动失败时Skill 不会报错只会静默地用不了。所以部署后一定要单独验证每个 Server 是否真的起来了。注意安装第三方 Skill 和 MCP Server 前务必确认来源可信。这类组件往往有文件读写甚至命令执行权限来源不明的包风险很高。6. 云上落地GKE 环境里管理 Skills 的工程化思路6.1 为什么要在 GKE 上跑 Agent热搜里Google Cloud、GKE和Agent Skills绑在一起指向一个真实需求把 Agent 能力做成可弹性伸缩的服务。本地跑 Skill 适合个人但团队协作、批量任务、定时调度这些场景还是得放到集群里。在 GKE 上跑 Agent 的典型架构是一个 Deployment 跑 Agent 运行时Skills 通过 ConfigMap 或镜像内置的方式挂载MCP Server 作为 Sidecar 容器或者独立 Service。这样扩容、灰度、回滚都能用 K8s 那套成熟机制。6.2 Skills 的版本管理别用 latest这是我在生产环境踩过的最疼的坑。早期图省事Skill 镜像 tag 用latest结果某次上游更新了一个 Skill 的描述触发逻辑变了线上任务大面积跑偏排查了半天才发现是镜像被悄悄更新了。正确做法是给每个 Skill 打语义化版本镜像 tag 固定到具体版本号apiVersion: apps/v1 kind: Deployment metadata: name: agent-runtime spec: template: spec: containers: - name: agent image: registry.example.com/agent-runtime:1.4.2 volumeMounts: - name: skills mountPath: /app/skills volumes: - name: skills configMap: name: agent-skills-v3Skills 用 ConfigMap 挂载的好处是更新不用重建镜像改完 ConfigMap 滚动重启即可。但要注意 ConfigMap 有大小限制默认 1MBSkill 多了或者带大文件就得改用其他方案。6.3 资源配额与超时Agent 任务的两个隐形杀手Agent 任务和普通 Web 服务不一样它的执行时间波动极大——简单任务几秒复杂任务可能跑几分钟。如果不设超时一个卡住的 Skill 会一直占着 Pod把资源耗光。我的配置经验是给 Agent 容器设activeDeadlineSeconds或者应用层的任务超时一般单任务 300 秒封顶资源 request 给保守值limit 给足因为 Agent 加载模型和读文件时内存峰值不低。另外建议给 Agent 单独建一个 Node Pool避免和在线服务抢资源。6.4 可观测性日志里要能看到用了哪个 SkillAgent 出问题时最难查的是它到底走了哪条路。所以从第一天起就要在 Skill 执行的关键节点打结构化日志Skill 名称、版本、触发原因、每步耗时、最终结果。这样出问题能快速定位是触发错了、还是某一步执行失败了。我一般会在 Agent 运行时里统一埋点Skill 本身不用管日志降低开发负担。日志格式用 JSON方便接 GKE 的 Cloud Logging 做检索和告警。7. 那些只有踩过才知道的坑与经验7.1 描述写太宽Skill 变成万金油前面提过这里再强调一次因为它太常见了。一个 Skill 的描述如果覆盖了太多场景模型会在不相关的时候也触发它反而干扰主流程。我的经验是描述里出现的场景词最好和 Skill 实际能处理的场景严格对应宁可窄一点也不要宽。7.2 正文里别写尽量最好这类模糊词模型对模糊词的处理很不稳定。尽量检查边界条件和必须检查空值、越界、并发三种情况后者执行率高得多。写 Skill 正文时把尽量建议可以考虑全部换成明确的动作和条件判断。7.3 脚本要幂等失败要能重跑Skill 里的脚本经常会被重试执行所以必须幂等。比如一个生成报告的脚本重复跑不应该产生重复文件或者重复追加内容。我习惯在脚本开头做状态检查已经完成的步骤直接跳过。这个习惯在云上批量任务里能救命。7.4 别把密钥写进 Skill见过有人图方便把 API Key 直接写在 Skill 的脚本里。这在本地可能没事一旦 Skill 被分发或者镜像被推送密钥就泄露了。正确做法是通过环境变量或密钥管理服务注入Skill 里只引用变量名。7.5 定期清理不再使用的 SkillSkill 越积越多元数据全量加载时占的 token 也越来越多会拖慢模型判断。我一般每季度过一遍把三个月没触发过的 Skill 归档。保持活跃 Skill 列表精简触发准确率会明显提升。8. 关于 Skills 生态的一点个人判断从热搜词能看出来Skills 生态现在处于一个快速膨胀的阶段skills大全、skills推荐、codex好用的skills、github skills这些词说明大家已经在互相分享和挑选了。这是好事但也意味着质量参差不齐。我自己挑 Skill 的标准就三条描述是否具体、正文是否有失败兜底、脚本是否幂等。满足这三条的基本都能用缺一条就要谨慎。至于自己开发我的建议永远是先从一个最小可用的 Skill 开始跑通触发、执行、异常处理这条完整链路再考虑复杂化。很多人一上来就想写超级 Skill最后往往连触发都调不准。这套东西真正的价值不在于技术多高深而在于它逼着你把脑子里那些只可意会的经验显式化、结构化。写 Skill 的过程其实也是梳理自己工作方法的过程。我写完第一个能用的 Skill 之后最大的感受不是AI 变强了而是我终于把自己那套流程说明白了。
