1. 先搞清楚agent-skills到底在解决什么问题这两年做大模型应用的人应该都有同感Agent框架越来越成熟但真正把Agent用好的团队少之又少。模型幻觉、工具调用不稳定、多步任务中断这些都是表面现象根子往往出在一个很朴素的问题上——你根本没有给Agent一套足够清晰、足够可复用的“干活手册”。我最早接触到agent-skills这个概念是在做内部自动化助手的时候。当时的痛点很典型同一个团队里有人用Cline做代码审查有人用Claude写测试用例还有人写Python脚本整理报表。表面上大家的工具链不一样实际做的事情却有大量重叠。但问题是每个Agent的指令写法和技能调用方式都不一样换个场景就要重新调试提示词换个人维护就完全看不懂之前的配置时间全耗在这上面了。agent-skills不是某个单一框架的专有名词它更像是一套给AI智能体预置“技能包”的方法论。每个技能包通常包含一份结构化的技能说明SKILL.md、一个或多个可执行的脚本/工具、以及必要的配置和资源文件。Agent在运行时会先扫描这些技能包根据用户需求匹配合适的技能节点再按技能说明中的步骤去执行任务。这个思路最妙的地方在于它把“教Agent做事”从写提示词变成了一种工程化的流程。你不需要每次都在系统提示词里塞一大段指令也不用担心上下文被无关内容撑爆。技能包独立存在、按需加载、随时增删这就和你给新员工写SOP手册有点像——手册写得越清楚他上手越快犯错的概率越低。从我实际使用下来的感受来说这套体系的适用面非常广。如果你是独立开发者可以用它管理自己常用的代码生成、调试、文档整理流程如果你在带团队它可以作为一种团队知识沉淀的方式把项目里那些默认的规矩、常用的脚本、反复踩的坑全部固化下来就算你不是程序员只要日常需要用聊天机器人处理固定类型的任务比如做会议纪要、整理Excel、写周报技能包同样能帮上大忙。这篇文章我就打算按我自己的实操路径来聊先是设计层面用三个真实案例拆解技能包的结构和选型逻辑然后讲从零构建一个技能包的完整过程包括SKILL.md怎么写、脚本怎么组织、依赖怎么管理接着把我调试过程中遇到的几个典型问题拿出来复盘附上排查思路最后聊聊团队落地时最容易踩的管理和版本坑。中间会穿插不少我个人的偏好和习惯仅供参考真正好用的配置还是得结合你自己的场景来定。2. 先想清楚再做技能包的三种常见形态与设计原则2.1 三种形态文档型、脚本型、混合型很多人一上来就问“agent-skills怎么写”其实在这之前得先想明白你的技能包属于哪种形态这个选错后面全是返工。第一种是纯文档型技能包。它没有可执行脚本核心就是一份写得极其详细的SKILL.md外加几个示例文件。典型场景是“教Agent怎么按规范做事”比如写PRD、做代码审查、整理发布日志。这种技能包的价值在于约束Agent的行为边界让它别发挥过头。我之前给团队做过一个“技术方案评审”技能包里面定义了评审的对象、维度、输出格式、以及哪些情况下可以直接驳回Agent每次都能按模板给出结构化的评审意见比让开发自己凭感觉写要稳定得多。第二种是脚本型技能包。这类技能包的核心是一个或多个可调用的小工具SKILL.md只是告诉Agent什么时候调用、传什么参数。比如“批量重命名文件”“把Markdown转成Word”“抓取网页提取正文”都属于这类。它们的共同特点是任务明确、边界清晰、结果可验证脚本本身不复杂但Agent能通过一段自然语言需求自动匹配到正确的工具。第三种是混合型也是我目前用得最多的一种。它既有详细的流程定义也有配套的辅助脚本适合那种“半规则半开放”的任务。举个例子我做“周报生成”技能包的时候SKILL.md里定义了周报的框架和写作风格要求同时又带了一个小脚本专门用来读取本周的git提交记录并按模块聚类。Agent先跑脚本拿到素材再按文档里的框架组织语言效率和稳定性都提升了一大截。三种形态没有绝对的优劣完全取决于你面对的任务类型。我见过有人为了一个一句prompt就能搞定的简单任务非写一个100行的Python脚本这就是过度设计。反过来像代码库级重构这种任务如果只靠文档约束、不配脚本辅助Agent做起来基本就是盲人摸象。2.2 设计原则原子、自包含、可组合我用下来的经验是好的技能包都必须满足三个原则缺一不可。第一个是原子性。一个技能包只做一类事情不要想着“全能工具箱”。你做了一个“文档处理”技能包里面又管Markdown转换又管PDF合并又管表格提取Agent在匹配的时候会非常痛苦因为它不知道该选哪一步。我一开始就吃过这个亏后来把大包拆成“md转docx”“PDF批量合并”“表格数据清洗”三个小包调用成功率高了很多。技能的粒度和需求场景直接相关原子不代表“微小”而是“职责单一且可独立完成”。第二个是自包含。技能包最好能自带运行所需的一切脚本、依赖清单、配置文件、示例输入输出。为什么强调这个因为Agent执行任务时通常没有机会去问你要额外信息如果你包里的脚本依赖某个第三方库而Agent又不知道需要先安装那整个执行链就断了。我现在每个技能包都会带一个requirements.txt或者setup说明部分依赖复杂的环境直接用容器或者可执行文件封装省去大量环境问题。第三个是可组合。单个技能解决单个问题但真实用户需求经常是多步的。Agent在拿到一个复杂请求时如果能把任务拆解成多个步骤然后分别匹配不同的技能包那效果会大幅提升。我自己的做法是在每个技能包的SKILL.md里明确写出“本技能的前置依赖”和“完成后建议调用的后续技能”相当于给Agent画了一张无形的执行地图。比如“生成季度复盘报告”这个技能前置是“拉取项目统计”后续是“格式化导出PPT”串起来就是一条完整的流水线。2.3 和Tools、Prompt的边界在哪见过不少同学问agent-skills和Function Calling、和MCP有什么区别这里我说一下自己的理解。Tools强调的是“调用”它本质上是给模型暴露了一些函数接口模型决定要不要用、怎么用、传什么参数。它的优点是灵活可控缺点是需要为每个工具做详细的function schema且工具之间的逻辑关系需要代码层面去维护。MCPModel Context Protocol则是把工具和资源做了标准化的协议封装属于通信层的东西让不同的Agent能发现并调用同一个工具服务。而agent-skills更接近“人做事的方法论在Agent侧的具体化”。一个技能包不限于“调用某个工具”它还可以定义任务执行中的流程、规范、思考步骤、输出格式。换句话说它介于抽象Prompt和具体Function之间比Function更柔性比Prompt更结构。实际工程中它们并不互斥反而是互补的。我自己的使用习惯是工具调用交给Tools/MCP处理稳定的操作路径和业务规范用Skill封装日常自由对话靠Prompt兜底。这样做的好处是Agent面对非常规需求时有通用的对话能力做保障面对常规重复需求时能够切换到高确定性、高可控性的技能执行模式效果是肉眼可见的变好。3. 复现一个真实技能包从需求拆解到SKILL.md落盘3.1 先选一个高频场景文档批量格式清洗实战部分我拿一个最近在用的“文档批量格式清洗”技能包来做例子。这个场景足够高频但又不像“写代码”那样让人有距离感方便你把注意力集中在技能包的设计逻辑上。背景是这样我们团队日常有大量从不同渠道收集来的Markdown文件有的来自语雀导出有的来自飞书复制有的干脆是别人直接粘贴的富文本。这些文件混到一起后格式极其混乱标题层级不统一、代码块没有语言标注、多余的空行和空格到处都是、图片引用方式五花八门。让Grammarly这类的办公Copilot处理这种细分场景基本无能为力通用Prompt处理时还会“自由发挥”地改内容容易引入事实错误。于是我就想能不能做一个技能包让Agent在收到“清洗这个文件夹”这样的指令时自动按指定规则处理所有文件保证格式一致的同时内容一个字都不动。这个场景天然适合做成技能包因为需求边界清晰、判定标准明确、执行步骤固定基本就是“把规则写成文档把操作写成脚本”的事儿。3.2 用三步法拆需求再把规则写成SKILL.md拿到需求后先别急着写文件我习惯先用三步拆解第一步明确输入输出。输入是一个包含多个Markdown文件的目录输出是清洗后的Markdown文件保证原文件名不变覆盖写入或另存到新目录由参数控制。第二步定义“清洗”的规则。这个必须具体到可以机械执行的程度比如统一标题层级为从一级开始最多到四级去掉所有空行中的空格和Tab代码块统一标注语言类型无法识别时标注为plaintext去掉全角空格和行尾多余空白图片引用统一转换为相对路径格式。第三步定义“不作为”的边界。比如不修改文章措辞不调整段落顺序不改变链接文字不新增小标题不做语法纠错。这个边界特别重要Agent凡是自由度太大的任务就容易画蛇添足。拆完需求后写SKILL.md就变成了一个填空题。我的SKILL.md有一套固定的骨架name技能名、description什么时候该用这个技能写清楚触发条件、when_not_to_use什么时候不该用、input_format输入要求、steps具体执行步骤按顺序编号、quality_checklist输出前自检清单、examples两三个典型输入输出示例。这个结构是我对比过几个开源项目之后固定下来的实用性好过那些写得天花乱坠的文档。Steps部分我会刻意用祈使句每一条指令尽量只包含一个动作。比如扫描目标目录下的所有.md文件。读取每一个文件按3.1中的规则进行样式修正。检测代码块补齐缺失的语言标识。移除行尾空白字符。检查图片引用路径转换为相对路径。输出处理报告列出每个文件的修改项。为什么这样写因为Agent在执行时不是真人它对模糊指令的容忍度很低。你把一个复杂规则拆得越细它执行越准确。这就像是给刚入职的实习生写执行清单写清楚“做什么、怎么做、做到什么程度算完成”他才能独立干活。3.3 脚本侧的设计既要通用也要有“安全阀”虽然SKILL.md已经定义清楚了流程但如果能让Agent直接调用一个脚本去批量处理稳定性会好得多。我自己是用Python脚本实现的核心逻辑大概如下import re import pathlib import argparse def clean_whitespace(text: str) - str: # 去掉行尾空白字符 lines text.splitlines() cleaned [line.rstrip() for line in lines] return \n.join(cleaned) def normalize_heading(text: str, base_level: int 1) - str: # 记录最大标题级别并将其作为一级其余级别依次平移 max_level 4 # ... return text def annotate_code_blocks(text: str) - str: pattern re.compile(r(.*)$, re.MULTILINE) output [] # 识别每个代码块若语言为空则补为 plaintext # ... return \n.join(output) def process_file(src: pathlib.Path, dst: pathlib.Path) - dict: raw src.read_text(encodingutf-8) raw clean_whitespace(raw) raw normalize_heading(raw) raw annotate_code_blocks(raw) dst.write_text(raw, encodingutf-8) return {file: str(src), status: ok} def main(): parser argparse.ArgumentParser(description清洗指定目录下的 Markdown 文件) parser.add_argument(--source, requiredTrue, help源目录) parser.add_argument(--dest, requiredTrue, help输出目录) parser.add_argument(--dry-run, actionstore_true, help只输出变更预览不写文件) args parser.parse_args() src_dir pathlib.Path(args.source) dst_dir pathlib.Path(args.dest) dst_dir.mkdir(parentsTrue, exist_okTrue) results [] for p in sorted(src_dir.rglob(*.md)): rel p.relative_to(src_dir) out dst_dir / rel out.parent.mkdir(parentsTrue, exist_okTrue) results.append(process_file(p, out)) for r in results: print(r) print(f已完成 {len(results)} 个文件的处理) if __name__ __main__: main()这个脚本本身不复杂但有几个细节必须注意。一个是dry-run参数这是“安全阀”。Agent在第一次面对陌生任务时直接让它全量覆盖写入风险很高先预览一遍再决定按不按预期执行至少能拦住一部分误操作。另一个是编码问题统一强制使用UTF-8否则Windows环境下中文文件容易乱码。还有就是输出报告的结构化脚本跑完后要输出每个文件的处理状态Agent拿到报告后才能知道这个技能到底执行成功了没有。有同学可能会问这种简单逻辑的脚本有必要单独搞成技能包吗直接让Agent读一段Prompt然后自己处理不也行吗实测下来的答案是有必要。Prompt让Agent自己去处理它没法保证“内容一个字都不动”上下文多了以后很容易出现漏改、错改的问题。而脚本的处理是确定性的要么正确执行要么输出错误不会有随机发挥的空间。这一点在高频重复任务里体验差异非常明显。4. 我踩过的坑技能触发的三类典型失败4.1 提示词触发失败Agent根本没识别出该用哪个技能这是我初期遇到最多的问题。技能包建了一堆结果用户提需求的时候Agent要么完全没有匹配到技能绕了一大圈绕到通用对话处理要么匹配错了技能比如要做Markdown转Word的时候匹配到了“文档格式清洗”跑出来的结果完全不是用户想要的。排查下来主要原因集中在描述写得不够具体。我一开始给技能写description经常很随意比如“这个技能用于处理文档”看着似乎没问题但模型做语义匹配的时候这种模糊描述和用户问题之间的相关性就差很多。后来我改成带触发词和反例的写法比如“当用户要求清理或规范化Markdown文件格式如统一标题层级、清理空白、补充代码块语言标注时使用如果用户要求的是内容改写或翻译请不要使用本技能”。效果立即改善因为模型在判断时会结合正例和反例做更准确的匹配。再补一个习惯在SKILL.md里加一栏keywords把可能触发该技能的口语化表达全部列上去。比如“美化一下这个文档”“排版乱了帮我理理”“把代码块显示问题修一下”这些Agent在扫描技能包时多一个匹配入口成功率更高。4.2 任务执行中跑偏技能包约束不住Agent的“发挥”第二种典型问题是技能触发了但Agent在执行过程中没有严格按SKILL.md来干着干着开始自由发挥。我之前做“会议纪要生成”技能包的时候就翻过车SKILL.md里明明写了“只提取讨论结论和待办事项不添加个人评价”结果Agent在生成的纪要里加了一大段“建议改善团队协作”之类的主观意见气得我当场想摔键盘。这个问题本质上是技能文档的“指令强度”不够。模型在生成过程中会把它看到的所有文本都当作参考如果技能文档里的描述偏“建议”而不是“强制”它就默认这是开放任务。解决办法是在文档里把关键约束写成硬性规则用“必须”“严禁”“不得”这类强指令词并且加一行“如果生成了本条规则不允许的内容请重写整个输出”。实测下来虽然不能保证100%执行但跑偏概率会降低很多。还有一种情况是Agent执行到一半忘记规则。这个通常发生在多步任务里前面几步正常后面就离谱。我的应对方案是在quality_checklist部分要求Agent在每次输出前逐项自查并且把自查结果作为回复的一部分输出。比如会议纪要技能里我要求它在结尾附上“合规自检本纪要包含主观评价无本纪要包含建议措施无”。这个“强制输出自查结果”的机制非常好用因为它让模型在输出时对潜在违规内容多了一道过滤。4.3 上下文污染技能包内容太多挤占了有效窗口还有一个容易被忽视的问题就是技能包本身写得过长。有些团队为了让Agent表现更好把各种规范、背景、案例全塞进技能文档里结果技能包本身就把上下文窗口占掉一大半Agent真正处理用户数据时反而没有足够空间。这个问题没有标准答案因为窗口大小取决于具体使用的模型。但有一个实用原则可以参考技能包的SKILL.md尽量控制在2000字以内核心是“够用”。更详细的背景知识可以拆到单独的文件里比如references/子目录SKILL.md中只写“如果需要了解背景规则请先阅读references/team_rules.md”。这样平时加载时不占额外空间真到需要时再按需读取整体效率和稳定性更好。5. 团队落地一套用标准目录结构管理技能包的方法5.1 为什么必须统一技能包的目录结构一个人自己玩技能包随便丢哪儿都行。但一旦进入团队协作没有统一的目录结构就是灾难。我接手过一沓别人写的技能包有的直接扔在项目根目录有的放在docs/下面有的把脚本和文档混在一起找起来极其痛苦。后来我定了一套团队规范所有技能包统一放到skills/目录下每个技能包一个文件夹命名规则用kebab-case小写字母连字符比如skill-doc-cleaner、skill-meeting-minutes。每个技能包内部强制包含以下文件skill-doc-cleaner/ ├── SKILL.md ├── scripts/ │ └── main.py ├── assets/ │ ├── example_input/ │ └── example_output/ ├── requirements.txt └── README.md这套结构的目的很明确SKILL.md是给Agent看的README.md是给人看的scripts放可执行代码assets放示例和测试数据。Agent扫描技能包时只需要读SKILL.md人维护时需要看README.md示例文件用来做回归测试。各取所需互不干扰。5.2 版本管理和变更流程别让技能包成了“人人都能改的烂摊子”代码有版本管理技能包同样需要。我们团队现在所有技能包都放进同一个Git仓库遵循“提议-评审-试用-发布”的流程。任何人觉得需要新增或修改技能包先提Issue描述场景和想法然后创建分支写SKILL.md和脚本。写完之后先小范围试点一周收集使用反馈再发Merge Request让其他成员评审。评审不是看代码格式而是看SKILL.md的表达是否会被Agent误解、脚本是否有边界隐患、示例是否覆盖了所有典型输入。每个技能包合并前必须附带至少3个真实测试案例连同预期输出一起贴出来。这里特别想强调一下测试的重要性。Agent技能包和普通代码不一样很多问题不会编译报错只是在运行时表现不对。所以每次改动后我都会跑一遍assets里的示例输入对比输出和预期是否一致。这套东西虽然没有自动化流水线但只要有意识去做技能包的稳定性会显著提升。5.3 给Agent配置技能包轻量加载与按需发现的平衡说到Agent实际怎么用上这些技能包不同框架的配置方式不太一样。有些框架支持在启动时指定技能包目录让它全量扫描有些框架走类似MCP的动态发现机制还有一些简单的方案把SKILL.md合并到系统提示词里。我个人的建议是不要全量塞进去要做“按需发现”。以我常用的实现方式为例Agent启动时会先读取一个skill_index.yaml里面是技能包的索引列表技能名、一句话简介、对应目录路径。当用户输入问题时Agent会基于用户意图在索引里找匹配的技能包再加载对应的SKILL.md。这样加载开销最小也不容易发生技能之间互相干扰的问题。索引文件这样写skills: - name: skill-doc-cleaner description: 清理 Markdown 文件格式统一标题、代码块等样式 path: skills/skill-doc-cleaner enabled: true - name: skill-meeting-minutes description: 将会议录音转写文本整理为结构化会议纪要 path: skills/skill-meeting-minutes enabled: true - name: skill-weekly-report description: 根据 git 提交记录自动生成周报草稿 path: skills/skill-weekly-report enabled: false这个索引文件还能非常方便地做技能开关比如某个技能包暂时不稳定把enabled字段改成false就行不用把文件删掉或者改动SKILL.md。这个方案我用了很久简单可靠管理成本很低。6. 用到现在我对agent-skills的整体评价和两点心得如果让我用一个词评价agent-skills这套思路我会说“顺手”。它不是那种需要复杂理论支撑的技术革命更像是一套被验证过很多次的工程习惯——把模糊的Agent任务变成清晰的、可复用、可测试的工作流。我见过不少人一开始对这个概念嗤之以鼻觉得直接写Prompt不就行了但用了一段技能包之后回头改老方案的不在少数。最后分享两个我坚持了很久的小习惯。第一个是“每做一个新技能包先写为什么不通用”。在README里明确说明这个技能不处理哪些场景、和现有技能包的边界在哪。这样做能极大减少重复造轮子的问题团队里搜一下就知道有没有人做过类似的事。第二个是“定期看技能包的使用记录”。哪个包长期没被触发要么是场景变了要么是索引描述写得不对要么就是该清理了。技能包和所有代码一样是需要持续的维护和淘汰的。