在给 Agent 加能力这件事上，我过去的第一反应永远是“再写一段 Prompt”。直到某次给一个数据处理类 Agent 增加“PDF 表格抽取”功能，我在提示词里反复强调格式、补充了三四页示例，结果模型的输出依然时好时坏，同一份文档换个排版就崩。那一刻我才意识到，如果 Agent 的能力边界全靠提示词去“说服”模型，那它永远不够稳定，也永远无法像真正的软件模块一样被测试、复用和迭代。后来我接触并实践了 Agent Skills（智能体技能包）的思路，才真正体会到什么叫“从 Prompt 工程走向软件工程”——把技能封装成结构化的、可运行、可测试的软件组件，而不是一段靠运气生效的文本指令。这篇就拿我一个实际的可复用技能包为例，拆解 Agent Skills 的设计思路、落地步骤，以及从提示词思维切换到软件工程思维后我踩过的坑和收获。1. 为什么 Agent 的“技能”不能再靠提示词硬撑1.1 Prompt 工程的天花板：不稳定、难复用、不可测试先聊聊我过去几年用 Prompt 工程给 Agent 加能力的真实体感。早期做一个问答机器人，要让它能查询内部知识库，我的方案很简单：把检索到的文档片段拼进系统提示词，再写一大段“请基于以下内容回答”。效果尚可，但一旦文档数量增加、问题变复杂，提示词就开始失控。后来做结构化抽取、多步工具调用，问题更明显。Prompt 工程的瓶颈，我总结下来就三件事。不稳定。模型对措辞极其敏感，换一个同义词、调一下示例顺序，输出格式就可能偏离。你没法用“断言”来保证它一定返回合法的 JSON，只能说“概率很高”。难复用。一段提示词写完后，换一个业务场景就要重新调。项目 A 里调通的情感分析 Prompt，项目 B 里几乎没法直接搬，因为阈值、示例、输出格式全都依赖当时的数据分布和模型版本。不可测试。你很难对一段 Prompt 写单元测试。它不是确定性的程序，没有明确的输入输出契约。你说“输出必须包含三个字段”，但模型可能给你输出四个、五个，或者把字段名改一改。回归测试这件事，在传统提示词方案里基本等同于“人工再看一遍”。这不是说 Prompt 工程没有价值，而是它更适合做“模型行为引导”，不适合做“能力封装”。当你想给 Agent 增加一个确定性的功能——比如“把 CSV 转成 JSON”或“调用某个 API 并解析结果”——你真正需要的不是一段话术，而是一段可靠的代码，外加一份让模型知道“何时用、怎么用”的说明。1.2 一个让我转向 Skill 思维的真实场景我在某开源学习社区组织过一次 AI Agent 组队学习，当时的任务之一是给 Agent 增加“网页表格抽取”能力。第一次尝试就是纯 Prompt：给模型看几个 HTML 片段，让它提取表格数据并输出 Markdown。结果很有意思。对规整的表格，模型表现很好；对带合并单元格、多层表头、或者表格嵌套在复杂布局里的页面，输出就开始离谱。更麻烦的是，抽取结果里偶尔混入页面导航栏里的文字，模型自己根本意识不到。这种“幻觉式抽取”不是靠提示词能修好的，因为问题不在模型理解能力，而在任务本身需要一个确定性的解析流程。后来我把这个功能重写成一个 Python 脚本，用专门的 HTML 解析库去识别表格节点，再写一个清晰的能力描述文档，告诉 Agent“什么时候调用这段代码，传什么参数，拿什么结果”。从那以后，输出稳定了，而且这套逻辑可以给任何 Agent 用，不需要重新调 Prompt。这个转变，就是“从 Prompt 工程走向软件工程”的起点：把模型擅长的事情（意图理解、计划制定、内容生成）留给模型，把模型不擅长的事情（精确定位字符、解析结构化数据、调用外部系统）交给确定性代码。而 Agent Skills，正是承载这种分工的标准容器。1.3 “软件工程”在这里到底指什么很多人一听“走向软件工程”，以为是要上微服务、K8s，其实没那么玄。在 Agent Skills 的语境下，软件工程指的是四件事：版本管理：技能包有版本号，改了逻辑不影响旧调用方，可以随时回滚。接口契约：技能有明确的入参、出参、错误码，调用方（模型或代码）可以按约定使用。测试机制：每个技能可以写自动化测试，跑一次就知道有没有改坏。依赖声明：技能依赖哪些库、需要什么运行环境，写清楚，别人拿到就能跑。一句话：把“能力”当作“软件模块”来管理，而不是当作“灵感”来发挥。Agent Skills 恰好就是这套思维的最小落地单元。2. Agent Skills 到底是什么：把能力封装成“可运行的说明书”2.1 核心概念：描述文件 + 脚本 + 依赖清单我第一次理解 Agent Skills 时，脑子里冒出来的类比是 Linux 的 man 手册加一个可执行文件。模型是用户，它遇到任务时先去“翻手册”（读技能描述），发现手册说“这个活我能干”，于是按手册里的指引去执行一段脚本，最后把结果拿回来处理。一个标准的 Skill 包通常包含三类内容：描述文件：告诉模型这个技能什么时候用、怎么用、有哪些限制。核心是 SKILL.md 这类 Markdown 文档。可执行脚本：真正干活的代码，可以是 Python、JavaScript、Shell，或者任何能在你的 Agent 运行环境里执行的语言。依赖与配置：脚本所需的第三方库、环境变量、配置文件，保证技能可以被干净地安装和运行。我见过的开源技能仓库里，目录结构一般都长这样：agent-skills/ ├── csv-to-json/ │ ├── SKILL.md │ ├── script.py │ └── requirements.txt ├── fetch-webpage/ │ ├── SKILL.md │ ├── fetch.py │ └── requirements.txt └── ...每个子目录就是一个独立技能。Agent 运行时按目录加载，把 SKILL.md 的内容注入上下文，让模型“知道有这个工具可用”，等模型决定调用后，再由运行时去执行对应脚本。2.2 一段描述与一段代码的本质区别理解 Agent Skills 的关键，是分清“模型负责什么”和“代码负责什么”。描述文件负责的是“决策”。模型读到 SKILL.md，认识到当前用户请求“把附件里的 Excel 转成 JSON”正好命中 csv-to-json 的技能描述，于是决定调用它。这个决策过程是模型擅长的：自然语言理解、意图匹配、参数提取。脚本负责的是“执行”。一旦模型确定了调用意图，剩下的就交给脚本：读文件、解析内容、做格式转换、输出结果。这段逻辑是确定性的，不会因为模型心情不好就漏掉一行数据。传统 Prompt 工程把两件事混在一起：决策靠文本，执行也靠文本。模型既要理解意图，又要“手算”每一个字符，结果自然是既不高效也不可靠。Skills 的核心价值，是让模型只在它擅长的层面做决策，把高精密操作交给代码。2.3 常见的 Skill 类型根据我的观察，现有生态里比较常见的技能包大致分四类：信息检索类：从文件、数据库、网页里提取指定内容，输出结构化结果。典型如读取 PDF、抓取网页、查询本地文件。数据转换类：把一种格式转成另一种。CSV 转 JSON、Markdown 转 HTML、日志清洗、字段映射。工具封装类：把外部 API、命令行工具包成统一接口。比如调用天气接口返回结构化数据，或者把图像压缩命令封装成一个函数。流程编排类：把多步操作固化成固定流程。比如“下载附件 → 解压 → 校验 → 汇总”一条龙服务。这些技能的一个共同点是：执行路径是确定的，不需要模型临场发挥。只有“确定能做好的事”，才值得封装成技能；那些需要开放思考、创意生成的任务，反而更适合直接对话式 Prompt。2.4 Prompt 工程与 Agent Skills 的一个直观对比我把两种方式在几个关键维度上的差异整理成了一张表，方便对照理解：维度Prompt 工程Agent Skills实现方式在提示词里描述指令和示例写代码实现功能，写文档描述用途稳定性依赖模型对措辞的理解，波动大代码逻辑固定，结果可预期复用性换场景基本要重调技能包可跨 Agent、跨项目复用可测试性难以自动化断言可写单元测试和集成测试定位边界适用于开放任务、生成式任务适用于确定性任务、固定流程维护方式调提示词、试错、碰运气改代码、发版本、跑测试这张表可以解释为什么“技能包”的提法越来越流行：它不是对 Prompt 工程的否定，而是给 Agent 补上了一个可靠的“手和脚”，让它不只是一个会说话的脑袋。3. 从零搭建一个可复用 Skill 的完整过程3.1 顶层目录与命名：先定规矩再动手我建议在一开始就建一个单独的目录来放所有技能包，比如agent-skills/。每一个技能包用短横线命名，全部小写，一眼能看出功能。我常用规则是“动词-对象”，例如fetch-webpage、parse-pdf、csv-to-json。命名这个事看起来无关紧要，但等你攒了二十个技能包之后就会明白，命名混乱是最令人头疼的问题。模型是通过 SKILL.md 的描述来匹配技能的，它不关心目录名，但你自己需要一眼找到目标技能。另外，很多运行时是按目录名加载技能的，如果命名有歧义，可能出现两个相似技能同时匹配用户请求的情况，导致模型不知道选哪个。3.2 SKILL.md 要写清楚“什么情况用、怎么用、注意什么”SKILL.md 是整个技能包的灵魂，但它不是给人类看的开发文档，而是给模型看的“操作手册”。模型依据这份文档判断是否调用、如何传参，所以写法跟传统 README 很不一样。我一般按这样的结构写：# 技能名称 ## 功能概述 这个技能做了什么，一句话说清。 ## 适用场景 什么时候应该调用这个技能？触发条件是什么？ 什么时候不应该调用？明确写出边界。 ## 输入参数 | 参数名 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | file_path | string | 是 | 待处理的文件路径 | | encoding | string | 否 | 文件编码，默认 utf-8 | ## 输出格式 返回什么结构的数据？给出一个具体示例。 ## 使用示例 举一个用户请求和技能调用的对应案例。 ## 注意事项 有哪些坑需要提醒模型？例如“文件不存在时返回错误码 404，不要尝试自行修复”。关键点在于“注意事项”这一节。模型看到技能描述后，会在调用时自动遵循这些限制。如果你不写“文件不存在就报错”，模型可能自作主张地编造一个空结果，这是最典型的幻觉来源。写清楚边界，等于把错误处理策略前置到决策阶段。3.3 核心脚本：真的写代码，而不是写提示词技能的核心脚本要遵循一个原则：输入输出尽量接近 SKILL.md 里声明的契约，用命令行接收参数，用标准输出返回结果。这样无论 Agent 运行时是本地进程、容器还是沙箱，都能统一对接。我以自己实现的一个 “markdown 表格转 CSV” 技能为例。脚本很短，但足够说明问题：#!/usr/bin/env python3 """markdown_table_to_csv.py - 把 Markdown 表格转换为 CSV 格式。""" import csv import io import re import sys def parse_markdown_table(md_text: str) -> list[list[str]]: lines = md_text.strip().splitlines() table_lines = [line for line in lines if line.startswith("|")] if not table_lines: return [] header = _split_row(table_lines[0]) rows = [_split_row(line) for line in table_lines[2:]] return [header] + rows def _split_row(line: str) -> list[str]: stripped = line.strip().strip("|") cells = [cell.strip() for cell in stripped.split("|")] return cells def to_csv(rows: list[list[str]]) -> str: output = io.StringIO() writer = csv.writer(output, lineterminator="\n") writer.writerows(rows) return output.getvalue() def main(): md_text = sys.stdin.read() rows = parse_markdown_table(md_text) if not rows: print(json.dumps({"error": "no table found"}), file=sys.stderr) sys.exit(1) print(to_csv(rows)) if __name__ == "__main__": main()从这个例子可以看到，核心逻辑完全由代码掌控：正则匹配表格行、分隔单元格、跳过分隔行、用标准库解析 CSV 输出。没有给模型“发挥”的空间，结果自然稳定。现实中更复杂的技能也遵循同一套模型：标准输入进、标准输出出，错误走 stderr 并附带非零退出码。3.4 依赖与运行环境：让别人拿起来就能跑一个技能如果依赖第三方库，必须在 requirements.txt 里声明清楚，最好再附一句“用 Python 3.10+ 运行”。依赖声明看着琐碎，但它是技能可复用的前提。我曾经接过别人的技能包，里面用到了某个特定版本的数据处理库，文档里完全没提，结果在我本地环境一跑就报错，排查了半天。我建议每个技能包里至少包含：requirements.txt：列出直接依赖的库，尽量不要用“大于等于”的范围写法，锁定主版本即可。一个简短的运行说明：在 SKILL.md 的末尾附上“安装依赖：pip install -r requirements.txt”。尽量使用标准库：如果标准库能解决，就别引入外部依赖。依赖越少，技能越稳，越不容易出现环境冲突。3.5 本地加载与测试：先让脚本能跑，再让模型能调技能目录和脚本写好后，第一步是本地直接测功能，不要立刻接进 Agent。我的做法是先测脚本本身：echo "| name | age |\n| --- | --- |\n| Alice | 30 |" | python markdown_table_to_csv.py确认输出符合预期后，再写几组边界输入测异常：空表格、没有表头、多余空格。脚本的确定性保证在这里得到验证。下一步是“模拟模型调用”。这一步很关键：找一个支持工具调用的 LLM 接口（我常用本地模型和主流云模型各测一遍），给它注入 SKILL.md 的内容，并提供一个执行脚本的函数，然后观察模型是否能在合适的时机调用技能、是否用对了参数。这一步能暴露很多问题，最常见的是：模型把技能描述里没写的参数传进来。模型对多个相似技能产生混淆。模型在技能返回错误后，自作主张重试多次，而不是把错误返回给用户。发现这些问题后，修改的方向不是调提示词，而是改 SKILL.md 的描述，明确参数、边界和错误处理策略。这个过程很像在调接口文档，而不是在调 Prompt。4. 工程化落地时的关键决策与避坑4.1 什么时候该用 Skill，什么时候直接写代码一个我反复思考的问题：技能包和普通函数到底有什么区别？难道把功能写成一个 Python 函数、让 Agent 直接调用不就行了？确实可以，但 Agent Skills 有一个普通函数不具备的优势：它自带“决策说明”。模型不需要在代码里看到函数定义才知道该用它，而是通过读 SKILL.md 这样的自然语言描述，在对话上下文中主动发现技能的存在。这意味着技能可以被动态加载：Agent 遇到新任务时，从技能仓库里检索并注入相关描述，而不是把所有函数都塞进上下文。当技能数量有几十个上百个时，这个差别是致命的。我的判断标准是：如果这个功能会被多个 Agent 复用、需要独立于对话逻辑进行测试，就封装成 Skill；如果只是某个 Agent 内部的一次性 helper，写普通函数就够了。4.2 测试策略：不要只测代码，还要测“模型的理解”技能的测试比普通代码多一个维度。普通代码测试的是“输入输出是否正确”；技能测试还要加一条：“模型看了 SKILL.md 之后，能不能在正确时机调用它”。我用的测试方案分三层：第一层是单元测试。只测脚本逻辑，相当于你在任何 Python 项目里写的那种 testcase。第二层是描述测试。构造一批模拟的用户请求，把 SKILL.md 和请求一起喂给模型，看它是否触发了技能调用，调用参数是否满足契约。这层测试很灵活，我通常对每个技能准备 10 条左右的正例和负例，正例里预期技能被触发，负例里预期不触发。第三层是端到端测试。把技能装进一个真实的 Agent 应用里，模拟用户完整对话流程，验证最终体验。这层最花时间，但最能发现问题。很多技能写失败，不是代码写错了，而是 SKILL.md 写得含糊，模型压根不知道这个技能的存在，或者在错误时机错误调用。每一层测试都能从不同角度拦住问题。4.3 版本管理与兼容性：技能也会演化技能一旦接入线上 Agent，就要考虑版本管理。我最开始完全忽略这点：想改某个技能的行为，直接改脚本，结果旧对话里已经缓存的 Agent 行为和新行为不一致，出了不少问题。现在的做法是给每个技能加version字段，写在 SKILL.md 的头部。改代码时更新版本号，并在头部记录变更摘要。这样即使运行时只加载了旧描述，你也能从日志里追踪到具体版本，快速定位问题。另一个跟版本相关的坑是“描述与代码不同步”。有时你只改了脚本逻辑，忘了更新 SKILL.md，模型还是在按旧描述调用技能，参数对不上，运行时报错。这个只能靠人为自律：每次改脚本必须同步改描述，最好在代码评审清单里加上这一条。4.4 安全边界：别让模型把技能当万能执行器技能包的引入给 Agent 带来了执行能力，也带来了新的安全风险。最典型的风险点有三个：第一，任意命令执行风险。如果技能包允许传入任意 Shell 命令，模型一旦被提示词注入攻击，就可能让 Agent 执行恶意命令。我的建议是技能接口尽量收窄，不要暴露通用执行接口，而是暴露“封装好的具体操作”，比如“重命名文件”而不是“执行任意命令”。第二，路径穿越风险。文件处理类技能如果直接拼接用户提供的路径，可能读取到预期之外的文件。脚本里要校验输入路径是否在允许的根目录之内。第三，外部资源访问。涉及网络请求的技能，要限制目标域名范围，避免 SSRF 类问题。我在封装网页抓取技能时，就加了一个简单的域名白名单。安全设计不需要很复杂，但必须有边界意识。技能越强大，边界越要收紧。4.5 团队协作：技能仓库也要有“评审机制”当多个人一起维护技能仓库时，就出现了一个非常“软件工程”的问题：如何保证技能质量。我所在的团队，技能合并到主分支前至少要过三关：代码评审：看脚本是否有明显 bug、是否有安全隐患。描述评审：看 SKILL.md 是否清楚、会不会误导模型。测试通过：要求新增技能必须附带至少一层测试。这些流程不是凭空想出来的，而是踩过坑之后沉淀的。曾经有一个技能包，代码质量很高，但 SKILL.md 里把适用场景写得太宽泛，结果模型在用户问“怎么炖排骨”时调用了这个“读取菜谱文件”的技能，场面一度失控。把描述评审加入流程之后，这种低级误用明显少了很多。5. 从 Prompt 工程走向软件工程：思维转变的几点体会5.1 关注点从“调模型”转移到“设计系统”当我开始用 Agent Skills 组织能力后，一个很明显的感知是：我不再那么关心“模型会不会按我的提示词行事”，而是更关心“整个系统的边界和接口是否清晰”。Prompt 工程的核心动作是“试”：反复修改措辞，观察输出变化，直到满意。这是调模型。而 Agent Skills 的核心动作是“建”：确定边界，定义接口，实现逻辑，测试验证，版本管理。这是建系统。这种转变带来的是稳定性和可扩展性。以前每加一个能力，都要重新调一遍 Prompt，越调越复杂，越复杂越不稳定；现在加一个能力，就是新建一个技能包，装上之后哪里都能用。系统的复杂度从“一团提示词”变成了“一组可管理的模块”，心智负担完全不同。5.2 对个人开发者来说，这意味着“杠杆”技能包还有一个特别吸引我的特性：可组合性。做一个调研类 Agent，可以挂上“网页抓取”“PDF 解析”“摘要生成”三个技能；做一个数据处理类 Agent，可以挂上“CSV 清洗”“格式转换”“图表渲染”三个技能。同一套技能在不同 Agent 之间组合复用，形成自己的“私人工具链”。技能包本质上是把“会写特定代码的人”的经验，固化成可被任意语言模型调用的模块。这意味着你不用每次让模型从零开始理解某个业务领域，只需要告诉它“这个活用这个技能干”，它就能稳定输出结果。对于个体开发者，这种组合式杠杆的价值，怎么强调都不为过。5.3 最后分享一个技巧：先做减法，再做加法如果你正打算开始实践 Agent Skills，我的核心建议是：不要一开始就追求大而全的技能仓库，先从你能想到的、最确定的、最重复性的任务开始。做一个最小技能包，跑通从描述到调用到测试的完整流程，再逐步扩展。我在实际操作中最常见的问题是“过度设计”：把技能描述写得又长又细，把脚本抽象得又泛又复杂，结果模型反而不知道在什么场景下调用，测试也花了大量时间维护。后来我改成“描述只写必要信息，脚本只处理一种确定的输入输出”，技能包的可用性反而直线上升。另外，每次给 Agent 加完一个技能，记得留出时间观察真实使用中的错误日志，尤其是“模型想调用但没调用”“模型调用了但参数不对”这两类情况。它们是衡量 SKILL.md 质量最重要的信号。把这些信号定期梳理回填到描述文档里，技能会越用越顺。这些经验不来自什么高深理论，就是一次次改描述、改脚本、跑测试、看日志里磨出来的。Agent 的能力边界，说到底是由你封装的这些“技能”决定的。从一段提示词到一个技能包，不只是写法的变化，更是对“Agent 如何工作”这件事理解的升级。
在给 Agent 加能力这件事上，我过去的第一反应永远是“再写一段 Prompt”。直到某次给一个数据处理类 Agent 增加“PDF 表格抽取”功能，我在提示词里反复强调格式、补充了三四页示例，结果模型的输出依然时好时坏，同一份文档换个排版就崩。那一刻我才意识到，如果 Agent 的能力边界全靠提示词去“说服”模型，那它永远不够稳定，也永远无法像真正的软件模块一样被测试、复用和迭代。后来我接触并实践了 Agent Skills（智能体技能包）的思路，才真正体会到什么叫“从 Prompt 工程走向软件工程”——把技能封装成结构化的、可运行、可测试的软件组件，而不是一段靠运气生效的文本指令。这篇就拿我一个实际的可复用技能包为例，拆解 Agent Skills 的设计思路、落地步骤，以及从提示词思维切换到软件工程思维后我踩过的坑和收获。1. 为什么 Agent 的“技能”不能再靠提示词硬撑1.1 Prompt 工程的天花板：不稳定、难复用、不可测试先聊聊我过去几年用 Prompt 工程给 Agent 加能力的真实体感。早期做一个问答机器人，要让它能查询内部知识库，我的方案很简单：把检索到的文档片段拼进系统提示词，再写一大段“请基于以下内容回答”。效果尚可，但一旦文档数量增加、问题变复杂，提示词就开始失控。后来做结构化抽取、多步工具调用，问题更明显。Prompt 工程的瓶颈，我总结下来就三件事。不稳定。模型对措辞极其敏感，换一个同义词、调一下示例顺序，输出格式就可能偏离。你没法用“断言”来保证它一定返回合法的 JSON，只能说“概率很高”。难复用。一段提示词写完后，换一个业务场景就要重新调。项目 A 里调通的情感分析 Prompt，项目 B 里几乎没法直接搬，因为阈值、示例、输出格式全都依赖当时的数据分布和模型版本。不可测试。你很难对一段 Prompt 写单元测试。它不是确定性的程序，没有明确的输入输出契约。你说“输出必须包含三个字段”，但模型可能给你输出四个、五个，或者把字段名改一改。回归测试这件事，在传统提示词方案里基本等同于“人工再看一遍”。这不是说 Prompt 工程没有价值，而是它更适合做“模型行为引导”，不适合做“能力封装”。当你想给 Agent 增加一个确定性的功能——比如“把 CSV 转成 JSON”或“调用某个 API 并解析结果”——你真正需要的不是一段话术，而是一段可靠的代码，外加一份让模型知道“何时用、怎么用”的说明。1.2 一个让我转向 Skill 思维的真实场景我在某开源学习社区组织过一次 AI Agent 组队学习，当时的任务之一是给 Agent 增加“网页表格抽取”能力。第一次尝试就是纯 Prompt：给模型看几个 HTML 片段，让它提取表格数据并输出 Markdown。结果很有意思。对规整的表格，模型表现很好；对带合并单元格、多层表头、或者表格嵌套在复杂布局里的页面，输出就开始离谱。更麻烦的是，抽取结果里偶尔混入页面导航栏里的文字，模型自己根本意识不到。这种“幻觉式抽取”不是靠提示词能修好的，因为问题不在模型理解能力，而在任务本身需要一个确定性的解析流程。后来我把这个功能重写成一个 Python 脚本，用专门的 HTML 解析库去识别表格节点，再写一个清晰的能力描述文档，告诉 Agent“什么时候调用这段代码，传什么参数，拿什么结果”。从那以后，输出稳定了，而且这套逻辑可以给任何 Agent 用，不需要重新调 Prompt。这个转变，就是“从 Prompt 工程走向软件工程”的起点：把模型擅长的事情（意图理解、计划制定、内容生成）留给模型，把模型不擅长的事情（精确定位字符、解析结构化数据、调用外部系统）交给确定性代码。而 Agent Skills，正是承载这种分工的标准容器。1.3 “软件工程”在这里到底指什么很多人一听“走向软件工程”，以为是要上微服务、K8s，其实没那么玄。在 Agent Skills 的语境下，软件工程指的是四件事：版本管理：技能包有版本号，改了逻辑不影响旧调用方，可以随时回滚。接口契约：技能有明确的入参、出参、错误码，调用方（模型或代码）可以按约定使用。测试机制：每个技能可以写自动化测试，跑一次就知道有没有改坏。依赖声明：技能依赖哪些库、需要什么运行环境，写清楚，别人拿到就能跑。一句话：把“能力”当作“软件模块”来管理，而不是当作“灵感”来发挥。Agent Skills 恰好就是这套思维的最小落地单元。2. Agent Skills 到底是什么：把能力封装成“可运行的说明书”2.1 核心概念：描述文件 + 脚本 + 依赖清单我第一次理解 Agent Skills 时，脑子里冒出来的类比是 Linux 的 man 手册加一个可执行文件。模型是用户，它遇到任务时先去“翻手册”（读技能描述），发现手册说“这个活我能干”，于是按手册里的指引去执行一段脚本，最后把结果拿回来处理。一个标准的 Skill 包通常包含三类内容：描述文件：告诉模型这个技能什么时候用、怎么用、有哪些限制。核心是 SKILL.md 这类 Markdown 文档。可执行脚本：真正干活的代码，可以是 Python、JavaScript、Shell，或者任何能在你的 Agent 运行环境里执行的语言。依赖与配置：脚本所需的第三方库、环境变量、配置文件，保证技能可以被干净地安装和运行。我见过的开源技能仓库里，目录结构一般都长这样：agent-skills/ ├── csv-to-json/ │ ├── SKILL.md │ ├── script.py │ └── requirements.txt ├── fetch-webpage/ │ ├── SKILL.md │ ├── fetch.py │ └── requirements.txt └── ...每个子目录就是一个独立技能。Agent 运行时按目录加载，把 SKILL.md 的内容注入上下文，让模型“知道有这个工具可用”，等模型决定调用后，再由运行时去执行对应脚本。2.2 一段描述与一段代码的本质区别理解 Agent Skills 的关键，是分清“模型负责什么”和“代码负责什么”。描述文件负责的是“决策”。模型读到 SKILL.md，认识到当前用户请求“把附件里的 Excel 转成 JSON”正好命中 csv-to-json 的技能描述，于是决定调用它。这个决策过程是模型擅长的：自然语言理解、意图匹配、参数提取。脚本负责的是“执行”。一旦模型确定了调用意图，剩下的就交给脚本：读文件、解析内容、做格式转换、输出结果。这段逻辑是确定性的，不会因为模型心情不好就漏掉一行数据。传统 Prompt 工程把两件事混在一起：决策靠文本，执行也靠文本。模型既要理解意图，又要“手算”每一个字符，结果自然是既不高效也不可靠。Skills 的核心价值，是让模型只在它擅长的层面做决策，把高精密操作交给代码。2.3 常见的 Skill 类型根据我的观察，现有生态里比较常见的技能包大致分四类：信息检索类：从文件、数据库、网页里提取指定内容，输出结构化结果。典型如读取 PDF、抓取网页、查询本地文件。数据转换类：把一种格式转成另一种。CSV 转 JSON、Markdown 转 HTML、日志清洗、字段映射。工具封装类：把外部 API、命令行工具包成统一接口。比如调用天气接口返回结构化数据，或者把图像压缩命令封装成一个函数。流程编排类：把多步操作固化成固定流程。比如“下载附件 → 解压 → 校验 → 汇总”一条龙服务。这些技能的一个共同点是：执行路径是确定的，不需要模型临场发挥。只有“确定能做好的事”，才值得封装成技能；那些需要开放思考、创意生成的任务，反而更适合直接对话式 Prompt。2.4 Prompt 工程与 Agent Skills 的一个直观对比我把两种方式在几个关键维度上的差异整理成了一张表，方便对照理解：维度Prompt 工程Agent Skills实现方式在提示词里描述指令和示例写代码实现功能，写文档描述用途稳定性依赖模型对措辞的理解，波动大代码逻辑固定，结果可预期复用性换场景基本要重调技能包可跨 Agent、跨项目复用可测试性难以自动化断言可写单元测试和集成测试定位边界适用于开放任务、生成式任务适用于确定性任务、固定流程维护方式调提示词、试错、碰运气改代码、发版本、跑测试这张表可以解释为什么“技能包”的提法越来越流行：它不是对 Prompt 工程的否定，而是给 Agent 补上了一个可靠的“手和脚”，让它不只是一个会说话的脑袋。3. 从零搭建一个可复用 Skill 的完整过程3.1 顶层目录与命名：先定规矩再动手我建议在一开始就建一个单独的目录来放所有技能包，比如agent-skills/。每一个技能包用短横线命名，全部小写，一眼能看出功能。我常用规则是“动词-对象”，例如fetch-webpage、parse-pdf、csv-to-json。命名这个事看起来无关紧要，但等你攒了二十个技能包之后就会明白，命名混乱是最令人头疼的问题。模型是通过 SKILL.md 的描述来匹配技能的，它不关心目录名，但你自己需要一眼找到目标技能。另外，很多运行时是按目录名加载技能的，如果命名有歧义，可能出现两个相似技能同时匹配用户请求的情况，导致模型不知道选哪个。3.2 SKILL.md 要写清楚“什么情况用、怎么用、注意什么”SKILL.md 是整个技能包的灵魂，但它不是给人类看的开发文档，而是给模型看的“操作手册”。模型依据这份文档判断是否调用、如何传参，所以写法跟传统 README 很不一样。我一般按这样的结构写：# 技能名称 ## 功能概述 这个技能做了什么，一句话说清。 ## 适用场景 什么时候应该调用这个技能？触发条件是什么？ 什么时候不应该调用？明确写出边界。 ## 输入参数 | 参数名 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | file_path | string | 是 | 待处理的文件路径 | | encoding | string | 否 | 文件编码，默认 utf-8 | ## 输出格式 返回什么结构的数据？给出一个具体示例。 ## 使用示例 举一个用户请求和技能调用的对应案例。 ## 注意事项 有哪些坑需要提醒模型？例如“文件不存在时返回错误码 404，不要尝试自行修复”。关键点在于“注意事项”这一节。模型看到技能描述后，会在调用时自动遵循这些限制。如果你不写“文件不存在就报错”，模型可能自作主张地编造一个空结果，这是最典型的幻觉来源。写清楚边界，等于把错误处理策略前置到决策阶段。3.3 核心脚本：真的写代码，而不是写提示词技能的核心脚本要遵循一个原则：输入输出尽量接近 SKILL.md 里声明的契约，用命令行接收参数，用标准输出返回结果。这样无论 Agent 运行时是本地进程、容器还是沙箱，都能统一对接。我以自己实现的一个 “markdown 表格转 CSV” 技能为例。脚本很短，但足够说明问题：#!/usr/bin/env python3 """markdown_table_to_csv.py - 把 Markdown 表格转换为 CSV 格式。""" import csv import io import re import sys def parse_markdown_table(md_text: str) -> list[list[str]]: lines = md_text.strip().splitlines() table_lines = [line for line in lines if line.startswith("|")] if not table_lines: return [] header = _split_row(table_lines[0]) rows = [_split_row(line) for line in table_lines[2:]] return [header] + rows def _split_row(line: str) -> list[str]: stripped = line.strip().strip("|") cells = [cell.strip() for cell in stripped.split("|")] return cells def to_csv(rows: list[list[str]]) -> str: output = io.StringIO() writer = csv.writer(output, lineterminator="\n") writer.writerows(rows) return output.getvalue() def main(): md_text = sys.stdin.read() rows = parse_markdown_table(md_text) if not rows: print(json.dumps({"error": "no table found"}), file=sys.stderr) sys.exit(1) print(to_csv(rows)) if __name__ == "__main__": main()从这个例子可以看到，核心逻辑完全由代码掌控：正则匹配表格行、分隔单元格、跳过分隔行、用标准库解析 CSV 输出。没有给模型“发挥”的空间，结果自然稳定。现实中更复杂的技能也遵循同一套模型：标准输入进、标准输出出，错误走 stderr 并附带非零退出码。3.4 依赖与运行环境：让别人拿起来就能跑一个技能如果依赖第三方库，必须在 requirements.txt 里声明清楚，最好再附一句“用 Python 3.10+ 运行”。依赖声明看着琐碎，但它是技能可复用的前提。我曾经接过别人的技能包，里面用到了某个特定版本的数据处理库，文档里完全没提，结果在我本地环境一跑就报错，排查了半天。我建议每个技能包里至少包含：requirements.txt：列出直接依赖的库，尽量不要用“大于等于”的范围写法，锁定主版本即可。一个简短的运行说明：在 SKILL.md 的末尾附上“安装依赖：pip install -r requirements.txt”。尽量使用标准库：如果标准库能解决，就别引入外部依赖。依赖越少，技能越稳，越不容易出现环境冲突。3.5 本地加载与测试：先让脚本能跑，再让模型能调技能目录和脚本写好后，第一步是本地直接测功能，不要立刻接进 Agent。我的做法是先测脚本本身：echo "| name | age |\n| --- | --- |\n| Alice | 30 |" | python markdown_table_to_csv.py确认输出符合预期后，再写几组边界输入测异常：空表格、没有表头、多余空格。脚本的确定性保证在这里得到验证。下一步是“模拟模型调用”。这一步很关键：找一个支持工具调用的 LLM 接口（我常用本地模型和主流云模型各测一遍），给它注入 SKILL.md 的内容，并提供一个执行脚本的函数，然后观察模型是否能在合适的时机调用技能、是否用对了参数。这一步能暴露很多问题，最常见的是：模型把技能描述里没写的参数传进来。模型对多个相似技能产生混淆。模型在技能返回错误后，自作主张重试多次，而不是把错误返回给用户。发现这些问题后，修改的方向不是调提示词，而是改 SKILL.md 的描述，明确参数、边界和错误处理策略。这个过程很像在调接口文档，而不是在调 Prompt。4. 工程化落地时的关键决策与避坑4.1 什么时候该用 Skill，什么时候直接写代码一个我反复思考的问题：技能包和普通函数到底有什么区别？难道把功能写成一个 Python 函数、让 Agent 直接调用不就行了？确实可以，但 Agent Skills 有一个普通函数不具备的优势：它自带“决策说明”。模型不需要在代码里看到函数定义才知道该用它，而是通过读 SKILL.md 这样的自然语言描述，在对话上下文中主动发现技能的存在。这意味着技能可以被动态加载：Agent 遇到新任务时，从技能仓库里检索并注入相关描述，而不是把所有函数都塞进上下文。当技能数量有几十个上百个时，这个差别是致命的。我的判断标准是：如果这个功能会被多个 Agent 复用、需要独立于对话逻辑进行测试，就封装成 Skill；如果只是某个 Agent 内部的一次性 helper，写普通函数就够了。4.2 测试策略：不要只测代码，还要测“模型的理解”技能的测试比普通代码多一个维度。普通代码测试的是“输入输出是否正确”；技能测试还要加一条：“模型看了 SKILL.md 之后，能不能在正确时机调用它”。我用的测试方案分三层：第一层是单元测试。只测脚本逻辑，相当于你在任何 Python 项目里写的那种 testcase。第二层是描述测试。构造一批模拟的用户请求，把 SKILL.md 和请求一起喂给模型，看它是否触发了技能调用，调用参数是否满足契约。这层测试很灵活，我通常对每个技能准备 10 条左右的正例和负例，正例里预期技能被触发，负例里预期不触发。第三层是端到端测试。把技能装进一个真实的 Agent 应用里，模拟用户完整对话流程，验证最终体验。这层最花时间，但最能发现问题。很多技能写失败，不是代码写错了，而是 SKILL.md 写得含糊，模型压根不知道这个技能的存在，或者在错误时机错误调用。每一层测试都能从不同角度拦住问题。4.3 版本管理与兼容性：技能也会演化技能一旦接入线上 Agent，就要考虑版本管理。我最开始完全忽略这点：想改某个技能的行为，直接改脚本，结果旧对话里已经缓存的 Agent 行为和新行为不一致，出了不少问题。现在的做法是给每个技能加version字段，写在 SKILL.md 的头部。改代码时更新版本号，并在头部记录变更摘要。这样即使运行时只加载了旧描述，你也能从日志里追踪到具体版本，快速定位问题。另一个跟版本相关的坑是“描述与代码不同步”。有时你只改了脚本逻辑，忘了更新 SKILL.md，模型还是在按旧描述调用技能，参数对不上，运行时报错。这个只能靠人为自律：每次改脚本必须同步改描述，最好在代码评审清单里加上这一条。4.4 安全边界：别让模型把技能当万能执行器技能包的引入给 Agent 带来了执行能力，也带来了新的安全风险。最典型的风险点有三个：第一，任意命令执行风险。如果技能包允许传入任意 Shell 命令，模型一旦被提示词注入攻击，就可能让 Agent 执行恶意命令。我的建议是技能接口尽量收窄，不要暴露通用执行接口，而是暴露“封装好的具体操作”，比如“重命名文件”而不是“执行任意命令”。第二，路径穿越风险。文件处理类技能如果直接拼接用户提供的路径，可能读取到预期之外的文件。脚本里要校验输入路径是否在允许的根目录之内。第三，外部资源访问。涉及网络请求的技能，要限制目标域名范围，避免 SSRF 类问题。我在封装网页抓取技能时，就加了一个简单的域名白名单。安全设计不需要很复杂，但必须有边界意识。技能越强大，边界越要收紧。4.5 团队协作：技能仓库也要有“评审机制”当多个人一起维护技能仓库时，就出现了一个非常“软件工程”的问题：如何保证技能质量。我所在的团队，技能合并到主分支前至少要过三关：代码评审：看脚本是否有明显 bug、是否有安全隐患。描述评审：看 SKILL.md 是否清楚、会不会误导模型。测试通过：要求新增技能必须附带至少一层测试。这些流程不是凭空想出来的，而是踩过坑之后沉淀的。曾经有一个技能包，代码质量很高，但 SKILL.md 里把适用场景写得太宽泛，结果模型在用户问“怎么炖排骨”时调用了这个“读取菜谱文件”的技能，场面一度失控。把描述评审加入流程之后，这种低级误用明显少了很多。5. 从 Prompt 工程走向软件工程：思维转变的几点体会5.1 关注点从“调模型”转移到“设计系统”当我开始用 Agent Skills 组织能力后，一个很明显的感知是：我不再那么关心“模型会不会按我的提示词行事”，而是更关心“整个系统的边界和接口是否清晰”。Prompt 工程的核心动作是“试”：反复修改措辞，观察输出变化，直到满意。这是调模型。而 Agent Skills 的核心动作是“建”：确定边界，定义接口，实现逻辑，测试验证，版本管理。这是建系统。这种转变带来的是稳定性和可扩展性。以前每加一个能力，都要重新调一遍 Prompt，越调越复杂，越复杂越不稳定；现在加一个能力，就是新建一个技能包，装上之后哪里都能用。系统的复杂度从“一团提示词”变成了“一组可管理的模块”，心智负担完全不同。5.2 对个人开发者来说，这意味着“杠杆”技能包还有一个特别吸引我的特性：可组合性。做一个调研类 Agent，可以挂上“网页抓取”“PDF 解析”“摘要生成”三个技能；做一个数据处理类 Agent，可以挂上“CSV 清洗”“格式转换”“图表渲染”三个技能。同一套技能在不同 Agent 之间组合复用，形成自己的“私人工具链”。技能包本质上是把“会写特定代码的人”的经验，固化成可被任意语言模型调用的模块。这意味着你不用每次让模型从零开始理解某个业务领域，只需要告诉它“这个活用这个技能干”，它就能稳定输出结果。对于个体开发者，这种组合式杠杆的价值，怎么强调都不为过。5.3 最后分享一个技巧：先做减法，再做加法如果你正打算开始实践 Agent Skills，我的核心建议是：不要一开始就追求大而全的技能仓库，先从你能想到的、最确定的、最重复性的任务开始。做一个最小技能包，跑通从描述到调用到测试的完整流程，再逐步扩展。我在实际操作中最常见的问题是“过度设计”：把技能描述写得又长又细，把脚本抽象得又泛又复杂，结果模型反而不知道在什么场景下调用，测试也花了大量时间维护。后来我改成“描述只写必要信息，脚本只处理一种确定的输入输出”，技能包的可用性反而直线上升。另外，每次给 Agent 加完一个技能，记得留出时间观察真实使用中的错误日志，尤其是“模型想调用但没调用”“模型调用了但参数不对”这两类情况。它们是衡量 SKILL.md 质量最重要的信号。把这些信号定期梳理回填到描述文档里，技能会越用越顺。这些经验不来自什么高深理论，就是一次次改描述、改脚本、跑测试、看日志里磨出来的。Agent 的能力边界，说到底是由你封装的这些“技能”决定的。从一段提示词到一个技能包，不只是写法的变化，更是对“Agent 如何工作”这件事理解的升级。