AI Skills机制详解：从SKILL.md到Agent技能包开发实战

1. 先想清楚一个问题skills到底是给谁用的解决什么痛点最近“skills”这个词在AI圈子里突然刷屏——从Claude官方发技能包到Codex社区里一大堆人分享自己的“codex skills”再到GitHub上各种skill合集仓库。老实说我第一次看到这个词的时候也愣了一下以为是某个游戏里的天赋树后来才发现这其实是AI编程助手和Agent工具里正在流行的一套扩展机制。先说人话解释一下在Claude、Codex这类AI代打工具里skills本质上是一套打包好的“技能说明书操作手册工具集”。你把它放到指定目录AI在干活的时候会先读这个说明书知道“遇到这类任务应该用什么流程、按什么格式、调哪些脚本”。你可以把它理解为招了一个新员工之后HR递给他的一本《岗位手册》——里面不只是说“你负责写报表”而是写清楚“报表长什么样、数据从哪来、有哪些模板、常见错误怎么处理”。为什么这件事值得专门写一篇文章讲因为过去我们使用AI的方式是“在对话里临时交代任务”AI的表现完全取决于你prompt写得有多细。但prompt天生有两个问题第一每次重新开会话你都得把规矩重新讲一遍讲少了它就自由发挥第二AI在长任务执行到后半段会出现“指令漂移”——前面你明明说了要输出JSON它到后面突然给你来一段Markdown表格很常见。Skills要解决的就是这两个问题把“规矩”固化成文件让AI每次干活前自动读一遍稳定性和一致性一下子上来了。这篇文章适合三类人一类是已经在用Claude或Codex、但总觉得AI输出不稳定、想提升效率的开发者一类是刚接触Agent编程、想搞清楚“skills到底是个什么新概念”的好奇者还有一类是自己做过一两个技能包、想系统梳理方法论的人。我会从概念拆解、目录结构、开发实操、案例参考、避坑指南五个方面完整过一遍全部基于我自己实际折腾过的经验。2. skills的底层结构拆解一个skill到底长什么样2.1 目录结构一切从SKILL.md开始先说最核心的一条规则在Claude Agent Skills的体系里每个技能就是一个文件夹文件夹名字就是技能名文件夹里必须有且只有一个入口文件叫SKILL.md。其他所有东西——脚本、模板、参考文档、示例代码——全部放在这个文件夹里通过SKILL.md里的相对路径引用。真实的结构大概长这样my-project/ ├── .claude/ │ └── skills/ │ ├── pdf-paper-extractor/ │ │ ├── SKILL.md │ │ ├── scripts/ │ │ │ └── extract_pdf.py │ │ ├── templates/ │ │ │ └── paper_summary_template.md │ │ └── references/ │ │ └── paper_structure_guide.md │ └── code-reviewer/ │ ├── SKILL.md │ └── rules/ │ └── review_checklist.md └── src/ └── ...这个设计其实很有讲究。文件夹做隔离意味着技能之间互不干扰入口固定叫SKILL.md意味着Agent拿到任务后能快速扫描这个文件判断“这个技能适不适合当前任务”。你如果用过其他插件系统就会发现很多插件要注册、要配置文件、要初始化而Skills的机制极简——目录放对了Agent自己会去读。有人可能会问Agent是怎么知道什么时候该读哪个技能的这里就涉及到Claude Skills的加载机制了。Claude在初始化任务时会扫描skills目录下所有子文件夹里的SKILL.md并把每个技能的description信息注入到上下文中。真正触发技能调用的是description里那几句话——说得直白点Agent是个“按描述匹配”的系统你的技能描述写得越准确、越清晰它就越能在正确的时候自动掏出这个技能。2.2 SKILL.md的两个关键部分frontmatter和正文SKILL.md不只写说明文字它有严格的结构要求。最开头是YAML格式的frontmatter目前最核心的字段有两个name和description。后面是正文正文没有强制模板但官方推荐包含“何时使用、技能做什么、如何使用、示例、排查指南”这几块。我见过很多第一次写技能的人在frontmatter上就翻车了。最常见的错误是把description写成一句干巴巴的功能概括比如“用于PDF解析”然后AI根本不知道什么时候该用它。好的description应该是一小段自然语言描述的是“这个技能在什么场景下解决什么问题”最好带两三个具体例子让Agent能判断“用户当前的任务跟这个描述匹配吗”。举个例子我自己的一个论文解析技能的description是这么写的--- name: pdf-paper-extractor description: 当用户需要从PDF文件中提取论文内容、生成结构化摘要、抽取核心论点时使用。适用于分析研究论文、技术报告、白皮书等学术文档能够处理扫描版和文字版PDF输出包含背景、方法、结论的分段总结。 ---注意我在description里写的是“当用户需要……时使用”而不是“本技能可以提取PDF内容”。这两个写法看起来差不多但对模型而言差异很大——前者是场景导向Agent容易在正确时机触发后者是能力罗列Agent可能在无关任务里也误触发。这个细节后面我再展开讲。2.3 正文的推荐写作结构像写教学手册别像写需求文档正文是技能的核心资产。我的经验是SKILL.md正文应该按照“场景→流程→标准→示例→排查”的顺序组织而不是按“功能一、功能二、功能三”的功能列表组织。原因很简单你写的是给Agent看的手册不是软件需求说明书。Agent在做任务时要的是“第一步做什么、第二步做什么、输出成什么样”而不是“本模块支持以下能力”。我自己常用的正文模板是这样的# PDF论文解析器 ## 何时使用 当用户给出PDF文件路径并要求解析论文、生成摘要、提取关键信息时使用本技能。 ## 技能功能 将PDF论文转换为结构化Markdown摘要保留标题层级、提取引用、标注图表位置。 ## 使用步骤 1. 用scripts/extract_pdf.py提取PDF文本输出为临时文本文件。 2. 根据templates/paper_summary_template.md生成摘要。 3. 对照references/paper_structure_guide.md检查是否遗漏章节。 4. 输出最终Markdown并注明原文页码。 ## 示例 用户输入请解析paper.pdf输出一份500字摘要。 输出格式参考templates/example_output.md。 ## 常见问题 - PDF扫描版识别率低先提示用户确认是否为扫描版并说明当前脚本仅支持文字版。 - 提取结果乱码检查PDF是否为加密文件要求用户解除密码后重试。有个细节需要注意正文里要尽量给出“什么时候不要用这个技能”。这是很多人会忽略的。比如我的PDF技能里写了一句话“如果用户只是问论文大意而不需要结构化输出不建议使用本技能直接根据对话内容回答。”这句话有什么用呢它能防止Agent把事情搞复杂——用户只是想闲聊几句论文的事Agent却跑去调脚本、跑文件体验非常糟糕。2.4 Skills和Plugins、MCP工具到底有什么区别很多人一开始会把Skills和Claude的Plugins、以及MCPModel Context Protocol模型上下文协议工具搞混。我在这里用一个简单类比来厘清。Plugins更像“外挂驱动”它给你装上去的是一组可以调用的命令工具。比如说装了一个网络请求插件AI就多了一个fetch_url()的能力调用入口。Skills更像“操作手册”它不改变AI的调用能力而是改变AI的行为方式——它告诉AI“遇到这类任务你应该遵循什么流程、输出什么格式”。简单说Plugins给你新工具Skills给你新规矩。MCP则是工具和AI之间的一套通信协议让外部工具能被统一注册、描述、调用。Skills可以和MCP工具配合使用MCP负责打通外部系统Skills负责约束行为流程。很多开发者在实践中发现光有MCP没有SkillsAI虽然能调用工具但做事方式依然飘忽光有Skills没有MCPAI只能在自己已有的能力范围内调整行为。两者配合才是完整的。这个区分不是纯理论会影响你的架构选择如果你的需求是“让AI能访问数据库”去搞MCP工具如果你的需求是“让AI写SQL时俩字段不要老是写反、输出要带执行计划”这才是写Skills的场景。3. 从零开发一个可复用的skill完整实操记录3.1 实操前想清楚的三件事技能边界、大小、放置位置在动手写SKILL.md之前我建议你先想清楚三个问题这三个问题决定了你后续开发的方向对不对。第一技能的边界是什么。一个技能只解决一类任务不要试图做一个“万能技能”。我见过有人把“数据分析画图报告生成邮件发送”全塞进一个技能里结果是每次AI执行任务的时候光读手册就消耗了大量上下文最后执行得还很毛糙。正确的做法是一个技能聚焦一个场景闭环。比如“数据分析”和“画图”拆成两个技能“生成报告”再单独一个让Agent按需组合。第二技能该多大。在Claude Agent Skills的设计中一个技能的全部内容包括SKILL.md和所有附带文件有一个上限不能超过模型的上下文窗口限制。公开仓库里的技能可以写得详细因为不怕占空间但如果你给自己用要记住技能越大Agent每次初始化时加载的token就越多留给实际任务的上下文就越少。我的经验是SKILL.md本身控制在200400行左右辅助脚本和模板文件控制在总大小12MB以内这样在性能和完整性之间比较平衡。第三技能放在哪里。这个直接影响“AI能不能读到”。在Claude桌面版和Claude Code里用户级技能放在~/.claude/skills/目录项目级技能放在项目根目录/.claude/skills/目录。Codex那边也有类似的目录约定。一个常见的坑是你在项目目录下放了一套技能又装了另一套同名的用户级技能两套还会互相覆盖搞到后面AI读的到底是谁的你根本分不清。建议日常开发统一用项目级目录只有通用性极强的技能比如PDF解析、代码审查才放进用户级目录。3.2 动手写一个“论文写作规范”技能从零到一的完整步骤为了展示完整流程我这次用一个真实的项目来演示。我最近在帮一个研究小组搭一套学术写作辅助流程——他们希望AI在帮忙写论文草稿的时候能统一遵守目标期刊的格式规则、引用格式、段落长度并且能生成符合投稿要求的Markdown初稿。如果不用Skills每次跟AI说“请按照APA格式写摘要、不要超过150字、关键词至少3个”AI大概率会在第3次对话之后开始跑偏。于是我把这些规则打包成了一个技能。第一步先创建目录结构mkdir -p .claude/skills/academic-paper-writer cd .claude/skills/academic-paper-writer touch SKILL.md mkdir -p templates references examples第二步写frontmatter。这次我特别打磨了description让它能精确匹配“帮我写论文”“写个摘要”“整理参考文献”这几类高频请求--- name: academic-paper-writer description: 当用户需要撰写、修改学术论文、生成摘要、整理参考文献、调整格式时使用。适用于论文初稿写作、稿件结构优化、参考文献规范化等学术写作相关任务。如果用户只是简单咨询学术问题而非要求输出正式文本不建议使用本技能。 ---第三步写正文。我把期刊的排版规范、摘要字数限制、引言结构、结果部分的图表要求全部写进了正文。关键点是所有规范不是“建议”而是“必须执行”我在正文里用了一个“硬性规则”区块让Agent知道这些是不能讨价还价的。下面是正文的节选# 学术论文写作助手 ## 何时使用 用户要求撰写或修改学术论文、生成结构化摘要、整理参考文献时使用。 ## 硬性规则 - 摘要字数目标期刊要求不超过250字。 - 关键词35个按重要程度排序。 - 引用格式统一使用author-date格式参考文献列表按字母排序。 - 段落长度每段不超过120个英文单词或200个中文字符。 - 图表位置文中标注图1、图2并在文末附图表说明。 ## 实施步骤 1. 确认用户提供的论文主题、目标期刊、已有材料清单。 2. 按templates/paper_structure_template.md的结构组织论文框架。 3. 起草各部分内容引用参考文献时在正文中插入位置标记。 4. 对照references/formatting_checklist.md逐项自查。 5. 输出完整论文草稿并在末尾附“待补充材料清单”。 ## 示例 用户输入帮我写一篇关于无人机路径规划算法的论文开头目标期刊是Sensors。 期望输出包含标题、摘要、引言的结构化草稿并按Sensors的格式要求标注。第四步写辅助文件。templates目录里放论文框架模板references目录里放自查清单examples目录里放一个“完成品示例”。我特别强调examples的重要性——Agent从示例中学到的“好的输出长什么样”比任何规则描述都管用。写示例的时候不要随手糊一个要按照你真正期望的完整产出格式来写这样AI才能照着葫芦画瓢。3.3 测试技能不看“能不能跑通”要看“稳不稳定”技能写完不要直接宣布完工测试这一步非常关键。我的测试方法跟很多人不一样——不是自己准备好prompt然后看AI输出一次就完事而是把技能放到多个不同的会话里、换不同的说法来触发测试它的稳定性和触发准确率。我推荐做三组测试。第一组直接命中测试用description里明确提到的句子去触发比如“帮我写一篇论文的摘要”看AI是否调用了技能。第二组模糊接近测试用一些不那么直接的表述比如“我有个研究想整理成文章给我出个框架”看看AI是不是也能正确触发。第三组干扰测试故意问一些和技能无关但沾边的问题比如“给我讲讲论文摘要一般写什么”期望AI不要滥用技能——如果它识别不了直接回答反而调用了PDF脚本那说明description写得还不够精确需要再打磨。我总结了一个简单的判断标准连续触发成功率要超过80%误触发率要低于10%。达不到这个标准说明技能描述或正文字面上的边界还不够清晰需要迭代。实测中最有效的一个优化是在description末尾加一句“不适合使用的场景”这句话对降低误触发率帮助极大。我在前面写的两个示例里都加了这句话不是偶然。4. 写出好skills的关键心得从官方到社区从入门到精通4.1 官方技能列表最值得学习的一手教材Claude官方在发布Agent Skills功能时顺手开放了一批官方技能文件格式统一、文档规范、测试充分。如果你不知道技能该怎么写得专业直接去研究这些官方技能比看任何教程都有效。我梳理了一下官方技能的类型按使用频率和价值排个序大家可以根据需求对标技能名用途适合对标场景docx生成和编辑Word文档处理段落、样式、表格办公自动化、合同生成、报告输出pdf读取和解析PDF文件提取文本和元数据论文解析、文献整理、档案归档pptx生成PowerPoint演示文稿汇报材料、课程课件、方案演示xlsx读写Excel表格处理公式和图表数据分析、报表生成、预算管理svg生成和编辑SVG矢量图流程图、架构图、图标绘制研究官方技能你会发现一些共性每个SKILL.md都写得非常精炼没有废话每个都附带测试文件每个技能目录内都允许携带脚本、模板和示例输出。看它们怎么组织目录、怎么写description、怎么在不同子任务间切换比自己从头摸索效率高得多。4.2 社区里最热门的skills从写论文到分镜到自动化研究顺着热搜词“codex好用的skills”往下翻其实社区里已经沉淀出了不少很有想象力的技能包。我挑几个比较有代表性的方向来说说不一定都是代码类技能大家也能看看这套机制能玩出什么花。一个是“论文写作”方向的技能包。其实很多学术博主分享过这类技能输入一个研究方向Agent会按照科技论文的结构自动组织框架、补全引言、生成方法部分的描述还能根据目标期刊的要求调整格式。这类技能的核心价值不是“省去写论文的功夫”而是把写作结构、格式规范、术语风格统一成一套显式规则避免AI自由发挥导致返工。另一个值得注意的是“分镜”方向的技能包。这个在短视频制作圈子里特别火——输入一段脚本文案技能包会按“开场—冲突—转折—高潮—结尾”的结构帮你拆出分镜表每一镜给到景别、运镜、台词、画面描述。说白了它不是一个视频工具而是一个创意结构的约束器。这类非编程技能恰恰说明了一个事skills的本质是“给AI装规矩”跟代码写不写得好没有必然关系。还有一个方向值得提的是“自动化研究”类的技能包。以“自动挖洞”这类自动化安全研究技能来说这类技能通常是给AI设定一套漏洞挖掘的标准化流程信息收集、资产盘点、漏洞验证、报告输出每一步都有对应的工具调用和输出模板。这类技能包往往会把方法论、工具链、报告模板打包在一起让AI以一个“受过训练的实习生”的方式参与研究工作而不是每次从零教一遍。当然安全研究本身是一把双刃剑技能包只做规范化流程具体的使用场景要遵守所在组织的授权和合规要求。4.3 我踩过的坑技能写得“太大”和“太玄”都会出问题开发skills做多了我总结出两个最容易踩的坑这里单独拿出来说说。第一个坑是“太大”。我最早写技能时什么都往里塞——规则、示例、脚本、参考文献、历史版本记录全放在一个目录里。结果就是Agent在任务开始前加载技能时上下文已经被吃掉了一大截真正干活的时候反而施展不开。后来我学乖了把SKILL.md里只保留“执行步骤、硬性规则、参考文件索引”把所有大段的细节内容拆到references目录下的独立文件里在正文里用相对路径引用。这样Agent看到的是精简版手册需要细节时再读取对应文件上下文压力小很多。第二个坑是“太玄”。所谓“太玄”就是description和正文里写了很多模糊的形容词比如“高质量”“全面”“精准”让Agent无所适从。你写“高质量论文”它不知道什么算高质量你写“摘要不超过300字”它反而能执行。技能文件里一切指令都必须可量——至少是可验证的。把“使用正确的引用格式”改成“参考文献按APA第7版格式排列作者姓在前、年份在括号内”把“输出结构清晰的报告”改成“报告包含背景、方法、结果、结论四部分每部分至少包含2个小标题”。你会发现改动之后Agent输出质量是肉眼可见地上升。5. 常见问题与排查技巧实录5.1 技能没生效先别怪AI按顺序排查这三个地方技能写好了也放对了目录但用了半天发现AI根本不理会它这种情况大概每个做skill的人都经历过。我自己的排查顺序是固定的。先查路径。确认技能文件夹是不是在Agent实际读取的目录下。我碰到过最乌龙的一次是把技能放到了~/.claude/skills/但当时用的项目跑在Docker里容器内根本没有这个目录——Agent自然完全没加载到。Claude Code和桌面版、Codex的目录约定不完全相同换环境之后第一件事就是确认路径别想当然。再查文件权限和命名。SKILL.md的文件名必须是这个格式如果手滑写成了skill.md或者SKILL.MD有些环境会识别不了。另外文件夹名字里的空格、中文、特殊字符也可能造成解析问题好的实践是统一用小写字母加连字符比如pdf-paper-extractor。最后查description。如果路径没问题、文件也没问题但Agent就是不触发大概率是description写得和用户请求匹配不上。我之前有个技能是处理日志分析的description里写的场景是“分析服务器日志”结果用户每次开口都说“帮我看下这个log文件”——模型一看“log”和“日志”不完全一样就没触发。后来我在description里补上“支持log、日志文件、错误追踪记录分析”之后触发率立刻上来了。5.2 上下文爆炸技能文件太大导致的隐性灾难这是一个非常隐蔽的问题不容易被发现等你发现时往往已经晚了。技能的SKILL.md和附带的模板、示例会在Agent加载时占用上下文token如果你的技能包动辄几万字Agent每次干活光读技能就花了大量“脑容量”留给真正任务的空间就少了表现为生成质量的整体下降。怎么判断是不是这个问题一个非常有效的办法是关掉技能之后用同样的prompt让AI跑一遍对比输出质量。如果“没技能”时AI反而输出更好那就是技能膨胀太严重了。遇到这种情况我的处理方式是做“分层加载”SKILL.md只保留最关键的执行步骤和硬性规则把详细模板、完整示例、FAQ全部拆到子目录的独立文件里在正文中用相对路径引用。Agent默认只读SKILL.md需要时会定向读取附件。这个机制实操下来特别管用。5.3 技能之间互相打架同名覆盖和触发冲突当技能多了新的问题就来了——两个技能可能抢同一个场景。比如你有一个“写日报”的技能另一个“周报生成”的技能两者的description里都写了“生成工作汇报”Agent每次拿到日报需求时可能两个技能都触发或者触发了错误的那一个。解决办法有两个。第一在description里加互斥条件比如日报技能写明“仅适用于每日更新不适用于周度汇总”周报技能写明“仅适用于周度汇总不适用于每日更新”。第二在SKILL.md正文中写一个“如果检测到任务更适合其他技能请自行忽略本技能并建议用户换用对应技能”的指令这样既避免冲突也给Agent留了退路。同名覆盖的问题也需要警惕——项目级目录和用户级目录存在同名技能时以项目级优先。很多时候你改了用户级的技能但项目里残留一个旧的同名副本AI依然读的是旧文件你怎么改都没效果。碰到“改了技能好像没生效”的问题多半就是这个。5.4 快查表开发技能最常见的10个问题症状原因解决方案AI完全不提技能目录路径不对确认技能放在正确的skills目录下技能在A环境能用B环境失效不同工具的目录约定不同按工具官方文档查路径不要跨环境假设触发率低经常不调用description太泛或太窄重写description加具体场景和互斥条件误触发严重总在不该用时出现description缺少排除场景在description末尾明确“不适合的场景”输出跟规则不一致SKILL.md硬性规则不够具体把模糊要求改成可量化的指令上下文不足生成质量下降技能文件过于庞大拆分文件SKILL.md只保留核心细节放入references修改后没效果存在同名覆盖检查项目级和用户级目录删掉旧副本脚本类技能报错依赖环境不匹配在SKILL.md中写明依赖包并附带安装脚本中文文件名乱码文件夹命名不规范统一使用小写英文加连字符命名输出风格不稳定缺少示例文件在examples目录放23个完整的“期望输出”样板6. 最后的实用建议skills开发的两个心法写了这么多最后分享两个我个人的体会也是想给刚开始接触这套机制的朋友提个醒。第一skills的开发是一个“先窄后宽”的过程。一开始只做一个非常明确的、小范围的技能——比如每周五帮你整理本周工作记录并生成周报——把它打磨到稳定之后再逐步扩展到其他场景。很多人一上来就想做一个涵盖所有工作场景的“万能技能包”结果不是上下文爆炸就是触发混乱。小步快跑在技能开发里同样适用。第二skills真正要写的是“例外”和“边界”不是“流程”。AI本来就会做大部分常规事情你写技能不是为了教它怎么做而是为了告诉它“哪些地方容易出错、哪些情况要特殊处理、你的偏好是什么”。我第一次写技能时长篇大论地描述“什么是好的代码”后来发现AI早就懂这些真正有用的是那些我踩过坑之后总结的“坑点清单”。把你自己工作中反复纠正AI的话术沉淀到技能里这就是最好的技能素材。我现在开发任何一套给Agent用的流程都默认从技能的角度思考这个任务哪些步骤是稳定的、可固化的哪些边界是要反复强调的写成SKILL.md之后AI的输出稳定性和我可控感确实提升了一个档次。这套东西的门槛不高但天花板很高——你给它多少“规矩”它还你多少“靠谱”。