1. 从“skills”这个标题说起它到底指什么第一次看到“skills”这个标题很多人会以为是某个泛泛而谈的能力清单或者一份简历上的技能罗列。但结合热搜词里反复出现的 Agent Skills、Google Cloud、npx、GKE、claude agent skills、codex skills 这些词基本可以确定这里说的 skills 不是人类的能力而是给 AI Agent 使用的一套可插拔能力包。简单讲它把“让 Agent 干某件事”的完整流程——包括指令、脚本、资源文件、依赖声明——打包成一个目录Agent 在需要的时候按需加载用完即走。这个思路解决了一个很现实的问题。过去我们让大模型干活要么把所有背景塞进一个超长提示词里要么临时写一段代码让模型调用。前者上下文爆炸、维护困难后者每次都要重造轮子。skills 把“能力”变成了像手机 App 一样的东西需要导航就装导航需要写论文就装论文助手需要做分镜就装分镜工具。它适合谁适合所有在用 Agent 做实际工作的人——写代码的、做内容的、跑自动化的、搞测试的甚至做安全研究的。哪怕你只是刚接触 Agent理解 skills 这套机制也能让你少走很多弯路。我自己的体会是skills 真正有意思的地方不在于“多了一个功能”而在于它把上下文管理和能力复用这两件事同时解决了。Agent 的上下文窗口是有限资源skills 的渐进式加载机制让 Agent 只在需要时才把完整指令读进来平时只保留一句描述。这个设计思路值得每个做 Agent 应用的人琢磨。2. skills 的整体设计与核心思路拆解2.1 为什么是“目录 描述文件”这种形态skills 最常见的组织方式是一个文件夹里面放一个描述文件通常是 SKILL.md 或类似的元数据文件再加上可选的脚本、模板、参考资料。Agent 启动时只扫描所有 skills 的描述信息形成一个“能力清单”。当用户的请求匹配到某个 skill 的描述时Agent 才把那个 skill 的完整内容加载进上下文。这个设计背后的逻辑很清晰上下文是稀缺资源。假设你有 50 个 skills每个完整内容 2000 字全量加载就是 10 万字还没开始干活上下文就满了。而只加载描述50 个描述可能才 3000 字剩下的空间留给真正的任务。这就像你手机里装了几十个 App但桌面只显示图标点开哪个才加载哪个的完整界面。另一个考量是可维护性。把能力封装成独立目录意味着你可以单独更新、测试、分享一个 skill而不影响其他部分。团队协作时一个人写好“周报生成 skill”另一个人直接拿来用不需要理解内部实现。这种模块化思路在软件工程里很常见但用在 Agent 能力管理上skills 算是把它做得足够轻量。2.2 渐进式披露skills 最核心的机制渐进式披露progressive disclosure是 skills 的灵魂。它分三层第一层是描述Agent 平时只看到这个第二层是主指令文件匹配后才加载第三层是附属资源比如脚本、模板、示例只有在执行具体步骤时才读取。我举个实际场景。你有一个“论文写作 skill”描述是“帮助撰写学术论文包括结构规划、文献引用、格式调整”。当你说“帮我写一篇关于机器学习的论文”Agent 匹配到这个描述加载主指令里面写着“第一步确认论文类型和字数要求第二步生成大纲第三步逐节撰写引用格式参考 templates/citation.md”。只有走到第三步时Agent 才会去读那个引用模板文件。整个过程上下文占用是动态的而不是一开始就全部塞进去。提示设计 skill 时描述要写得“可匹配但不误导”。太宽泛会导致误触发太窄又匹配不上。我的经验是描述里包含“做什么 什么时候用”两个要素比如“生成周报当用户提到周报、工作总结、本周汇报时使用”。2.3 和传统插件、MCP 的区别在哪热搜词里出现了 claude mcpservers npx说明很多人会把 skills 和 MCPModel Context Protocol放在一起比较。两者确实有关联但定位不同。MCP 更像是“连接器”解决的是 Agent 如何访问外部工具和数据源的问题比如连数据库、连 API。skills 更像是“操作手册”解决的是 Agent 知道有这个工具之后怎么按正确流程使用它。打个比方MCP 是给你一把螺丝刀skills 是告诉你“先拆外壳再拧左下角那颗螺丝注意别滑丝”。两者可以配合使用。一个 skill 里可以调用 MCP 提供的工具也可以直接跑本地脚本。理解这个区别很重要因为它决定了你在设计系统时哪些东西该做成 MCP server哪些该做成 skill。3. 核心细节解析与实操要点3.1 一个 skill 目录里到底放什么标准结构通常长这样my-skill/ SKILL.md # 主指令和元数据 scripts/ # 可执行脚本 process.py templates/ # 模板文件 report.md references/ # 参考资料 api-doc.mdSKILL.md 是入口里面一般包含 frontmatter元数据和正文指令。元数据部分写 name、description、version 这些正文写具体步骤。脚本目录放需要执行的代码模板目录放可复用的文本结构参考资料放按需读取的长文档。我踩过的一个坑是不要把大段参考资料直接写进 SKILL.md。有一次我把一份 5000 字的 API 文档塞进主指令结果每次触发这个 skill 都占用大量上下文其他任务的空间被挤压。后来改成放 references 目录主指令里只写“需要查 API 时读取 references/api-doc.md”问题就解决了。3.2 描述文件怎么写才容易被正确触发描述文件的质量直接决定 skill 能不能被 Agent 正确调用。我总结了一个模板name: weekly-report description: 生成结构化周报。当用户提到周报、工作总结、本周汇报、weekly report 时使用。输入为本周完成事项列表输出为 Markdown 格式周报。关键点有三个。第一动作明确用“生成”“分析”“转换”这类动词开头。第二触发词覆盖把用户可能说的同义词都列上。第三输入输出说明让 Agent 知道什么时候该用、用了之后能得到什么。注意描述不要写得太“聪明”。我见过有人写“当用户需要帮助时使用”这种描述几乎会匹配所有请求导致 skill 被滥用。宁可窄一点也不要宽到失控。3.3 脚本和指令的边界怎么划一个常见困惑是某件事到底该写成指令让模型执行还是写成脚本直接跑我的判断标准是确定性高的用脚本需要判断的用指令。比如“把日期格式从 2024/1/1 转成 2024-01-01”这是确定性操作写个 Python 脚本最稳模型不需要参与。“根据本周完成事项判断哪些值得写进周报”这需要判断写成指令让模型处理。混合使用也很常见指令里写“调用 scripts/format_date.py 处理日期然后根据结果生成周报正文”。这样做的好处是减少模型出错的空间。模型擅长理解和生成不擅长精确计算和格式转换。把后者交给脚本整体可靠性会明显提升。4. 实操过程与核心环节实现4.1 从零创建一个 skill 的完整流程假设我们要做一个“代码审查 skill”帮 Agent 在收到代码时按团队规范做检查。步骤如下。第一步建目录。在 skills 根目录下创建code-review/再建scripts/和references/子目录。第二步写 SKILL.md。元数据部分name: code-review description: 对代码进行规范审查。当用户提交代码片段或文件并提到审查、review、检查规范时使用。 version: 1.0.0正文部分写审查流程先读 references/style-guide.md 获取团队规范然后逐条检查命名、注释、错误处理、测试覆盖最后输出问题列表和修改建议。第三步放参考资料。把团队的代码规范文档放进 references/style-guide.md注意这份文档可以写得详细因为它只在审查时才加载。第四步加脚本可选。如果有一些机械性检查比如“函数长度超过 50 行就报警”可以写个scripts/check_length.py指令里让 Agent 调用它。第五步测试。用几个典型代码片段试触发看 Agent 是否能正确匹配、是否正确读取了参考资料、输出是否符合预期。4.2 参数选择与配置的实际考量skill 的元数据里通常还有一些可选参数比如allowed-tools限制这个 skill 能用哪些工具、model指定用哪个模型执行。这些参数的选择有实际影响。allowed-tools我建议按最小权限原则配置。比如一个只做文本处理的 skill就不需要给它文件删除权限。这样即使指令被误触发也不会造成破坏性操作。model的选择则看任务复杂度简单的格式转换用轻量模型就够复杂的代码审查可能需要更强的模型。还有一个容易被忽略的参数是加载优先级。当多个 skill 描述相似时优先级高的先被考虑。我一般把专用性强的 skill 优先级调高通用性的调低避免“万能 skill”抢走本该由专用 skill 处理的任务。4.3 在 Google Cloud 和 GKE 环境下的部署思路热搜词里出现了 Google Cloud 和 GKE说明很多团队会把 skills 跑在云上。基本思路是把 skills 目录放在一个共享存储里Agent 运行时挂载这个目录。如果用量大可以做成服务一个轻量 API 负责按需返回 skill 内容Agent 通过调用这个 API 来加载。在 GKE 上部署时我建议把 skills 做成 ConfigMap 或者单独的镜像层。ConfigMap 适合内容经常变的情况改完直接更新镜像层适合版本化管理每次发布打一个新 tag。两种方式各有优劣看团队的工作流。关键是不要让 skills 和 Agent 主程序耦合太紧保持独立更新能力。提示云端部署时注意 skill 里的脚本执行环境。本地跑得好好的 Python 脚本到了容器里可能缺依赖。建议每个 skill 自带 requirements 说明或者在镜像构建阶段统一装好。5. 常见问题与排查技巧实录5.1 skill 不触发或误触发怎么办这是最高频的问题。不触发通常是描述写得太窄或者用户的表达方式和描述里的触发词对不上。解决办法是收集实际使用中的用户表达反哺到描述里。误触发则是描述太宽或者多个 skill 描述重叠。这时候要检查是否有 skill 的职责边界不清该合并的合并该拆分的拆分。我自己的排查习惯是打开 Agent 的日志看它匹配到了哪个 skill、匹配理由是什么。大部分问题看日志就能定位。5.2 脚本执行失败的典型原因脚本失败常见于三种情况路径问题、依赖缺失、权限不足。路径问题最多因为 skill 被加载时工作目录可能和你想的不一样。建议脚本里统一用相对于 skill 目录的路径或者由指令明确传入绝对路径。依赖缺失在跨环境时很常见本地有 pandas、云上没有跑起来就报错。权限不足则多见于需要写文件的 skill容器里没挂载可写目录。问题现象可能原因排查方法脚本报文件找不到工作目录不对打印当前目录改用绝对路径报模块不存在依赖未安装检查环境补 requirements报权限拒绝无写权限检查挂载和用户权限输出乱码编码不一致统一用 UTF-85.3 上下文被占满的优化手段如果发现 Agent 响应变慢或者开始“忘事”很可能是上下文被 skills 占多了。优化手段有几个把大段参考资料移到 references 按需加载精简主指令去掉冗余解释合并功能相近的 skill减少描述数量给 skill 设置更严格的触发条件减少不必要的加载。我实测下来一个设计良好的 skill 在未触发时只占几十个 token 的描述触发后主指令控制在 500 到 1500 token参考资料按需读取。这样即使有几十个 skills也不会对日常使用造成明显负担。5.4 跨平台使用 skills 的兼容性注意点不同 Agent 平台对 skills 的支持细节有差异。有的要求特定文件名有的对元数据字段有额外要求有的脚本执行环境不同。如果你想让一个 skill 在多个平台通用建议把平台相关的部分抽出来用条件判断处理。核心指令和参考资料尽量保持平台无关这样迁移成本最低。6. 进阶玩法与经验沉淀6.1 组合多个 skill 完成复杂任务单个 skill 解决单点问题组合起来能完成复杂工作流。比如“论文写作”可以拆成“大纲生成”“文献整理”“格式调整”三个 skillAgent 根据任务阶段依次调用。这种组合方式比写一个巨型 skill 更好维护每个部分可以独立迭代。组合的关键是接口清晰。前一个 skill 的输出格式要和后一个的输入格式对得上。我一般会在 skill 描述里明确写“输入为 XX 格式输出为 YY 格式”这样 Agent 在编排时不容易出错。6.2 把个人经验固化成 skillskills 最有价值的用法之一是把你自己的工作经验固化下来。比如你有一套独特的代码审查清单或者一套内容创作的检查流程写成 skill 之后Agent 就能按你的标准工作而不是按通用标准。这相当于把你的“手艺”变成了可复用的资产。我建议从最高频、最标准化的任务开始做 skill。不要一上来就追求大而全先做一个能跑通的小 skill用起来再迭代。很多人的问题是设计阶段想太多结果一直没落地。6.3 版本管理与团队协作skills 多了之后版本管理就重要了。建议用 Git 管理 skills 目录每个 skill 独立版本号。团队协作时可以建一个共享仓库大家提交自己的 skill定期 review 和合并。这样能避免重复造轮子也能让好的实践快速传播。注意共享 skill 时注意脱敏。skill 里可能包含内部规范、API 地址、示例数据分享前检查一遍避免泄露敏感信息。6.4 性能与成本的平衡skills 用多了token 消耗会上升。控制成本的手段包括精简描述、按需加载、缓存常用 skill 的加载结果、对简单任务用轻量模型。我自己的做法是给 skills 分等级核心 skill 常驻边缘 skill 按需加载很少用的 skill 归档。这样在能力和成本之间找到一个平衡点。最后分享一个我踩过的坑早期我做了很多 skill但没有统一命名规范结果时间一长自己都记不清哪个是哪个。后来改成“领域-动作”的命名方式比如code-review、doc-summary、>