Agent Skills开发实战：从概念到落地的完整指南

1. 聊聊Skills到底是什么为什么突然火起来先从一个具体场景说起。我最早用Agent干活的时候最烦的一件事就是同一套知识每次都要重新讲一遍。比如我想让Agent帮我整理会议纪要每次都要把你是谁、按什么格式整理、重点抓什么、术语怎么处理这些背景信息在对话里砸进去长度堪比一篇小作文。后来依赖长上下文把几十份历史记录全塞进会话效果是好了一点但token成本和响应延迟都上去了而且换一个任务模型忘记的概率照样不低。Hotword列表里有个很有意思的词叫Superpower Skills我第一次看到这个名字还愣了一下。它本质上是把一批预先定义好的能力包以技能的形式注入到Agent的工作流里让Agent在接到指令时不是从零开始猜该怎么干而是直接调用一个成熟的、经过测试的作业流程。这个概念本身不新但它的产品化程度和生态扩张速度确实在过去一年里肉眼可见地加速了。所以在这篇第21课里我想围绕Skills开发这件事把概念、结构、实践路径和踩坑记录完整展开。这篇文章适合谁两类人。一类是已经跑通过Agent基础应用、手头有具体任务想提升准确率的人另一类是刚入坑、看到Skills这个词但搞不清它和普通Prompt、插件到底差在哪的人。无论你是哪一类读完至少能自己写一个可以用的Skill而不是停留在知道这个词的层面。2. 动手之前先搞清楚Skill的文件结构与运行逻辑2.1 Skill本质上是一份作业指导书加一套工具包很多教程会把Skill讲得很玄什么Agent的可复用能力抽象认知外包之类的。我用一个更接地气的比喻Skill就像你给新来的实习生写的一份作业指导书加上配套的模板和工具。想象一个场景你是团队里带新人的组长。实习生刚进来你不可能把公司所有流程细节一次性全部教给他那样他记不住真到干活的时候还是会抓瞎。正确的做法是你先写一份会议纪要整理SOP里面写明步骤、格式、注意事项再附上几个以前的样例下次实习生接到类似任务翻出这份SOP照做就能产出一个合格的结果。Skill对Agent来说就是这份SOP。它不是把答案写死而是把做到什么标准、按照什么步骤、参考什么样例写清楚。模型本身还是那个模型认知能力没有变但因为有了这份SOP的引导它的输出方差大幅降低翻车概率明显下降。一个标准的Skill目录一般长这样my-skill/ ├── SKILL.md # 核心描述文件 ├── scripts/ # 可选辅助脚本 │ └── generate_report.py └── assets/ # 可选模板、样例、参考文档 └── report_template.md2.2 SKILL.mdAgent唯一必须读的文件在绝大多数Skill规范里SKILL.md是这个技能包的门面。Agent并不会在任务一开始就遍历整个目录它首先读取的是SKILL.md根据这个文件的描述来决定当前任务是否适合调用这个技能以及调用了之后该怎么干。所以SKILL.md写得好不好直接决定了这个Skill会不会被触发、触发了之后能不能跑出预期效果。它一般包含以下几个部分组成部分作用写作要点名称与描述告诉Agent这个技能是干嘛的描述要具体覆盖典型任务场景适用场景什么任务适合用这个Skill写明触发条件和边界使用步骤一步步指导Agent可操作步骤要可执行不要出现抽象指令输出要求规定最终交付的形式格式、结构、质量标准示例给出1-2个完整样例样例质量要高Agent会模仿我见过很多新手写的SKILL.md本质上就是一篇简单的Prompt把描述写得太泛比如处理与分析数据。这句话Agent读了等于没读它根本不知道该什么时候用、怎么用。合格的描述应该是这样的name: structured-report-generator description: 根据用户提供的原始数据或会议记录生成结构化分析报告。 适用于周报整理、会议纪要、数据分析摘要等场景。 当用户要求整理报告做周报总结会议时使用。2.3 辅助脚本什么时候才需要写代码不是每个Skill都需要写脚本。早期Skills刚流行的时候很多Skill就是纯文本的SOP让Agent靠模型能力完成任务。但后来大家发现一个趋势把那些模型不擅长或容易出错的环节用确定性代码兜底Skill的成功率能提高一大截。举个例子。你要做一个CSV数据分析Skill。如果你让Agent直接用Python写分析代码它每次生成的结果可能都不一样有时候变量名都对但跑不通有时候处理方式有问题逻辑错了。但如果你把这个Skill写成一个带固定入口的Python脚本让Agent只负责理解用户需求、填参数然后调用脚本拿到结果再解释给用户稳定性就完全可控了。脚本在Skill里的角色很清楚模型负责理解、规划、表达脚本负责计算、转换、生成。各干各擅长的活。不过这里有一个分寸问题。脚本太重Skill就退化成普通Plugin了纯指令太轻又没有发挥出包的威力。我的经验是如果你的Skill只是改变输出的格式和风格——纯文本SOP就够了如果涉及文件处理、网络请求、复杂计算——果断上脚本。2.4 触发机制Agent到底怎么决定用哪个Skill这是我在开发Skills时最困惑的问题之一也是很多人容易搞错的。在Claude Code或Codex这类环境里Agent拿到用户任务后会先看有哪些Skills可用然后把任务与每个SKILL.md里的description做匹配。匹配度高的才会被拉进上下文作为任务执行的参考。这意味着两件事。第一描述信息是触发的唯一凭据。动手写Skill之前想清楚你想覆盖什么场景然后把这个场景翻译成一段有辨识度的描述。描述不是给人类看的是给模型的embedding匹配用的所以它必须包含足够多的关键词触发点。第二不要试图用触发条件做精确控制。模型匹配本身是概率性的很难做到只有我指定的那句话才触发。如果你发现某个Skill在错误的任务上被频繁误触发与其在描述里反复加否定句不如想想是不是这个Skill的定位本身就太宽了。一个小经验描述里写的触发词最好是你真实使用场景中用户会说的原话。比如用户经常说把这个整理一下那你可以在描述里写上当用户说整理一下整理成文档做个汇总时使用。这些口语化的说法比官方术语命中率高很多。3. 手把手开发一个Skills以结构化报告生成器为例概念说再多不如动手跑通一个。这一节我们完整开发一个Skill结构化报告生成器。它的使用场景是用户丢来一段会议记录或者一堆零散笔记Skill自动整理成一份带标题层级、重点摘要、待办事项的Markdown报告。3.1 第一步确定需求边界动手写任何代码或文档之前先想清楚三件事——输入是什么、输出是什么、不做什么。我的输入定义用户提供的任何文本可能是聊天记录、会议录音转文字、零散想法。输出定义一份结构化Markdown报告包含总览、关键信息摘要、行动项列表、风险点提示如果有。不做什么不做事实核查不改写用户原意不生成超出输入范围的内容。刚开始开发Skill时最容易犯的错误是什么都想做。一个刚起步的Skill范围宁可窄一点把它跑稳了再往宽了扩展。我最初写的版本还想做情感分析和发言人识别结果发现这些功能需要额外的模型或逻辑支撑强行塞进来反而让Skill变得不可控最后全部砍掉了。3.2 第二步编写SKILL.md这是一个标准的SKILL.md长这样--- name: structured-report-generator description: 将零散的会议记录、聊天记录或工作笔记整理成结构化Markdown报告。 适用于会议纪要、周报生成、信息汇总等场景。 当用户要求整理会议记录做个纪要把这段内容整理成报告总结一下这段对话时使用。 不适合用于翻译、代码生成、事实核查。 --- # Structured Report Generator ## 输出格式 生成一份 Markdown 报告包含以下结构 1. ## 概览用3-5句话概括原始材料的核心内容。 2. ## 关键信息用无序列表列出重要的结论、决定、数据。 3. ## 行动项用表格列出待办事项包含负责人如果原文有、截止时间、事项描述。 4. ## 风险与注意如果原文提到潜在问题或风险列出没有则删除此部分。 ## 写作原则 - 保持原文信息完整不添加原文没有的事实。 - 用词客观不主观评价。 - 行动项必须以可执行的动作开头例如确认更新联络。 - 如果原文信息不足在对应位置标注[信息不足]不要凭空编造。 ## 示例 用户输入今天讨论了两个事第一是下周的版本发布张伟负责最终验收周三前要完成第二是客户的反馈说登录页加载太慢李楠下周去查一下性能问题。 输出 ## 概览 本次讨论涉及两个事项版本发布验收与客户反馈的性能问题排查。 ## 关键信息 - 下周进行版本发布张伟负责最终验收。 - 客户反馈登录页加载缓慢需要排查性能问题。 ## 行动项 | 事项 | 负责人 | 截止时间 | 说明 | |------|--------|----------|------| | 版本发布验收 | 张伟 | 周三 | 完成最终验收 | | 登录页性能排查 | 李楠 | 下周 | 定位加载缓慢原因 | ## 风险与注意 - 登录页性能问题如未能及时解决可能影响用户体验和客户满意度。注意几个关键设计description里用了大量用户可能会讲的原话覆盖了整理会议记录做个纪要整理报告这些高频触发词。输出格式不是用请提供报告这种抽象表述而是具体到一级标题的名字、段落的内容、表格的列名。写作原则里有一条信息不足就标注不要编造这能显著减少模型幻觉。示例虽然只有一个但非常完整模型能从例子中学会格式和语气。3.3 第三步添加辅助脚本如果需要第一个版本这个Skill不需要脚本纯靠模型理解能力就能跑。但在实际使用中我发现一个问题当用户输入的文字特别长比如超过5000字模型自己总结时容易丢掉后面的部分因为注意力窗口的末尾信息权重偏高。于是我给这个Skill加了一个可选的预处理脚本split_and_summarize.py专门负责把超长文本分段摘要。脚本的逻辑不复杂#!/usr/bin/env python3 import sys def chunk_text(text, max_chars2000): 按段落切分长文本保证每个chunk不超过max_chars paragraphs text.split(\n) chunks [] current for para in paragraphs: if len(current) len(para) 1 max_chars: chunks.append(current) current para else: current current \n para if current else para if current: chunks.append(current) return chunks if __name__ __main__: input_text sys.stdin.read() chunks chunk_text(input_text) for i, chunk in enumerate(chunks): print(f--- Part {i1} ---) print(chunk)是的脚本非常简陋就是一个工具人。但在实际工作流里这个脚本让Agent处理超长文本时先拆段、后总结最后合并成完整报告。分段总结比一次性硬刚完整文本要稳定得多。注意脚本不一定需要多高级。在Skill开发里脚本的价值在于兜住模型的短板而不是自己成为主角。能用10行代码解决的事情不要写成100行。3.4 第四步放入正确的位置并测试写完之后把这个目录放到手头环境期望的位置。不同工具的位置不同以Claude Code为例通常是~/.claude/skills/Codex可能是~/.codex/skills/你用哪个就用哪个的规范。放好之后重启会话让Agent重新加载Skills列表然后开始测试。测试的时候我建议按从易到难推进直接命中测试输入和描述里触发词完全一致的文本比如把这段会议记录整理成报告看能不能正常触发、输出格式对不对。语义相似测试换一种说法比如这段对话帮我捋一下看模型能不能通过语义理解命中Skill。边界测试输入一个完全不适合的场景比如帮我写一段代码确认模型不会错误触发这个报告Skill。极端输入测试输入空文本、只有一行的文本、全是乱码的文本看模型会不会崩溃。第一轮测试跑下来大概率会发现各种问题不要慌这太正常了。接下来进入第4章的踩坑环节我把这个过程中最典型的几种翻车现场拆开讲讲你大概率也会遇到。4. 真实踩坑记录从翻车到稳定的调试过程4.1 坑一描述太抽象模型干脆不触发第一个版本的description我写的是For generating structured reports这句话的匹配效果极其糟糕。因为structured reports是个术语用户平时根本不会这么说话。实际测试的时候我输入帮我总结一下今天的会议Agent完全没意识到有这个Skill可用直接用默认能力给了一个纯文本回复。后来我把描述改成将零散的会议记录、聊天记录或工作笔记整理成结构化Markdown报告并且把用户口语集中写入触发率立刻上来了。这里有个经验描述信息要模拟用户怎么问而不是你想做什么。4.2 坑二过程指令与结果指令混在一起刚开始写SKILL.md的时候我写了一段先分析文本主题再抽取关键实体再构建语义树最后生成报告。这看起来挺合理结果实测下来模型确实按这个流程走了但输出报告的信息密度反而下降了。问题出在哪分析主题抽取实体构建语义树这些都是内部思考过程不应该和最终输出混在同一个用户可读的指令空间里。当这些过程指令被写进SKILL.md的正文时模型会误以为这也是要输出的内容于是报告里出现了大段的主题分析实体列表元信息整个报告变得又长又冗余。正确的做法是只把最终输出要求写清楚过程步骤留给模型自己规划。除非过程步骤会直接影响输出质量比如先列大纲再逐段填充否则没必要写进去。4.3 坑三试图做一个万能Skill第三版的时候我往这个Skill里堆了很多能力既能做会议纪又能做周报还能做数据分析、翻译摘要、甚至生成邮件草稿。想着一包多用结果实测每一样都做不精。原因很好理解一个Skill的描述越宽泛触发阈值就越低模型拿它做各种不匹配任务的概率就越高。而SKILL.md里的格式要求又面向特定场景外部任务进来的时候就容易出现套模板式的生硬输出。后来我把它拆成了三个独立的Skillmeeting-minutes-generator、weekly-report-generator、analysis-summary-generator。每个的SKILL.md针对性极强测试效果立刻变好。拆开之后每个Skill的体积都很小维护成本低触发精准度也高。一个Skill解决一个问题而不是一个Skill解决所有问题。4.4 调试方法论判断是Skill的问题还是模型的问题这是我在做Agent开发时觉得最有价值的一套方法。遇到输出结果不对的时候很容易下意识就去改SKILL.md但很多时候其实问题不在Skill本身。我的排查顺序是这样的排查层问题表现验证方法解决方案触发层Skill根本没被调用在Skill里加一个输出标记或在对话日志确认修改description关键词指令层Skill被调用了但执行不对给模型同一个任务手动指定让它参考Skill执行修改SKILL.md步骤描述能力层手动指定参考Skill还是做不对把SKILL.md的内容当成Prompt直接发给一个裸模型降低任务难度或引入脚本兜底期望层模型做对了但用户不满意检查是否存在主观偏好问题明确输出质量标准和示例这个排查链路帮我在很多场景下省下了大量无效调参时间。如果你开发Skill遇到怎么改都不对的情况先用这套流程定位问题到底出在哪一层。5. 换个视角评估Skills好的Skill有哪些共性Skills开发多了之后光靠手感不够最好有一个相对客观的评估体系。这一节我会分享一套我常用的评估方法也是我在社区里和其他开发者交流后总结出来的。搜索热词里出现skills怎么测评说明很多人都在纠结这个问题。5.1 核心评估维度评估一个Skill的好坏我建议从三个维度下手触发准确度该触发的时候能不能触发不该触发的时候会不会乱触发。这个维度衡量的是描述与真实用户表达的匹配度。测试方法很简单准备10个正向用例和10个负向用例跑一遍记录命中率。输出稳定度同一个输入跑5次输出结构是不是一致的这个维度非常关键但它经常被忽略。很多人测试Skill只跑一次看效果不错就上线了。但在实际使用中模型有采样随机性同一个任务跑三次可能得到三种不同的结构。一个合格的Skill应该在不同运行轮次中保持稳定的输出框架。内容准确度输出的信息有没有忠实于输入有没有幻觉这一步是最难量化但又最重要的。我自己的方法是对比抽取关键事实把输出里的关键信息与原始输入逐一对照找到不一致的地方。5.2 量化测试用一个公开测试集来打分我自己会维护一个简单的测试集每条内容包含输入、期望触发的Skill、期望的输出结构。每次开发新Skill或修改旧Skill都跑一遍这个测试集记录触发和生成的完整日志用脚本统计本次改动是否引入回归。这个过程不需要很复杂一个简单的表格就够了用例输入期望Skill是否触发结构是否正确内容是否准确001帮我总结会议meeting-minutes-generator是/否是/否是/否002写个Python脚本无是/否(期望否)--跑完统计触发率、稳定性指标比你凭感觉判断好像变好了靠谱得多。我后来还在考虑把这一套做成了半自动的评测脚本半年之后回头看这套近乎笨拙的回归测试反而是Skill质量提升最关键的工具。5.3 好的Skill共性清单从这些测试里我总结出三个好的Skill的共性粒度小。一个Skill只解决一个任务类型。对于周报生成就专注周报会议纪要就专注纪要绝不为了省事把多个任务塞进一个Skill里。步骤可执行。SKILL.md里的每一条指令都是看得见、能执行的动作。少用质量要高语言要自然这类无法被机器直接执行的抽象形容词多用用表格列出行动项按时间顺序排列事件这类可验证的指令。自带质量底线。好的Skill不只是告诉Agent该做什么还要告诉Agent做到什么程度算是满意、什么情况算信息不足。比如如果原文没有提到负责人在表格对应位置标注未知不要臆造这句话看似没什么技术含量但在实际跑出来的输出里这类边界约束对减少幻觉的帮助极大。6. 生态观察从Claude Code到CodexSkills进化到什么阶段了最后聊聊生态层面的观察。搜索热词里有一大串和特定工具绑定的Skills相关词条比如claude code skills 安装、codex skills、opencode skills、codebuddy skills、pi agent桌面端热度分布非常分散这说明Skills这个概念已经在不同Agent工具里全面铺开了。6.1 各家实现的关键差异不同工具对Skills的称呼和加载机制不完全一样但底层的设计思路出奇一致都是用一份描述文件作为Agent的索引通过匹配来决定是否加载。区别主要体现在三个方面维度典型差异安装方式有的存放在固定目录有的支持通过命令安装/固定版本的第三方Skills描述格式多为Markdown或YAML Front Matter个别工具开始支持JSON Schema校验辅助脚本有的完全不允许执行本地脚本受控安全策略有的支持完整本地执行这就引出一个实际建议一个Skill如果只依赖SKILL.md和纯文本基本可以跨工具复用一旦引入了脚本就要考虑目标环境的执行权限。我在开发时会先做纯文本版本确认逻辑没问题之后再考虑加脚本。6.2 两个正在发生的趋势第一个趋势是Skill与数据源绑定。新一代Skills不再只是给Agent一份写死的操作手册而是允许Skill携带访问特定数据源或API的凭证和调用逻辑。以后Skill之间不光是文本能力的竞争更是数据接入能力的竞争。第二个趋势是Skill的评测标准化。社区里讨论skills怎么测评的人越来越多已经有组织在尝试建立公开的Skill benchmark。一旦有了标准化的评测集Skill开发就会走上和开源软件类似的路可量化、可对比、可回归测试。那时候写Skill就真的是在开发一个软件资产了。6.3 给新人的学习路线如果你现在刚准备入坑Skills开发我建议的路线是这样的先用。去装几个成熟社区里口碑好的Skills比如结构图生成、图片生成、LaTeX排版这些体验一下SKILL.md长什么样、Agent怎么用它们。再改。挑一个简单的Skill试着修改它的输出格式、增加一个步骤、换一个示例看看行为变化有多大。后写。给自己手头最重复的一个任务写一个Skill跑通上面说的测试流程。最后分享。把Skill发到社区收集反馈迭代版本。我自己的几个Skill初期问题和别人提的意见对我的帮助比我自己埋头瞅着屏幕大多了。说到底Skills开发不是一个学会一个API就会用的东西它更像是一种写作——把模糊的需求写成机器能理解、模型能执行的规约。写多了你基本就能自然而然地判断什么样的指令是清晰的什么样的边界是模糊的。而我自己的体会是这个技能不只对Agent开发有用就算只把它当成一种和AI沟通的方法论投入产出比也很划得来。最后给个具体建议从今天手头最烦琐、重复次数最多的一个文本处理任务开始给它写第一个Skill。别追求全面先追求这个任务我自己用着顺就行。跑通了第一版后面的事情就是水到渠成的事了。