1. 从会聊天到能干活Agent只差一张技能卡片先讲一个场景。几个月前我还在跟大多数用户一样把 Agent 当聊天框用——问它怎么写一段 Python 脚本帮我分析这段日志它答得头头是道但真让它去处理一件完整的事比如把这个 Markdown 文件按固定格式转成一整套技能包它就拉胯了要么步骤拆分不对要么中途自己改主意要么给出的结果格式前后不统一。说白了Agent 没有肌肉记忆每次都在临时发挥。后来开始折腾 Skill 技能系统才彻底想明白一件事聊天和干活之间的鸿沟靠的不是模型变聪明而是能不能把已知的最佳做法沉淀下来让 Agent 稳定复现。这就像老员工带新人——你嘴上讲一百遍流程不如甩给他一本操作手册加一套检查清单他照着做就不会跑偏。Skill 就是给 Agent 的这本操作手册也是这个系列第八篇要重点拆解的东西。什么是 Skill往简单了说它是一个结构化的能力单元包含元数据、指令、资源和验证方式让 Agent 在特定场景下自动加载一套经过验证的执行流程。往深了说它把一次性的 Prompt 调用升级成了可复用、可测试、可共享的能力模块。这篇内容适合谁两类人。第一类是正在做 Agent 开发的朋友无论是基于 Claude Code、Codex 还是自研框架Skill 都是绕不开的架构层第二类是重度使用 AI 工具、觉得 Agent 总是不够靠谱、想把它调教成顺手工具的进阶用户。读完你应该能自己动手写一个可用的 Skill并且理解它背后的设计逻辑而不是只停留在给 Agent 写个系统提示词的层面。2. Skill 机制拆解它和 Prompt、Plugin、Workflow 的本质区别很多人一开始会混淆 Skill 和 Prompt。我在不少技术社区里看到有人在问写了 Skill 是不是就等于写了个 Prompt答案是否定的。Prompt 是每次对话时塞给模型的上下文指令用完即弃没有结构没有版本概念更没有办法验证执行结果是否符合预期Skill 则是一个独立封装的单元它有明确的输入输出定义有可选的辅助脚本和资源文件还能挂上测试用例做回归验证。换个更生活化的比喻。Prompt 相当于你在餐厅口头跟厨师说少放盐、多放辣、要快厨师凭经验发挥Skill 相当于后厨墙上贴的标准菜谱加配料表和出餐检查单任何一位厨师甚至是新来的照着做出品都能稳定在及格线以上。差别不是写的字多字少而是有没有把隐性经验显性化、标准化、可复用化。再看 Plugin插件和 Workflow工作流。Plugin 是更偏重代码执行的外挂能力比如连数据库、调外部 API、操作文件系统本质上是给 Agent 加手Workflow 是多个步骤的编排强调先做 A、再做 B、再判断 C的流程控制。Skill 处在两者的中间地带它既可以完全不写代码纯靠指令和模板驱动也可以内嵌脚本、调用工具。用一个不太严谨但容易理解的坐标系来说——Plugin 解决的是能碰到什么Workflow 解决的是按什么顺序做Skill 解决的是这个任务到底该怎么做才算好。我个人理解 Skill 的核心价值是三层封装层把任务的目标、约束、输入、输出、步骤全部收进一个目录和日常对话上下文隔离不污染其他任务。激活层通过元数据里的描述让 Agent 在遇到相关任务时自动想起这套技能。这里有个关键技术点——激活成败取决于描述质量后文我会专门讲。验证层Skill 可以自带测试用例跑一遍就知道这次执行和预期差多少便于迭代这是 Prompt 完全做不到的。从这个角度看Skill 设计得好的话Agent 的行为会从随机应变变成按标准执行、异常时再随机应变。做 Agent 开发久了你会明白后者才叫能干活前者只配叫能聊天。3. 动手之前先理解一份 Skill 的骨架长什么样想写一个能用的 Skill不能拍脑袋直接写指令。我建议先理解它的目录和文件结构再谈内容。不同工具对 Skill 的实现略有差异但主干高度一致基本都是元数据 主指令 资源 测试这样的布局。下面以我在实际项目里比较常用的结构为例skill-book-to-skill/ ├── SKILL.md # 核心指令Agent 加载后首先读这个文件 ├── meta.yaml # 元数据名称、描述、触发词、输入输出、版本 ├── assets/ # 资源目录模板、示例、参考文档 │ ├── skill_template.md │ └── example_output.md ├── scripts/ # 可选辅助脚本如文件解析、格式转换 │ └── parse_skill.py └── tests/ # 测试集验证 Skill 行为是否符合预期 ├── test_case_1.md └── test_case_2.md你可能会问为什么非要把一套东西拆成这么多文件直接在一个 Markdown 里写清楚不行吗我在早期就是这么干的结果发现两个问题第一指令文件越写越长Agent 加载后光读上下文就占掉一大截留给真正推理的空间变小了导致执行质量下降第二没有独立的元数据文件Agent 判断该不该用这个 Skill时只能从正文里猜触发很不稳定。所以后来我老老实实做拆分让描述、指令、参考、验证各司其职。元数据是容易被新手忽略但极其实在的部分。拿我刚才提到的meta.yaml举例name: book-to-skill description: 把一本电子书的内容转化为一个可复用的Agent技能包。 适用于用户提供PDF/TXT/Markdown格式的书籍文件 要求提取核心方法论、步骤流程、检查清单并生成标准SKILL结构。 version: 1.0.0 triggers: - 把这本书变成技能 - book to skill - 提取这本书的方法论 inputs: book_path: 书籍文件的本地路径或上传路径 outputs: skill_dir: 生成的技能包目录这里最关键的是description。很多 Agent 框架的 Skill 调度逻辑是靠把描述嵌入系统提示或做向量检索来决定何时加载这个 Skill所以描述里必须说清楚什么场景用、什么输入、产生什么输出。写得太抽象Agent 可能在需要的时候想不到它写得太啰嗦又会挤占上下文窗口。这个描述密度的火候我建议反复打磨到一段话能说清类似写技术封装文档的摘要。SKILL.md是 Agent 真正照着干活的文件内容要写得更像标准作业规程而不是聊天记录。它一般包括任务目标、前置条件、执行步骤、输出格式、常见错误规避。写步骤的时候我习惯用动词开头 验收标准的格式例如解析输入文件读取书籍目录和章节结构确认内容完整输出章节大纲。提炼核心方法论按问题背景 — 解决方案 — 操作步骤 — 适用边界四段式整理不得主观扩写原文没有的内容。生成技能包目录按模板填充 SKILL.md、meta.yaml、assets每个文件必须有实际内容不允许用 TODO 占位。后面我会用一个完整案例带你走一遍这里先搭好架子。总之Skill 的结构本身不复杂难点在于每个文件的内容质量以及它们能否组合成一个可稳定复现的流程。4. 手把手开发把一本书变成一个可复用的技能包这个案例是从热搜词里book to skill这个方向想到的也是我在实际工作中被问得最多的需求——很多知识工作者手里有大量电子书、内部手册想让 Agent 读完并变成一项可调用的技能但不知道具体怎么做。下面一套流程我已经跑了很多遍直接抄作业即可。4.1 确定能力边界和输入输出第一件事不是写代码而是问自己这个 Skill 到底要封装什么能力注意能力边界一定不能贪大。比如处理书籍听起来很美好实际执行起来你会疯掉——书有技术书、小说、手册、论文集处理逻辑完全不一样。我建议把边界收敛到一个具体场景本案例中我选择的是把一本偏实操方法论的书转化为一个同样偏实操的技能包。输入输出定义如下输入书籍文件路径支持 PDF、TXT、Markdown外加用户的一句话指点方向可选例如我关心如何写技术方案输出一个标准 Skill 目录里面包含同名 SKILL.md、meta.yaml, assets 中的模板文件和示例输出明确输入输出之后后续所有步骤都有了锚点。我见过很多人卡在这一步总觉得到时候让 Agent 自己发挥就行结果输出五花八门根本没法用。4.2 写主指令 SKILL.md主指令我不建议从零开始憋可以先拉一个模板骨架再针对当前场景细化。以下是我在案例中用到的主指令核心段落做了脱敏简化# 任务定义 将输入的书籍内容转化为一个符合本库规范的 Skill 技能包。 # 前置条件 1. 输入文件必须存在且可解析如无法解析必须停止并说明原因。 2. 原书内容超过 500 页时只提炼目录、序言、每章小结、关键图表说明不得逐页展开。 # 执行步骤 1. 读取书籍结构生成章节大纲。 2. 识别书中反复出现的核心术语和方法论整理为术语表Glossary。 3. 对每个核心方法论章节提取背景、步骤、工具、成果物、注意事项五项内容。 4. 基于提炼结果填充 skill_template.md生成新技能包目录。 # 输出格式 输出目录必须包含 - meta.yaml填写 name、description、triggers - SKILL.md执行步骤不少于 10 条且全部为可操作指令 - assets/glossary.md术语表 - assets/workflow.md方法论流程总结 # 禁止行为 - 不得引入原书不存在的观点和方法。 - 不得仅生成大纲就结束必须生成完整可用文件。 - 不得在生成文件里写 TODO 或待补充。写主指令有两条经验必须分享。第一步骤粒度要适中——太粗会失控太细会把上下文撑爆。我一般控制在 5 到 10 大步骤每个步骤下面可以有一两个子项但不能无限细化。第二要有明确的禁止行为这对限制 Agent 自由发挥比正向指令更有效。像不得写 TODO这种约束能避免输出一堆半成品实测效果显著。4.3 准备资源文件和辅助脚本assets目录是很多 Starter 指南里不会细讲的部分但我觉得它是 Skill 质量的胜负手。你的 Skill 最终要生成一个新 Skill 包那总得有个模板吧这个模板放在 assets 里Agent 读取后照着填充比自己凭空编格式稳定得多。# 技能包模板skill_template.md ## 技能名称 !-- 一句话说明这个技能做什么 -- ## 适用场景 !-- 列出该技能可应对的任务类型 -- ## 执行步骤 !-- 编号列表每步必须是可操作动作 -- ## 输入要求 !-- 列出需要哪些外部输入 -- ## 输出规范 !-- 说明产出物的格式和质量标准 --辅助脚本在纯指令型 Skill 里不是必须的但当你需要处理 PDF 转文本、批量文件重命名、JSON 结构校验时脚本能让 Skill 的执行稳定度上一个台阶。我在这个案例里放了一个轻量 Python 脚本用来把 PDF 转成可解析的纯文本避免 Agent 拿到二进制内容后不知所措#!/usr/bin/env python3 # parse_pdf.py — 将 PDF 转为纯文本便于 Agent 后续处理 import sys from pathlib import Path from pypdf import PdfReader def convert_to_text(pdf_path: str, output_dir: str) - Path: reader PdfReader(pdf_path) text \n\n.join(page.extract_text() or for page in reader.pages) out_path Path(output_dir) / f{Path(pdf_path).stem}.txt out_path.write_text(text, encodingutf-8) return out_path if __name__ __main__: convert_to_text(sys.argv[1], sys.argv[2])放脚本有个注意点Agent 执行环境里不一定有对应依赖所以脚本要么用标准库实现要么在元数据里声明依赖项。我在meta.yaml里加了一行requires_python_packages: [pypdf]方便跑之前安装避免脚本运行到一半报错。搜索词里有一条agent execution terminated due to error我几乎能肯定就是这类环境问题造成的后面会专门讲怎么避免。4.4 设计验证用例并跑通Skill 写完之后立刻上线使用是新手常犯的错误。你必须先设计测试用例。不需要很复杂准备两个输入即可一个理想输入一个边界输入。理想输入是一本结构清晰、章节完整的书边界输入可以是一份只有十几页的 PDF 或纯 Markdown 笔记目的是检验 Skill 在面对原材料不足时会不会垮掉。我在测试这套 book-to-skill 流程时边界用例用的是自己一篇 20 页左右的 PDF 技术笔记。当时就发现一个 bug主指令里写了前置条件 2说超过 500 页才只提炼目录和小结但笔记只有 20 页Agent 反而不知道该做多细输出的技能包像一篇读书笔记不像技能包。后来调整指令明确不足 50 页时允许直接全文解析但技能包内的步骤必须仍然可操作问题才算解决。这也解释了为什么测试集对 Skill 如此重要——没有测试你就无法判断修改指令后行为是否变好。我见过很多人改了一轮 Prompt 觉得好像好点了其实只是这次运气好下次换了输入照样翻车。有测试集在你才能精准定位是哪个步骤出了问题。5. 让 Skill 真正被调度起来元数据描述和框架适配细节写好一个 Skill 只是第一步它要在真实 Agent 系统里被正确调度才算真正生效。这里有两个层面的问题一是触发机制二是上下文管理。5.1 触发机制主动触发和自动触发的取舍Skill 的触发方式主流 Agent 框架基本都支持两种我分别说下经验。主动触发就是用户明确说用某某技能来做这件事。这种方式的优点是确定性高但依赖用户记得有哪些 Skill 存在这不符合让 Agent 自动进化的愿景。更常见的是自动触发——框架根据用户输入匹配 Skill 的 description 和 triggers决定是否把 Skill 内容装入上下文。自动触发的效果完全取决于描述怎么写。我用个表总结一下不同写法的差异描述写法匹配效果典型问题知识管理工具过宽频繁误触发Skill 被加载但内容不相关浪费上下文提取书籍中的方法论并生成技能包适中推荐能覆盖核心场景边缘场景需靠 triggers 补适用于 PDF/TXT/Markdown 书籍的技能包生成器要求输入带章节结构输出为完整目录偏细匹配精准客户需求稍变就匹配不上需要额外触发词兜底我的实践结论是description 写场景 输入 输出三段式触发词列 5 到 8 个典型说法即可不要试图覆盖所有变体。搜热词里那些codex skillclaude code skill用不好十有八九就是 description 写得过于含糊——工具平台并不是不给能力是描述根本没法支撑调度器做判断。5.2 上下文管理别让 Skill 挤爆窗口Agent 加载 Skill 时实际上是把它当作一段系统级上下文喂给大模型。窗口有限每个 Skill 动辄几万字符的话加载几个就没什么剩余空间了。这个问题的解法是分级加载——只把元数据和 SKILL.md 主指令放上层辅助资源和脚本留在文件系统里Agent 在执行到对应步骤时按需读取。具体到代码层面很多框架支持在 SKILL.md 里通过相对路径引用资源文件例如# 执行步骤 1. 使用技能包模板见 assets/skill_template.md生成目标技能包。 2. 如有 PDF 输入先运行 scripts/parse_pdf.py 转为文本。这种做法有两个好处。第一主指令保持精简Agent 不用把模板内容也读进上下文第二资源文件作为工作参考资料随用随取内容超长也不影响主流程决策。我把这个模式比作目录和正文分开SKILL.md 是目录让 Agent 知道什么阶段该查什么assets 是正文需要时才打开。凡是把全部资料塞进 SKILL.md 的最后都会栽在长上下文导致的注意力分散上我踩过不建议你重蹈。5.3 框架适配从单机脚本到 Agent 框架的加载规范Skill 的加载在不同框架里细节不同。比如 Codex 这类工具通常会在工程目录下建固定的.agents/skills或.codex/skills目录Claude Code 则通常约定从工作区根目录的.claude/skills读取。还有热词里反复出现的 Hermes Agent、Pi Agent它们在配置上也有专门字段指向技能库目录。我建议你拿到一个新框架时先搞清楚三件事技能目录约定在哪、元数据格式是 JSON 还是 YAML、框架默认是否会全量加载所有技能。前两件查文档就能解决第三件才是重点——如果默认全量加载技能多了之后响应会变慢且不稳定。这种时候就要去配置里把加载策略改成按需检索或BM25 匹配不要让框架把所有技能一锅端进上下文。设定集里若有agent框架与编排这类热搜词基本都是在解决这个层面的问题。6. 踩坑实录我在 Skill 开发中反复经历的五个问题技术方案讲完说点偏经验的东西。下面这几个坑没有一个是冷门偏门问题都是大部分 Skill 开发者会在真实项目中遇到的每个我都栽过跟头写出来帮你省时间。6.1 描述写得太宽泛Skill 变成啥都沾一点的万金油有一次我把一个写周报的 Skill 描述写得特别宽生成工作总结、汇报材料、项目同步文案。结果用户问帮我写个项目简报这个 Skill 被触发了但生成的项目简报带着周报的模板味完全不符合简报的文体要求。原因就是我不该把不同输出格式的任务强行塞进一个 Skill。修法拆成weekly-report和project-brief两个技能各自描述边界。很多人觉得多一个技能多一套维护成本但实操下来边界清晰的多个轻量技能远比一个模糊的巨型技能好用——因为调度准确率上去了单次执行成功率也上去了。6.2 指令细节过度上下文爆炸早期写 SKILL.md 时我犯过追求详细的毛病把步骤写到了 30 多条塞了各种注意事项细节提示结果每次加载占用将近 15k token执行复杂任务时模型明显变笨。后来做了一次瘦身把所有需要展开的细节挪到 assets主指令压缩到 12 步左右每次加载成本降了 60%成功率反而提升。这说明一个道理Skill 的目的是提供稳定流程不是把模型变成一个背书的机器人过于详细的指令反而会让模型失去必要的灵活判断力。6.3 缺少测试集改一处毁三处这个坑是看起来没问题但时间久了最致命的典型。最初我没有给 Skill 配测试集所有修改凭感觉验证。某次为了优化一个技能的输出格式改动了模板结果同一个 Skill 在另一个输入端场景下输出开始出现空字段。因为没有测试用例花了半天才定位到是模板改动引入的回归问题。从那以后我给每个 Skill 至少配两个测试用例并且每次改完跑一遍全量测试。如果你不想项目上线后疲于奔命修 bug这一步不能省。6.4 技能内容写死了模型能力边界Skill 经常被人误解为只要写得好什么模型都能执行这是错的。各模型的能力差异非常大有些任务——比如复杂 PDF 解析、超长文档摘要、特定语种的指令理解——在 Claude 上表现不错换到另一个基座模型上可能完全走样。所以写 Skill 时要尽量做能力降级兼容主指令用中性的任务描述不要强依赖某个模型独有的特殊能力如果确实依赖就在 meta.yaml 里标注 recommended_model并在加载时做版本检查避免在弱模型上静默失败。还记得热词里那条execution terminated due to error吗很多类似错误就是因为技能指令和当前模型能力不匹配模型在某个环节做不了直接中止流程报错信息又不明确。6.5 忽略权限边界技能变成裸奔工具Skill 如果带了脚本或文件读写操作就会涉及权限问题。我见过一个文档批量整理的 Skill脚本里用了shutil.rmtree清理临时目录结果因为路径拼接处理不当差点把整个工作目录删了。这之后我给所有涉及破坏性操作的脚本加了三重保险路径白名单校验、执行前打印将要删除的文件列表、默认进入 dry-run 模式。Agent 开发里安全经常被排在功能后面但 Skill 一旦在正式场景中跑起来权限出问题是会出大事的。即使你的项目只在本地跑也建议至少把脚本的输入路径限制在某个明确目录内别让 Agent 获得超出预期的文件系统控制权。7. 从单个 Skill 到技能矩阵让 Agent 变成靠得住的老员工单个 Skill 能做成一件事多个 Skill 组织好了Agent 才算真正从聊天工具变成数字员工。这个转变我是在技能数超过十个之后才明显感受到的——之前每个 Skill 都是独立处理单一问题互相之间没有配合整体效率提升有限。后来我开始按技能矩阵的思路去做组织效果立刻不一样。技能矩阵的核心是四层结构基础技能层文件处理、格式转换、代码执行、网络请求等通用能力它们是其他技能的地基。领域技能层某个业务领域的具体流程比如数学建模设备运维日志分析电商周报生成它们内部会调用基础层能力。编排技能层把多个领域技能按顺序组合成一整套流程。比如客户问题处理可以编排出信息收集 → 归因分析 → 解决方案生成 → 回执输出四个环节。治理技能层负责检查其他技能输出的质量做安全审查和一致性校验。这个层级很容易被忽略但对正式环境非常有必要。组织技能矩阵时有一个实用原则技能之间不要互相调用对方的内部文件只通过明确定义的输入输出接口协作。否则技能 A 改了内部结构技能 B 就莫名失灵排查起来极其痛苦。我在第 5 步测试集那部分强调的回归问题在技能协作场景会被放大数倍接口隔离是唯一能稳住局面的办法。另外技能矩阵一定要有冲突处理的预案。当两个技能被同时触发比如生成周报和生成项目同步文档模型可能不知道该以哪个为准。我在实践中一般这样处理在元数据里给每个 Skill 加一个priority字段调度冲突时按优先级决定如果优先级相同则默认不自动执行而是向用户列出候选技能让用户来定。这套规则在真实项目里能减少很多莫名其妙的输出偏差点。当技能矩阵跑顺之后你会观察到 Agent 的行为模式和纯聊天时代完全不一样。它会在面对任务时立刻匹配到合适的技能按标准步骤执行输出检查清单最后追加一句发现以下异常情况需要人工确认。这就是干活和聊天的直观区别。整个 Skill 技能系统做的就是把模型从聪明的应届毕业生往靠得住的老员工方向推你给它建好流程、配好资源、做好验证它就能稳定输出比你临时指挥省心得多。