尧图网站建设 
1. 从“skills”这个标题说起它到底指什么第一次看到“skills”这个标题很多人会以为是泛泛而谈的能力清单或者某个招聘网站的技能标签页。但结合热搜词里的 Agent Skills、Google Cloud、npx、AI agents、claude agent skills、codex skills 这些词来看这里说的 skills 并不是人类简历上的技能而是给 AI Agent 使用的一套可插拔能力包。你可以把它理解成给一个刚入职的实习生发的“岗位操作手册加工具箱”手册告诉他遇到什么情况该怎么做工具箱里放着具体能调用的脚本、模板和配置。我最早接触这个概念是在折腾 Claude 的 Agent 能力扩展时。当时我手里有一个需要反复执行的流程读取一批 Markdown 文档按固定规则抽取字段生成结构化表格再调用外部命令做校验。每次都要把这一长串要求重新贴进对话里既费 token 又容易漏步骤。后来我把这套流程写成一个 skill 目录里面放一个说明文件加几个脚本Agent 就能在需要时自动加载并执行。那一刻的感觉就是热搜词里说的“今天学会了 skills打开新世界”。所以这篇内容要聊的 skills核心定义是一种以目录和说明文件为载体的、面向 AI Agent 的能力封装形式。它通常包含一个描述元信息的入口文件、若干操作指令、可选的脚本与资源文件。Agent 在运行时根据任务匹配并加载对应 skill从而获得原本不具备的专门能力。它能解决的问题很具体把重复的、多步骤的、需要特定工具链的任务固化下来让 Agent 稳定复现而不是每次靠临场发挥。适合读这篇的人有三类。第一类是已经在用 Claude、Codex 这类 AI 编程助手的开发者想让 Agent 干更复杂的活第二类是做自动化流程、测试、文档处理的工程师想把现有脚本包装成 Agent 可调用的形式第三类是对 Agent Skills 好奇、想先搞清楚它和普通提示词、和 MCP 服务有什么区别的技术爱好者。下面我会从设计思路、目录结构、实操步骤、常见故障几个层面把它拆开讲尽量让没接触过的人也能照着做出来。2. 整体设计思路为什么是“目录加说明文件”这种形态2.1 从提示词工程到能力封装的演进逻辑早期让 AI 干复杂任务靠的是把要求写进对话里也就是提示词工程。但提示词有几个绕不开的毛病。一是长度受限流程一复杂就得压缩压缩就会丢细节。二是不可复用换个会话就得重贴一遍。三是无法携带可执行资源你没法在提示词里塞一个 Python 脚本进去让它直接跑。四是版本管理困难改了哪一版、哪一版效果好全靠人脑记。Agent Skills 的设计思路正是针对这四点。它把“怎么做”从对话里抽出来落到文件系统上。说明文件负责描述“什么时候用、按什么步骤做”脚本文件负责“具体执行”资源文件负责“提供模板和数据”。Agent 运行时只加载元信息做匹配真正需要时才读取完整内容这就解决了长度和复用问题。文件放在版本控制里改动可追溯这就解决了版本管理问题。我个人的判断是这种形态的本质是把过程性知识从即时上下文里剥离出来。过程性知识变化慢、复用高适合固化即时上下文变化快、针对性强适合留在对话里。两者分开各司其职Agent 的表现就稳定得多。2.2 与 MCP 服务、普通脚本的区别和取舍热搜词里同时出现了 claude mcpservers npx 和 agent skills说明很多人会把这两者混在一起。我按自己的理解做个区分。MCP 服务更像是一个常驻的能力服务器。它通过标准协议对外暴露工具、资源和提示模板Agent 连接上去就能调用。它的优势是能力集中、跨会话共享、适合对接外部系统。代价是需要单独进程、需要配置连接、调试链路更长。Skill 更像是一个按需加载的操作包。它不常驻Agent 判断当前任务匹配某个 skill 时才把它读进来。优势是轻量、无需额外进程、随项目走、易于分享。代价是它本身不提供运行时复杂逻辑还是得靠脚本或外部命令。普通脚本则是纯执行层没有“什么时候该用我”的元信息Agent 不知道它的存在除非你手动在提示词里指明。所以取舍很清楚需要跨项目共享、需要对接外部 API、需要长期运行的能力用 MCP 服务更合适需要跟随项目、需要固化操作流程、需要轻量分发的用 skill 更合适。两者并不冲突实际项目里经常是 skill 负责编排流程MCP 服务负责提供底层工具。2.3 一个 skill 应该封装到什么粒度这是设计阶段最容易踩的坑。粒度太细一个 skill 只干一件事Agent 要加载一堆 skill 才能完成一个任务匹配开销大、协调复杂。粒度太粗一个 skill 包山包海说明文件写了几千行Agent 读进来就占满上下文反而降低效果。我的经验法则是一个 skill 对应一类可独立描述的任务。判断标准是你能不能用一句话说清“这个 skill 是干什么的”并且这句话里不出现“然后”“接着”“顺便”这类连接词。比如“把 Markdown 文档转成结构化表格”是一个合适的粒度“读取文档、清洗数据、生成表格、发送邮件”就太粗应该拆成读取清洗、生成表格、发送通知三个 skill再用一个上层流程把它们串起来。另一个判断维度是复用频率。高频复用的流程值得单独成 skill一次性任务直接写在对话里就行没必要封装。我见过有人把只跑一次的数据迁移脚本也做成 skill结果项目结束就再没用过纯属浪费时间。3. 核心细节解析一个 skill 目录里到底放什么3.1 入口说明文件的字段与写法入口说明文件是整个 skill 的门面Agent 首先读的就是它。不同平台的字段命名略有差异但核心信息是一致的。我按通用结构来讲你迁移到具体平台时对照官方文档调整字段名即可。必备字段通常包括名称、描述、适用场景。名称要短、要唯一、用英文小写加连字符比如markdown-to-table。描述要一句话说清能力边界不要写“强大的”“智能的”这类形容词Agent 匹配靠的是语义形容词只会干扰判断。适用场景要写清楚什么情况下该触发这个 skill最好带上典型输入输出的例子。可选字段包括版本号、作者、依赖项、允许使用的工具列表。依赖项这块要特别注意如果 skill 里的脚本依赖某个命令行工具一定要在入口文件里声明否则 Agent 在别的环境里加载后会执行失败。允许使用的工具列表是安全边界限制这个 skill 只能调用哪些工具避免它越权操作。我写入口文件有个习惯把“不适用场景”也写进去。比如一个处理 CSV 的 skill我会明确写“不适用于 Excel 二进制格式遇到 xlsx 请先转换”。这样能显著减少 Agent 误用的情况。这个技巧在官方文档里很少提但实测下来非常有用。3.2 脚本与资源文件的组织方式脚本文件放在 skill 目录下的子目录里常见命名是scripts或bin。资源文件放resources或assets。说明文件里引用这些文件时用相对路径不要用绝对路径否则换台机器就失效。脚本的语言选择上我优先用 Python 和 Shell。Python 跨平台好、库丰富适合做数据处理Shell 适合做流程编排和调用外部命令。Node.js 也可以但要注意 npx 相关的依赖安装问题热搜词里 npx playwright install 失败就是个典型后面故障排查部分会细讲。资源文件要控制体积。模板、配置、示例数据可以放大文件不要放。我见过有人把几百兆的模型文件塞进 skill 目录结果分发时痛苦不堪。大文件应该放在外部存储skill 里只放下载或引用的脚本。还有一个细节脚本要有可执行权限并且要有清晰的退出码。Agent 判断脚本是否成功靠的是退出码和标准输出。退出码为 0 表示成功非 0 表示失败标准错误里写清楚失败原因。这一点如果做不好Agent 拿到失败结果也不知道该怎么办只能干瞪眼。3.3 元信息如何影响 Agent 的匹配与加载Agent 决定用不用某个 skill靠的是元信息和当前任务的语义匹配。这个过程通常是两阶段先粗筛把所有 skill 的名称和描述拿出来和任务做相似度比较选出候选再精读把候选 skill 的完整说明读进来确认是否真的适用。这个机制决定了两件事。第一描述写得准不准直接决定 skill 会不会被选中。描述太泛什么任务都匹配会被频繁误加载描述太窄真正需要时又匹配不上。第二说明文件的长度要控制。粗筛阶段只读元信息精读阶段才读全文但如果全文太长精读阶段会占用大量上下文影响后续任务执行。我的做法是把说明文件分成两层入口文件只放元信息和简短概述详细步骤放在同目录的另一个文件里入口文件里用链接指向它。Agent 确认要用这个 skill 后再按需读取详细步骤。这样粗筛快、精读省整体效率高很多。4. 实操过程从零做一个可用的 skill4.1 环境准备与目录初始化先确认你的运行环境。我用的是 macOS 加 Python 3.11Linux 下流程基本一致Windows 下建议用 WSL避免路径和权限的坑。检查 Python 版本用python3 --version检查 pip 用pip3 --version。如果要做 Node 相关的 skill再确认node --version和npm --version。目录初始化我习惯用命令行建清晰可控。假设 skill 名叫doc-extract放在项目的.skills目录下mkdir -p .skills/doc-extract/scripts mkdir -p .skills/doc-extract/resources touch .skills/doc-extract/SKILL.md touch .skills/doc-extract/scripts/extract.py这里.skills是存放所有 skill 的根目录每个 skill 一个子目录。用点开头是为了和业务代码区分也方便在版本控制里单独配置忽略规则。SKILL.md 是入口说明文件这个命名是常见约定具体平台可能要求别的名字按平台文档来。初始化完成后先别急着写内容用tree .skills看一眼结构确认目录层级正确。结构错了后面全乱这一步花十秒确认很值。4.2 编写入口说明文件的完整示例下面是我实际在用的一个入口文件模板做了脱敏处理你可以直接改成自己的场景--- name: doc-extract description: 从 Markdown 文档中抽取指定字段并输出为 CSV 表格适用于批量文档结构化处理 version: 1.0.0 dependencies: - python3 - pandas allowed-tools: - read_file - write_file - run_script --- # 文档字段抽取 ## 适用场景 当用户需要从一批 Markdown 文档中抽取标题、日期、作者、摘要等字段 并整理成表格时使用本 skill。 ## 不适用场景 - 输入为 PDF 或 Word 二进制格式请先转换为 Markdown - 需要抽取的字段没有固定格式需要人工判断 ## 操作步骤 1. 确认输入目录路径和输出文件路径 2. 运行 scripts/extract.py传入输入目录和输出路径 3. 检查输出 CSV 的行数和字段完整性 4. 如发现字段缺失查看脚本标准错误输出定位问题 ## 示例 输入docs/ 目录下 20 个 Markdown 文件 输出result.csv包含 title、date、author、summary 四列这个模板里frontmatter 部分放元信息正文部分放人看的说明。注意描述里带了“批量文档结构化处理”这个关键词这是为了匹配时更容易被选中。不适用场景单独成节减少误用。4.3 脚本编写与参数传递的实操要点脚本是 skill 的执行核心。我以extract.py为例讲几个关键点。第一参数用命令行传入不要硬编码路径。第二输出用标准输出和标准错误区分成功信息走 stdout错误信息走 stderr。第三退出码要明确成功返回 0失败返回非 0。import sys import os import csv import re def extract_fields(filepath): with open(filepath, r, encodingutf-8) as f: content f.read() title re.search(r^#\s(.)$, content, re.MULTILINE) date re.search(r日期[:]\s*(\S), content) author re.search(r作者[:]\s*(\S), content) return { title: title.group(1) if title else , date: date.group(1) if date else , author: author.group(1) if author else , } def main(): if len(sys.argv) 3: print(用法: extract.py 输入目录 输出文件, filesys.stderr) sys.exit(1) input_dir, output_file sys.argv[1], sys.argv[2] if not os.path.isdir(input_dir): print(f输入目录不存在: {input_dir}, filesys.stderr) sys.exit(2) rows [] for name in sorted(os.listdir(input_dir)): if name.endswith(.md): fields extract_fields(os.path.join(input_dir, name)) fields[file] name rows.append(fields) with open(output_file, w, encodingutf-8, newline) as f: writer csv.DictWriter(f, fieldnames[file, title, date, author]) writer.writeheader() writer.writerows(rows) print(f完成共处理 {len(rows)} 个文件输出到 {output_file}) if __name__ __main__: main()这段脚本里参数校验、目录检查、错误输出、退出码都齐了。Agent 调用后如果退出码非 0它会读 stderr 里的信息知道是参数问题还是目录问题从而决定下一步。如果退出码为 0它读 stdout 里的完成信息确认处理了多少文件。这种约定让 Agent 和脚本之间的协作变得可靠。4.4 本地验证与调试的完整流程写完脚本别急着交给 Agent先在本地手动跑一遍。这是最容易被跳过、也最容易出问题的一步。cd .skills/doc-extract python3 scripts/extract.py ../../docs /tmp/result.csv echo 退出码: $? head -5 /tmp/result.csv先看退出码是不是 0再看输出文件的前几行确认字段抽取正确。如果字段为空检查正则是不是没匹配上把文档里的实际格式打印出来对比。我踩过的坑是文档里日期格式有全角和半角冒号混用正则只写了半角结果一半文件抽不到日期。后来把正则改成[:]才解决。本地验证通过后再在 Agent 环境里加载测试。测试时故意给一个不存在的目录看 Agent 能不能正确报告错误再给一个空目录看它能不能处理边界情况。这些边界测试做完skill 才算基本可用。5. 常见问题与排查技巧实录5.1 npx 相关安装失败的排查思路热搜词里 npx playwright install 失败是个高频问题本质是 Node 生态的依赖安装问题和 skill 本身无关但会卡住依赖 Node 的 skill。排查顺序我一般是这样的。先看网络。npx 安装需要从包仓库拉取网络不通会直接失败。用npm config get registry看当前源如果源不可达换成可达的源再试。这一步能解决大部分问题。再看权限。全局安装需要写权限如果报 EACCES说明当前用户没有目标目录的写权限。解决办法是配置 npm 的全局目录到用户目录下而不是用管理员权限硬装。用管理员权限装出来的东西后续升级和维护都是麻烦。再看版本。Node 版本太低会导致某些包不兼容报错信息里通常有 engine 相关的提示。用node --version确认版本对照包的文档要求升级。我遇到过 Node 14 装新版 playwright 失败的情况升到 18 就好了。最后看缓存。npm 缓存损坏也会导致安装失败用npm cache clean --force清一下再试。这个操作要谨慎清完第一次安装会慢一些但能解决一些莫名其妙的报错。5.2 skill 不被加载或匹配错误的处理Agent 不加载你的 skill先查三件事。第一目录位置对不对。不同平台对 skill 存放路径有要求放错地方 Agent 根本扫不到。第二入口文件格式对不对。frontmatter 的语法错误会导致元信息解析失败Agent 读不到名称和描述自然无法匹配。第三描述和任务语义是否匹配。描述写得太偏Agent 匹配不上。匹配错误分两种。一种是该加载没加载解决办法是在描述里补充任务里常出现的关键词。另一种是不该加载却加载了解决办法是在描述里收紧边界把不适用场景写清楚。我有个 skill 因为描述里写了“处理文档”结果每次涉及文档的任务都被加载后来改成“从 Markdown 抽取固定字段生成 CSV”误加载就没了。还有一个隐蔽问题多个 skill 描述高度相似Agent 分不清该用哪个。这时候要么合并成一个 skill要么在描述里明确区分各自的适用边界。我倾向于合并因为让 Agent 做细粒度区分本身就不可靠。5.3 脚本执行权限与路径问题的速查表下面这张表是我整理的高频问题速查遇到报错先对照查一遍能省不少时间。现象可能原因排查方法解决方式脚本无法执行缺少可执行权限ls -l scripts/chmod x scripts/*.py找不到脚本路径写成了绝对路径检查说明文件里的引用改为相对路径依赖缺失未声明依赖或未安装运行脚本看报错在入口文件声明并安装输出为空输入路径错误或格式不符手动跑脚本看 stderr修正路径或调整解析逻辑中文乱码编码未指定检查文件读写编码统一用 utf-8退出码非 0脚本内部异常看 stderr 具体信息按错误信息定位修复这张表里的每一条我都实际遇到过。权限问题最常见尤其是从别处拷贝过来的 skill权限位经常丢失。路径问题第二常见很多人习惯写绝对路径换环境就崩。编码问题在处理中文文档时几乎必现统一用 utf-8 能避免绝大多数乱码。5.4 我踩过的三个真实坑与避坑建议第一个坑是把 skill 当成了万能容器。我早期做了一个 skill想让它同时处理文档抽取、格式转换、邮件发送三件事。结果说明文件写了八百多行Agent 每次加载都占用大量上下文执行到一半就忘了前面的步骤。后来拆成三个独立 skill每个只干一件事稳定性立刻上来了。教训是skill 的边界要清晰宁可多拆几个不要贪大求全。第二个坑是忽略了脚本的幂等性。有个 skill 会往输出文件里追加内容我测试时跑了两遍结果数据重复了。Agent 在重试时也会重复执行导致输出污染。后来改成先清空再写入或者用时间戳生成新文件名问题才解决。凡是会写文件的 skill都要考虑重复执行的情况。第三个坑是没有做输入校验。有次 Agent 传进来的目录路径带了个尾部斜杠脚本里的字符串拼接出了双斜杠在某些系统上能跑在某些系统上就报错。后来在脚本开头统一做路径规范化用os.path.normpath处理跨平台问题就没了。输入校验这件事做的时候觉得多余出问题的时候才知道值。6. 进阶玩法让 skills 组合起来干活6.1 用上层流程编排多个 skill单个 skill 能力有限真正复杂的任务需要多个 skill 协作。我的做法是写一个编排型的 skill它本身不干具体活只负责按顺序调用其他 skill并在中间做数据传递和错误处理。比如一个“文档处理流水线”的编排 skill步骤是先调用doc-extract抽取字段再调用> Agent Skills 实战：为 AI Agent 封装可插拔能力包
1. 从“skills”这个标题说起它到底指什么第一次看到“skills”这个标题很多人会以为是泛泛而谈的能力清单或者某个招聘网站的技能标签页。但结合热搜词里的 Agent Skills、Google Cloud、npx、AI agents、claude agent skills、codex skills 这些词来看这里说的 skills 并不是人类简历上的技能而是给 AI Agent 使用的一套可插拔能力包。你可以把它理解成给一个刚入职的实习生发的“岗位操作手册加工具箱”手册告诉他遇到什么情况该怎么做工具箱里放着具体能调用的脚本、模板和配置。我最早接触这个概念是在折腾 Claude 的 Agent 能力扩展时。当时我手里有一个需要反复执行的流程读取一批 Markdown 文档按固定规则抽取字段生成结构化表格再调用外部命令做校验。每次都要把这一长串要求重新贴进对话里既费 token 又容易漏步骤。后来我把这套流程写成一个 skill 目录里面放一个说明文件加几个脚本Agent 就能在需要时自动加载并执行。那一刻的感觉就是热搜词里说的“今天学会了 skills打开新世界”。所以这篇内容要聊的 skills核心定义是一种以目录和说明文件为载体的、面向 AI Agent 的能力封装形式。它通常包含一个描述元信息的入口文件、若干操作指令、可选的脚本与资源文件。Agent 在运行时根据任务匹配并加载对应 skill从而获得原本不具备的专门能力。它能解决的问题很具体把重复的、多步骤的、需要特定工具链的任务固化下来让 Agent 稳定复现而不是每次靠临场发挥。适合读这篇的人有三类。第一类是已经在用 Claude、Codex 这类 AI 编程助手的开发者想让 Agent 干更复杂的活第二类是做自动化流程、测试、文档处理的工程师想把现有脚本包装成 Agent 可调用的形式第三类是对 Agent Skills 好奇、想先搞清楚它和普通提示词、和 MCP 服务有什么区别的技术爱好者。下面我会从设计思路、目录结构、实操步骤、常见故障几个层面把它拆开讲尽量让没接触过的人也能照着做出来。2. 整体设计思路为什么是“目录加说明文件”这种形态2.1 从提示词工程到能力封装的演进逻辑早期让 AI 干复杂任务靠的是把要求写进对话里也就是提示词工程。但提示词有几个绕不开的毛病。一是长度受限流程一复杂就得压缩压缩就会丢细节。二是不可复用换个会话就得重贴一遍。三是无法携带可执行资源你没法在提示词里塞一个 Python 脚本进去让它直接跑。四是版本管理困难改了哪一版、哪一版效果好全靠人脑记。Agent Skills 的设计思路正是针对这四点。它把“怎么做”从对话里抽出来落到文件系统上。说明文件负责描述“什么时候用、按什么步骤做”脚本文件负责“具体执行”资源文件负责“提供模板和数据”。Agent 运行时只加载元信息做匹配真正需要时才读取完整内容这就解决了长度和复用问题。文件放在版本控制里改动可追溯这就解决了版本管理问题。我个人的判断是这种形态的本质是把过程性知识从即时上下文里剥离出来。过程性知识变化慢、复用高适合固化即时上下文变化快、针对性强适合留在对话里。两者分开各司其职Agent 的表现就稳定得多。2.2 与 MCP 服务、普通脚本的区别和取舍热搜词里同时出现了 claude mcpservers npx 和 agent skills说明很多人会把这两者混在一起。我按自己的理解做个区分。MCP 服务更像是一个常驻的能力服务器。它通过标准协议对外暴露工具、资源和提示模板Agent 连接上去就能调用。它的优势是能力集中、跨会话共享、适合对接外部系统。代价是需要单独进程、需要配置连接、调试链路更长。Skill 更像是一个按需加载的操作包。它不常驻Agent 判断当前任务匹配某个 skill 时才把它读进来。优势是轻量、无需额外进程、随项目走、易于分享。代价是它本身不提供运行时复杂逻辑还是得靠脚本或外部命令。普通脚本则是纯执行层没有“什么时候该用我”的元信息Agent 不知道它的存在除非你手动在提示词里指明。所以取舍很清楚需要跨项目共享、需要对接外部 API、需要长期运行的能力用 MCP 服务更合适需要跟随项目、需要固化操作流程、需要轻量分发的用 skill 更合适。两者并不冲突实际项目里经常是 skill 负责编排流程MCP 服务负责提供底层工具。2.3 一个 skill 应该封装到什么粒度这是设计阶段最容易踩的坑。粒度太细一个 skill 只干一件事Agent 要加载一堆 skill 才能完成一个任务匹配开销大、协调复杂。粒度太粗一个 skill 包山包海说明文件写了几千行Agent 读进来就占满上下文反而降低效果。我的经验法则是一个 skill 对应一类可独立描述的任务。判断标准是你能不能用一句话说清“这个 skill 是干什么的”并且这句话里不出现“然后”“接着”“顺便”这类连接词。比如“把 Markdown 文档转成结构化表格”是一个合适的粒度“读取文档、清洗数据、生成表格、发送邮件”就太粗应该拆成读取清洗、生成表格、发送通知三个 skill再用一个上层流程把它们串起来。另一个判断维度是复用频率。高频复用的流程值得单独成 skill一次性任务直接写在对话里就行没必要封装。我见过有人把只跑一次的数据迁移脚本也做成 skill结果项目结束就再没用过纯属浪费时间。3. 核心细节解析一个 skill 目录里到底放什么3.1 入口说明文件的字段与写法入口说明文件是整个 skill 的门面Agent 首先读的就是它。不同平台的字段命名略有差异但核心信息是一致的。我按通用结构来讲你迁移到具体平台时对照官方文档调整字段名即可。必备字段通常包括名称、描述、适用场景。名称要短、要唯一、用英文小写加连字符比如markdown-to-table。描述要一句话说清能力边界不要写“强大的”“智能的”这类形容词Agent 匹配靠的是语义形容词只会干扰判断。适用场景要写清楚什么情况下该触发这个 skill最好带上典型输入输出的例子。可选字段包括版本号、作者、依赖项、允许使用的工具列表。依赖项这块要特别注意如果 skill 里的脚本依赖某个命令行工具一定要在入口文件里声明否则 Agent 在别的环境里加载后会执行失败。允许使用的工具列表是安全边界限制这个 skill 只能调用哪些工具避免它越权操作。我写入口文件有个习惯把“不适用场景”也写进去。比如一个处理 CSV 的 skill我会明确写“不适用于 Excel 二进制格式遇到 xlsx 请先转换”。这样能显著减少 Agent 误用的情况。这个技巧在官方文档里很少提但实测下来非常有用。3.2 脚本与资源文件的组织方式脚本文件放在 skill 目录下的子目录里常见命名是scripts或bin。资源文件放resources或assets。说明文件里引用这些文件时用相对路径不要用绝对路径否则换台机器就失效。脚本的语言选择上我优先用 Python 和 Shell。Python 跨平台好、库丰富适合做数据处理Shell 适合做流程编排和调用外部命令。Node.js 也可以但要注意 npx 相关的依赖安装问题热搜词里 npx playwright install 失败就是个典型后面故障排查部分会细讲。资源文件要控制体积。模板、配置、示例数据可以放大文件不要放。我见过有人把几百兆的模型文件塞进 skill 目录结果分发时痛苦不堪。大文件应该放在外部存储skill 里只放下载或引用的脚本。还有一个细节脚本要有可执行权限并且要有清晰的退出码。Agent 判断脚本是否成功靠的是退出码和标准输出。退出码为 0 表示成功非 0 表示失败标准错误里写清楚失败原因。这一点如果做不好Agent 拿到失败结果也不知道该怎么办只能干瞪眼。3.3 元信息如何影响 Agent 的匹配与加载Agent 决定用不用某个 skill靠的是元信息和当前任务的语义匹配。这个过程通常是两阶段先粗筛把所有 skill 的名称和描述拿出来和任务做相似度比较选出候选再精读把候选 skill 的完整说明读进来确认是否真的适用。这个机制决定了两件事。第一描述写得准不准直接决定 skill 会不会被选中。描述太泛什么任务都匹配会被频繁误加载描述太窄真正需要时又匹配不上。第二说明文件的长度要控制。粗筛阶段只读元信息精读阶段才读全文但如果全文太长精读阶段会占用大量上下文影响后续任务执行。我的做法是把说明文件分成两层入口文件只放元信息和简短概述详细步骤放在同目录的另一个文件里入口文件里用链接指向它。Agent 确认要用这个 skill 后再按需读取详细步骤。这样粗筛快、精读省整体效率高很多。4. 实操过程从零做一个可用的 skill4.1 环境准备与目录初始化先确认你的运行环境。我用的是 macOS 加 Python 3.11Linux 下流程基本一致Windows 下建议用 WSL避免路径和权限的坑。检查 Python 版本用python3 --version检查 pip 用pip3 --version。如果要做 Node 相关的 skill再确认node --version和npm --version。目录初始化我习惯用命令行建清晰可控。假设 skill 名叫doc-extract放在项目的.skills目录下mkdir -p .skills/doc-extract/scripts mkdir -p .skills/doc-extract/resources touch .skills/doc-extract/SKILL.md touch .skills/doc-extract/scripts/extract.py这里.skills是存放所有 skill 的根目录每个 skill 一个子目录。用点开头是为了和业务代码区分也方便在版本控制里单独配置忽略规则。SKILL.md 是入口说明文件这个命名是常见约定具体平台可能要求别的名字按平台文档来。初始化完成后先别急着写内容用tree .skills看一眼结构确认目录层级正确。结构错了后面全乱这一步花十秒确认很值。4.2 编写入口说明文件的完整示例下面是我实际在用的一个入口文件模板做了脱敏处理你可以直接改成自己的场景--- name: doc-extract description: 从 Markdown 文档中抽取指定字段并输出为 CSV 表格适用于批量文档结构化处理 version: 1.0.0 dependencies: - python3 - pandas allowed-tools: - read_file - write_file - run_script --- # 文档字段抽取 ## 适用场景 当用户需要从一批 Markdown 文档中抽取标题、日期、作者、摘要等字段 并整理成表格时使用本 skill。 ## 不适用场景 - 输入为 PDF 或 Word 二进制格式请先转换为 Markdown - 需要抽取的字段没有固定格式需要人工判断 ## 操作步骤 1. 确认输入目录路径和输出文件路径 2. 运行 scripts/extract.py传入输入目录和输出路径 3. 检查输出 CSV 的行数和字段完整性 4. 如发现字段缺失查看脚本标准错误输出定位问题 ## 示例 输入docs/ 目录下 20 个 Markdown 文件 输出result.csv包含 title、date、author、summary 四列这个模板里frontmatter 部分放元信息正文部分放人看的说明。注意描述里带了“批量文档结构化处理”这个关键词这是为了匹配时更容易被选中。不适用场景单独成节减少误用。4.3 脚本编写与参数传递的实操要点脚本是 skill 的执行核心。我以extract.py为例讲几个关键点。第一参数用命令行传入不要硬编码路径。第二输出用标准输出和标准错误区分成功信息走 stdout错误信息走 stderr。第三退出码要明确成功返回 0失败返回非 0。import sys import os import csv import re def extract_fields(filepath): with open(filepath, r, encodingutf-8) as f: content f.read() title re.search(r^#\s(.)$, content, re.MULTILINE) date re.search(r日期[:]\s*(\S), content) author re.search(r作者[:]\s*(\S), content) return { title: title.group(1) if title else , date: date.group(1) if date else , author: author.group(1) if author else , } def main(): if len(sys.argv) 3: print(用法: extract.py 输入目录 输出文件, filesys.stderr) sys.exit(1) input_dir, output_file sys.argv[1], sys.argv[2] if not os.path.isdir(input_dir): print(f输入目录不存在: {input_dir}, filesys.stderr) sys.exit(2) rows [] for name in sorted(os.listdir(input_dir)): if name.endswith(.md): fields extract_fields(os.path.join(input_dir, name)) fields[file] name rows.append(fields) with open(output_file, w, encodingutf-8, newline) as f: writer csv.DictWriter(f, fieldnames[file, title, date, author]) writer.writeheader() writer.writerows(rows) print(f完成共处理 {len(rows)} 个文件输出到 {output_file}) if __name__ __main__: main()这段脚本里参数校验、目录检查、错误输出、退出码都齐了。Agent 调用后如果退出码非 0它会读 stderr 里的信息知道是参数问题还是目录问题从而决定下一步。如果退出码为 0它读 stdout 里的完成信息确认处理了多少文件。这种约定让 Agent 和脚本之间的协作变得可靠。4.4 本地验证与调试的完整流程写完脚本别急着交给 Agent先在本地手动跑一遍。这是最容易被跳过、也最容易出问题的一步。cd .skills/doc-extract python3 scripts/extract.py ../../docs /tmp/result.csv echo 退出码: $? head -5 /tmp/result.csv先看退出码是不是 0再看输出文件的前几行确认字段抽取正确。如果字段为空检查正则是不是没匹配上把文档里的实际格式打印出来对比。我踩过的坑是文档里日期格式有全角和半角冒号混用正则只写了半角结果一半文件抽不到日期。后来把正则改成[:]才解决。本地验证通过后再在 Agent 环境里加载测试。测试时故意给一个不存在的目录看 Agent 能不能正确报告错误再给一个空目录看它能不能处理边界情况。这些边界测试做完skill 才算基本可用。5. 常见问题与排查技巧实录5.1 npx 相关安装失败的排查思路热搜词里 npx playwright install 失败是个高频问题本质是 Node 生态的依赖安装问题和 skill 本身无关但会卡住依赖 Node 的 skill。排查顺序我一般是这样的。先看网络。npx 安装需要从包仓库拉取网络不通会直接失败。用npm config get registry看当前源如果源不可达换成可达的源再试。这一步能解决大部分问题。再看权限。全局安装需要写权限如果报 EACCES说明当前用户没有目标目录的写权限。解决办法是配置 npm 的全局目录到用户目录下而不是用管理员权限硬装。用管理员权限装出来的东西后续升级和维护都是麻烦。再看版本。Node 版本太低会导致某些包不兼容报错信息里通常有 engine 相关的提示。用node --version确认版本对照包的文档要求升级。我遇到过 Node 14 装新版 playwright 失败的情况升到 18 就好了。最后看缓存。npm 缓存损坏也会导致安装失败用npm cache clean --force清一下再试。这个操作要谨慎清完第一次安装会慢一些但能解决一些莫名其妙的报错。5.2 skill 不被加载或匹配错误的处理Agent 不加载你的 skill先查三件事。第一目录位置对不对。不同平台对 skill 存放路径有要求放错地方 Agent 根本扫不到。第二入口文件格式对不对。frontmatter 的语法错误会导致元信息解析失败Agent 读不到名称和描述自然无法匹配。第三描述和任务语义是否匹配。描述写得太偏Agent 匹配不上。匹配错误分两种。一种是该加载没加载解决办法是在描述里补充任务里常出现的关键词。另一种是不该加载却加载了解决办法是在描述里收紧边界把不适用场景写清楚。我有个 skill 因为描述里写了“处理文档”结果每次涉及文档的任务都被加载后来改成“从 Markdown 抽取固定字段生成 CSV”误加载就没了。还有一个隐蔽问题多个 skill 描述高度相似Agent 分不清该用哪个。这时候要么合并成一个 skill要么在描述里明确区分各自的适用边界。我倾向于合并因为让 Agent 做细粒度区分本身就不可靠。5.3 脚本执行权限与路径问题的速查表下面这张表是我整理的高频问题速查遇到报错先对照查一遍能省不少时间。现象可能原因排查方法解决方式脚本无法执行缺少可执行权限ls -l scripts/chmod x scripts/*.py找不到脚本路径写成了绝对路径检查说明文件里的引用改为相对路径依赖缺失未声明依赖或未安装运行脚本看报错在入口文件声明并安装输出为空输入路径错误或格式不符手动跑脚本看 stderr修正路径或调整解析逻辑中文乱码编码未指定检查文件读写编码统一用 utf-8退出码非 0脚本内部异常看 stderr 具体信息按错误信息定位修复这张表里的每一条我都实际遇到过。权限问题最常见尤其是从别处拷贝过来的 skill权限位经常丢失。路径问题第二常见很多人习惯写绝对路径换环境就崩。编码问题在处理中文文档时几乎必现统一用 utf-8 能避免绝大多数乱码。5.4 我踩过的三个真实坑与避坑建议第一个坑是把 skill 当成了万能容器。我早期做了一个 skill想让它同时处理文档抽取、格式转换、邮件发送三件事。结果说明文件写了八百多行Agent 每次加载都占用大量上下文执行到一半就忘了前面的步骤。后来拆成三个独立 skill每个只干一件事稳定性立刻上来了。教训是skill 的边界要清晰宁可多拆几个不要贪大求全。第二个坑是忽略了脚本的幂等性。有个 skill 会往输出文件里追加内容我测试时跑了两遍结果数据重复了。Agent 在重试时也会重复执行导致输出污染。后来改成先清空再写入或者用时间戳生成新文件名问题才解决。凡是会写文件的 skill都要考虑重复执行的情况。第三个坑是没有做输入校验。有次 Agent 传进来的目录路径带了个尾部斜杠脚本里的字符串拼接出了双斜杠在某些系统上能跑在某些系统上就报错。后来在脚本开头统一做路径规范化用os.path.normpath处理跨平台问题就没了。输入校验这件事做的时候觉得多余出问题的时候才知道值。6. 进阶玩法让 skills 组合起来干活6.1 用上层流程编排多个 skill单个 skill 能力有限真正复杂的任务需要多个 skill 协作。我的做法是写一个编排型的 skill它本身不干具体活只负责按顺序调用其他 skill并在中间做数据传递和错误处理。比如一个“文档处理流水线”的编排 skill步骤是先调用doc-extract抽取字段再调用>