尧图网站建设 
不知道你有没有遇到过这种尴尬提示词写了一整屏结果模型跑两轮就绕晕了好不容易把一段复杂业务流程调通换个人接手根本不知道你当初为什么加某句话。过去两年我一直在折腾Agent相关的落地工作慢慢发现问题并不在提示词本身——真正缺的是一层结构化的“技能封装”机制。这个机制从2024年底开始被越来越多团队统称为Skills技能包。这篇文章我会从实际使用者的角度把Skills这层机制讲透它到底解决了什么问题和Prompt、Function Calling、MCP这些概念怎么区分怎么手写一个能用的Skill以及我在调试和团队落地过程中踩过哪些坑。如果你正在做Agent应用或者正准备把散落各处的提示词、工作流整理成可复用的资产这篇内容值得花十分钟看完。1. Skills是什么它到底解决了什么问题1.1 一句人话解释给Agent递“岗位操作手册”先给一个最直白的理解方式。假设你团队来了个能力很强但没干过你们这行的新人你会怎么带他一般不会把公司所有业务规则一次性倒给他而是按岗位整理手册这位同事负责数据清洗就给他一份“数据清洗操作手册”里面写清楚输入是什么、按什么步骤处理、输出长什么样、有哪些坑要避开。**Skills做的就是这件事只不过对象从新人换成了大模型Agent。**一个Skill就是一个独立的目录里面打包了某个特定任务的完整操作说明——包括任务目标、执行步骤、约束条件、输入输出的示例、以及允许调用的工具清单。Agent不干活的时候它只是躺在仓库里的普通文件夹一旦碰到匹配的任务就会被自动加载并照着这套手册执行。我见过很多团队把这种机制叫做“技能包”或者“技能插件”叫法不同本质是一回事。它和普通提示词最大的区别在于提示词是“一次性对话上下文”而Skill是可复用、可版本管理、可多人协作的独立工件。你可以把一个Skill提交到Git仓库走Code Review像管理代码一样管理业务经验。1.2 从“提示词堆叠”到“技能分层”的演进要理解Skills为什么会出现得先回顾一下我们是怎么一步步走到这里的。最早做Agent应用大家习惯把什么逻辑都塞进system prompt里一个任务写一大段规则。这种方式在任务单一的时候挺好用但任务一多就出问题多个任务的规则混在一起互相干扰模型上下文被无关内容占满响应变慢错误率上升。这就是典型的“提示词堆叠”困境。后来有了Function Calling函数调用模型可以根据用户输入决定要不要调用某个函数、传什么参数。这个机制解决了一部分“工具选择”的问题但函数的粒度控制在开发者手里业务规则仍然散落在代码逻辑里业务人员想调整规则还得找开发改代码。再往后是MCPModel Context Protocol它把Agent和外部工具、数据源的连接方式标准化了。不同系统的API以统一协议接入Agent可以动态发现和调用这些能力。但MCP解决的是“连得上什么”没有解决“这个任务应该怎么做”——数据拿回来了怎么处理、按什么规则判断、输出什么格式仍然没人管。Skills堵上的正是这个口子。它把“怎么做”这层沉淀下来而且和MCP是互补关系MCP负责打通外部资源Skills负责固化内部任务流程。两者配合Agent才真正具备“知道该连什么、也知道该怎么处理”的完整能力。1.3 Skills的典型适用场景根据我自己和身边团队的实践下面几类场景特别适合用Skills来承接高频重复的专有流程。比如每周五的周报、每天早上的数据汇总、每月固定的账单分析。这类任务流程稳定、重复度高写成Skill之后每次直接触发省去反复写提示词的时间。需要严格输出格式的业务。合同审查要输出风险等级、条款原文、修改建议招聘要输出候选人评分卡信贷初审要输出风险项列表。这时候把格式规范写死在Skill里输出稳定度会提高很多。依赖特定领域知识的任务。金融术语解释、医疗报告初步整理、法律条文检索这些任务的知识边界比较清晰可以做成“领域知识型Skill”。多步骤数据处理任务。从一个Excel拿到原始数据清洗、合并、转换格式、生成图表描述串成流水线。这种任务如果用普通对话来做用户每进行一步都要重新解释一遍需求而Skill能一次性把整条流水线的规矩讲清楚。注意如果一个任务你用15行提示词就能稳定搞定其实没必要上Skill。它是为“复杂度到了一定程度、且需要反复使用”的任务准备的过度封装反而增加维护成本。2. Skills和其他方案分得清吗Prompt、Function Calling、MCP2.1 四者横向对比各管哪一段很多刚接触这层概念的人会混淆我建议用一个最简单的模型来理解**Prompt是“一次性口述需求”Function Calling是“规定哪些按钮可以按”MCP是“统一插线板”Skills是“标准作业指导书”。**它们解决的是不同层的问题。方案核心回答的问题粒度典型形态主要局限Prompt这次任务想要什么结果对话级一段文本每次都要重新写无法复用Function Calling这个请求能调哪些函数函数级JSON Schema定义只管参数传递不管业务流程MCP外部工具和数据怎么连服务级协议工具集合管连接不管任务怎么执行Skills这类任务应该怎么做任务级目录说明资源需要额外设计有学习成本分开来看更清楚。Prompt面向“单次对话”你这次想让模型干什么就写什么写完了这次用完就没了下次重新写。Function Calling面向“接口暴露”系统有哪些函数可以被调用每个函数接收什么参数它主要解决的是“怎么把模型意图转换为程序调用”但任务内部的业务判断逻辑不在它的职责范围。MCP面向“资源连接”它把数据库、API、文件系统统一暴露给Agent解决的是“Agent能不能访问到这些数据”的问题但拿到数据之后怎么分析、怎么判断、怎么产出结论MCP不管。Skills的定位是“任务级”的。它既包含了指令也包含了示例、工具约束甚至可以把脚本、模板等资源文件一起打包。这意味着它可以描述一个相对完整的业务流程而不仅仅是单次调用。2.2 Skills和MCP是互补关系不是替代关系我见过不少团队在这个问题上纠结总觉得新概念出来就要取代旧概念。实际用下来Skills和MCP根本不是同一层的东西它们配合起来才完整。我举个实际场景。假设你要做一个“企业财报分析Skill”里面需要联网拉取上市公司的财报数据。这时候两边的分工是这样的MCP层提供一个“财报数据源MCP服务器”它定义好有哪些工具比如get_financial_statements(ticker, year)、search_reports(keyword)底层连真实数据API。MCP解决的是“这些外部数据怎么被Agent访问”。Skills层写一份“财报分析操作手册”规定拿到财报数据后先看哪些指标、怎么计算同比增速、风险信号怎么判断、最终报告按什么模板输出。Skills解决的是“数据到手之后怎么处理和分析”。实际操作中Skill的frontmatter元信息区里可以声明它需要用到哪些MCP工具。Agent加载Skill的时候就知道该连接哪个MCP服务器、允许调用哪些工具。一个管“手”一个管“脑子”分工非常明确。2.3 什么时候不该用Skills配合方案虽然好但Skills不是万能药。我自己总结了几类不适合用Skills的场景供你参考一次性小任务。就是那种你随手写个Prompt就能搞定的事没必要建目录、写说明、做版本管理。一个Task运转的开销和复杂度对简单任务来说是负担。频繁变动的边缘逻辑。如果业务规则一周改三次每次改动都要改Skill、重新验证团队会非常痛苦。这种情况更适合把规则外置到配置文件里让Skill去读配置而不是把规则写死在Skill内部。强实时交互场景。比如用户和Agent来回对话量很大每一步都需要动态决策的任务不太适合用固定流程的Skill来约束否则Agent会被死板流程绑住手脚。判断标准其实很简单如果这个任务写得“为什么要这么做”比“怎么做”更重要那就适合用Skill把它固化下来如果这个任务的核心价值在于临场应变和灵活动态那就更适合用普通对话或轻量提示词来处理。3. 手写一个Skills从目录结构到完整实现3.1 目录结构和文件约定目前主流的Agent Skills规范在目录结构上大同小异我这里以一个比较通用且易扩展的结构来说明。一个Skill本质上是一个目录目录里包含一个核心说明文件以及若干辅助资源。weekly-report-skill/ ├── SKILL.md # 核心说明文件定义这个技能是什么、怎么用 ├── scripts/ # 可选的辅助脚本目录 │ ├── analyze.py # 数据分析脚本 │ └── format.py # 输出格式化脚本 ├── references/ # 参考文档、模板、示例文件 │ ├── template.md # 周报输出模板 │ └── example-input.csv # 示例输入数据 └── assets/ # 资源文件如图片、配置文件其中SKILL.md是灵魂文件Agent加载Skill的机制就是从这个文件开始。它的基本结构分两部分一是开头的YAML frontmatter元信息用---包裹二是正文部分用Markdown书写具体指令。我平时常用这样的frontmatter字段--- name: weekly-report-generator description: 根据本周工作日志生成结构化周报。当用户提供工作内容、项目进度、问题清单时使用。不适用于月报或年度总结。 version: 1.2.0 license: MIT allowed-tools: - ReadFile - RunCommand - WebSearch ---字段含义拆开说name技能的唯一标识要简短、好记单词用连字符连接。description最重要的字段Agent靠它来决定是否触发这个Skill。后面我会专门讲怎么写。version语义化版本号方便追踪变更。license声明开源许可团队内部使用也不能省。allowed-tools明确这个Skill运行时允许调用哪些工具。这是一个安全边界非常关键。3.2 一个完整示例周报生成Skill我拿一个自己实际用过的“周报生成Skill”做完整演示你可以直接照着改来用。首先是目录weekly-report-skill/ ├── SKILL.md └── references/ └── default-template.md然后是SKILL.md的完整内容--- name: weekly-report-generator description: 根据用户提供的一周工作内容生成结构化周报。当用户提到“写周报”“周报生成”“本周工作汇总”或粘贴本周工作日志、待办列表时使用。不适用于生成月报、季度总结或个人简历。 version: 1.2.0 license: MIT allowed-tools: - ReadFile - WriteFile --- # 周报生成技能 ## 目标 把用户输入的零散工作信息整理成一份结构清晰、重点突出、可直接粘贴到公司OA系统的周报。 ## 输入要求 - 用户可能提供工作事项列表、项目进度说明、遇到的问题、明日计划。 - 如果输入信息过于零散或缺少关键部分不要编造先向用户确认缺失项。 ## 执行步骤 1. 阅读用户提供的所有工作内容按项目或工作模块归类。 2. 对每个模块提炼“本周进展”用2-3句话描述避免流水账。 3. 识别当前风险或阻塞问题单列成“问题与风险”部分并给出建议举措。 4. 如果用户提供了下周计划整理到“下周计划”部分如果没有此部分留空不要自动生成。 5. 按照 references/default-template.md 中的模板格式输出最终周报。 ## 输出格式 - 使用Markdown格式。 - 每个模块下用“进展要点”列表呈现每条不超过一行。 - 风险项使用加粗标注突出优先级。 ## 注意事项 - 不确定的信息必须标注“待确认”严禁编造工作成果。 - 中文环境下统一使用简洁的职场书面语不使用口语化表达。 - 不要把过去的周报内容带进来除非用户明确要求参考历史。再配上references/default-template.md# 周报第X周 ## 本周核心进展 - 模块一... - 模块二... ## 问题与风险 - **高风险**... - 待确认... ## 下周计划 - ...这个Skill在真实环境中跑起来我就算只丢给它一句“这周我把用户画像系统重构了一下有几个接口延迟问题在跟”它也能按模板输出一份像样的周报草稿。关键点在于我把“怎么归类、怎么提炼、什么该留空、什么该标注”这些业务规则都写死在Skill里了用的时候不需要每次重新交代。3.3 description怎么写才容易被正确触发Skill的description字段决定了Agent在什么时候会加载这个Skill它的质量直接影响整个技能的准确率。我在初版踩过很多坑最典型的就是把description写成“功能列表”比如“生成周报、汇总数据、提炼要点”结果Agent在用户问“帮我把明天要做的事整理一下”的时候也把周报Skill拉出来了——因为“整理”“汇总”这些词撞上了。正确的写法要包含两部分信息什么时候该用它什么时候不该用它。拿上面周报Skill的description举例根据用户提供的一周工作内容生成结构化周报。当用户提到“写周报”“周报生成”“本周工作汇总”或粘贴本周工作日志、待办列表时使用。不适用于生成月报、季度总结或个人简历。前半句描述核心能力“根据一周工作内容生成结构化周报”中间半句列举触发信号“写周报、周报生成、本周工作汇总”最后半句明确排除项“不适用于月报、季度总结”。这个结构能让Agent的触发判断准很多。我见过更有经验的团队会把“排除条件”写成显式的负例清单。因为负例比正例更稀缺模型判断“这个场景不该用”通常比判断“这个场景该用”更难所以你必须帮它划掉容易混淆的边界场景。实操技巧调试期可以故意准备几个“容易被误触发”的测试场景比如“帮我写年度总结”“帮我整理简历”验证你的Skill会不会被错误加载。如果会说明description的排除条件没写够。3.4 让Skill可被复用参数化与工具授权大部分早期的Skill只是把一段提示词搬了个家这种使用方式浪费了这套机制。真正让Skill具备复用价值的是参数化和工具授权。参数化的意思是让Skill内部的具体规则尽量通过参数或外部配置来调整而不是写死在正文里。比如周报Skill的模板文件就是参数化的一种体现——想换模板就改references下的文件不用动SKILL.md正文。更复杂的Skill还可以在frontmatter里声明输入参数比如分析类Skill可以声明target_year、data_source等参数调用时动态传入。工具授权指的是allowed-tools字段。这里要专门提醒一下**不要图省事给Skill全工具权限。**我见过有人把所有Skill的allowed-tools都写成“允许所有工具”结果一个本应只读文件的分析Skill去调用了服务器上的写操作命令造成线上数据异常。工具授权的本质是给Skill划定最小可用权限就像你不会让一个财务实习生直接访问生产数据库一样。实际设置时可以参照最小权限原则这个Skill的流程中必须用哪些工具就列哪些。比如“周报生成”只需要读文件、写文件就只列ReadFile和WriteFile不需要网络搜索、代码执行就不列。Agent会严格按照清单来这既是功能边界也是安全边界。4. 调试、评估与实测避坑4.1 一个Skill跑偏时先查哪三层Skill写出来不是就完事了我自己的经验是没有几个版本调试是跑不通的。但调试过几轮之后我总结出一个固定的排查顺序效率很高。第一层加载层有没有被正确触发。如果Skill压根儿没被加载后面说什么都是白搭。排查方法是看运行日志里有没有加载记录或者直接问Agent“你现在有没有在使用什么技能”。如果没触发一般就是description写得不够清晰要么正例触发词没覆盖要么负例没排除掉。第二层指令层内部指令是否互相矛盾。Skill触发了但行为不对这时候把注意力放到SKILL.md正文的指令文本上。最常见的问题是“执行步骤”和“注意事项”互相冲突。比如一处写着“所有数据都要清洗”另一处写着“保留原始值”模型两头为难行为就会飘。出现这种情况时需要重新梳理指令逻辑把唯一性表述确定下来。第三层执行层工具返回是否意外。指令没问题但实际结果不对那大概率是工具返回的数据和Skill预期的格式不一致。比如Skill假设数据是CSV格式实际API返回的是JSON或者某个字段叫amountSkill里却按price去读取。这类问题一般通过增加数据格式校验逻辑来解决。三条排查顺序不要乱。很多人一上来就改指令结果改了半天根本没触发白忙活。4.2 常见问题速查表下面这张表是我和团队在实际使用中整理出来的高频问题和对应解法建议直接截图保存。问题现象根本原因排查方法解决办法Skill从未被触发description触发信号写得不够清楚检查日志中是否有加载记录重写description加正例触发词、加排除条件Skill在错误场景被触发负例边界没写清楚测试易混淆场景如“写月报”误触发“周报Skill”在description中补充排除场景输出格式不符合预期模板引用路径不对或模板内部结构混乱检查references目录文件内容收敛模板明确占位符作用结果时对时不对指令中存在模糊表述对比好/坏输出定位模糊指令把模糊表述改为“必须/禁止”级确定性规则工具调用被拒allowed-tools没包含所需工具查看工具调用报错信息在frontmatter中显式加入所需工具多个Skill互相干扰多个Skill的description边界重叠检查每个Skill的description重叠部分收敛description边界避免关键词重叠改造后行为回退没有回归测试跑一遍历史测试用例建立最小测试集每次改动后回归4.3 我的验证方法一套最小测试集Skill也是代码凡是代码就要有回归测试意识。这里分享一个很轻量、不用引入测试框架的验证方法给每个Skill建一个测试清单文件。我会在每个Skill目录下放一个tests.md里面写5条左右的测试用例覆盖正常场景、边界场景和误触发场景。举周报Skill的例子# 测试集v1.2.0 ## 用例1正常输入 输入“这周完成了用户画像系统重构周末发现延迟接口还有两个没解决下周打算继续优化。” 预期输出包含“本周核心进展”“问题与风险”“下周计划”三部分且“问题与风险”中标注了延迟接口问题。 ## 用例2信息不全 输入“这周挺忙的。” 预期不生成完整周报而是向用户追问具体工作内容。 ## 用例3误触发测试 输入“帮我写一份本月度经营分析报告。” 预期不触发周报Skill。每次改完Skill就先跑一遍tests.md里的用例把输出记录下来。如果某个用例的行为变了就说明你的改动影响到了已有逻辑。这套方法我用了很久虽然没有自动化那么好用但胜在零成本、随时可跑对个人开发者特别友好。好输入配上好输出还可以顺手统计一个“触发准确率”——测试集里正确触发的用例数除以总用例数。我自己的目标是每个Skill至少要有80%的触发准确率才敢放进正式库里。4.4 我在实际调试中踩过的坑写Skill这一年多踩过的坑比成功经验多得多挑几个特别典型的讲坑一试图做一个“万能Skill”。刚开始我图省事想做一个“数据分析大包”把所有数据分析相关的处理逻辑都塞进去。结果这个Skill又长又臃肿每次加载消耗大量上下文还经常因为指令矛盾输出奇怪的结果。后来把它拆成了“数据清洗”“统计汇总”“图表描述”三个独立Skill每个都又轻又准。单个Skill的定位要足够窄窄到一句话能说清边界。坑二示例数据太特化导致过拟合。有一次我写了一个客服工单分类Skill示例里给的都是“退款纠纷”“物流延误”这类电商场景文本结果一上线遇到一条“APP崩溃”的工单分类结果完全跑偏。后来我把示例数据改成覆盖六类场景每类2-3条模型才学会了抽象规律而不是死记示例。示例的本质是教模型“この類型的输入长这样”所以要广覆盖而不是只给一个“完美样板”。坑三加载时输出大段“我的技能说明”。早期版本我在SKILL.md末尾写了很长一段关于这个技能背景的废话结果模型加载后会在回答前复述一遍这段背景。浪费token不说用户体验也差。后来我把所有指令都改成“务实型”只保留“做什么、怎么做、边界在哪”三类内容。SKILL.md里的每个字都是要烧token的要以信息密度为准写。坑四工具权限开太宽松。说过一次就不再展开只提醒一句agent的工具权限是安全底线宁可在调试阶段多试几次不够权限的报错也不要一次性放开全部工具然后把线上数据搞坏。5. 再往前一步如何把Skills纳入团队协作5.1 团队共享与评审机制Skill如果只有你一个人用那它只是一个顺手的工具但如果想要整个团队共用就得把它当“代码资产”来管。我们团队现在对Skill采用和代码一样的协作流程统一仓库所有Skill放在一个专门的Git仓库里按业务域分子目录。常用前缀名如hr-、finance-、> Agent Skills技能包：从提示词堆叠到结构化封装的工程实践
不知道你有没有遇到过这种尴尬提示词写了一整屏结果模型跑两轮就绕晕了好不容易把一段复杂业务流程调通换个人接手根本不知道你当初为什么加某句话。过去两年我一直在折腾Agent相关的落地工作慢慢发现问题并不在提示词本身——真正缺的是一层结构化的“技能封装”机制。这个机制从2024年底开始被越来越多团队统称为Skills技能包。这篇文章我会从实际使用者的角度把Skills这层机制讲透它到底解决了什么问题和Prompt、Function Calling、MCP这些概念怎么区分怎么手写一个能用的Skill以及我在调试和团队落地过程中踩过哪些坑。如果你正在做Agent应用或者正准备把散落各处的提示词、工作流整理成可复用的资产这篇内容值得花十分钟看完。1. Skills是什么它到底解决了什么问题1.1 一句人话解释给Agent递“岗位操作手册”先给一个最直白的理解方式。假设你团队来了个能力很强但没干过你们这行的新人你会怎么带他一般不会把公司所有业务规则一次性倒给他而是按岗位整理手册这位同事负责数据清洗就给他一份“数据清洗操作手册”里面写清楚输入是什么、按什么步骤处理、输出长什么样、有哪些坑要避开。**Skills做的就是这件事只不过对象从新人换成了大模型Agent。**一个Skill就是一个独立的目录里面打包了某个特定任务的完整操作说明——包括任务目标、执行步骤、约束条件、输入输出的示例、以及允许调用的工具清单。Agent不干活的时候它只是躺在仓库里的普通文件夹一旦碰到匹配的任务就会被自动加载并照着这套手册执行。我见过很多团队把这种机制叫做“技能包”或者“技能插件”叫法不同本质是一回事。它和普通提示词最大的区别在于提示词是“一次性对话上下文”而Skill是可复用、可版本管理、可多人协作的独立工件。你可以把一个Skill提交到Git仓库走Code Review像管理代码一样管理业务经验。1.2 从“提示词堆叠”到“技能分层”的演进要理解Skills为什么会出现得先回顾一下我们是怎么一步步走到这里的。最早做Agent应用大家习惯把什么逻辑都塞进system prompt里一个任务写一大段规则。这种方式在任务单一的时候挺好用但任务一多就出问题多个任务的规则混在一起互相干扰模型上下文被无关内容占满响应变慢错误率上升。这就是典型的“提示词堆叠”困境。后来有了Function Calling函数调用模型可以根据用户输入决定要不要调用某个函数、传什么参数。这个机制解决了一部分“工具选择”的问题但函数的粒度控制在开发者手里业务规则仍然散落在代码逻辑里业务人员想调整规则还得找开发改代码。再往后是MCPModel Context Protocol它把Agent和外部工具、数据源的连接方式标准化了。不同系统的API以统一协议接入Agent可以动态发现和调用这些能力。但MCP解决的是“连得上什么”没有解决“这个任务应该怎么做”——数据拿回来了怎么处理、按什么规则判断、输出什么格式仍然没人管。Skills堵上的正是这个口子。它把“怎么做”这层沉淀下来而且和MCP是互补关系MCP负责打通外部资源Skills负责固化内部任务流程。两者配合Agent才真正具备“知道该连什么、也知道该怎么处理”的完整能力。1.3 Skills的典型适用场景根据我自己和身边团队的实践下面几类场景特别适合用Skills来承接高频重复的专有流程。比如每周五的周报、每天早上的数据汇总、每月固定的账单分析。这类任务流程稳定、重复度高写成Skill之后每次直接触发省去反复写提示词的时间。需要严格输出格式的业务。合同审查要输出风险等级、条款原文、修改建议招聘要输出候选人评分卡信贷初审要输出风险项列表。这时候把格式规范写死在Skill里输出稳定度会提高很多。依赖特定领域知识的任务。金融术语解释、医疗报告初步整理、法律条文检索这些任务的知识边界比较清晰可以做成“领域知识型Skill”。多步骤数据处理任务。从一个Excel拿到原始数据清洗、合并、转换格式、生成图表描述串成流水线。这种任务如果用普通对话来做用户每进行一步都要重新解释一遍需求而Skill能一次性把整条流水线的规矩讲清楚。注意如果一个任务你用15行提示词就能稳定搞定其实没必要上Skill。它是为“复杂度到了一定程度、且需要反复使用”的任务准备的过度封装反而增加维护成本。2. Skills和其他方案分得清吗Prompt、Function Calling、MCP2.1 四者横向对比各管哪一段很多刚接触这层概念的人会混淆我建议用一个最简单的模型来理解**Prompt是“一次性口述需求”Function Calling是“规定哪些按钮可以按”MCP是“统一插线板”Skills是“标准作业指导书”。**它们解决的是不同层的问题。方案核心回答的问题粒度典型形态主要局限Prompt这次任务想要什么结果对话级一段文本每次都要重新写无法复用Function Calling这个请求能调哪些函数函数级JSON Schema定义只管参数传递不管业务流程MCP外部工具和数据怎么连服务级协议工具集合管连接不管任务怎么执行Skills这类任务应该怎么做任务级目录说明资源需要额外设计有学习成本分开来看更清楚。Prompt面向“单次对话”你这次想让模型干什么就写什么写完了这次用完就没了下次重新写。Function Calling面向“接口暴露”系统有哪些函数可以被调用每个函数接收什么参数它主要解决的是“怎么把模型意图转换为程序调用”但任务内部的业务判断逻辑不在它的职责范围。MCP面向“资源连接”它把数据库、API、文件系统统一暴露给Agent解决的是“Agent能不能访问到这些数据”的问题但拿到数据之后怎么分析、怎么判断、怎么产出结论MCP不管。Skills的定位是“任务级”的。它既包含了指令也包含了示例、工具约束甚至可以把脚本、模板等资源文件一起打包。这意味着它可以描述一个相对完整的业务流程而不仅仅是单次调用。2.2 Skills和MCP是互补关系不是替代关系我见过不少团队在这个问题上纠结总觉得新概念出来就要取代旧概念。实际用下来Skills和MCP根本不是同一层的东西它们配合起来才完整。我举个实际场景。假设你要做一个“企业财报分析Skill”里面需要联网拉取上市公司的财报数据。这时候两边的分工是这样的MCP层提供一个“财报数据源MCP服务器”它定义好有哪些工具比如get_financial_statements(ticker, year)、search_reports(keyword)底层连真实数据API。MCP解决的是“这些外部数据怎么被Agent访问”。Skills层写一份“财报分析操作手册”规定拿到财报数据后先看哪些指标、怎么计算同比增速、风险信号怎么判断、最终报告按什么模板输出。Skills解决的是“数据到手之后怎么处理和分析”。实际操作中Skill的frontmatter元信息区里可以声明它需要用到哪些MCP工具。Agent加载Skill的时候就知道该连接哪个MCP服务器、允许调用哪些工具。一个管“手”一个管“脑子”分工非常明确。2.3 什么时候不该用Skills配合方案虽然好但Skills不是万能药。我自己总结了几类不适合用Skills的场景供你参考一次性小任务。就是那种你随手写个Prompt就能搞定的事没必要建目录、写说明、做版本管理。一个Task运转的开销和复杂度对简单任务来说是负担。频繁变动的边缘逻辑。如果业务规则一周改三次每次改动都要改Skill、重新验证团队会非常痛苦。这种情况更适合把规则外置到配置文件里让Skill去读配置而不是把规则写死在Skill内部。强实时交互场景。比如用户和Agent来回对话量很大每一步都需要动态决策的任务不太适合用固定流程的Skill来约束否则Agent会被死板流程绑住手脚。判断标准其实很简单如果这个任务写得“为什么要这么做”比“怎么做”更重要那就适合用Skill把它固化下来如果这个任务的核心价值在于临场应变和灵活动态那就更适合用普通对话或轻量提示词来处理。3. 手写一个Skills从目录结构到完整实现3.1 目录结构和文件约定目前主流的Agent Skills规范在目录结构上大同小异我这里以一个比较通用且易扩展的结构来说明。一个Skill本质上是一个目录目录里包含一个核心说明文件以及若干辅助资源。weekly-report-skill/ ├── SKILL.md # 核心说明文件定义这个技能是什么、怎么用 ├── scripts/ # 可选的辅助脚本目录 │ ├── analyze.py # 数据分析脚本 │ └── format.py # 输出格式化脚本 ├── references/ # 参考文档、模板、示例文件 │ ├── template.md # 周报输出模板 │ └── example-input.csv # 示例输入数据 └── assets/ # 资源文件如图片、配置文件其中SKILL.md是灵魂文件Agent加载Skill的机制就是从这个文件开始。它的基本结构分两部分一是开头的YAML frontmatter元信息用---包裹二是正文部分用Markdown书写具体指令。我平时常用这样的frontmatter字段--- name: weekly-report-generator description: 根据本周工作日志生成结构化周报。当用户提供工作内容、项目进度、问题清单时使用。不适用于月报或年度总结。 version: 1.2.0 license: MIT allowed-tools: - ReadFile - RunCommand - WebSearch ---字段含义拆开说name技能的唯一标识要简短、好记单词用连字符连接。description最重要的字段Agent靠它来决定是否触发这个Skill。后面我会专门讲怎么写。version语义化版本号方便追踪变更。license声明开源许可团队内部使用也不能省。allowed-tools明确这个Skill运行时允许调用哪些工具。这是一个安全边界非常关键。3.2 一个完整示例周报生成Skill我拿一个自己实际用过的“周报生成Skill”做完整演示你可以直接照着改来用。首先是目录weekly-report-skill/ ├── SKILL.md └── references/ └── default-template.md然后是SKILL.md的完整内容--- name: weekly-report-generator description: 根据用户提供的一周工作内容生成结构化周报。当用户提到“写周报”“周报生成”“本周工作汇总”或粘贴本周工作日志、待办列表时使用。不适用于生成月报、季度总结或个人简历。 version: 1.2.0 license: MIT allowed-tools: - ReadFile - WriteFile --- # 周报生成技能 ## 目标 把用户输入的零散工作信息整理成一份结构清晰、重点突出、可直接粘贴到公司OA系统的周报。 ## 输入要求 - 用户可能提供工作事项列表、项目进度说明、遇到的问题、明日计划。 - 如果输入信息过于零散或缺少关键部分不要编造先向用户确认缺失项。 ## 执行步骤 1. 阅读用户提供的所有工作内容按项目或工作模块归类。 2. 对每个模块提炼“本周进展”用2-3句话描述避免流水账。 3. 识别当前风险或阻塞问题单列成“问题与风险”部分并给出建议举措。 4. 如果用户提供了下周计划整理到“下周计划”部分如果没有此部分留空不要自动生成。 5. 按照 references/default-template.md 中的模板格式输出最终周报。 ## 输出格式 - 使用Markdown格式。 - 每个模块下用“进展要点”列表呈现每条不超过一行。 - 风险项使用加粗标注突出优先级。 ## 注意事项 - 不确定的信息必须标注“待确认”严禁编造工作成果。 - 中文环境下统一使用简洁的职场书面语不使用口语化表达。 - 不要把过去的周报内容带进来除非用户明确要求参考历史。再配上references/default-template.md# 周报第X周 ## 本周核心进展 - 模块一... - 模块二... ## 问题与风险 - **高风险**... - 待确认... ## 下周计划 - ...这个Skill在真实环境中跑起来我就算只丢给它一句“这周我把用户画像系统重构了一下有几个接口延迟问题在跟”它也能按模板输出一份像样的周报草稿。关键点在于我把“怎么归类、怎么提炼、什么该留空、什么该标注”这些业务规则都写死在Skill里了用的时候不需要每次重新交代。3.3 description怎么写才容易被正确触发Skill的description字段决定了Agent在什么时候会加载这个Skill它的质量直接影响整个技能的准确率。我在初版踩过很多坑最典型的就是把description写成“功能列表”比如“生成周报、汇总数据、提炼要点”结果Agent在用户问“帮我把明天要做的事整理一下”的时候也把周报Skill拉出来了——因为“整理”“汇总”这些词撞上了。正确的写法要包含两部分信息什么时候该用它什么时候不该用它。拿上面周报Skill的description举例根据用户提供的一周工作内容生成结构化周报。当用户提到“写周报”“周报生成”“本周工作汇总”或粘贴本周工作日志、待办列表时使用。不适用于生成月报、季度总结或个人简历。前半句描述核心能力“根据一周工作内容生成结构化周报”中间半句列举触发信号“写周报、周报生成、本周工作汇总”最后半句明确排除项“不适用于月报、季度总结”。这个结构能让Agent的触发判断准很多。我见过更有经验的团队会把“排除条件”写成显式的负例清单。因为负例比正例更稀缺模型判断“这个场景不该用”通常比判断“这个场景该用”更难所以你必须帮它划掉容易混淆的边界场景。实操技巧调试期可以故意准备几个“容易被误触发”的测试场景比如“帮我写年度总结”“帮我整理简历”验证你的Skill会不会被错误加载。如果会说明description的排除条件没写够。3.4 让Skill可被复用参数化与工具授权大部分早期的Skill只是把一段提示词搬了个家这种使用方式浪费了这套机制。真正让Skill具备复用价值的是参数化和工具授权。参数化的意思是让Skill内部的具体规则尽量通过参数或外部配置来调整而不是写死在正文里。比如周报Skill的模板文件就是参数化的一种体现——想换模板就改references下的文件不用动SKILL.md正文。更复杂的Skill还可以在frontmatter里声明输入参数比如分析类Skill可以声明target_year、data_source等参数调用时动态传入。工具授权指的是allowed-tools字段。这里要专门提醒一下**不要图省事给Skill全工具权限。**我见过有人把所有Skill的allowed-tools都写成“允许所有工具”结果一个本应只读文件的分析Skill去调用了服务器上的写操作命令造成线上数据异常。工具授权的本质是给Skill划定最小可用权限就像你不会让一个财务实习生直接访问生产数据库一样。实际设置时可以参照最小权限原则这个Skill的流程中必须用哪些工具就列哪些。比如“周报生成”只需要读文件、写文件就只列ReadFile和WriteFile不需要网络搜索、代码执行就不列。Agent会严格按照清单来这既是功能边界也是安全边界。4. 调试、评估与实测避坑4.1 一个Skill跑偏时先查哪三层Skill写出来不是就完事了我自己的经验是没有几个版本调试是跑不通的。但调试过几轮之后我总结出一个固定的排查顺序效率很高。第一层加载层有没有被正确触发。如果Skill压根儿没被加载后面说什么都是白搭。排查方法是看运行日志里有没有加载记录或者直接问Agent“你现在有没有在使用什么技能”。如果没触发一般就是description写得不够清晰要么正例触发词没覆盖要么负例没排除掉。第二层指令层内部指令是否互相矛盾。Skill触发了但行为不对这时候把注意力放到SKILL.md正文的指令文本上。最常见的问题是“执行步骤”和“注意事项”互相冲突。比如一处写着“所有数据都要清洗”另一处写着“保留原始值”模型两头为难行为就会飘。出现这种情况时需要重新梳理指令逻辑把唯一性表述确定下来。第三层执行层工具返回是否意外。指令没问题但实际结果不对那大概率是工具返回的数据和Skill预期的格式不一致。比如Skill假设数据是CSV格式实际API返回的是JSON或者某个字段叫amountSkill里却按price去读取。这类问题一般通过增加数据格式校验逻辑来解决。三条排查顺序不要乱。很多人一上来就改指令结果改了半天根本没触发白忙活。4.2 常见问题速查表下面这张表是我和团队在实际使用中整理出来的高频问题和对应解法建议直接截图保存。问题现象根本原因排查方法解决办法Skill从未被触发description触发信号写得不够清楚检查日志中是否有加载记录重写description加正例触发词、加排除条件Skill在错误场景被触发负例边界没写清楚测试易混淆场景如“写月报”误触发“周报Skill”在description中补充排除场景输出格式不符合预期模板引用路径不对或模板内部结构混乱检查references目录文件内容收敛模板明确占位符作用结果时对时不对指令中存在模糊表述对比好/坏输出定位模糊指令把模糊表述改为“必须/禁止”级确定性规则工具调用被拒allowed-tools没包含所需工具查看工具调用报错信息在frontmatter中显式加入所需工具多个Skill互相干扰多个Skill的description边界重叠检查每个Skill的description重叠部分收敛description边界避免关键词重叠改造后行为回退没有回归测试跑一遍历史测试用例建立最小测试集每次改动后回归4.3 我的验证方法一套最小测试集Skill也是代码凡是代码就要有回归测试意识。这里分享一个很轻量、不用引入测试框架的验证方法给每个Skill建一个测试清单文件。我会在每个Skill目录下放一个tests.md里面写5条左右的测试用例覆盖正常场景、边界场景和误触发场景。举周报Skill的例子# 测试集v1.2.0 ## 用例1正常输入 输入“这周完成了用户画像系统重构周末发现延迟接口还有两个没解决下周打算继续优化。” 预期输出包含“本周核心进展”“问题与风险”“下周计划”三部分且“问题与风险”中标注了延迟接口问题。 ## 用例2信息不全 输入“这周挺忙的。” 预期不生成完整周报而是向用户追问具体工作内容。 ## 用例3误触发测试 输入“帮我写一份本月度经营分析报告。” 预期不触发周报Skill。每次改完Skill就先跑一遍tests.md里的用例把输出记录下来。如果某个用例的行为变了就说明你的改动影响到了已有逻辑。这套方法我用了很久虽然没有自动化那么好用但胜在零成本、随时可跑对个人开发者特别友好。好输入配上好输出还可以顺手统计一个“触发准确率”——测试集里正确触发的用例数除以总用例数。我自己的目标是每个Skill至少要有80%的触发准确率才敢放进正式库里。4.4 我在实际调试中踩过的坑写Skill这一年多踩过的坑比成功经验多得多挑几个特别典型的讲坑一试图做一个“万能Skill”。刚开始我图省事想做一个“数据分析大包”把所有数据分析相关的处理逻辑都塞进去。结果这个Skill又长又臃肿每次加载消耗大量上下文还经常因为指令矛盾输出奇怪的结果。后来把它拆成了“数据清洗”“统计汇总”“图表描述”三个独立Skill每个都又轻又准。单个Skill的定位要足够窄窄到一句话能说清边界。坑二示例数据太特化导致过拟合。有一次我写了一个客服工单分类Skill示例里给的都是“退款纠纷”“物流延误”这类电商场景文本结果一上线遇到一条“APP崩溃”的工单分类结果完全跑偏。后来我把示例数据改成覆盖六类场景每类2-3条模型才学会了抽象规律而不是死记示例。示例的本质是教模型“この類型的输入长这样”所以要广覆盖而不是只给一个“完美样板”。坑三加载时输出大段“我的技能说明”。早期版本我在SKILL.md末尾写了很长一段关于这个技能背景的废话结果模型加载后会在回答前复述一遍这段背景。浪费token不说用户体验也差。后来我把所有指令都改成“务实型”只保留“做什么、怎么做、边界在哪”三类内容。SKILL.md里的每个字都是要烧token的要以信息密度为准写。坑四工具权限开太宽松。说过一次就不再展开只提醒一句agent的工具权限是安全底线宁可在调试阶段多试几次不够权限的报错也不要一次性放开全部工具然后把线上数据搞坏。5. 再往前一步如何把Skills纳入团队协作5.1 团队共享与评审机制Skill如果只有你一个人用那它只是一个顺手的工具但如果想要整个团队共用就得把它当“代码资产”来管。我们团队现在对Skill采用和代码一样的协作流程统一仓库所有Skill放在一个专门的Git仓库里按业务域分子目录。常用前缀名如hr-、finance-、>