1. 从skills这个模糊词说起它到底指什么第一次看到skills这个标题很多人会一头雾水。它既不是某个具体软件的名字也不是一个能一眼看懂的技术名词。但如果你最近在折腾 Claude Code、Codex 这类 AI 编程助手或者关注过 Agent 相关的开发圈子就会发现skills已经成了一个高频词。它指的是Agent Skills——一种给 AI 智能体挂载技能包的机制让模型在特定任务上表现得更专业、更稳定。说白了skills 就是一套约定好的文件结构和描述规范把某类任务该怎么做沉淀成可复用的模块。你写一个SKILL.md里面说清楚这个技能是干什么的、什么时候触发、需要哪些工具、执行步骤是什么AI 在遇到匹配场景时就会自动加载并遵循。这跟传统写 prompt 最大的区别在于prompt 是一次性的、散落的而 skill 是结构化的、可版本管理的、能跨会话复用的。我最初接触这个概念时也犯嘀咕——不就是把提示词存成文件吗有什么新鲜的真正用起来才发现差别大了。散装 prompt 你每次都得重新描述背景、约束、输出格式稍微复杂点的任务模型跑着跑着就忘了前面的要求。而 skill 通过固定的元数据字段比如名称、描述、触发条件和正文规范把上下文约束固化下来模型加载后行为一致性明显提升。尤其是多步骤任务比如帮我做一次数学建模的完整流程或者按团队规范生成前端组件有 skill 和没 skill 完全是两个体验。这篇文章适合几类人看一是刚接触 Claude Code、想搞清楚 skills 到底怎么用的新手二是已经在用 AI 编程助手、但觉得每次都要重复交代背景、效率上不去的开发者三是想自己写 skill、把团队经验沉淀下来的进阶用户。我会从概念、目录结构、编写方法、安装配置、实战案例到常见坑一条线讲透尽量让你看完就能动手。需要先说明一点skills 这套机制目前主要围绕 Claude 生态Claude Code、Claude Desktop 等以及部分兼容的 Agent 框架展开不同工具对 skill 的支持程度和加载方式有差异。下面讲的内容以通用规范为主具体到某个工具时会单独标注。2. Agent Skills 的运行机制模型是怎么学会一个技能的2.1 skill 的加载不是训练而是按需注入上下文很多人第一次听说 skills会误以为是把技能训练进模型里。不是的。模型本身没变变的是它每次执行任务时看到的上下文。skill 的本质是一段被结构化组织的指令文本当系统判断当前任务和某个 skill 的描述匹配时就把这个 skill 的内容注入到模型的上下文里模型再基于这些指令去行动。这个机制有个关键点匹配靠的是 skill 的元数据描述而不是全文。也就是说系统先看每个 skill 的 name 和 description判断这个任务要不要用这个技能决定加载之后才读正文。所以 description 写得好不好直接决定 skill 会不会被正确触发。我见过太多人正文写得洋洋洒洒description 就一句处理文档结果模型根本不知道什么时候该用它。2.2 渐进式披露为什么 skill 能做到又轻又专Agent Skills 有个设计叫渐进式披露progressive disclosure。意思是信息分层次暴露第一层是元数据名称、描述常驻在系统提示里占用极少 token第二层是 SKILL.md 正文只在触发时加载第三层是技能目录下的附加文件脚本、模板、参考文档只在正文明确引用时才读取。这个设计解决了一个核心矛盾你希望 AI 知道很多东西但上下文窗口是有限的。如果把所有技能全文都塞进系统提示token 直接爆炸而且模型注意力会被稀释。渐进式披露让知道有这个技能和真正读取技能细节分开既保证了可发现性又控制了成本。理解这一点你写 skill 时就会自觉地把最重要的触发信息放前面把大段参考资料放附加文件里。2.3 skill 和 prompt、tool、MCP 的边界在哪这几个概念经常被混在一起我用自己的理解捋一遍概念作用触发方式典型场景Prompt单次指令用户手动输入临时问答、一次性任务Skill可复用任务规范按描述自动匹配固定流程、团队规范Tool可调用的能力模型主动调用读写文件、执行命令MCP外部服务接入协议配置后常驻连接数据库、第三方 API简单说tool 是手让模型能操作外部世界MCP 是接口标准让模型能连上外部服务skill 是操作手册告诉模型在什么场景下、按什么步骤、用哪些工具去完成任务。三者是配合关系不是替代关系。一个成熟的 skill 往往会声明它需要哪些 tool甚至引用 MCP 提供的服务。2.4 为什么这个机制对复杂任务特别有价值拿数学建模举例。一个完整的建模任务包含审题、选模型、写代码、跑结果、写论文好几个阶段每个阶段的要求都不一样。如果全靠临时 prompt你每次都得重新交代用 Python 还是 MATLAB论文格式什么要求结果要保留几位小数。而把这些沉淀成一个 skill模型一加载就知道整套流程和约束输出质量稳定得多。再比如前端开发团队有自己的组件规范、目录结构、命名约定。把这些写进 skill新人用 AI 生成代码时就不会跑偏。这也是为什么 skills 在团队协作场景里特别受欢迎——它把老员工脑子里的隐性知识变成了AI 能读到的显性规范。3. 一个 skill 的目录长什么样从 SKILL.md 到附加资源3.1 最小可用结构一个文件就能跑最简单的 skill 就是一个目录里面放一个SKILL.md。目录名通常就是技能名比如math-modeling/、frontend-component/。SKILL.md 用 YAML frontmatter 开头声明元数据下面是 Markdown 正文。--- name: math-modeling description: 用于数学建模竞赛的完整流程指导包括审题、模型选择、代码实现和论文撰写。当用户提到数学建模、建模比赛、竞赛论文时使用。 --- # 数学建模技能 ## 使用场景 当用户需要进行数学建模任务时... ## 执行步骤 1. 先审题提取关键约束... 2. 根据问题类型选择模型...这个结构看起来简单但每个部分都有讲究。name 要短、唯一、能一眼看懂description 要包含做什么和什么时候用两个信息正文则要按任务的实际执行顺序组织。3.2 进阶结构用附加文件拆分复杂技能当技能内容变多全塞进 SKILL.md 会让正文臃肿加载时 token 消耗大。这时候就该拆分math-modeling/ ├── SKILL.md # 主入口精简的流程说明 ├── references/ │ ├── models.md # 常用模型参考 │ └── paper-format.md # 论文格式要求 ├── scripts/ │ └── data_clean.py # 数据清洗脚本 └── assets/ └── template.tex # 论文模板SKILL.md 里用相对路径引用这些文件比如详细模型列表见 references/models.md。模型只有在需要时才会去读这些文件这就是前面说的渐进式披露。我个人的经验是SKILL.md 正文控制在 500 行以内超出的内容一律外置。这样加载快模型也更容易抓住重点。3.3 frontmatter 字段怎么写才不踩坑frontmatter 里最关键的字段是 name 和 description有些实现还支持 allowed-tools、version 等。这里重点说 description因为它决定触发准确率。写 description 有个实用公式能力描述 触发场景 边界说明。举个例子差的写法description: 处理数据好的写法description: 对结构化数据CSV、Excel进行清洗、转换和统计分析。当用户需要处理表格数据、做数据预处理或生成统计报告时使用。不适用于非结构化文本处理。好的写法里结构化数据限定了能力范围当用户需要...给出了触发信号不适用于...划清了边界避免误触发。我踩过的坑就是 description 写太泛结果模型在完全不相关的任务上也加载了这个 skill反而干扰了正常输出。3.4 正文组织的三条实用原则第一按执行顺序写不要按知识分类写。模型是照着步骤干活的你把步骤一、步骤二写清楚比按概念、原理、方法分类有用得多。第二关键约束前置。最重要的规则放最前面因为模型对上下文开头和结尾的注意力最强中间容易被忽略。第三用具体例子代替抽象描述。与其说输出要规范不如给一个规范输出的样例。模型模仿样例的能力远强于理解抽象要求。4. 手把手写第一个 skill从需求到可运行4.1 先想清楚这个技能解决什么重复问题写 skill 之前先问自己我是不是经常重复交代同一套要求如果某个任务你做过三次以上、每次都要重新描述背景和步骤那它就值得沉淀成 skill。反过来一次性的、高度依赖具体情境的任务写 skill 反而累赘。我建议新手从流程固定、步骤明确的任务入手。比如按规范生成 React 组件把会议记录整理成结构化纪要对代码做安全审查。这类任务边界清晰容易写出可复用的规范。4.2 起草 SKILL.md一个完整示例假设我要写一个代码审查技能目标是让 AI 按团队规范审查代码。草稿如下--- name: code-review description: 按团队规范审查代码检查命名、错误处理、性能和安全问题。当用户提交代码请求审查、或要求 review 某段代码时使用。 --- # 代码审查技能 ## 审查顺序 按以下优先级逐项检查不要跳步 1. **正确性**逻辑是否有误边界条件是否处理 2. **错误处理**异常是否捕获失败路径是否明确 3. **命名规范**变量、函数、类名是否符合团队约定 4. **性能**是否有明显的低效操作循环内查询、重复计算 5. **安全**是否有注入风险、敏感信息硬编码 ## 输出格式 每条问题按以下格式输出 - 位置文件名 行号 - 级别阻断 / 建议 / 提示 - 问题一句话描述 - 建议具体修改方案 ## 团队命名约定 - 变量小驼峰如 userName - 常量全大写下划线如 MAX_RETRY - 组件大驼峰如 UserProfile - 布尔值is/has/can 开头如 isValid ## 注意事项 - 不要只指出问题必须给出可执行的修改建议 - 阻断级问题必须说明为什么阻断 - 如果代码整体没问题明确说未发现阻断级问题这个 skill 有几个特点审查顺序明确、输出格式固定、命名约定具体、还专门写了注意事项防止模型只挑刺不给方案。这些都是从实际使用中总结出来的——早期版本我没写输出格式结果模型每次输出的结构都不一样很难对比。4.3 测试与迭代怎么知道 skill 写得好不好写完不是结束得测。测试方法很直接构造几个典型任务看模型加载 skill 后的表现。重点观察三件事触发准不准该用的时候用了吗不该用的时候有没有误触发执行全不全步骤有没有漏约束有没有遵守输出稳不稳多次运行结果结构是否一致我一般会准备一组正例和反例。正例是应该触发 skill 的任务反例是不该触发的。如果反例也触发了说明 description 太宽泛得收紧。如果正例没触发说明 description 缺少关键触发词。迭代时优先改 description因为它是触发开关。正文的问题通常表现为执行不全这时候检查是不是步骤写得太抽象或者关键约束被埋在了中间。4.4 版本管理skill 也要进 Gitskill 是文本文件天然适合版本管理。我习惯把 skill 目录放进 Git 仓库每次修改都提交commit message 写清楚改了什么、为什么改。这样做有两个好处一是能回溯哪次改动导致触发变差二是团队多人维护时能 review。如果团队用 Claude Code可以把 skill 放在项目的.claude/skills/目录下跟着代码一起提交。这样每个人的 AI 助手加载的都是同一套规范输出一致性有保障。5. 安装与配置让 skill 真正被加载起来5.1 不同工具的 skill 存放位置skill 放哪里取决于你用的是什么工具。常见的位置有这么几类工具/场景典型存放路径说明Claude Code 项目级项目根目录.claude/skills/跟随项目团队共享Claude Code 用户级用户主目录下配置目录个人全局可用Claude Desktop应用配置目录下的 skills桌面端加载兼容框架框架约定的 skills 目录看具体框架文档路径这东西各版本可能有调整最稳妥的做法是查你所用工具的官方文档或者看工具启动时打印的配置目录。我见过有人把 skill 放错目录折腾半天以为 skill 没生效其实是根本没被扫描到。5.2 从 GitHub 手动安装 skill 的完整流程热词里claude code怎么手动装github上的skills出现频率很高说明这是很多人的痛点。手动安装的通用流程是这样的找到 skill 仓库在 GitHub 上搜索相关 skill确认仓库里有 SKILL.md 或符合规范的目录结构。克隆或下载用git clone把仓库拉到本地或者直接下载压缩包解压。确认目录结构打开看是不是标准的 skill 结构有没有 SKILL.mdfrontmatter 是否完整。放到正确位置把 skill 目录整体复制到你的 skills 目录下。注意是整个目录不是只复制 SKILL.md。重启或重载多数工具需要重启会话或执行重载命令才能识别新 skill。验证加载用一个应该触发该 skill 的任务测试看行为是否符合预期。# 示例克隆一个 skill 仓库到项目 skills 目录 git clone https://github.com/example/some-skill.git cp -r some-skill /path/to/project/.claude/skills/这里有个容易忽略的点有些 skill 依赖附加文件或脚本只复制 SKILL.md 会导致引用失效。所以一定要整个目录搬过去。另外如果 skill 里有可执行脚本注意检查权限和依赖别直接跑来源不明的脚本。5.3 验证 skill 是否生效的三种方法装完不确定生效没有可以用这几招验证看日志很多工具在加载 skill 时会打印日志能看到扫描到了哪些 skill。触发测试构造一个明确匹配 description 的任务观察模型是否按 skill 的步骤走。反向测试构造一个不该触发的任务看模型有没有误加载。如果三种方法都指向没生效排查顺序是目录位置对不对 → 目录结构对不对 → frontmatter 格式对不对 → 工具版本支不支持。我遇到最多的问题是 frontmatter 的 YAML 格式错误比如冒号后面没空格、缩进用了 tab这些都会导致解析失败。5.4 环境准备里那些容易卡住的细节热词里还出现了claudes workspace requires the virtual machine platform on windows这类报错说明环境配置是新手的一道坎。这类问题的通用排查思路是确认系统版本和依赖某些工具对操作系统版本、运行时有要求先对照官方要求检查。确认权限安装和运行可能需要管理员权限尤其是涉及系统级配置时。确认网络可达部分工具需要访问外部服务网络不通会表现为各种奇怪的错误。看完整报错不要只看最后一行往上翻找根因很多报错是连锁反应。我个人的习惯是遇到环境问题先别急着搜解决方案先把完整报错读一遍往往答案就在里面。盲目照搬网上的命令有时候会把简单问题搞复杂。6. 实战场景skills 在不同领域的落地方式6.1 数学建模把竞赛流程标准化数学建模是 skills 的典型应用场景因为它的流程高度固定审题、假设、建模、求解、验证、写作。把这套流程写成 skill模型在接到建模任务时就会按部就班走不会一上来就闷头写代码。一个实用的建模 skill 应该包含常见模型的选择依据优化问题用规划模型、预测问题用时间序列或回归、代码模板数据读取、求解、可视化、论文结构要求摘要、问题重述、模型建立、求解、灵敏度分析。我见过有人把历年优秀论文的结构提炼进 skill效果很好——模型写出来的论文框架明显更规范。6.2 前端开发统一组件生成规范前端团队用 skill 统一组件生成收益很直接。把技术栈React/Vue、样式方案CSS Modules/Tailwind、目录结构、命名约定、测试要求写进 skillAI 生成的组件就能直接进项目不用大改。关键是把团队约定写具体。比如组件文件放 components 目录下每个组件一个文件夹包含 index.tsx、styles.module.css、index.test.tsx。这种具体到文件名的约定模型执行起来最不容易出错。6.3 AI 内容创作漫剧、文案的流程化生产热词里提到ai漫剧常用skills说明内容创作领域也在用这套机制。漫剧生产涉及剧本、分镜、角色设定、台词环节多且需要风格统一。把这些环节的规范写成 skill能保证多集内容风格一致。内容类 skill 的写法和代码类不太一样重点在风格约束和结构模板。比如规定每集开头用悬念钩子中间两次反转结尾留悬念或者给出角色台词的语气示例。模型对示例的模仿能力很强给几个好例子比写一堆形容词管用。6.4 嵌入式与硬件STM32 这类场景怎么用热词里出现claude code stm32说明嵌入式开发也在尝试。这类场景的特点是涉及具体硬件、寄存器、外设配置skill 里应该包含芯片手册的关键信息、常用外设初始化模板、调试注意事项。嵌入式 skill 有个特殊点要强调验证步骤。硬件开发不像纯软件编译通过不代表能跑skill 里应该要求模型生成代码后说明如何验证比如用示波器看哪个引脚、预期波形是什么。这能避免代码看着对、实际跑不通的情况。7. 踩坑实录skill 不生效、误触发、输出跑偏怎么排查7.1 skill 完全不生效从目录到格式逐层排查skill 不生效是最常见的问题排查要按顺序来别跳步目录位置确认 skill 放在工具会扫描的目录下。不同工具路径不同查文档确认。目录结构确认是目录 SKILL.md的结构不是单个散文件。frontmatter 格式YAML 对格式敏感冒号后要有空格缩进用空格不用 tab字符串含特殊字符要加引号。工具版本确认你的工具版本支持 skills 功能老版本可能不支持。重载改完配置要重启会话或重载很多不生效其实是没重载。我踩过最坑的一次是 frontmatter 里 description 写了个冒号但没加引号YAML 解析直接失败整个 skill 被跳过但工具不报错排查了半天。7.2 误触发description 写太宽的典型症状误触发的表现是明明在做 A 任务模型却加载了 B 技能的规范输出变得不伦不类。根因几乎都是 description 太宽泛。比如一个 skill 的 description 写处理文本那几乎所有涉及文字的任务都可能触发它。修正方法是加限定词和边界说明处理结构化文本数据JSON、CSV的格式转换不适用于自然语言写作。判断 description 是否够窄有个简单测试把它读给一个不了解你项目的人听他能不能准确说出什么时候该用、什么时候不该用。说不出来就还得改。7.3 输出跑偏正文约束没写清还是模型没遵守有时候 skill 触发了但输出还是不符合预期。要区分两种情况是 skill 里没写清楚还是写了但模型没遵守。如果是没写清楚补具体约束和示例。如果是写了没遵守通常是约束位置太靠后、或者表述太抽象。解决办法是把关键约束前置并用必须禁止这类强指令词配合正反示例。还有一种情况是 skill 之间冲突。两个 skill 都触发了规范互相矛盾模型就懵了。这时候要检查 description 的边界是否重叠必要时合并或明确优先级。7.4 加载慢、token 消耗大该瘦身了如果发现加了 skill 之后响应变慢、成本上升多半是 skill 太臃肿。检查两点SKILL.md 正文是不是太长附加文件是不是被频繁加载。优化方向就是前面说的渐进式披露正文只留流程和关键约束大段参考资料外置只在需要时引用。我一般会把超过 100 行的参考内容都拆出去正文保持精简。8. 把 skill 用出复利维护、分享与团队协作8.1 定期清理删掉不再用的 skillskill 不是越多越好。装了一堆用不上的 skill不仅占用扫描和匹配成本还可能增加误触发概率。我建议每隔一段时间清理一次把长期没触发、或者已经被更好方案替代的 skill 删掉。清理的判断标准很简单过去一个月它被触发过吗触发后输出质量比不用时好吗两个都是否就可以删了。热词里tibo关于清理skills的方法推荐也说明清理是个普遍需求。8.2 团队共享让 skill 成为团队资产skill 最大的价值在团队场景。把团队规范写成 skill跟着项目仓库走新人入职拉下代码就自带一套 AI 助手规范省去大量口头交代。团队维护 skill 要注意两点一是变更要走 review因为 skill 影响所有人的 AI 输出二是保持文档同步skill 里的规范和团队文档不能打架否则模型和人都无所适从。8.3 从消费到生产自己写 skill 的收益用别人的 skill 是消费自己写是生产。生产的收益在于你把自己对某类任务的理解固化下来形成可复用的资产。写得越多你对怎么把隐性经验变成显性规范这件事就越有感觉这本身就是一种能力提升。我的建议是从小处着手先写一个自己天天用的小技能跑顺了再扩展。别一上来就想写个大而全的框架那种通常写不完也用不起来。8.4 我个人的几条经验最后分享几条实打实的体会。第一description 值得反复打磨它决定了 skill 能不能被用上我经常为一个 description 改五六版。第二正文要短短到模型一眼能看完长文反而抓不住重点。第三示例比描述重要给一个具体样例胜过三段抽象说明。第四skill 要跟着实践迭代用一次改一次别指望一次写完美。第五别迷信数量三个打磨好的 skill 比三十个半成品有用得多。这套机制还在快速演进不同工具的兼容性和加载方式也在变。保持关注官方文档同时多动手试比看一堆教程管用。真正跑通一个自己的 skill你对 Agent 工作方式的理解会上一个台阶。