朋友前几天问我你天天讲agent skills、superpower skills这些到底是怎么跑起来的为什么我装了一个skills有时候灵有时候完全不触发这个问题其实很典型。做Agent开发的人大多听说过skills也装过一两个但能把目录结构-触发机制-编写思路-测评方法串起来讲明白的人并不多。这篇文章就是我基于实际折腾的总结适合那些已经在用Claude Code、Codex CLI或OpenCode想系统理解skills的读者也适合准备自己动手写第一个skill的同学。我会从概念讲到落地中间包含安装方式、手写示例、来源推荐和测评手段尽量让你看完就能照着自己搞一个。1. 先搞明白一件事Skills不是Agent而是Agent的外接记忆1.1 一个没有Skills的Agent有多尴尬假设你给Claude Code接了一堆MCP工具能让它画图、查数据库、读文件。表面看起来能力很强但你让它把这篇论文摘要按照IEEE模板改写成150字以内它会怎么做大概率是打开文件、读一遍、凭感觉改改出来的格式往往还需要再手动调半天。问题出在哪模型有通用的语言能力但没有你这个特定需求下应该走哪几步的过程性知识。它可以对话、可以推理却不了解你手头这类任务的固定套路。Skills就是用来补这一块的它等于把一套操作手册常用资源校验脚本打包成一个目录让agent在某类任务被触发时按手册执行。我用一个类比agent本身像一个高分实习生知识面很广、学东西快skill则是一张标准作业流程表SOP加配套工具箱。没有SOP的实习生也能干活但每次做法都可能不一样质量不稳定给了SOP之后流程就相对固定结果也可复现。Skills的价值就在这个流程稳定上。这里要先划一条线技能和工具MCP不是一回事。MCP给agent的是能调用哪些外部动作skill给agent的是做某类事情时采用什么样的步骤和规则。一个解决的是触手问题一个解决的是大脑中的操作流程问题。1.2 Skill、Agent、Harness、MCP和Plugin的边界因为热搜词里反复出现harness和agent区别skill和agent的区别我把这几个概念放在一张表里做一个梳理也是我向团队新人解释时最常用的一张表概念本质类比典型例子Harness外壳agent运行时的执行环境负责上下文管理、模型调用、工具调度、权限控制车架/底盘Claude Code CLI、Codex CLI、OpenCodeAgent智能体模型基于当前上下文做决策的动态行为体由harness承载坐在方向盘前的司机一个正在执行修改代码任务的Claude Code会话Skill技能面向特定任务的指令文档资源脚本用过程性知识指导agent标准作业流程SOP工具箱论文排版skill、代码评审skillMCP Tool工具agent可以调用的外部能力接口车辆的外部附件/机械臂数据库查询工具、浏览器操作工具Plugin插件扩展harness本身功能的组件多作用于执行层面仪表盘改装自定义slash命令、权限检查插件这张表里最容易搞混的是skill和plugin。我个人的理解是plugin更靠近harness它改变的是执行环境本身的能力比如加一个命令、加一个权限检查skill更靠近模型该用什么思路干活它改变的是面对任务时的推理与操作流程。两者可以配合使用但不是一回事。很多刚接触的人把skills当成插件去理解会在后续排查问题时走不少弯路。Skill本质上是模型外接的操作记忆它不是在harness层面改变执行环境而是在模型加载指令后改变它对具体任务的处理方式。这个认知是后面所有实操的基础。2. Skills的文件组织方式与三种安装路径2.1 一个Skill的标准目录长什么样以目前Claude Code、Codex CLI这些常见agent工具为例一个skill通常是一个目录里面至少包含一个SKILL.mdmy-skill/ ├── SKILL.md ├── resources/ │ └── templates/ │ └── ieee-abstract.txt └── scripts/ └── validate_latex.pySKILL.md技能的核心文件也就是给模型的指令文档。resources/存放模板、参考资料、样例数据供模型在任务执行中按需读取。scripts/存放可执行脚本让模型把动手做的事交给脚本完成减少格式幻觉。这个目录结构不是随便拍的。它对agent的加载机制很友好模型不需要一次性读入整个skill的所有文件而是先读SKILL.md的关键部分遇到需要模板时再去resources里找需要执行校验时再去调用scripts。这种按需读取的懒加载设计能省下宝贵的上下文窗口。如果你把一大堆内容全塞进一个SKILL.md里模型光读指令就要消耗几千token反而影响后续任务质量。2.2 SKILL.md的frontmatter为什么是命门SKILL.md比较常见的格式是带YAML frontmatter例如--- name: latex-paper-formatter description: 用于将论文摘要和参考文献改写成符合LaTeX学术模板格式的规则。当用户提到论文排版、IEEE格式、摘要字数压缩时使用。 ---description这一段是整个skill的触发开关。agent在收到用户请求后会先扫描可用skills的描述计算用户请求与描述的匹配程度匹配上了才去加载正文。所以描述里应该尽量包含什么时候用、解决什么问题等信号而不是简单地写帮助处理LaTeX。我自己写description有个习惯里面至少要出现3组用户可能使用的说法比如论文排版、IEEE格式、摘要字数压缩这样触发率会明显提高。反过来如果description写得又宽又含糊比如帮助写论文那它既容易在无关场景被误触发也容易在真正需要时被其他skill抢走。2.3 三种安装方式复制、克隆、命令行把skills装进agent环境常见有三种方法直接复制把skills目录放到全局skills路径比如~/.claude/skills/或~/.codex/skills/只针对某个项目的就放进项目级.claude/skills/。这是最稳妥的方式适合自己手写的skill。Git克隆从GitHub把某个skills仓库克隆到skills目录。很多社区项目会打包好几十个skill克隆后按需保留。注意不要让仓库里的.git目录和冗余文件留在技能目录里否则可能干扰部分工具的文件扫描。命令行/远程安装部分agent工具支持通过URL直接安装远程skill或者使用插件管理器安装。安装完成后还是要回到本地确认目录结构是否被正确展开。注意不管用哪种方式装完都要做一次触发测试。最直接的验证方法是在新会话里用贴合description描述的自然语言问一句观察agent是否自动加载了那个skill或者是否能在上下文中看到它的内容。如果完全没反应大概率是目录结构或描述写出了问题。3. 实操手写一个LaTeX排版Skills并跑通3.1 选场景为什么拿LaTeX开刀我自己实际写过的第一个成品skills就是论文排版技能。为什么要选这个场景因为它的任务边界非常清晰用户输入一段论文摘要希望按目标会议或期刊的模板重新排版修掉英文拼写、压缩字数、补齐关键词。这类任务结果可以客观判断非常适合验证一个skill写得到不到位。而且很多做学术写作的人会反复遇到实际价值很高。如果你也想练手我建议选单个任务、有明确输入输出、结果可验证的场景别一上来就写帮忙做PPT这种范围巨大的全能skill。技能应该像瑞士军刀里的单个工具而不是整把瑞士军刀。一个只做一件事、做得好的skill远比一个什么都想干、什么都干不好的skill更有价值。3.2 指令正文把怎么干活写成人话SKILL.md的正文部分是给agent看的操作流程。我写LaTeX排版skill时正文里会明确规定目标把用户提供的摘要改写为符合目标模板的LaTeX片段。输入用户可能直接粘贴文本也可能提供.tex文件路径。步骤读取模板文件提取标题、作者、摘要、关键词等字段。检查摘要长度与模板要求的字数上限。重写摘要保留核心贡献删除冗余修饰语不虚构文献引用。输出LaTeX代码片段并在注释中标注改动前后字数。禁止事项不要改变作者列表和单位信息不要伪造实验结果不要把引用标记改成无法确认的编号。为什么要把步骤写得这么细因为在没有skill时模型遇到帮我改论文摘要会依赖自己的默认习惯不同模型甚至同一模型不同温度下的写法都不一样。给出显式步骤后agent会像照着SOP做事的员工输出质量稳定很多。同时禁止事项也很重要它往往比该做什么更能避免关键错误。我见过不少skill只写要做什么结果模型在边界情况上自由发挥出了错还没人背锅。3.3 配套脚本验证器与模板清理器纯文字指令仍不够还要配脚本。在我的LaTeX skill里我放了两个脚本scripts/validate_latex.py对模型生成的片段做粗校验比如花括号是否配对、\begin{abstract}...\end{abstract}是否存在、是否包含未定义的引用。scripts/clean_bib.py清理参考文献中多余的空行和重复条目。脚本的价值在于可执行、可判定。模型在推理过程中容易在格式细节上产生幻觉而脚本可以在执行阶段给出确定性结果。这个思路和单元测试很像把定性判断尽量转成定量判断让agent在自检时有据可依。没有脚本兜底单靠模型自己检查一遍往往只会得到一句我觉得没问题。3.4 第一次实测预期内和预期外的问题装好之后我实际跑了一次输入是一篇300词的计算机视觉会议摘要要求改成150词以内。预期内的问题模型第一次输出的LaTeX片段里\cite编号和原文一致但\begin{abstract}后多了一个空行。validate脚本立刻报错模型读取报错信息后自我修正第二次输出就干净了。预期外的问题模型在思考过程中跑去读了resources里一个旧的模板示例结果把作者单位格式也改了。这是我没想到的——skill的resources虽然方便但也可能成为过多的上下文干扰。后来我在SKILL.md里明确加了一条规则resources里的模板只用于字段结构参考不要复制作者格式和示例文本问题才被压住。这个例子很能说明Skills开发的常态踩坑→加规则→再测试。Skills不是一次写成而是通过多轮实测把边界条件写进去。你每发现一次模型在这里表现不稳就等于找到了一个可以固化成规则的机会。4. Skills生态优质来源、选型判断与过量安装清理4.1 去哪找社区聚合、官方示例与个人博客目前Skills生态已经有不少公开来源GitHub上的awesome类聚合仓库搜索awesome claude skills这类关键词就能看到大量列表。一些知名开发者发布的skills集合例如superpowers skills这类以超能力命名的仓库里面包含代码分析、文档生成等多种技能。工具官方仓库和文档中给出的示例skills是最稳妥的学习对象因为格式一定不会过时。个人技术博客和社交媒体上分享的单点skills质量差异大但往往很有针对性。我的建议是第一优先读官方示例和知名聚合仓库里star多的项目先把标准格式吃透然后再去个人博客里找小众但好用的技能。不要一开始就把几十个skills全部克隆下来否则后面光是排查冲突就够你受的。4.2 判断一个Skill值不值得装五个信号我判断一个skill值不值得花时间去安装和测试会看这五个信号README是否清晰有没有讲明白这个skill适用什么场景、不适用什么场景。SKILL.md是否可执行指令是你应帮助用户...这种空话还是有具体步骤和禁止事项。是否有resources和scripts落地只有纯文字没有校验脚本的skill通常效果不稳定。是否有版本记录或更新时间停更一年多的skill要谨慎agent工具变化很快。是否有示例输入输出没有示例的技能我默认它自己也没测过。这五条可以当做一个速查表。每命中一条装它的犹豫就会减少一点。反过来如果一个skill五条全不占那就毫不犹豫跳过。4.3 Skill装了太多会怎样冲突、稀释与隔离还有一个经常被提到的问题skill装太多会出乱子。这不一定是冲突报错更多是以下几种情况描述重叠两个skill都含有写论文润色等关键词模型不知道该用哪个或者两个都加载导致上下文被无关文本稀释。指令互相矛盾A skill要求必须用\citeB skill在示例里用了数字引用模型容易陷入纠结。上下文窗口被挤占agent会在匹配阶段扫描所有skill描述skill数量越多扫描开销越大实际留给任务推理的上下文就越少。应对办法是隔离和精简。我把skills分成全局常用和项目级专用两套跨项目通用的放全局比如通用的代码评审只和某个项目相关的放项目级目录比如该项目特有的打包脚本。同时定期清理那些装上后一个月没触发过的skill别舍不得。社区里甚至有人专门做了清理skills的脚本本质上就是扫描描述重叠和长期未触发项然后给出合并或归档建议。这个思路值得借鉴但要自己动手过一遍因为自动工具容易误删。5. 怎么测评一个Skill从感觉能用到可量化5.1 手工冒烟测试10个输入跑一遍很多刚接触skills的人测试方式就是把skill装上然后拿自己的任务试一次感觉输出还行就完事。但大模型具有随机性一次跑通并不能说明skill稳定。我建议至少做一个冒烟测试准备10个覆盖不同难度的输入依次让agent使用该skill执行逐个检查输出。比如我的latex skill会准备最短的摘要含图表的论文片段引用标记缺失的文本这几种用例。冒烟测试重点关注三件事是否被正确触发、是否执行了skill里规定的步骤、输出里有没有违背禁止事项。只要这三项里有一项不稳定就说明skill的定义还不够清晰需要回去修。这个阶段纯手工没问题因为一共就10个用例花不了多少时间。5.2 搭建轻量Evals样例集、判定规则、统计脚本如果想更进一步可以把冒烟测试脚本化做成轻量Evals。我自己维护了几个skills每个都配了一个小测试集用pytest跑。基本思路是维护一个YAML或JSON格式的样例集- input: 帮我改这段摘要目标期刊IEEE Access字数限制150词 expected: - contains: \\begin{abstract} - not_contains: \\section - max_length: 150 - input: 把这篇论文的参考文献清理一下 expected: - not_contains: DOI重复然后针对每个expected写判定代码批量执行后统计通过率再额外记录每次执行的耗时和token消耗。一个简单的pytest脚本就能做到。关键点在于把agent的输出表现转成可自动判定的断言。虽然无法完全替代人眼但能发现大多数回归问题。关于什么叫好的skill我习惯看四个量化指标触发准确率、任务完成率、格式合规率、平均耗时。前三个是效果指标最后一个是效率指标。如果完成率不错但耗时特别长可能是skill里的步骤链条太啰嗦可以精简指令。这四个指标一出来skill好不好就不再是主观感觉而是可以对比的数据。5.3 回归测试改完Prompt后最容易被忽视的动作最后一个建议是关于回归测试的。很多人改完SKILL.md只拿手头一个用例试了就发布结果某些隐藏场景悄悄退化。我在维护自己的skills时会坚持一点每次修改无论大小都把上一轮的测试集完整重跑一遍。这个习惯救过我很多次。有一次我只是改动了禁止事项的措辞把不要改变作者信息改成了不要修改作者相关字段结果模型错误地认为不能修改作者信息也包括不能修正作者名字里的拼写错误。这种语义边界问题人眼很难在单次测试里发现但回归测试一跑就露馅了。训练数据的随机性决定了skills是会退化的。一个skill今天表现不错不代表下个版本的模型、下一轮温度采样下还表现不错。把测试集保留下来配合一个简单的统计脚本就是最低成本的防线。最后说点个人体会agent skills这个概念看起来很简单——不过是一个带markdown文件的目录。但真正把它用好考验的是你能不能把经验拆成步骤把步骤变成可校验的规则。我写这篇文章之前也踩过不少坑最大的收获就是不要把skill当成一个可以一次写完的东西它更像一个需要持续迭代的规程。最后分享一个小技巧不要把skills的description写得太宽。宁可一个skill只服务一个具体场景也别让它什么都能干、什么都触发不了。这样的技能越多你的agent反而越好用。
