我第一次完整看完Agent Skills的技术说明时第一反应是这不就是给模型写了一份更规范的提示词文档吗后来我自己把一个数学建模的完整作战流程打包成skill装进Claude Code让它从头到尾独立完成一次建模任务我才发现这东西和prompt完全是两个物种。作为一个已经把大量日常任务交给编程Agent的人我花了两周时间把市面上主流的skills生态摸了一遍又自己拆解、开发、踩坑了好几个星期。这篇东西就是把这段时间的认知沉淀下来Skills到底是什么、它和Prompt/MCP/Knowledge怎么分工、怎么安装别人的技能包、怎么从零开发自己的第一个skill、以及那些文档里永远不会写但实战中一定会碰到的坑。如果你已经在用Claude Code、Codex、OpenCode这类工具但总觉得每次都要反复交代背景、重复粘贴规范或者你是团队里负责把领域经验沉淀成可复用资产的人这篇应该能帮你省下不少试错时间。1. Skills不是又一个插件格式而是Agent的入职培训手册1.1 从新员工入职理解Skills的设计动机我带过不少新人每次都会给他们一份文档什么时候做什么事、做到什么标准、遇到问题找谁、输出格式长什么样。这份文档不是百科全书而是一份可执行的SOP。Agent Skills本质上就是干这个的。官方对Skill的定义很简洁一个包含SKILL.md指令文件、以及可选脚本和资源的文件夹。模型在对话过程中根据用户任务的描述动态判断这个任务我应该加载哪个技能然后读取对应的SKILL.md按照里面写好的步骤、规范、注意事项去执行。关键就在按需加载这四个字。模型不会把所有技能都装进上下文而是在需要的时候才去读取那个技能文件。这一点和我最早理解的把提示词写得更长更细完全不同提示词是一次性塞给模型的而技能是模型自己决定何时去翻阅的操作手册。1.2 为什么模型越强反而越需要Skills有个反直觉的现象模型能力越强越需要精细的技能约束。我一开始也不理解后来想明白了。通用大模型就像是全科医生什么病都能看但真要处理某个专科的复杂病例还是需要专科医生的诊疗手册来规范流程。模型在没有任何技能约束时面对一个任务会按照自己的通用直觉去做结果就是做了但不够专业。举个例子你让Claude直接做前端开发它能写代码但大概率不会遵守你团队的代码风格、不会自动跑测试、不会按照你的目录结构组织项目。如果你给它一个前端开发skill里面写清楚了新项目初始化流程、组件规范、样式约定、提交前检查清单它就能按部就班地完成一整条流水线。这就是Skills存在的意义把会做变成做得好、做得稳。1.3 Skills解决的三类实际问题在我实际使用过程中Skills主要解决了三类问题。第一是跨项目复制领域方法论。我以前每开一个新项目都要重新给Agent交代一遍项目规范费时费力还容易漏。现在把前端开发、后端接口设计等常用方法论各自封装成skill新项目直接装上去就能用团队成员拿到的还是同一套标准。第二是组织经验资产化。团队里最资深的人脑子里往往装着大量隐性知识——这些东西平时写在Wiki里没人看但做成skill之后Agent会严格按照它执行相当于把老师傅的经验固化成了可运行的流程。我见过有人把发明专利写作的完整流程也做成了skill效果非常好因为专利写作的格式要求极其严格模型自由发挥很容易翻车。第三是跨Agent迁移。同一份skill可以装进Claude Code、Codex、OpenCode等不同Agent工具里。这意味着你不需要在每一个工具里重复调教模型一份技能包到处都能用。这个优势在团队里尤其明显一个人维护技能包所有人共享进步。2. 别再傻傻分不清Skill、Prompt、MCP、Knowledge的定位2.1 Prompt是一次性交代任务Skill是可复用的作业规程这是最基础的区分点。Prompt是你和模型对话时临时给的一段指令它是一次性的、无结构的、不可版本管理的。你今天写了一段很详细的prompt让Claude帮你写报告明天想再复用这段prompt只能复制粘贴到新会话里改一处就得全文改。Skill不一样。它是有结构的文件夹包含元数据、指令、脚本和资源可以被版本控制、被共享、被迭代。你用git管理代码的方式去管理skill每一次修改都有记录随时可以回滚。我的习惯是把skill仓库放在团队GitLab里更新走Merge Request就像维护一个开源项目一样。2.2 MCP回答能操作什么Skill回答干得够不够专业很多人把Skill和MCP搞混我自己也困惑过一阵子。现在我的理解很简单MCPModel Context Protocol解决的是Agent能调用什么外部能力的问题它让模型可以操作浏览器、数据库、设计工具等各种外部系统Skill解决的是Agent做这件事的专业流程是什么的问题它是一套方法论和操作规范。两者不是替代关系而是配合关系。MCP像是给Agent接上了手和眼睛Skill则是给Agent一份拿到这些工具之后怎么干活的说明书。我做过一个自动化测试skill里面就用到了浏览器MCP工具但skill里写清楚了测试用例设计规范、断言规则、报告格式——这些是MCP本身不会告诉模型的。没有skill的情况下模型有了浏览器能力也只能乱点一通有了skill它才知道该点哪里、怎么验证、怎么汇报。2.3 Knowledge是喂资料Skill是喂流程Knowledge知识库/RAG和Skills的区别也很微妙。知识库给模型提供的是参考资料——行业报告、产品文档、历史案例这些内容性信息Skill给模型提供的是行为方式——怎么做决策、按什么顺序执行、达到什么标准。我用一个生活例子来区分你去学做饭菜谱相当于Knowledge它告诉你食材和配方而后厨操作规范相当于Skill它告诉你先洗菜再切菜、炒菜时热锅凉油、出锅前试味。前者是信息后者是流程。在Agent场景里RAG负责让模型知道更多Skills负责让模型做得更对。下面这张表是我自己整理的概念对比方便你快速定位概念本质回答的问题典型形态与Skills的关系Prompt一次性对话指令这次任务怎么执行文本Skill被模型按需加载后本质上是结构化的长期PromptTool/MCP外部能力接口Agent能操作什么API、JSON SchemaSkill内部可以调用Tool协调工具完成流程Knowledge/RAG资料库模型知道什么向量库、文档Skill可以引用Knowledge作为参考资料Skill可复用技能包任务如何做到专业文件夹SKILL.md本尊实际上这几个概念可以组合使用。一个成熟的skill内部完全可能引用知识库中的资料同时调用MCP工具去执行操作再用SKILL.md里面的规范来约束整个过程。3. 从零跑通一个Skill安装、落点、首次触发实测3.1 环境准备三个前置条件在安装skill之前先确认三个前置条件。第一本机有较新的Node.js环境因为目前大部分skills工具链都跑在Node生态上。第二安装了对应的Agent工具比如Claude Code并且能在终端里直接执行claude命令。第三最好有一个干净的测试目录避免skill安装到生产项目里污染现有配置。我建议第一次试水时专门建一个~/skill-playground目录里面放一个测试项目然后在这个环境里安装和触发skill。这样即使配置出了问题也不会影响你日常的工作目录。3.2 用npx skills命令安装一个开源Skill社区里目前最常用的安装方式是通过npm上的skills工具。我在实测中跑通的命令长这样npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y拆解一下这条命令npx skills add是核心动作后面的sandai-org/vidmuse-skills是GitHub仓库地址--agent claude-code指定装到Claude Code的skills目录-g表示全局安装-y自动确认所有交互提示。执行完这个命令后工具会去GitHub拉取仓库内容识别里面的SKILL.md文件然后把整个文件夹复制到对应Agent的skills目录。对于Claude Code来说默认落点是~/.claude/skills/。你可以在项目里创建一个.claude/skills/目录把特定技能只装到当前项目内实现项目级隔离。我之前装过一套SuperPower类的超能力技能包社区里很火的那套superpowers集合安装方法和上面一模一样只是把仓库地址换掉。这类集合包的好处是开箱即用里面已经帮你把几十个常用技能分类整理好了。3.3 首次触发怎么确认skill真的生效了装完之后最关心的问题就是它到底啥时候会生效我实测下来Agent是在对话过程中动态判断是否加载某个skill的触发依据是SKILL.md文件里的description字段。模型读到你当前任务的内容和description描述的场景匹配上了它就会主动去读取完整的SKILL.md再执行。第一次测试时我用了一个非常明显的触发句请使用数学建模技能帮我分析这个赛题。然后在对话输出里能看到Claude先读取了math-modeling技能的SKILL.md然后才开始回答问题。如果没效果可以打开Agent的调试日志模式Claude Code里是/debug能看到模型是否加载了技能文件。这里有个容易误判的点如果模型已经在执行其他任务中途插进来一个需要用技能的任务它可能不会立刻切换。所以测试的时候尽量新开一个会话用一句干净明确的触发语别和上下文里的其他任务混在一起。4. 拆解一个SkillSKILL.md、scripts、assets各自的门道4.1 frontmatter是给模型看的自我介绍以我写的一个数学建模skill为例它的目录结构长这样math-modeling-skill/ ├── SKILL.md ├── scripts/ │ ├── check_model.py │ └── format_report.py ├── assets/ │ ├── templates/ │ │ └── paper_template.md │ └── references/ │ └── common_models.md └── requirements.txtSKILL.md是整个技能包的心脏它最开头有一段YAML格式的frontmatter这段信息就是技能的简历。我常用的字段是这些--- name: math-modeling description: 当用户需要完成数学建模任务时使用包括赛题分析、模型选择、求解实现和论文排版。适用于数学建模竞赛、数据分析建模等场景。 allowed-tools: bash, python ---name必须是全局唯一的技能名description是模型判断要不要激活这个技能的依据这段话一定要把触发条件写清楚后面避坑章节我会专门讲怎么写allowed-tools用来限制技能执行时能调用的工具能力比如上面只允许bash和python防止技能乱调浏览器。4.2 正文是操作SOP不是READMESKILL.md的正文部分我见过两类极端。一类写得像产品README大段大段讲背景、动机、架构把模型读到失去重点另一类写成论文从原理到推导全部铺开执行步骤淹没在文本海洋里。正确的写法是把它当成一份给新人的操作SOP少讲背景多讲动作每一步都给出判断条件和输出标准。我在数学建模skill里是这样写的# 数学建模技能 ## 何时使用 - 用户明确要求进行数学建模 - 用户给出赛题数据要求建立模型或输出建模论文 ## 解题流程 1. 问题重述用不超过200字概括问题 2. 模型选择根据数据类型选择回归/优化/微分方程/机器学习模型并说明选择理由 3. 求解实现使用Python的numpy/scipy/sklearn求解保留核心代码 4. 结果验证至少做一次灵敏度分析和误差分析 5. 论文输出按照assets/templates/paper_template.md排版 ## 注意事项 - 所有结论必须给出数值结果不能只写公式不求解 - 每个模型必须说明适用条件 - 如果数据量超过10000条优先考虑采样或分布式计算看到区别没有每一条都是可执行的指令都有明确的产出物。模型拿到这份SOP之后它不需要自己想接下来该干嘛而是精确地按流程走完五步最后产出一篇结构完整的建模论文。4.3 scripts和assets让Skill真正动手光有SKILL.mdskill还只是个高级提示词。真正让skill具备动手能力的是scripts目录。我习惯在这里放两种脚本一种是校验脚本比如检查模型代码有没有跑通、输出格式是否符合要求另一种是自动化脚本比如一键生成报告、自动整理数据。写脚本时有两个注意点。第一脚本必须能被模型直接执行我给Claude Code用的脚本都会加上shebang#!/usr/bin/env python3并设置可执行权限。第二要在SKILL.md中明确告诉模型这些脚本的用途和调用方式比如运行python scripts/check_model.py result.json来验证结果格式否则模型不知道有这些脚本可以用。assets目录则用来放模板和参考资料。我的数学建模skill里论文模板放在assets/templates/下常用模型清单放在assets/references/下。SKILL.md正文里会引用这些文件论文格式严格按照assets/templates/paper_template.md执行。这样SKILL.md本身保持简洁细节信息都放在外部文件中按需读取和写代码把公共逻辑抽到独立模块是同一个思路。依赖管理我用独立的requirements.txtSKILL.md里会指导模型在需要时用pip install -r requirements.txt安装。5. 从零开发自己的第一个Skill从会做到可交付5.1 选题标准什么样的任务值得做成Skill很多人的第一个skill都选错了方向。做skill是有成本的不是所有任务都值得封装。我自己总结了三个标准高频、有确定性流程、跨项目复用。高频意味着你不希望每次重新交代有确定性流程意味着这套打法已经相对成熟不需要模型每次都临场发挥跨项目复用意味着技能包能在不同项目、不同Agent之间通用。反例就是我之前试图把临时的头脑风暴做成skill后来发现这种开放性任务根本没有固定流程模型加载了技能反而束手束脚。如果符合这三个标准哪怕是一个很小的任务——比如把分析结果按固定格式生成周报——也值得做成skill。我宁可做十个小的技能包也不做一个什么都能干但什么都干不精的巨型技能。5.2 SKILL.md编写四步法我在大量实践中总结出一套SKILL.md编写流程四步走。第一步写何时使用。先定义触发条件明确这个技能在什么场景下激活、什么场景下不要激活。第二步写执行步骤。把整个任务拆成3到7个步骤每步只写动作、判断条件和产出物不要展开原理。第三步写注意事项。把容易翻车的点列清楚比如格式要求、常见错误、边界条件。第四步写验收标准。明确告诉模型做到什么程度算完成这是最容易被忽略的一步。我强烈建议第四步不要省。以前我写skill不写验收标准模型执行到一半就觉得自己干完了输出质量参差不齐。后来我在每个skill里都加了本技能完成的标准是……这一节交付质量立刻稳定很多。5.3 配合脚本让Skill拥有手这里用一个最简单的例子说明脚本在skill里的作用。假设我现在要做一个代码审查skillSKILL.md里定义了审查流程和规范但真正干活的是脚本#!/usr/bin/env python3 检查Python代码中的常见隐患输出审查结果。 import ast import sys from pathlib import Path def check_file(path: Path) - list[str]: 返回该文件中的风险条目列表。 tree ast.parse(path.read_text(encodingutf-8)) issues [] for node in ast.walk(tree): if isinstance(node, ast.Try): except_handlers_end node.handlers[-1].lineno if node.handlers else node.lineno if not any(isinstance(h.type, ast.Name) and h.type.id Exception for h in node.handlers): if except_handlers_end node.lineno: pass if isinstance(node, ast.FunctionDef) and len(node.body) 80: issues.append(f{path}:{node.lineno} 函数 {node.name} 超过80行建议拆分) return issues if __name__ __main__: for target in sys.argv[1:]: for issue in check_file(Path(target)): print(issue)然后SKILL.md里会写运行python scripts/check_style.py file检查代码风险将输出的问题逐条反馈给用户。这样一来模型不再只是根据经验看看而是真正执行代码分析工具输出可复现的结果。开发技能包这件事很大程度上就是在给模型配一位工序质检员。5.4 本地测试与迭代清单skill开发出来不测试就直接上生产一定会翻车。我的测试流程固定四步。第一步是触发测试。新开一个会话用预期触发语说出需求看模型是否在调试日志里加载了对应skill。第二步是执行测试。让模型完整执行一遍流程观察它是否按SKILL.md的步骤走、有没有跳过关键节点。第三步是边界测试。故意提出一些和skill描述相关但不应由它处理的需求确认模型不会误触发。第四步是回归测试。修改skill后旧用例仍然能通过。迭代频率在初期会很夸张我第一个skill改了十几版才稳定。每次修改SKILL.md后我都会把版本号加一比如0.1.0改成0.1.1并在metadata里记录变更说明。这个习惯在团队协作时尤其重要不然你会发现不同成员各自维护了一堆改得面目全非的副本。6. 踩坑实录Skills使用和开发中的6个典型问题6.1 description写得太泛导致该出手时不出手第一个坑就是这个。我最早给一个前端开发skill写的description是帮助用户进行前端开发结果模型在任何场景下都会优先加载这个技能甚至用户让它写Python后端代码它也先把这个技能读一遍白白浪费上下文。后来我改成当用户要求创建或修改前端页面、组件、样式且需要遵循团队前端规范时使用触发准确率立刻上来了。description不是产品简介而是给模型的路由条件。一定要写清楚触发场景和排除场景宁可保守一点也不要让模型在无关任务上浪费加载成本。6.2 SKILL.md塞满背景知识模型反而丢失关键指令第二个坑来自想把所有经验都写进去的冲动。我刚开始做数学建模skill的时候把常见模型原理、公式推导、参考资料全塞进了SKILL.md结果文件超过两千行。实测时模型执行到第三步就明显迷失了因为它要处理的信息量太大真正关键的步骤指令反而被背景知识稀释。后来我强制自己遵守一条铁律SKILL.md正文控制在80到150行只放流程步骤、判断条件和注意事项所有背景知识、模板、详细说明一律移到assets目录下的独立文件里在SKILL.md中通过引用指明路径。模型需要时再去读参考文件注意力不会被无关内容占用。6.3 脚本的相对路径在切换目录后失效这是个非常隐蔽的坑。我在skill里写了运行python scripts/check_model.py在skill目录下测试没问题但在项目目录下调用时模型执行的工作目录已经变了脚本根本找不到。后来我在SKILL.md里明确约定所有脚本路径均相对于当前skill所在目录并且在实际执行命令时用完整路径python ~/.claude/skills/math-modeling/scripts/check_model.py result.json更稳妥的做法是在SKILL.md正文中显式写清楚路径规则在执行本技能中的脚本时请使用{skill_dir}占位符代表技能所在目录替换为实际路径后再执行。这个问题在Claude Code中尤其常见因为它默认的工作目录是项目根目录不是skill目录。6.4 不同Agent对同一Skill的兼容性差异开源的世界什么都有同一个skill在不同Agent工具里的表现可能天差地别。我之前把一个依赖bash脚本的skill从Claude Code迁移到Codex结果Codex压根没识别到脚本只读了SKILL.md。后来一查发现不同Agent对allowed-tools字段的解析不一样有的支持、有的忽略对scripts目录的加载策略也不同。解决办法是在开发skill时尽量少依赖特定Agent的特性字段核心逻辑放在SKILL.md正文里脚本只做辅助如果要跨Agent分发最好在README里写明支持列表并在每个Agent环境里实测一遍触发和执行效果。6.5 修改Skill后不生效新会话和缓存问题这是最让人抓狂的坑。我改完SKILL.md之后在同一个会话里继续测试结果模型还在用旧指令执行。一开始我以为没改对后来发现是Agent的缓存机制——它在会话开始时已经生成了技能索引中途修改不会立刻生效。正确做法是修改完skill后新开一个会话测试。如果Agent工具支持刷新技能索引的命令或操作比如Claude Code里重启进程或者执行/reload先刷新再测试。这个坑踩多了之后我养成了一个习惯每次修改技能文件后第一件事就是新开会话绝不贪图方便复用旧会话。6.6 权限与安全allowed-tools别乱开最后一个坑和安全性有关而且容易被忽视。allowed-tools字段里写什么决定了这个skill在执行时能调用哪些能力。如果不加限制全开遇到一个写得不严谨的skill模型可能在你的服务器上执行任意代码。这看起来方便实际上非常危险。我自己的安全基线是skill默认只开必要的工具比如普通分析任务只开read和python绝不轻易开bash的写操作涉及网络请求的skill单独限制和执行域从网上下载的第三方skill先检查SKILL.md和scripts目录里有没有可疑内容再在隔离的测试目录里跑一遍确认没问题了才装到正式环境。安全领域相关的skill使用时要特别注意授权边界任何安全测试都应该在明确授权的前提下进行。踩完这些坑之后我对Skill的定位越来越清晰它不是提示词的替代品而是把提示词、脚本、模板、依赖、经验教训打包成一个可执行、可版本化、可共享的资产单元。如果你正打算开始用Agent Skills我的建议是别从头研究理论直接挑一个你每周都要重复做三次以上的任务花一个下午把它做成一版粗糙的skill然后在上线使用中不断迭代完善——没有比真实任务更好的老师。最后分享一个只有自己做了skill才容易发现的小技巧给你的SKILL.md写验收标准时可以用一段固定的开头词比如当以下条件全部满足时本任务才算完成……然后逐条列出。这个格式看起来朴素但实际执行中效果出奇地好模型有没有偷工减料一目了然。顺着这个思路你的技能积累会越来越厚团队里每个Agent都会因为这些小而实的技能包干活越来越像那个最靠谱的老师傅。
