1. 从skills这个热词说起它到底是什么最近半年不管是在技术群还是各种社区skills这个词出现的频率高得离谱。一开始我以为大家说的是技能这个泛泛的概念后来才发现它已经变成了一个专有名词——特指围绕 Claude 生态、尤其是 Claude Code 和 Agent 体系里那套可复用的能力模块。你如果搜skills推荐常用skills数学建模skills出来的基本都不是泛泛的学习方法而是具体的、能直接装进工具里跑起来的东西。说白了skills 就是给 AI Agent 用的技能包。一个 skill 通常是一个目录里面有一个核心文件叫SKILL.md再加上一些辅助脚本、模板、参考资料。SKILL.md用自然语言描述这个技能是干什么的、什么时候触发、怎么一步步执行。Agent 在干活的时候会根据当前任务去匹配这些 skill匹配上了就按里面的流程走。你可以把它理解成给 AI 写的一份操作手册只不过这份手册是 AI 自己能读、能执行的。它解决的核心问题是通用大模型什么都会一点但什么都不精。你让它做数学建模它可能给你一堆看起来对但实际跑不通的公式你让它做前端开发它可能写出能跑但结构一塌糊涂的代码。skills 的价值就在于把某个垂直领域里老手才知道的套路固化下来让 AI 每次都按这套经过验证的流程来。适合谁来学我觉得三类人最该关注一是天天用 Claude Code 写代码的开发者二是做数学建模、数据分析这类有固定方法论的学生和研究者三是想把 AI 能力封装成产品给别人用的创业者。2. skills 的整体设计与核心思路拆解2.1 为什么是文件自然语言而不是代码插件很多人第一次接触 skills 会疑惑这不就是个插件系统吗为什么不用传统的代码接口我一开始也这么想后来实际用下来才明白这套设计的精妙之处。传统的插件或工具调用需要你定义严格的输入输出 schema模型得按格式填参数。问题是很多真实任务根本没法用固定参数描述。比如帮我审一下这段代码的安全问题你没法定义清楚要传什么参数——代码语言、业务背景、安全等级、关注点这些全是模糊的。skills 用自然语言写流程模型可以自己理解上下文、自己决定读哪些参考文件、自己判断该走哪条分支。这种灵活性是硬编码接口给不了的。另一个关键点是渐进式披露。一个 skill 的SKILL.md不会把所有细节都塞进去它只写核心流程和触发条件具体的参考资料、模板、脚本放在旁边的文件里。Agent 先读主文件判断要不要用这个技能决定用了再去读细节。这样既省 token又不会让模型被无关信息干扰。这个设计思路我觉得是整个 skills 体系里最值得学的一点。2.2 目录结构背后的考量一个规范的 skill 目录通常长这样my-skill/ ├── SKILL.md # 核心文件必须有 ├── scripts/ # 可执行脚本 │ └── process.py ├── references/ # 参考资料 │ └── api-doc.md ├── assets/ # 模板、静态资源 │ └── template.html └── examples/ # 示例输入输出 └── sample.md为什么这么分SKILL.md是入口必须精简一般控制在几百行以内写清楚这个技能解决什么问题、什么时候用、核心步骤是什么。scripts放那些确定性强的操作比如数据清洗、格式转换这些用代码跑比让模型现写靠谱得多。references放那些需要时才查的长文档比如某个库的完整 API 说明。assets放模板文件模型直接套用而不是从零生成。examples最关键给模型几个输入长这样、输出应该长这样的样例比写一堆规则管用。我踩过的一个坑是一开始把所有东西都堆在SKILL.md里结果文件写到两千多行模型读起来又慢又容易抓不住重点。后来拆成主文件加参考文件效果立刻不一样。主文件负责指路参考文件负责给料这个分工一定要清楚。2.3 触发机制skill 是怎么被想起来的这是很多人搞不明白的地方。skill 不是你想用就自动生效的它得被 Agent 匹配到。匹配靠什么靠SKILL.md开头的元信息通常包括 name、description 和触发条件。description 写得越具体匹配越准。我见过有人写帮助处理数据这种描述基本等于没写模型根本不知道什么时候该用它。好的写法是当用户需要对 CSV 格式的销售数据做同比环比分析并生成图表时使用。把场景、输入格式、输出目标都点出来模型一看就知道该不该触发。还有一个技巧是在 description 里埋关键词。比如你做数学建模的 skill就把优化模型灵敏度分析论文格式这些词写进去。用户提问时只要碰到这些词匹配概率就大幅提升。这不是作弊这是让检索更精准的合理手段。3. 核心细节解析与实操要点3.1 SKILL.md 到底该怎么写这是整个 skills 开发里最核心的一环我把它拆成几个必须写清楚的部分。第一部分是身份和触发条件。开头用一两句话说明这个技能是什么、什么时候用。比如--- name: csv-sales-analysis description: 当用户提供 CSV 格式的销售数据需要做同比环比分析、生成趋势图表或输出分析报告时使用此技能。 ---这个 frontmatter 是给系统做检索用的必须写。description 里把CSV销售数据同比环比趋势图表这些关键词都覆盖到匹配率会高很多。第二部分是执行流程。用有序列表把步骤写清楚每一步说明做什么和为什么这么做。不要只写清洗数据要写检查缺失值和异常值缺失超过 30% 的列直接丢弃因为后续统计会被严重扭曲。把判断依据写出来模型遇到边界情况才知道怎么处理。第三部分是输出规范。明确告诉模型最终要产出什么格式。是 Markdown 报告、JSON 数据、还是代码文件字段有哪些命名规范是什么这部分越具体输出越稳定。第四部分是注意事项。把那些容易出错但文档里不会写的点列出来。比如金额字段可能带货币符号计算前必须去掉日期格式不统一先做标准化。这些就是老手的经验写进去能省掉大量返工。3.2 脚本和自然语言的分工边界什么时候该写脚本什么时候该让模型自己发挥我的经验是确定性的、重复性的、对精度要求高的操作一律写脚本。比如数据清洗里的去重、格式转换、数值计算这些用 Python 脚本跑结果稳定可复现。让模型现写代码每次可能都不一样还容易出 bug。反过来需要理解语义、做判断、生成内容的部分交给模型。比如根据数据趋势写一段分析结论这种脚本写不了必须模型来。一个实用的模式是脚本负责算模型负责说。脚本把数据算好输出成结构化结果模型读取结果后组织成自然语言。这样既保证了准确性又发挥了模型的语言能力。3.3 版本管理和迭代思路skills 是要迭代的。你第一次写完用几次就会发现各种问题触发不准、步骤有遗漏、输出格式不对。这时候别急着大改先记录问题。我的做法是建一个CHANGELOG.md每次改动记一笔改了什么、为什么改、效果如何。比如v1.2在 description 里加入环比关键词触发率从 60% 提升到 85%。这样迭代几轮下来你就知道哪些改动真正有效。还有一个技巧是保留失败案例。在examples目录里不光放成功样例也放几个这样输入会出错的反例并在SKILL.md里说明怎么避免。模型看到反例会主动规避那些坑。注意不要频繁大改 skill 的核心流程。每次只改一个变量观察效果确认有效再改下一个。一次改太多出了问题你都不知道是哪个改动导致的。4. 实操过程与核心环节实现4.1 从零搭建一个 skill 的完整流程我拿一个实际做过的例子来讲给数学建模比赛做一个论文格式检查的 skill。这个需求很典型比赛里格式不规范扣分很冤但人工检查又费时。第一步明确边界。这个 skill 只做格式检查不做内容评审。检查项包括摘要字数、章节编号、公式编号、图表标题、参考文献格式。边界划清楚skill 才不会越做越臃肿。第二步写 SKILL.md 骨架。先写 frontmatterdescription 里覆盖数学建模论文格式检查LaTeXWord这些词。然后写流程读取文档、逐项检查、输出问题清单。每项检查写清楚规则比如摘要不超过 800 字超出则标记。第三步写检查脚本。用 Python 写一个脚本输入文档路径输出 JSON 格式的问题列表。为什么要脚本因为字数统计、编号连续性检查这些是确定性的脚本跑得又快又准。脚本大概长这样import re import json from docx import Document def check_abstract_length(doc, max_words800): abstract extract_abstract(doc) count len(abstract) if count max_words: return {item: 摘要字数, status: fail, detail: f当前{count}字超出{count - max_words}字} return {item: 摘要字数, status: pass} def check_section_numbering(doc): sections extract_sections(doc) problems [] for i, sec in enumerate(sections, 1): expected str(i) if not sec.number.startswith(expected): problems.append(f第{i}节编号应为{expected}实际为{sec.number}) return {item: 章节编号, status: fail if problems else pass, detail: problems}第四步写输出模板。在assets里放一个 Markdown 模板规定问题清单的格式按严重程度排序每条包含位置、问题描述、修改建议。模型读脚本输出的 JSON套模板生成最终报告。第五步测试和调优。拿几篇真实的比赛论文跑一遍看检查结果准不准。我实测下来发现公式编号检查经常误报因为不同文档的公式编号方式不一样。后来在脚本里加了多种编号模式的识别误报率才降下来。4.2 参数选择与阈值设定skill 里很多地方需要设阈值这些数字不是拍脑袋定的得有依据。比如摘要字数上限设 800是因为大多数数学建模比赛的规范里写的就是 800 字左右。参考文献数量下限设 10 篇是因为少于这个数通常说明调研不充分。这些阈值最好在SKILL.md里注明来源比如依据 XX 比赛官方规范这样别人用的时候知道为什么这么设也方便调整。再比如触发匹配的置信度阈值。有些系统允许你设一个分数超过才触发。设太高该触发的不触发设太低不该触发的乱触发。我的经验是先用默认值跑一批测试用例统计准确率和召回率再微调。这个没有万能值得看你的 skill 具体场景。4.3 多 skill 协作的组织方式实际项目里往往不是一个 skill 打天下而是好几个 skill 配合。比如数学建模可能有数据预处理 skill模型选择 skill论文写作 skill格式检查 skill。它们怎么协作我的做法是用主 skill 做调度。主 skill 的SKILL.md里写清楚先调数据预处理再调模型选择最后调论文写作和格式检查。每个子 skill 保持独立可以单独使用也可以被主 skill 调用。这样既灵活又不会互相干扰。关键是子 skill 之间的接口要约定好。比如数据预处理 skill 的输出格式模型选择 skill 得能直接读。这个约定写在各自的SKILL.md里用统一的字段名和数据结构。提示多 skill 协作时最容易出问题的是数据格式不匹配。建议在项目初期就定好一套通用的数据 schema所有 skill 都遵守。后期改 schema 的成本极高。5. 常见问题与排查技巧实录5.1 skill 不触发怎么办这是最高频的问题。你写好了 skill用的时候模型压根不理你。排查思路按顺序来先看 description 写得够不够具体。如果只写处理数据那基本不会触发。改成当用户提供 Excel 格式的财务数据需要做利润表分析时使用触发率立刻上去。再看关键词覆盖。用户实际提问用的词和你 description 里的词对不上就匹配不到。解决办法是收集真实提问把高频词补进 description。我一般会攒二三十个真实问法逐个测触发情况。还有可能是 skill 没被正确加载。检查目录结构对不对SKILL.md文件名大小写对不对frontmatter 格式有没有错。这些低级错误我见过太多次了。5.2 输出不稳定怎么调同一个 skill有时候输出很好有时候一塌糊涂。这种波动通常来自三个地方。一是流程写得太模糊。比如分析数据并给出建议模型每次理解都不一样。改成计算同比增长率若超过 20% 则标记为高增长并在建议中优先提及输出就稳定了。二是缺少示例。模型是照着例子学的你给两三个输入-输出样例它就知道该长什么样。示例要覆盖典型情况和边界情况。三是脚本和模型的职责没分清。该脚本算的让模型算了结果每次不一样。把确定性计算挪到脚本里波动立刻减小。5.3 常见问题速查表问题现象可能原因排查方法解决方向skill 完全不触发description 太泛用真实提问测试补充具体场景和关键词触发但流程走偏步骤描述模糊检查 SKILL.md 流程部分每步写清判断依据输出格式不对缺少输出规范对比期望输出加模板和示例结果每次不同确定性操作交给模型定位波动环节挪到脚本执行读取参考文件失败路径写错检查相对路径统一用相对路径多 skill 冲突触发条件重叠看哪个先匹配收窄各自触发范围5.4 几个我踩过的坑坑一SKILL.md 写太长。一开始觉得写得越详细越好结果文件两千多行模型读到后面忘了前面。后来拆成主文件加参考文件主文件控制在 300 行以内效果反而更好。坑二示例太完美。只给理想输入模型遇到脏数据就懵。后来在 examples 里专门放几个脏数据案例并说明怎么处理鲁棒性明显提升。坑三忽略 token 成本。每次触发都把整个 skill 目录读一遍token 消耗巨大。后来改成渐进式读取主文件判断需要了再读细节成本降了一大半。坑四不做版本记录。改来改去最后忘了哪版效果好。现在每次改动都记 CHANGELOG回滚的时候心里有底。6. skills 的进阶玩法与扩展方向6.1 把 skill 做成可复用的团队资产一个人写的 skill如果只在本地用价值有限。把它放到团队共享的仓库里所有人都能装、能用、能改价值就放大了。做法是建一个 skills 仓库按领域分目录frontend/、>