最近大半年AI编程助手圈子里高频词除了MCP就是skills。Claude Code、Codex CLI、OpenCode这些工具陆续支持自定义技能之后前端开发skills数学建模skills这些关键词开始频繁出现在技术社区和GitHub。这东西到底是什么一句话讲清楚Skills就是给AI助手预装的操作手册它把你做某类任务的步骤、规范、经验写成结构化文档AI接到对应任务时按需加载照着你的规矩干活。我见过太多人手里的Claude Code只会裸奔让它写代码就写代码让它写文档就写文档结果质量全看运气。装上skills之后相当于你给AI配了一整套从实战里沉淀下来的SOP它不再自由发挥而是先看手册再动手。这篇文章我把安装、编写、排查的完整链路都过一遍适合刚听说skills想上手的人也适合已经在用但经常遇到不生效上下文爆炸的老手。1. Skills到底是什么AI助手的“SOP手册”1.1 从一次失败的建模论文生成说起先讲个我自己的例子。之前参加数学建模比赛队友把题目丢给Claude Code让它写一篇建模论文摘要。结果出来的东西四平八稳有背景、有方法、有结论但完全不是竞赛评委想看的样子。没有本文针对……问题建立了……模型采用……算法求解这种标准句式也没有把灵敏度分析、模型评价单独拎出来讲。问题不在模型笨是我没告诉它数学建模论文该按什么节奏写。后来我把一个数学建模论文写作的skill丢进去同样的请求出来的摘要结构立刻对了问题重述、模型假设、符号说明、模型建立与求解、模型评价、结论每个环节都有对应的书写规范。这就是skills的核心价值——把过程性知识固化成文件让AI每次都按你验证过的路径走而不是每次都在低水平重复里碰运气。从机制上看skills是写给Agent执行的上下文工程方案一个包含SKILL.md主文件和辅助资源的目录通过frontmatter里description字段描述什么时候用这个技能。当模型分析对话内容觉得当前任务和某个skill的描述匹配时它会把SKILL.md的内容加载进上下文并按文件里的指令组织行为。1.2 Skills、MCP与Prompt模板三者的边界在哪很多刚接触的人会把skills和MCP、普通Prompt模板混在一起我简单拆一下Prompt模板一次性使用的提示词写完用掉就完了没有结构、没有版本管理。Skills结构化的操作手册包含元信息、步骤、示例、辅助脚本可以被复用、版本化、团队共享核心目标让AI按规范办事。MCP给AI接外部工具和数据源核心目标让AI能干什么事比如查数据库、调浏览器、操作文件系统。用生活化的类比Prompt模板是一张便利贴Skills是一本员工手册MCP是一个工具箱。便利贴随手写手册要沉淀要维护工具箱则决定AI有没有趁手的装备。它们不是替代关系实际项目中经常配合使用。我在一些实际项目里就让Claude Code通过MCP读数据库再用一个数据表设计skill约束它产出规范的建表语句效果比单独用哪一样都稳。2. 5分钟上手从GitHub装一个现成Skills2.1 先搞清楚目录结构个人级还是项目级动手装之前先确认你要把skill装到哪个层级。以Claude Code为例skills目录按作用范围分几档层级路径适用场景项目级项目根目录下.claude/skills/跟着仓库走团队所有人都能共享个人级用户目录下~/.claude/skills/你自己跨项目通用的技能组织级团队或企业配置的管理目录统一规范强制推给成员Codex CLI、OpenCode这类工具也引入了类似机制目录位置和命名略有差别但思路一致放对位置工具才能发现它。新手最容易犯的错就是把skill文件夹放到项目根目录或者随便某个位置结果Claude Code完全看不到。我自己的做法是通用性强、和个人习惯相关的skill放个人级比如代码审查、提交信息规范跟具体项目强绑定的放项目级比如某个前后端项目的组件开发规范。这样换项目时不至于一堆无关skill到处乱跑。2.2 手动安装的完整流程clone、拷贝、验证从GitHub手动装一个skill核心三步下载、放到正确的目录、验证。以安装官方anthropics/skills仓库里某个技能为例# 第一步把仓库clone到本地 git clone https://github.com/anthropics/skills.git # 第二步进入仓库找到你要的skill目录 cd skills ls -la # 你会看到类似 doc-writing / code-review 这样的子目录 # 第三步把需要的skill拷贝到Claude Code的个人级skills目录 cp -r skills/doc-writing ~/.claude/skills/如果你不想clone整个仓库也可以直接在GitHub网页上进入某个skill目录下载SKILL.md以及它引用的辅助文件手动创建.claude/skills/技能名/目录结构再放进去。下载ZIP的方式同样可行但注意解压后要把文件夹整理成技能名/SKILL.md的层级不要直接把SKILL.md散落在根目录。装完之后在Claude Code里执行/skills命令看到列表里出现对应的技能名就说明安装成功。这个命令还会显示技能描述和启用状态我在日常使用中基本靠它确认每装一个技能是否被正确识别。2.3 日常管理用/skills命令查看和切换/skills是Claude Code里管理技能的高频入口值得多说几句。输入/skills回车会列出当前环境能看到的全部技能。如果你只想关注当前项目生效的技能可以配合目录过滤在输入时加上路径或者名称关键字。实际使用中还有个很实用的小技巧当某个任务没自动触发skill时可以直接在对话里指定。比如我明明装了代码审查skill但提交代码时AI没有按照审查清单执行我就直接说请使用code-review这个skill来审查下面的代码模型会主动去加载对应技能并按流程走。遇到多技能同时匹配的场景Claude Code通常会选择描述相关性最高的但有时候结果不是你想要的那个这时候手动点名比反复改prompt省事得多。3. 自己动手写SKILL.md格式、触发与最佳实践3.1 SKILL.md的标准骨架与frontmatter写法现成的skills用多了你会发现终究要自己写——毕竟团队规范、个人工作流这种东西网上很难找到完全贴合的。写一个skill并不需要会编程核心就是创建一个文件夹里面放一个SKILL.md主文件。标准的SKILL.md长这样--- name: my-custom-skill description: 当需要编写/优化xxx类型的代码或文档时使用 --- # 技能说明 这个技能用于…… ## 执行步骤 1. 先做…… 2. 再做…… 3. 最后检查……name是这个技能的唯一ID小写、用连字符分隔单词description是触发开关模型靠它判断当前任务是否匹配这个技能。很多人写description时喜欢写这是一个用于xxx的技能这就是典型的浪费模型需要知道的是什么时候用而不是它是什么。正确写法是当用户要求xxx时使用在处理xxx任务时使用这类偏场景化的表达。3.2 实战示例一个数学建模论文Skill是怎么写的数学建模是skills最受欢迎的落地场景之一我拿它当例子拆解一下。我写过一个数学建模论文写作技能核心文件是SKILL.md正文里规定了论文的整体结构和摘要写法--- name: math-modeling-paper description: 在撰写数学建模竞赛论文、建模报告或相关学术文档时使用 --- # 数学建模论文写作规范 ## 摘要 - 第一句说明问题的背景与研究意义 - 第二句一句概括本文提出的模型或方法 - 第三句说明使用的数据或求解算法 - 后文给出主要结果与误差分析 ## 论文结构 1. 问题重述 2. 模型假设 3. 符号说明 4. 模型建立与求解 5. 模型评价与灵敏度分析 6. 结论 ## 排版要求 - 数学公式统一用LaTeX语法 - 图表必须有编号和标题写完之后让AI生成的内容从自由发挥体变成了竞赛标准体。技能的威力不在于文件写得有多花哨而在于把你脑子里的规范转成AI能执行的步骤。数学模型推荐、华为杯这类比赛里真正好用的skill往往就是这种朴实无华的结构规范。3.3 写Skills的三条铁律少一条都容易翻车第一description决定生死。description写得模糊模型要么不触发要么在无关任务里乱触发。我见过有人把description写成数学建模结果任何和数学沾边的请求都会触发它上下文被无用内容堵满。写场景、写任务动词别写空泛名词。第二控制文件篇幅。SKILL.md不是越长越好它是要占用模型上下文的。我一般把主文件控制在一次能看完的长度大约150到300行以内。太长的内容拆成辅助文件比如把示例论文放在examples/目录下在SKILL.md里用相对路径引用让模型按需读取而不是一次性全吞进去。第三用辅助文件做深度支撑。一个skill文件夹不只有SKILL.md还可以有模板、脚本、示例、代码片段。比如前端开发skill里放一个组件模板文件AI生成新组件时直接套模板比在SKILL.md里用大段文字描述要准确得多。把规范描述和具体样例分开模型加载更轻输出也更稳定。4. 别自己憋技能热门场景与靠谱来源清单4.1 按场景选Skills建模、前端、AI内容创作与其从零憋一个skill不如先看别人怎么写的尤其是高频场景里已经形成共识的。我按三个热门方向列一下实际感受数学建模方向这个场景的skill重点在论文结构、摘要句式、LaTeX规范。比赛时间紧AI能按竞赛套路输出省下的全是整理格式的时间。华为杯、美赛这类比赛前后GitHub上会冒出很多好用的建模skills遇到评价高、结构清晰的就直接装进个人级目录。前端开发方向前端项目的skill通常包含组件规范、样式约束、状态管理约定。比如你团队规定所有组件必须用TypeScript CSS Modules禁止内联样式把这些写进skill后AI生成的代码会自动遵守。团队里有人写了一版优质组件也可以把组件代码抽成skill的参考模板让后续所有AI生成都向这个标准看齐。AI漫剧与内容创作方向AI漫剧、短视频脚本这类需求skills同样适用。常用做法是把分镜脚本格式、角色一致性要求、对白风格限定写进skill再附一个标准的分镜表格示例文件。AI每次生成时按这个格式走作品风格就稳定了不会今天一个风格明天一个风格。4.2 值得收藏的Skills来源仓库与社区合集找skills最直接的渠道是GitHub几个方向可以关注anthropics/skills官方仓库质量有保证适合作为学习范例。superpowers社区里很火的一套技能包包含大量相互关联的子技能覆盖代码、写作、推理等场景安装之后能明显感觉到AI干活更有章法。各类awesome-skills合集仓库搜索awesome claude skills或者awesome agent skills就能找到一批汇总清单维护者会定期更新省去你到处翻仓库的时间。工程化团队的公开仓库像Typesafe AI这类主打工程规范的组织会在GitHub上开源内部skill特点是结构严谨、拆分细致很值得参考。另外我在推荐大家一个习惯看到好的skill先点开它的SKILL.md读一遍再决定装不装。很多skill描述写得很诱人实际内容却很水读一遍能帮你筛掉大部分垃圾技能。有些技能库还提供网页版浏览直接在浏览器里看文件结构比clone整个仓库再翻要快得多。5. SKILL.md不生效这份避坑排查清单请收好5.1 装了不生效先按这四个环节查遇到skill装了但AI完全不按它执行按下面顺序排查目录结构确认是否放在.claude/skills/技能名/SKILL.mdClaude Code只认这个结构漏一层目录就找不到。frontmatter格式确认文件开头有---包裹的name和descriptionYAML格式写错会导致解析失败整个skill被静默忽略。description匹配度检查你的请求是否和description描述的场景一致。你让AI优化一下这段代码装的却是文档写作skill它自然不会被加载。工具版本早期版本的Claude Code对skills支持不全如果目录和格式都对但仍不生效先更新到最新版本。我踩过一个很蠢的坑把SKILL.md放在了~/.claude/skills/下但文件名写成了skill.mdLinux下大小写敏感Claude Code找的是SKILL.md结果整整一下午这个skill都没有触发。这种细节比想象中更容易翻车。5.2 上下文被Skill吃掉了怎么办skill加载后占用上下文装多了、写长了Agent的有效思考空间就被压缩。两个解决办法一是精简文件。SKILL.md只留必要规范示例文件改成按需加载。比如LaTeX模板这样的长文件不要直接写在正文里放在templates/目录让AI需要时自己读取。二是控制同时触发的技能数量。如果你的多个skill都是宽泛的description一次请求可能同时命中三四个上下文直接爆炸。给每个skill的description写得窄一些、职责边界清楚一些能显著减少这种挤占。我自己在写description时会刻意避免出现帮助用户解决各种问题这类万能表述让匹配更精准。5.3 定期给技能库“瘦身”别让垃圾Skill拖慢Agentskills越多不代表越强维护一个乱糟糟的技能库反而会让AI分心、上下文膨胀。我见过有人一口气装了五六十个skill结果日常任务里经常触发错误的技能输出风格来回横跳。我自己的习惯是每月做一次技能体检在Claude Code里运行/skills快速过一遍列表凡是过去两周一次都没被动用过的先禁用观察再果断移除。清理时不要直接删文件夹先备份到独立的git仓库这样真要恢复也能回来。社区里也有一些关于清理skills的方法推荐比如定期review每个skill的触发次数、关注description是否经常造成误匹配、把临时用不到的大技能归档到独立目录。这套思路的核心只有一个技能库是处置资源不是收藏夹留精不留多。6. 最后说点实操体会搞了这么久的skills我最大的体会是它的价值不在skill文件本身写得有多漂亮而在于你把团队的做事标准沉淀成了一堆AI能直接执行的资产。以前带新人要反复强调摘要要按这个结构写组件必须加类型注解提交信息要规范化现在把这些规则全部拆进各自的skillAI接手新人只需要看AI产出的结果再review效率完全不是一个量级。我也越来越倾向于先找后写的流程接到一个新领域的任务先上GitHub搜一搜有没有成熟的skill拿来主义用着不顺再改改完再回推给社区。这样你维护的每个技能都是经过真实任务检验的而不是凭空想象出来的完美模板。最后分享一个小技巧写skill的时候把你自己过去踩过的坑直接写进正文。比如这个任务常见的错误做法是把符号说明放在模型求解之后生成组件时禁止通过index访问数组元素AI看到这些负面约束比只给正面规范效果更好因为工程里的隐性知识往往恰恰藏在这些错误里。