1. 从“每次都要重新解释一遍”说起如果你已经在日常工作中重度使用各类AI助手大概率经历过这种场景新开一个对话窗口你花了五分钟把项目背景、代码规范、输出格式、注意事项全部交代一遍AI终于给出了一个还算满意的结果。第二天你又开了一个新窗口同样的事情再来一遍。第三天、第四天……你开始怀疑到底是我在用AI还是AI在训练我的耐心。这个问题的本质不是AI不够聪明而是它没有持久化的“工作方式记忆”。大模型的上下文窗口再大也是会话级的关掉就清零。你每次输入的提示词本质上是在做一次性的“临时教学”教完就忘。Agent-Skills 这套机制要解决的就是这个问题。它做的事情说起来很朴素把你的工作方式、领域知识、操作流程写成AI能读懂的结构化文件让AI在需要的时候自动加载并遵循。你不再需要每次重复交代AI也不再是那个“每次都要从头教起的新人”。我最初接触这个概念的时候觉得它不过是“高级一点的提示词模板”。但实际用下来发现它和提示词模板有本质区别提示词模板是静态的文本替换而Agent-Skills是一套可发现、可组合、可按需加载的能力单元。AI会根据当前任务自动判断该调用哪个Skill而不是你手动去拼接一大段提示词。这篇文章适合三类人看一是每天和AI打交道、想提升效率的开发者或知识工作者二是正在搭建AI Agent应用、需要给Agent注入领域能力的工程师三是单纯好奇“AI怎么记住我的偏好”这个问题的普通用户。我会从核心机制、文件结构、实操步骤、常见坑几个维度展开尽量把这件事讲透。2. Agent-Skills到底在解决什么问题2.1 传统提示词工程的三个死穴先说清楚为什么需要Agent-Skills。大部分人用AI的方式是“对话式提示”也就是在聊天框里打字。这种方式有三个绕不过去的死穴。第一个死穴是不可复用。你精心写了一段提示词效果很好但它只存在于那个对话窗口里。换个窗口、换个任务你得重新写。有人会说“我存到备忘录里不就行了”但备忘录是给人看的你每次还得复制粘贴而且不同AI平台的格式要求还不一样。第二个死穴是不可组合。假设你有一个“代码审查”的提示词还有一个“写单元测试”的提示词。现在你要做的是“审查代码并补充单元测试”你得把两段提示词拼在一起还要处理它们之间的冲突和优先级。提示词一多组合爆炸维护成本急剧上升。第三个死穴是不可发现。你团队里有个同事写了一个特别好用的“数据分析报告生成”提示词但你不知道它存在。没有统一的注册和发现机制好的提示词只能靠口口相传。Agent-Skills针对这三个问题分别给出了答案用文件持久化解决复用用模块化设计解决组合用元数据描述解决发现。2.2 Skill和普通提示词的本质区别很多人第一次看到Skill文件会觉得“这不就是Markdown格式的提示词吗”。表面上看确实像但核心区别在于加载时机和触发方式。普通提示词是你主动粘贴给AI的AI被动接收。Skill是AI根据当前任务上下文主动判断“我需要加载这个Skill”然后去读取对应的文件内容。这个区别听起来小实际影响很大。举个例子。你有一个“生成API文档”的Skill里面规定了文档的格式模板、字段说明、示例代码风格。当你对AI说“帮我给这个接口写个文档”时AI会自动识别出这属于API文档生成任务然后加载对应的Skill文件按照里面定义的规范来输出。你不需要说“请按照以下规范生成文档”也不需要粘贴任何模板。这背后依赖的是Skill的元数据描述。每个Skill文件开头都有一段结构化的描述信息告诉AI“我是干什么的、什么时候该用我”。AI在规划任务时会先扫描所有可用Skill的描述匹配当前任务需求再决定加载哪个。2.3 一个生活化的类比你可以把Agent-Skills想象成一家餐厅的标准化菜谱系统。没有Skill的时候厨师AI每次做菜都要问老板你“今天这个红烧肉要放多少糖火候多大炖多久”老板每次都要重新说一遍。老板累厨师也累而且每次说的可能还不一样导致菜品质量不稳定。有了Skill之后老板把每道菜的配方写成标准菜谱Skill文件放在厨房的架子上。厨师接到订单任务后自己去看该用哪本菜谱按照菜谱上的步骤操作。老板不需要每次都在旁边盯着厨师也不会因为记性不好而翻车。更妙的是菜谱可以组合。比如“红烧肉”菜谱里可以引用“基础炒糖色”菜谱厨师做红烧肉的时候自动就会去查炒糖色的步骤。这就是Skill的组合能力。3. SKILL.md文件里到底该写什么3.1 元数据区让AI知道“什么时候该用我”SKILL.md文件通常分为两大部分元数据区和正文区。元数据区是给AI做匹配用的正文区是给AI做执行用的。元数据区一般包含这几个字段字段名作用写法建议nameSkill的唯一标识用英文短横线连接如api-doc-generatordescription一句话说明用途写清楚“做什么”和“什么时候用”不要写“这是一个很好的工具”这种废话trigger触发条件描述列出典型用户输入场景如“用户要求生成接口文档时”version版本号方便迭代管理如1.0.0author作者团队协作时方便追溯这里最关键的是description和trigger。很多人写这两个字段时太随意导致AI匹配不准。我的经验是description要写成“能力声明”trigger要写成“场景枚举”。举个例子一个“代码审查”Skill的元数据name: code-review description: 对指定代码进行规范性审查检查命名、注释、边界条件、异常处理等维度输出结构化审查报告 trigger: 当用户要求审查代码、检查代码质量、review代码、找代码问题时 version: 1.2.0注意trigger里列了多种用户可能的表达方式。因为不同人说话习惯不一样有人会说“帮我看看这段代码”有人会说“review一下”有人会说“检查代码质量”。把这些都列进去AI匹配的命中率会高很多。3.2 正文区把“工作方式”拆成可执行的步骤正文区是Skill的核心它决定了AI实际执行任务时的行为。我见过很多人把正文写成一大段散文AI读起来费劲执行起来也容易跑偏。正确的做法是结构化、步骤化、可验证。一个高质量的Skill正文通常包含这几个部分角色定义AI在这个Skill中扮演什么角色具备什么专业背景输入要求需要用户提供什么信息格式是什么执行步骤按顺序列出每一步做什么每步的产出是什么输出格式最终结果的结构、字段、示例约束条件什么不能做什么必须做异常处理遇到信息缺失、格式错误时怎么办我拿一个实际用过的“周报生成”Skill来举例。这个Skill帮我每周五自动把本周的工作记录整理成周报省了我至少二十分钟。## 角色 你是一位擅长信息整理和结构化表达的职场助理。 ## 输入 用户提供本周的工作记录可能是零散的文本、列表或聊天记录截图转文字。 ## 执行步骤 1. 提取所有工作项按项目维度归类 2. 每个工作项标注状态已完成 / 进行中 / 受阻 3. 识别本周关键产出放在周报开头 4. 识别下周计划放在周报末尾 5. 对受阻项补充原因和需要的支持 ## 输出格式 ### 本周关键产出 - [产出1] - [产出2] ### 项目进展 | 项目 | 工作项 | 状态 | 备注 | |------|--------|------|------| | ... | ... | ... | ... | ### 下周计划 - [计划1] - [计划2] ### 需要支持 - [事项1]这个Skill写完之后我每周只需要把零散记录丢给AI说一句“生成周报”它就会按照这个格式输出。我不需要每次说“帮我按项目归类”“标注状态”“把关键产出放前面”。这些“工作方式”已经被固化在Skill里了。3.3 写Skill时最容易犯的三个错误第一个错误是把Skill写成教程。有些人写Skill时会写“首先你需要了解什么是API文档API文档是一种……”。这些背景知识AI本来就知道不需要你教。Skill应该写的是“在这个特定场景下我希望你怎么做”而不是“这个领域的基础知识是什么”。第二个错误是步骤太粗。比如写“分析代码并给出建议”这等于没写。AI不知道分析哪些维度、建议以什么形式给出、优先级怎么排。好的步骤应该是“检查变量命名是否符合驼峰规范”“检查每个函数是否有入参校验”“按严重程度分级列出问题”。第三个错误是没有输出示例。AI对格式的理解和你对格式的理解可能有偏差。与其用文字描述“输出一个表格”不如直接给一个表格示例。示例是最精确的格式说明。4. 从零手搓一个Skill的完整流程4.1 先别急着写文件想清楚这三件事很多人一上来就开始敲SKILL.md结果写到一半发现逻辑不顺又推翻重来。我的习惯是先在纸上回答三个问题第一这个Skill的边界是什么它只做一件事还是做一类事我建议一个Skill只解决一个明确的任务。比如“生成API文档”是一个Skill“生成API文档并部署到内网”就是两个Skill。边界越清晰AI匹配越准复用性也越强。第二这个Skill的输入是什么用户会提供什么信息是代码片段、文件路径、还是自然语言描述输入格式是否固定如果输入不稳定Skill里就要写清楚“如果用户没有提供X则询问用户”。第三这个Skill的输出是什么是纯文本、Markdown表格、JSON、还是代码文件输出给谁看给人看还是给另一个AI看这些决定了输出格式的设计。把这三个问题想清楚写SKILL.md就是水到渠成的事。4.2 用skill-creator辅助生成初稿如果你用的是支持Skill机制的AI平台通常会提供一个叫skill-creator的元Skill。它的作用是你告诉它你想创建一个什么Skill它帮你生成SKILL.md的初稿。我实测下来skill-creator生成的初稿大概能到70分水平。元数据区基本没问题正文区的步骤也还算合理但输出格式和异常处理往往不够细致。我的做法是用skill-creator生成初稿然后自己手动补充输出示例和边界情况。具体操作流程对AI说“用skill-creator帮我创建一个Skill功能是XXX”AI会问你一些澄清问题比如“输入是什么”“输出格式有要求吗”回答完之后AI生成SKILL.md初稿你把初稿复制出来手动修改补充输出示例、细化步骤、增加异常处理把修改后的文件放到Skill目录下测试匹配和执行效果这里有个小技巧在让skill-creator生成初稿之前先把你现有的提示词或工作流程整理成文字。哪怕是一段粗糙的描述也比让AI凭空想象要好。AI擅长结构化但不擅长读心。4.3 目录结构与文件放置不同平台的Skill目录结构略有差异但大体逻辑是一样的。通常是在项目根目录或用户配置目录下建一个skills文件夹每个Skill一个子文件夹文件夹名就是Skill的name。skills/ ├── code-review/ │ └── SKILL.md ├── weekly-report/ │ └── SKILL.md ├── api-doc-generator/ │ ├── SKILL.md │ └── templates/ │ └── api-doc-template.md └──>## 更新日志 - 1.2.0: 增加异常处理步骤优化输出格式 - 1.1.0: 补充触发词修复表格列数不一致问题 - 1.0.0: 初始版本团队协作时Skill文件应该放在版本控制系统里如Git每个人都可以提交新的Skill或修改现有Skill。但要注意修改别人的Skill之前先沟通。因为Skill是“工作方式”的固化你改了输出格式可能影响所有依赖这个Skill的人。6. 那些让我踩过坑的细节6.1 Skill加载失败最常见的原因排查Skill加载失败是新手最常遇到的问题。我总结了一个排查顺序排查项检查内容常见问题文件路径SKILL.md是否在正确的目录下放错了文件夹层级文件命名文件名是否严格为SKILL.md写成了skill.md或Skill.md元数据格式YAML语法是否正确冒号后面没空格、缩进错误name一致性name字段和文件夹名是否一致不一致导致匹配失败编码格式文件是否为UTF-8中文乱码导致解析失败其中最容易忽略的是YAML语法。YAML对缩进和空格非常敏感一个多余的空格就可能导致解析失败。我的建议是写完元数据后用YAML校验工具检查一遍。6.2 输出格式漂移为什么AI不按我写的格式来输出格式漂移是另一个高频问题。你明明在Skill里写了“输出Markdown表格”AI却给你输出了一段散文。原因通常有三个第一示例不够具体。你写“输出表格”AI不知道几列、列名是什么、对齐方式是什么。改成给出一个完整的表格示例问题基本就解决了。第二步骤里有冲突。比如前面写“简洁输出”后面又写“详细列出每个字段”AI不知道该听谁的。检查Skill内部是否有矛盾指令。第三上下文干扰。如果对话历史里有大量其他格式的内容AI可能会被带偏。这种情况下在Skill里加一句“忽略之前的格式严格按照以下格式输出”会有帮助。6.3 触发词太宽泛导致的误匹配触发词写得太宽泛会导致AI在不该用这个Skill的时候也加载它。比如一个“数据分析”Skill触发词里写了“分析”结果用户说“分析一下这段代码的逻辑”AI也去加载数据分析Skill这就跑偏了。解决办法是增加限定词。把“分析”改成“分析数据”“数据趋势分析”“统计报表分析”。限定词越多匹配越精准但也要注意不要过于狭窄导致漏匹配。我的经验法则是触发词覆盖3-5种典型表达即可不要试图穷举所有可能。剩下的靠AI的语义理解能力来兜底。6.4 多个Skill冲突时AI听谁的当多个Skill同时被触发时AI需要决定优先级。这个优先级通常由平台决定但你可以通过Skill设计来影响。一种做法是在Skill的元数据里加priority字段数值越高优先级越高。另一种做法是在Skill正文里写清楚“当与其他Skill冲突时以本Skill为准”。但更好的做法是从设计上避免冲突。每个Skill的职责边界清晰触发条件不重叠自然就不会冲突。如果两个Skill经常同时被触发说明它们可能应该合并成一个Skill或者应该拆得更细。7. 进阶玩法让Skill成为你的第二大脑7.1 把个人偏好写成Skill除了工作流程你的个人偏好也可以写成Skill。比如你写文档时喜欢用短句、喜欢用主动语态、不喜欢用“进行”“相关”这类虚词。把这些偏好写成一个“写作风格”SkillAI在帮你写任何文档时都会自动遵循。## 写作风格规范 - 句子长度不超过40字 - 优先使用主动语态 - 避免使用“进行”“相关”“方面”等虚词 - 技术术语首次出现时附英文原文 - 列表项以动词开头这个Skill一旦写好你所有文档的输出风格都会统一。不需要每次说“帮我写文档注意用短句用主动语态”。7.2 把领域知识封装成Skill如果你在某个垂直领域工作比如法律、医疗、金融可以把领域知识封装成Skill。比如一个“合同审查”Skill里面包含常见风险条款清单、审查要点、输出格式。这种Skill的价值在于把专家的隐性知识显性化。以前只有资深律师知道怎么快速审查合同现在AI加载这个Skill后也能给出接近专家水平的审查意见。7.3 Skill的分享与复用Skill文件本质上是纯文本非常容易分享。你可以把Skill文件发给同事放到团队共享目录或者发布到社区。我见过有人把自己写的“专利检索”Skill分享出来帮助了很多不熟悉专利检索流程的研发人员。分享Skill时建议附上一个简短的说明这个Skill解决什么问题、适合什么场景、有什么注意事项。这样别人拿到之后能快速判断是否适合自己。8. 我个人的一些使用体会用了大半年Agent-Skills之后我最大的感受是它改变了我与AI协作的方式。以前是我适应AI每次都要想“怎么把需求说清楚”现在是AI适应我我把工作方式固化下来AI自动遵循。有几个小技巧是我在实际使用中总结出来的第一从高频任务开始。不要一上来就写十个Skill先挑你每天都要做的、最烦的那件事写一个Skill。用顺了再扩展。第二Skill要短。一个Skill文件控制在200行以内太长了AI读起来费劲执行也容易遗漏。如果内容太多拆成多个Skill。第三定期清理。有些Skill用了一段时间发现不好用或者场景变了不再需要就删掉。Skill目录太臃肿会影响AI的匹配效率。第四别追求完美。第一版Skill能跑通就行后面根据实际使用中的问题慢慢迭代。我现在的几个核心Skill都迭代了五六版每一版都是被实际问题逼出来的改进。最后分享一个我最近在用的组合一个“会议纪要”Skill负责把录音转文字整理成结构化纪要一个“任务提取”Skill负责从纪要里提取待办事项并分配负责人一个“周报生成”Skill负责把本周所有待办汇总成周报。三个Skill串起来每周省了我至少一个小时。这种组合的威力单靠一个提示词是做不到的。