1. 从skills这个模糊词说起它到底指什么第一次看到skills这个标题很多人会懵——这词太泛了技能技巧还是某个具体产品但如果你最近在折腾 Claude Code、Codex 这类 AI 编程助手大概率已经撞见过它一个叫SKILL.md的文件扔进某个目录AI 就突然会了一件事。这就是当前 AI Agent 圈子里最热的一个概念——Agent Skills。我把它理解成给 AI 装的技能插件。传统做法是你每次对话都要把背景、规范、步骤重新讲一遍AI 每次都是从零开始理解。而 Skills 的思路是把一套可复用的能力比如如何按团队规范写 React 组件如何做数学建模的论文排版如何生成漫剧分镜脚本固化成一个带元数据的 Markdown 文件AI 在需要时自动加载。它解决的核心问题是上下文复用和能力标准化——你不用再当人肉提示词复读机。这篇内容适合三类人一是刚接触 Claude Code、还在纠结怎么让它听话的新手二是想把团队内部规范沉淀成 AI 可调用资产的工程师三是做数学建模、AI 漫剧、前端开发这类垂直场景想找现成 Skills 直接抄作业的人。我会从 Skills 的本质讲起一路讲到怎么写、怎么装、怎么避坑尽量把网上那些零散的热词串成一条能落地的线。先说结论Skills 不是什么黑魔法它的本质是结构化提示词 按需加载机制。理解了这一点后面所有操作都是顺理成章的。2. Agent Skills 的底层逻辑为什么一个 Markdown 文件就能让 AI 变聪明2.1 从每次重讲到一次写好处处调用要理解 Skills 的价值得先理解当前 AI 编程助手的一个根本痛点上下文窗口是稀缺资源。你不可能把公司所有的编码规范、所有的业务背景、所有的历史决策都塞进每一次对话。塞进去的后果是 token 爆炸、响应变慢、AI 抓不住重点。传统解法是写一个巨大的CLAUDE.md或者系统提示词把所有规则堆在一起。问题是这些规则大部分时候用不上却每次都占用上下文。就像你出门带了一个装满所有工具的行李箱其实今天只需要一把螺丝刀。Skills 的解法是分层 按需。每个 Skill 是一个独立目录里面有个SKILL.md文件头部用 YAML frontmatter 写清楚这个技能的名称、描述、触发条件。AI 启动时只读取这些元数据很轻量当它判断当前任务匹配某个 Skill 的描述时才把完整的技能内容加载进来。这就是所谓的渐进式披露progressive disclosure。打个比方CLAUDE.md像是贴在墙上的员工手册天天看Skills 像是工具间里的一排工具箱标签朝外需要哪个拿哪个。2.2 SKILL.md 的解剖frontmatter 才是灵魂很多人第一次写 Skill把重点全放在正文的步骤描述上结果发现 AI 根本不触发。问题几乎都出在 frontmatter。一个典型的SKILL.md长这样--- name: react-component-generator description: 当用户需要创建符合团队规范的 React 函数组件时使用。包括 TypeScript 类型定义、样式方案、测试文件生成。触发词新建组件、写个组件、React 组件。 --- # React 组件生成规范 ## 步骤 1. 使用函数组件 Hooks禁止 class 组件 2. Props 必须用 interface 定义命名以 Props 结尾 3. 样式统一用 CSS Modules文件名 xxx.module.css ...关键在description。它不是给你看的是给 AI 做语义匹配用的。写得越具体、越贴近用户真实会说的话触发越准。我见过太多人写description: 帮助处理前端任务这种描述等于没写AI 根本不知道什么时候该用它。一个实操心得在 description 里显式列出触发词。比如触发词新建组件、写个组件这招对提升命中率非常有效因为 AI 在做匹配时对这些关键词敏感。2.3 Skills 和 MCP、子 Agent 的区别在哪热词里经常混着 MCP、Subagent、Skills 这几个概念新手容易搞混。我用一张表说清楚机制本质解决什么典型场景MCP外部工具/数据源协议让 AI 能调用外部能力连数据库、查 API、读 FigmaSubagent独立上下文的子任务代理隔离复杂任务避免污染主上下文大规模代码搜索、独立调研Skills结构化知识与流程封装复用领域知识和操作规范编码规范、建模流程、写作模板简单说MCP 是手让 AI 能操作外部世界Subagent 是分身帮 AI 分担任务Skills 是脑子里的经验告诉 AI 该怎么做。三者不冲突经常配合使用。比如一个数学建模 Skill 里可以指导 AI 去调用某个 MCP 工具拉数据再派一个 Subagent 去做敏感性分析。理解了这层关系你就不会再有学了 Skills 是不是就不用学 MCP这种困惑了。3. 手写第一个 Skill从目录结构到触发验证的完整链路3.1 目录放哪里项目级 vs 用户级Skills 的存放位置决定了它的作用范围这是新手最容易踩的第一个坑。常见有两种项目级放在项目根目录的.claude/skills/下。只对当前项目生效适合团队规范、项目特有的流程。提交到 Git 后团队所有人共享。用户级放在用户主目录的~/.claude/skills/下。对你所有项目生效适合个人通用习惯比如我写 Python 一律用 ruff 格式化。我的建议是通用习惯放用户级项目规范放项目级。别把所有东西都堆在用户级否则换个项目 AI 还在套用上个项目的规范反而添乱。目录结构上每个 Skill 一个文件夹文件夹名建议用英文短横线命名如react-component里面放SKILL.md。如果技能需要附带脚本、模板文件也一并放在这个文件夹里AI 加载时能一起读到。3.2 写 description 的三个反直觉技巧前面说了 description 是灵魂这里展开讲三个我踩坑总结出来的技巧。第一用用户会说的话而不是专业术语。用户不会说请执行组件脚手架生成流程他会说帮我写个组件。description 里要包含后者。第二描述里写清楚什么时候不用。有些 Skill 边界模糊容易误触发。比如一个代码审查Skill如果你不写清楚仅用于审查 PR diff不用于从零写代码AI 可能在你想新建文件时也触发它。第三长度控制在 2-4 句话。太短匹配不准太长又违背了轻量元数据的初衷。我一般写成一句话说能力 一句话说触发场景 一行触发词。3.3 正文怎么写才不啰嗦给流程别给百科正文部分最容易犯的错是写成知识科普。记住AI 不需要你教它什么是 React它需要的是你团队的特定约定。所以正文应该聚焦在具体的步骤顺序1、2、3硬性约束必须/禁止边界情况怎么处理一两个正例和反例我写 Skill 正文有个习惯先写禁止清单。因为 AI 的默认行为往往是通用最佳实践而团队规范经常是反直觉的。比如禁止使用any禁止在组件里直接发请求这些禁止项比正面指导更能纠正 AI 的默认倾向。另外正文里可以引用同目录下的其他文件比如参考 templates/component.tsx 模板。AI 加载 Skill 时会把整个目录纳入可读范围这样你就能把大段模板代码外置保持SKILL.md清爽。3.4 验证触发怎么知道 Skill 生效了写完不是结束得验证。我的验证流程是三步重启会话Skills 通常在会话启动时扫描改完文件要新开一个会话。用自然语言触发别说使用 react-component skill而是说帮我写个用户卡片组件看 AI 是否自动加载。看加载日志Claude Code 这类工具在加载 Skill 时会有提示比如显示正在使用 xxx skill确认它真的被调用了。如果没触发九成是 description 的问题。这时候别急着改正文先把 description 改得更贴近口语再试。我调一个 Skill 的触发平均要改 2-3 次 description这很正常。4. 装别人写好的 Skills手动安装与常见报错处理4.1 从 GitHub 拿 Skills 的正确姿势热词里claude code 怎么手动装 github 上的 skills出现频率极高说明这是刚需。流程其实不复杂在 GitHub 上找到目标 Skill 仓库很多是awesome-claude-skills这类聚合库确认仓库结构通常每个 Skill 是一个子目录里面有SKILL.md把需要的 Skill 目录整个复制到你的.claude/skills/或~/.claude/skills/下重启会话注意要复制整个目录不是只复制 SKILL.md。因为 Skill 经常依赖同目录的模板、脚本、参考文件只拿一个文件会缺胳膊少腿。如果你用 Git 管理项目更优雅的做法是把 Skill 作为 submodule 或者直接 vendor 进仓库这样团队更新时能同步。4.2 那些让人抓狂的报错逐条拆解新手装 Claude Code 和 Skills 时报错五花八门。我挑几个高频的说说。claude : 无法将claude项识别为 cmdlet、函数、脚本文件或可运行程序的名称——这是 Windows PowerShell 的经典报错意思是系统 PATH 里找不到 claude 命令。解决办法是确认安装路径被加进了环境变量或者用完整路径调用。装完之后一定要重开终端很多人忘了这步。claudes workspace requires the virtual machine platform on windows. enable——这个提示是让你在 Windows 功能里启用虚拟机平台。路径是控制面板 → 程序和功能 → 启用或关闭 Windows 功能勾选对应项后重启。这是底层依赖绕不过去。note: claude code might not be available in your country——这类地域提示我的建议是关注官方文档的可用性说明按官方指引操作不要轻信网上各种来路不明的解决方案。**claude code 接入 deepseek**这类需求本质是配置模型端点。这属于进阶玩法核心是找到配置文件里的模型设置项按官方支持的格式填写。我建议先把默认配置跑通再折腾替换否则出问题很难定位是环境问题还是配置问题。4.3 装完不生效先查这四件事装完 Skill 发现 AI 没反应按这个顺序排查目录层级对不对是不是多套了一层文件夹.claude/skills/my-skill/SKILL.md才对.claude/skills/my-skill/my-skill/SKILL.md就错了。frontmatter 格式对不对YAML 对缩进敏感---必须独占一行冒号后面要有空格。文件名大小写必须是SKILL.md全大写。有些系统不区分大小写但工具可能区分。会话有没有重启改完不重启等于没改。这四步能解决 90% 的装了没反应问题。剩下 10% 通常是 description 匹配问题回到上一节的方法调。5. 垂直场景实战数学建模、AI 漫剧、前端开发怎么用 Skills5.1 数学建模把套路沉淀成可复用技能数学建模比赛比如华为杯时间紧、任务重最耗时的往往不是建模本身而是论文排版、图表规范、代码组织这些重复劳动。这正是 Skills 的用武之地。我见过好用的建模 Skills 通常包含这几块论文结构模板摘要怎么写、假设怎么列、符号说明表怎么排图表规范统一配色、字号、图注格式避免每张图风格不一代码组织数据预处理、模型求解、结果导出分文件命名规范统一常见模型代码片段线性规划、灰色预测、层次分析法等直接调用关键在于这些内容平时散落在各个队员脑子里比赛时靠临时沟通效率极低。写成 Skill 后AI 在生成论文段落或代码时自动套用规范省下大量返工时间。我的经验是赛前把 Skill 写好并测试触发赛中直接调用比临时抱佛脚强太多。5.2 AI 漫剧分镜、台词、画风的标准化AI 漫剧是这两年的新热点痛点在于一致性——同一个角色在不同分镜里画风要统一台词风格要统一节奏要统一。Skills 在这里能做的事很具体角色设定卡把角色的外貌、性格、说话习惯写成 Skill每次生成台词时自动加载分镜模板规定每个分镜必须包含画面描述 台词 镜头运动 时长画风提示词库把验证过的画风提示词固化避免每次重新试我实操下来的体会是漫剧类 Skill 的 description 要写得特别场景化比如当需要为第 N 集生成分镜脚本时使用因为漫剧工作流是分阶段的触发时机很关键。5.3 前端开发把团队规范变成 AI 的肌肉记忆前端是 Skills 应用最成熟的领域之一。原因很简单前端规范多、变化快、新人上手成本高。一个成熟的前端 Skills 集合通常覆盖Skill 名称解决什么触发场景组件生成统一组件结构新建组件时样式规范统一 CSS 方案写样式时请求封装统一 API 调用发请求时测试生成统一测试写法写测试时提交规范统一 commit message提交代码时这里有个反直觉的点不要试图用一个巨大的 Skill 覆盖所有前端规范。我早期犯过这个错写了个 2000 行的前端总规范结果 AI 加载后反而抓不住重点触发也不准。后来拆成 5-6 个小 Skill每个聚焦一件事效果好得多。Skill 的粒度应该和一个具体的开发动作对齐。6. 让 Skills 真正好用的几个经验之谈6.1 版本管理Skill 也要进 GitSkill 是团队资产必须版本化。我的做法是项目级 Skills 直接进项目仓库用户级 Skills 单独建一个私有仓库管理。每次修改写清楚 commit message比如调整组件 Skill 的触发词修复误触发问题。为什么要这么较真因为 Skill 的改动会直接影响 AI 行为一旦改坏整个团队的 AI 辅助都会退化。有版本记录出问题能快速回滚。6.2 定期清理别让 Skill 库变成垃圾场热词里有个tibo 关于清理 skills 的方法推荐说明清理是个真需求。Skill 装多了会有两个问题一是启动扫描变慢二是触发冲突两个 Skill 描述太像AI 不知道用哪个。我的清理原则三个月没用过的删。别舍不得需要时再装回来。功能重叠的合并。两个都在讲代码风格就合成一个。触发不准又调不好的删。一个经常误触发的 Skill 比没有更糟。建议每季度过一遍 Skill 库像整理衣柜一样。清爽的 Skill 库AI 的表现会明显更稳。6.3 从抄到改再到写的学习路径新手学 Skills我推荐三步走抄先装几个社区热门 Skillsuperpower skills、typesafe ai skills 这类用起来感受它怎么工作。改把抄来的 Skill 按自己需求改改 description、改步骤观察 AI 行为变化。这一步最能建立直觉。写从零写自己的 Skill从最简单的开始比如我的 commit message 规范。别一上来就写复杂的。我第一个 Skill 只有 20 行就是规定 commit message 格式。跑通之后再逐步加复杂度。这个路径比看十篇教程都管用。6.4 一个容易被忽略的细节Skill 之间的协作高级玩法是让 Skills 互相引用。比如一个功能开发Skill 里可以写组件部分参考 react-component skill测试部分参考 test-generator skill。这样 AI 加载主 Skill 后会按需再去加载子 Skill形成能力网络。但要注意别搞成循环引用A 引用 B、B 又引用 AAI 会绕晕。我的经验是保持单向依赖主流程 Skill 引用细节 Skill细节 Skill 不再往回引用。7. 关于 Skills 的几个常见误解最后澄清几个我经常被问到的误解避免大家走弯路。误解一Skills 越多越好。错。Skills 是上下文资源装太多会稀释 AI 的注意力。精品 5-10 个胜过杂七杂八 50 个。误解二写了 Skill 就一劳永逸。错。模型在更新团队规范在变Skill 需要持续维护。把它当成活文档而不是一次性配置。误解三Skills 能替代提示词工程。不完全是。Skills 解决的是可复用知识的封装但具体任务的即时沟通仍然需要好的提示词。两者是互补不是替代。误解四只有编程能用。错。写作、设计、数据分析、甚至日常办公流程只要能抽象出重复的步骤和规范都能写成 Skill。我见过有人把周报模板写成 Skill效果出奇地好。我在实际使用中最大的体会是Skills 的价值不在于技术多高深而在于它逼着你把脑子里模糊的经验显性化。写 Skill 的过程本身就是一次知识梳理。很多时候写着写着你会发现自己原来的流程里有一堆没必要的步骤。这个被迫想清楚的过程可能比 Skill 本身更有价值。如果你刚开始别追求完美先写一个最丑但能跑的 Skill用起来再迭代。Skills 这东西是改出来的不是想出来的。