前阵子一直在折腾 AI 编程工作流我发现圈子里聊天最频繁的一个词已经从“大模型能做什么”变成了“怎么让大模型稳定地做某件事”。如果你也有同感应该会注意到 Agent Skills 这个概念。简而言之它就是给 AI 智能体配的一套“可复用能力包”以目录形式存在核心文件是一份 SKILL.md外加脚本、模板、样例等辅助资源。本篇文章我就以 skills 为主线掰开揉碎讲清楚它到底是什么、和提示词与 MCP 有什么本质区别、以及如何从零手写一个能真正上手的技能文件。全程不贴官方文档全是我在实际项目里验证过、踩过坑之后的理解。先说我自己的背景。我过去半年一直在做企业内部的文档自动化处理AI 要批量把 Word、Excel、PPT 转成结构化 Markdown还要按项目规范归档。刚开始用长提示词效果极其不稳定稍一改动格式要求模型就开始自由发挥。后来换成了 Skills 方案把任务拆成“技能包”挂在 AI 助手上效果几乎是断崖式提升模型不再记一堆庞杂的背景知识而是需要处理文档时临时调用对应技能按技能里的指令一步步执行。这个体验让我意识到Skills 不是提示词的一个花哨变种而是 AI Agent 应用里一套全新的工程范式。下面我会从概念讲起然后深入到技能文件的结构设计、手写流程、测试调试和实战避坑内容偏工程但也尽量照顾没接触过 Agent 开发的读者。你不需要预先了解 MCP 或智能体原理只需要跟着我把一个文档处理技能从头到尾实现一遍很多疑问自然就通了。1. Agent Skills 到底是什么先把它和提示词、MCP 分清楚1.1 技能包的本质一份会自我说明的说明书很多人第一次见到 skills 目录结构时都会愣一下这不就是一个带说明书的文件夹吗对本质就是这样但它的精妙之处在于这份“说明书”是给 AI 自己读的。当一个 AI 代理接到任务时它会根据当前的上下文决定要不要调用某个技能。如果决定调用就会加载该技能目录下的 SKILL.md把里面记录的步骤、规范、示例当成临时的操作指南来执行。这里最关键的差异是加载的时机。普通的系统提示词或者上下文填充是“不管用不用得着全都塞给模型”而技能是“按需加载”AI 发现当前任务和技能描述匹配才把整个目录内容读入。同样是一份操作手册前者像把整本字典当早餐吃掉后者像需要查某个字时再去翻对应页码。这个机制大大缓解了上下文窗口被无效信息占用的问题也让模型的注意力更集中。在实际工程里我会把技能目录放在一个统一约定好的位置通常叫 skills 文件夹里面每个子目录代表一个独立技能。每个子目录必须包含一个 SKILL.md 文件文件名大小写敏感格式是 Markdown。目录名建议用英文小写加下划线比如 doc_converter、pdf_analyzer这个目录名其实就是技能的唯一标识。除了 SKILL.md目录里还可以放 scripts、assets、templates 等子目录分别用来存放可执行脚本、静态资源、输出模板。1.2 和 Prompt 的区别从“灌输”到“按需调用”如果你写过比较复杂的提示词一定遇到过这种窘境为了应付模型“忘事”你恨不得把所有规则、例子、反面教材全部塞进提示词。但输入一长模型反而更容易混乱可能是抓不住重点也可能是每次对话都重新理解一遍长篇大论导致输出风格漂移。Skills 解决的是“上下文污染”问题。它把可复用的知识从对话里剥离出去固化成一个有结构的文件包。模型平时不加载这些内容只有命中技能描述时才会读取。这带来几个直接好处一是每次执行的稳定性明显上升因为指令是固定的不会因为用户换了一种问法就丢失二是用户可以随时更换技能版本不用重新开对话三是多技能可以共用一套基础设施AI 会自己判断该用哪个。我在实际项目中的一个对比很能说明问题。之前用提示词处理合同文本抽取遇到不同格式的合同时我至少要准备三到五套提示词模板还得在对话里反复解释。改成技能之后每个合同格式对应一个独立的 skill 子目录通过 SKILL.md 里的 description 字段描述适用场景。AI 拿到一份新合同时会先扫描技能列表自己决定加载哪个效果比我手动切换提示词好得多。1.3 和 MCP 的区别谁保存逻辑谁暴露能力MCPModel Context Protocol也是 AI 应用圈的另一大热词很多初学者会困惑 Skills 和 MCP 是不是同一个东西能不能互相替代。我的理解是这俩根本不在一个维度上。MCP 解决的是“AI 怎么调用外部工具和数据源”它是一层协议比如让 AI 能查数据库、调 API、操作浏览器而 Skills 解决的是“AI 面对一类任务时该按什么流程思考、用什么步骤执行”它是一套指令和知识的封装。可以这样打比方MCP 像是给 AI 装上了手和脚让它能触碰外部世界Skills 更像是一本本作业指导书告诉 AI 拿到任务后先干什么、后干什么、按什么标准验收。有时候两者还经常配合使用比如技能文件里可以写明“该任务需要调用代码解释器工具”或“需要请求某个 MCP 服务返回数据”这就把操作流程和外部工具绑定到了一起。所以别再问“Skills 会不会取代 MCP”在实际工程里它俩是搭档关系。理解了这层区别你就知道为什么要单独设计一个技能体系而不是把指令塞进 MCP 工具描述里。技能描述的是一个“任务场景”MCP 描述的是一个“原子能力”。一个技能内部通常会编排多个原子能力像一个熟练工人拿到图纸后安排自己先用尺子量、再上机床、最后打磨抛光。2. 设计思路为什么大多数技能文件都写不好2.1 先想清楚任务边界再写文件我见过不少刚接触 Agent Skills 的朋友上来就建一个巨无霸技能想让它“无所不能”结果就是什么都做不好。一个成熟技能的设计第一步不是写 SKILL.md而是把任务边界画出来。你要让技能解决什么问题它明确不处理什么输入是什么形态输出需要满足哪些约束只有在脑子里把这几个问题过一遍才能动笔。举个例子我做一个文档格式化技能时最初任务描述很含糊“处理各种格式的文档”。结果 AI 遇到扫描版 PDF 也加载这个技能遇到网页链接也加载这个技能当然就各种报错。后来我在设计阶段明确了三件事输入只接受 docx、xlsx、pptx 这三种办公文件输出统一为带 YAML 头部的 Markdown不处理需要 OCR 的扫描件。边界一旦清晰技能描述和内部指令都好写了模型的成功率立刻提升。我建议在设计阶段就用一份“需求卡片”把技能定下来内容包括技能名称、技能用途一句话、适用输入格式、生成输出格式、典型场景样例、明确不处理的场景。这步看起来和写代码没关系但能帮你过滤掉大量无效需求也能让你后面的描述写得精准。咱们写技能的最终目标是让 AI 在正确的时候选中它在选中后顺利执行完。边界模糊这两个目标一个都实现不了。2.2 Frontmatter 是触发系统的开关不是摆设每个 SKILL.md 都有一个 YAML 格式的头部信息一般包含 name 和 description 两个核心字段。很多人以为这只是个形式随便写一句“可以用来处理文档”就完事。这恰恰是大忌。description 字段是 AI 判断“要不要加载这个技能”的唯一依据它写得越精准技能被正确触发的概率越高。我写 description 有一定之规先点出技能的核心用途和对象再带上输入输出格式词最后写一个典型场景。比如一个文档转换技能的描述我会写成“将 docx、xlsx、pptx 办公文档转换为带有 YAML 头部的结构化 Markdown适用于合同整理、周报归档、数据表导出等场景”。这里的关键是在有限的字段里提供足够多的触发信号既有格式词也有场景词。而那些模糊词例如“强大的”“高级的”“多功能的”尽量不要出现在描述里因为它们不会给模型提供任何有效信息。Frontmatter 还可以带一些可选字段比如 allowed-tools 表明该技能允许调用哪些外部工具license 写明技能包的授权方式。不过我从实践中得到的建议是不要把这里塞太多自定义字段AI 对未知字段的处理是不可控的。如果你想传一些自己的配置建议放到技能目录内的单独配置文件里用 SKILL.md 正文去引用它而不是堆在 YAML 头里。2.3 指令正文要像标准作业指导书不论文笔过去两个月我看了不少开源的技能文件有一个通病非常明显正文写得像产品宣传文案而不是操作指导书。有些 SKILL.md 开篇来一大段“本技能旨在帮助用户...”的废话真正让模型执行的步骤却写得含含糊糊。模型不是人不吃情绪价值那一套它需要的是清晰、有序、可执行的步骤清单。编写正文的时候我一般按照“目标定义 → 输入检查 → 执行步骤 → 输出规范 → 示例”这个顺序来组织。每个步骤尽量用祈使句直接告诉模型“做什么”“怎么判断结果是否正常”“失败时该返回什么信息”。这就像给新员工写标准作业指导书每一步都要有明确的动作和验收标准。不要只写“转换文档”而是要写明“使用 Python 库 python-docx 读取.docx 段落对象提取正文内容并转成 Markdown 标题层级遇到表格时用标准表格语法输出”。还有一条容易被忽视的规则如果技能内容较长建议在正文前面加一个“执行前必读”的小节把关键约束浓缩成三到五条。我自己的项目里会把这条信息放到正文的第一段确保模型无论是从头读到尾还是先扫一眼摘要都能抓住重点。别小看这个细节实际测试中它能让首次执行的成功率提升一截。3. 实操案例手写一个文档格式化技能3.1 定义目标与准备文件结构下面我以自己做过的一个技能为蓝本完整演示从零写一个技能的全过程。我们要实现的能力是把 docx 文档转换成结构化 Markdown转换过程中自动处理标题层级、段落、表格并在输出文件开头生成一个 YAML 头部记录文档的来源文件名和转换日期。先规划目录结构。我在项目根目录下建一个 skills 文件夹技能目录叫 docx_to_md。完整的文件结构如下skills/docx_to_md/ ├── SKILL.md ├── scripts/ │ └── convert.py ├── assets/ │ └── sample_output.md └── requirements.txtscripts/convert.py 是实际的转换脚本requirements.txt 声明依赖assets/sample_output.md 是一个输出样例用来给 AI 参考格式。这个结构麻雀虽小但五脏俱全。关于为什么要单独放一个样例文件我在后面会详细讲。3.2 编写 SKILL.md从 Frontmatter 到执行步骤SKILL.md 是核心文件我们一行一行来写。首先是 YAML 头--- name: docx_to_md description: 将 docx 文档转换为带 YAML 头部的结构化 Markdown适用于合同整理、说明书归档、周报转换等场景。输入为 .docx 文件输出为 .md 文件。 ---description 里明确写了输入输出格式和场景词模型在遇到类似任务时才会有信心启动这个技能。接下来是正文我分了几块一是执行前检查二是转换步骤三是输出规范四是示例引用。正文里我特别强调了“先检查文件是否存在、是否能用 python-docx 打开”这一步看着多余实际能省掉很多排查时间。模型有时候会拿到一个错误路径还在强行解析最后给出一堆莫名其妙的报错。正文建议这么写# docx_to_md 文档转换技能 ## 执行前必读 - 目标文件必须存在且后缀为 .docx。 - 转换前先尝试用 python-docx 打开文件失败则直接返回错误原因。 ## 转换步骤 1. 使用 python-docx 读取文档全部段落和表格。 2. 段落样式名以 Heading 1-6 开头的转为对应层级 Markdown 标题。 3. 非标题段落直接输出为正文文本保留段落间的空行。 4. 文档中的表格依次转为 Markdown 表格表头以第一行内容生成。 5. 图片暂不处理但需在 Markdown 中以注释形式标记图片位置。 ## 输出规范 - 文件开头生成 YAML 头部包含 source(源文件名) 和 converted_at(转换时间)。 - 输出文件与源文件同名后缀改为 .md。这个格式是经过我多次调整后稳定下来的版本。你会发现我没有写“你可以”“请尝试”这类软性表达全是直接的祈使句。AI 对指令性语言的服从度比对建议性语言的服从度高得多这一点在所测试的多个主流模型上都成立。3.3 编写配套脚本与资源清单SKILL.md 描述完流程之后还要有一个真正能跑起来的脚本。我这里不贴完整的几百行代码只展示关键思路。第一步是用 python-docx 读取段落判断样式名写出内容第二步是读取表格并转成 Markdown第三步是添加 YAML 头部并保存文件。#!/usr/bin/env python3 import sys from datetime import datetime from pathlib import Path from docx import Document def convert_docx_to_md(input_path: str, output_path: str): doc Document(input_path) lines [] # 处理段落 for para in doc.paragraphs: style para.style.name if para.style else if style.startswith(Heading): level style.replace(Heading , ) prefix # * int(level) lines.append(f{prefix} {para.text}) elif para.text.strip(): lines.append(para.text) # 处理表格 for table in doc.tables: for row in table.rows: cells [cell.text.strip().replace(\n, ) for cell in row.cells] lines.append(| | .join(cells) |) lines.append() # 生成 YAML 头部 header ( ---\n fsource: {Path(input_path).name}\n fconverted_at: {datetime.now().isoformat()}\n ---\n\n ) Path(output_path).write_text(header \n.join(lines), encodingutf-8) if __name__ __main__: convert_docx_to_md(sys.argv[1], sys.argv[2])这个脚本并不复杂但覆盖面比较全。实际使用场景中AI 会被指示先去读 SKILL.md然后调用这个脚本生成结果。脚本本身承担了“确定性”的部分不管模型怎么发挥脚本输出的格式是固定的。这种“模型负责规划调度、脚本负责稳定执行”的分工方式是我觉得 Agent Skills 最理想的落地形态。requirements.txt 也得跟上内容很简单python-docx1.1.0assets/sample_output.md 也很重要。这个文件是一个转换后的示例它存在的意义是让模型看到最终格式长什么样比任何文字描述都直观。我在实际测试中发现有样例和无样例的差异非常大模型在模仿具体格式时几乎不会出错但让它凭空理解格式规范时就容易五花八门。3.4 和 IDE/终端集成后的行为验证写完了不等于能用了还得集成到你的 AI 编程环境里。现在主流 AI 编程助手基本都支持自定义技能目录最常见的做法是把 skills 文件夹放在你当前工作区的根目录下然后在对话里直接输入类似“帮我用 docx_to_md 技能把这份合同转成 Markdown”。第一次集成之后我建议大家做三个验证。第一把技能目录路径告诉 AI 环境后输入一个和技能无关的请求看它是否不会误加载技能这能检验 description 的边界描述是否有效。第二输入一个明确的转换请求观察 AI 是否读入 SKILL.md 并按其步骤执行而不是自己凭感觉直接写一段代码。第三把脚本故意指向一个不存在的文件看 AI 是否能从执行前必读里找到解决办法并给出正确的错误提示。这套验证流程我每次新增技能都会跑一遍比写十个单元测试都管用。如果发现 AI 在对话中始终没有调用技能首先要检查环境是否真的加载了对应目录其次要检查 description 是否足够精准。环境配置是新手最容易疏忽的点很多人以为把文件夹建好就完事了结果 AI 压根不知道有这个目录存在自然永远不会触发。多数的“技能不生效”问题都出在这一步而不是技能文件本身写错了。4. 测试、调试与迭代技能不是写一次就完事4.1 分层测试先验证脚本再验证触发技能的复杂性决定了我们不能只靠一次对话测试就判断“它能用了”。我把技能测试拆成两层脚本层和触发层。脚本层测试很简单就是直接在终端里把脚本跑一遍传入一个真实文档检查产出的 Markdown 是否符合预期。这一步必须先做因为脚本是整个技能里确定性最强的部分它通了技能就有了地基。触发层测试则复杂一些涉及到 AI 是否能在正确时机加载技能、是否严格按 SKILL.md 的步骤执行、出错时是否走预期分支。我的做法是准备一份测试对话脚本包含正例和反例。正例是“把这份周报转成 Markdown”反例是“今天天气怎么样”。观察 AI 的反应正例必须加载技能反例必须完全不碰技能。两三个来回之后技能的“可触发边界”基本就摸清了。分层测试给到的一个额外好处是快速定位问题。如果脚本层失败那很可能是代码 bug 或依赖缺失跟技能文件无关如果脚本层通过但 AI 不加载技能那就是 description 或环境配置的问题如果加载了技能但执行结果不对那就是 SKILL.md 里的指令不够明确。按照这个逻辑排查基本不会走弯路。4.2 观察调试日志与定位失败点调试技能时我会打开 AI 编程环境的详细日志输出重点关注两点技能文件是否被加载、模型在推理过程中读了哪些内容。这类日志在当前各家 AI IDE 里基本都能找到很多时候藏在设置的“开发模式”或“详细日志”开关里。日志里如果出现 Skills 加载记录说明触发成功如果没有就回头去检查 description 和环境目录配置。加载成功但执行结果不佳的情况通常问题出在 SKILL.md 的指令质量。我遇到最多的是指令歧义正文写了“处理文档中的图片”但没说怎么处理模型就自由发挥有时候把图片丢掉有时候插入一个错误路径。后来我改成“图片暂不处理但需在 Markdown 中以注释形式标记图片位置”模型就不再有发挥空间。这背后是 Agent 场景下的一个铁律你想让模型稳定输出就必须把模糊空间堵死任何你没写清楚的步骤它都可能给你“创造性”地补一个答案。还有一类失败的定位要花点心思模型按照 SKILL.md 执行了但在调用脚本时传参错误比如路径传成了相对路径或者参数顺序搞反了。这种情况我会在 SKILL.md 里增加一种示例命令格式明确告诉模型应该怎么调用脚本并在正文中强调“脚本仅接受两个参数第一个是输入文件路径第二个是输出文件路径”。这种把接口调用方式写进技能说明的习惯能省去不少在日志里翻代码的麻烦。4.3 迭代方法论从“能用”到“好用”任何一个技能第一次跑通只能算“能用”离“好用”还有不小距离。“好用”在我的标准里意味着AI 在 95% 以上的同类任务中能自动触发技能触发后不需要用户额外的补充说明就能完成输出而且格式完全统一。要达到这个标准通常要经历两到三轮迭代。第一轮迭代重点改 description。把实际触发失败的案例记录下来找到那些“该触发却没触发”的表述去扩充描述里的典型场景词。很多技能冷启动失败都是因为开发者觉得场景不言自明但模型没见过你的术语体系自然无法联想。第二轮迭代重点改正文步骤。把实际执行中模型反复困惑的地方抽出来补充判定条件和异常分支。第三轮迭代重点优化资源文件。比如脚本输出的内容分类有遗漏就在 assets 里更新样例让模型有更具体的模仿对象。这套迭代方法论听起来简单做起来需要耐心。我的习惯是每轮迭代都把测试对话截图或日志保存下来形成一个小型回归库。改完 description 之后把之前失败的正例重新跑一遍确保没有引入新问题。技能迭代像个滚雪球的过程前几轮可能痛苦但越往后你会越清楚哪些地方模型容易出幺蛾子改起来也越来越快。5. 实战经验与避坑清单5.1 写技能容易踩的五个坑第一个坑是技能“过大”。总想把一个技能设计成全流程解决方案文档转换要从 docx 管到 pdf还要带 OCR结果 SKILL.md 越来越长模型执行起来越来越混乱。正确做法是拆分一个技能只解决一个相对聚焦的问题拆出来的多个技能可以互相协作但不要塞进同一个目录里。第二个坑是依赖环境不写清楚。技能范围的脚本需要 python-docx但 SKILL.md 里没提AI 在全新环境里运行时报错然后开始“自己想办法修复”往往越修越乱。我的建议是技能正文里明确写下“运行前需要安装 requirements.txt 中的依赖若缺少则先执行 pip 安装”。依赖声明清楚AI 就不会乱猜。第三个坑是把大段背景知识写进技能。技能文件要聚焦操作步骤不适合承载冗长的领域知识。比如我们做合同转换没必要在 SKILL.md 里解释合同的法律条款有哪些只需要写清楚怎么读文档、怎么保留格式。背景知识塞给模型只会稀释真正指令的权重让关键步骤变得不明显。第四个坑是忘记更新样例文件。assets 里的样例是模型模仿的基准所有步骤和规范都该和样例保持一致。我见过有人改了脚本的输出格式却忘了更新样例结果模型执行脚本生成的是一套格式又对照旧样例调整了一遍出炉的东西反而四不像。每次改输出规范时记得同步重新生成样例文件。第五个坑是技能版本管理混乱。实际项目里技能文件会经常改动如果不加版本控制哪天改出问题就很难回溯。我建议在技能目录里放一个 CHANGELOG.md或者至少在 SKILL.md 里维护一个 version 字段同时在 Git 里单独把 skills 目录作为独立模块管理。任何一个 AI 应用项目里技能文件都值得像代码一样被认真对待。5.2 常见问题速查表下面这张表是我在多个项目中反复用到的排障清单。当你发现技能不工作或结果不对时先对照这张表自查通常比盲目改文件高效得多。症状可能原因排查方向AI 始终不加载技能环境未配置技能目录检查工作区根目录 skills 文件夹是否存在、路径是否正确AI 不加载技能description 与任务描述不匹配扩充场景关键词明确文件格式和任务动词加载技能但执行顺序混乱SKILL.md 步骤不够明确改为祈使句增加“按顺序执行”字样减少候选分支脚本运行时报缺少模块依赖声明遗漏在 SKILL.md 中写明依赖安装命令附上 requirements.txt输出格式不一致缺少样例文件在 assets 中放置固定输出样例并在正文中要求参考样例技能改坏了但不知道改了什么无版本管理给技能文件加 version 字段或用 Git 管理 skills 目录AI 在处理简单任务时也加载技能description 边界模糊在 description 末尾加上“不处理××场景”之类的排除说明这张表没法覆盖所有情况但覆盖了我遇到过的绝大多数问题。有个原则值得反复强调任何“异常行为”先确定问题出在脚本层还是决策层。脚本层就是代码能不能跑通决策层就是模型选择和执行指令的过程。这两个层面的排查逻辑完全不同混在一起只会两头抓瞎。5.3 一点个人体会技能文件写多了以后我最大的体会是它本质上是一种面向模型的“接口设计”。你写的每一句话都是在为 AI 定义一个执行接口什么时候该调用、进去了先做什么、每一步的输入输出是什么、异常怎么处理。接口设计得好AI 就是个靠谱的执行者设计得差再强的模型也会变得像无头苍蝇。这和传统软件开发中的 API 设计理念惊人地一致只不过调用方从一个程序员变成了一个语言模型。另外我强烈建议团队做技能库的沉淀。现在我们团队内部有一个共享的 skills 仓库大家把互相都能用到的技能提上去比如文档转换、周报生成、代码审查清单都做成了标准技能文件。新来的同事接入这个仓库后AI 的“工作习惯”立刻就和团队对齐了不再需要花两周时间互相调教。这个价值远超过单个技能本身。最后说一个小经验给技能写 description 的时候不妨站在用户真实会怎么提问的角度来写。你希望用户在什么场景下对 AI 说什么话就把这些关键词放进 description。不要用“处理文档”这种刚性的短语试试“把docx转成markdown”“整理合同并存为带引用的md”“把周报表格导出为md”。当你发现自己开始用用户的原话来写功能描述时技能的触发率自然就上去了。这套方法我每用一次都会感慨让 AI 理解你的意图最关键的一步不在代码里而在描述里。