最近我把工作流里的Agent又折腾了一遍起因很简单每天让Claude Code、Codex这类编程助手干活总觉得它们“懂技术但不懂业务”。同样是改一个前端页面它能把TypeScript类型修得整整齐齐却不知道我们这个项目的命名规范和历史包袱同样是跑一次数学建模的赛前检查它不会主动去看数据有没有量纲不一致。直到我把一些写好的skills塞进去这个问题才算真正解决。这篇就来聊聊skills这件事它到底是个什么东西为什么各家Agent都在推怎么把GitHub上别人写好的skills装到自己环境里以及更重要的——怎么动手写一个真正能用的skill。我会结合前端开发、数学建模、AI漫剧脚本这些我实际跑过的场景把安装、调试、踩坑的完整过程都摊开讲。1. 先搞清楚skills到底是什么为什么突然这么火1.1 从一段真实工作流说起先还原一个典型场景。我让AI助手“帮我整理一下这周提交的代码重点看有没有明显的逻辑漏洞”。如果没有skills模型会怎么做它会调用git相关工具把所有diff都翻一遍然后基于它内置的“代码审查常识”给你一顿输出。结果往往是常规问题说得头头是道但你项目里真正的隐患比如某个历史接口的兼容性约定、某张业务表的唯一键规则它一概不知道。加了skills之后就不一样。我提前写了一个“团队代码审查”技能里面有完整的分步流程先拉diff再对照项目自己的代码规范文档重点检查哪些容易踩坑的模式最后按固定格式输出报告。AI助手看到用户需求后会在合适时机加载这个skill然后按里面的步骤走。整个体验从“一个聪明但陌生的实习生”变成了“一个懂你项目规矩的老同事”。这就是skills的核心价值在不改变模型本身能力的前提下给它附加一层可复用、可共享、可维护的领域工作流和专业知识。1.2 skills、prompt、MCP到底有什么区别我经常被人问这不就是写个prompt吗跟MCP有什么区别这三者确实有重叠但定位完全不同。普通prompt是“一次性指令”你把它写进对话里这次有效下次还得重新写。哪怕你把prompt存成模板每次使用的时候本质上也还是在往上下文里塞大段文字既浪费token也容易让对话变乱。MCP是“给AI加工具”解决的是“AI能调用什么外部能力”的问题。比如接入一个数据库MCP模型就能查数据接入一个浏览器MCP模型就能操作页面。它侧重的是能力边界扩展。skills是“给AI加工作规范”解决的是“AI在特定任务里应该怎么按流程思考和执行”的问题。它不只是让模型“能做什么”更是告诉模型“这件事应该怎么做、按什么顺序做、验收标准是什么”。一个相对通俗的比方MCP是给厨师提供新食材和新厨具prompt是随口说一句“今天做清淡点”skills是直接给一本写好的标准菜谱里面连火候和装盘都给你排好了。对于需要稳定输出的重复性任务菜谱的威力远大于一句口头叮嘱。1.3 为什么说它是Agent的“肌肉记忆”我在调模型的时候越来越觉得纯粹靠模型“临场发挥”这件事效果方差非常大。同一个任务今天心情好上下文状态好它给你写得漂漂亮亮明天换个话题聊了一堆再来执行它可能连基本格式都不记得了。skills相当于把那些“稳定可靠的做法”固化下来让模型按图索骥。一次调通了以后每次都能复用。实际跑下来我觉得skills最大的三个收益是输出稳定性大幅提升。流程固定、格式固定、检查项固定不会今天给一种结果明天给另一种。领域知识可以沉淀。团队里踩过的坑、约定好的规范都可以写进skill不再依赖模型自己在网上瞎猜。上手成本低。新人来了把skills仓库拉下来AI助手立刻就能按团队标准干活。现在市面上主流的Agent工具比如Claude Code、Codex、OpenCode都对skills有一定支持。虽然各自的加载机制、目录约定略有差异但核心思路已经收敛得差不多了就是“一个技能一个文件夹里面有指令文件和可选脚本”。2. 一个Skill的标准结构与核心原理2.1 解剖SKILL.md先说最普遍的结构。一个标准的skill本质上就是一个文件夹里面必须有一个SKILL.md文件有时候还会有配套的脚本和资源文件。比如my-skill/ ├── SKILL.md ├── scripts/ │ └── check_data.py └── references/ └── team-rules.mdSKILL.md是整个skill的心脏。它通常分为两部分文件头部的元信息以及正文的指令内容。元信息一般用YAML格式包含name和description两个关键字段有些工具还会有version、author、license等附加信息。正文则是给模型读的Markdown格式说明书。以前端开发场景举个例子一个SKILL.md的头部可能长这样--- name: frontend-code-review description: 前端代码审查技能。在当前开发任务涉及React/Vue组件、样式规范、提交前检查时使用按照项目的编码规范与常见漏洞清单对代码进行逐项审查。 ---很多人会忽略description的重要性。实际上模型的“触发器”很大程度就是这个description。模型读取用户需求后会判断当前任务跟哪个skill的描述匹配匹配上了才加载。所以description写得越准确、越具体触发率越高。2.2 name和description才是真正的“触发器”我自己在写第一个skill时犯过一个错误description写得太泛比如“用于代码审查”结果AI在写代码的过程中动不动就触发审查流程烦得要命。后来我把触发条件写得非常具体限定到“涉及到React组件状态管理改动时”“提交前检查时”“明确要求审查时”才触发情况立刻就好转了。这里面有一条关键的逻辑skills不是常驻上下文的东西它是按需加载的。模型不会把所有skill都塞进上下文再慢慢挑而是靠匹配机制先选中一个或几个再把对应的SKILL.md内容加载进来。这样设计的好处是省token坏处是如果description写得不准确模型可能该触发时不触发或者不该触发时乱触发。实用的写法是在description里把“触发场景”和“不适用的场景”都写清楚。比如description: 用于数学建模赛前数据检查。当任务涉及数据清洗、缺失值处理、异常值检测、量纲统一时使用。如果是写建模论文或排版不要使用本技能。后面那句“不要使用”看着像废话但实测非常有效能显著降低误触发率。2.3 一条完整调用链是什么样的为了把原理说透我画一条文字版的调用链看一个skill到底是怎么被用起来的第一步用户在对话里发出请求比如“帮我检查一下这个CSV感觉数据有问题”。第二步Agent的调度层把请求跟所有已注册skill的description做匹配找到最合适的那个比如数学建模数据检查skill然后读取该skill目录下的SKILL.md。第三步模型把SKILL.md里的指令当作当前任务的工作规范再结合上下文里的具体数据文件开始按步骤执行。第四步如果SKILL.md里写了“需要运行scripts/check_data.py”模型就会调用本地的Python执行环境来跑这个脚本再把脚本输出结果纳入分析。最后模型按SKILL.md规定的输出格式给出结论。这条链路里最值得注意的点是脚本承担的是“确定性的计算工作”而模型承担的是“阅读理解、判断、生成结论”的工作。两者各干各擅长的事效果就很稳。我试过把整个数据检查逻辑全部写进SKILL.md指令文字里让模型“分析”缺失值比例。结果模型经常算错或者在不同轮次给出不一致的结论。后来改成脚本出统计数据、模型出分析和建议准确率一下就上来了。3. 手动安装GitHub上的skills的正确姿势3.1 准备工作先确定你的Agent支持哪种形式GitHub上现在有一大堆现成的skills仓库比如superpower skills、各类codex skills集合、数学建模专用skills库等等。安装方法跟你用的Agent工具有关系。以我常用的几个工具为例大方向上有三种形式一种是“项目内目录”你在项目的根目录下建立一个特定名称的文件夹比如.claude/skills然后把从GitHub下载的skill文件夹丢进去当前项目的Agent就能识别。一种是“全局目录”放在用户目录下的统一位置比如~/.claude/skills这样不管你打开哪个项目这些skill都可用。一种是“marketplace配置”通过一个marketplace.json或者plugins机制把远端仓库注册进来配置之后agent会自动去仓库里拉取和更新skills。不同工具的目录名称和配置文件名略有差异但大逻辑都逃不出这三种。安装前先花两分钟确认一下你用的工具是哪种能避免后面白折腾。3.2 手动安装的具体步骤手动安装GitHub上的skills说穿了就是三步下载、放对位置、确认能被识别。第一步到目标仓库看清楚目录结构。比如某仓库的目录是这样的awesome-skills/ ├── code-review/ │ ├── SKILL.md │ └── scripts/ ├── math-model-check/ │ ├── SKILL.md │ └── scripts/那你要的其实就是其中某个子文件夹。别图省事把整个仓库全clone到skills目录里那样Agent大概率识别不了因为你把多层级目录结构打乱了。第二步把对应的skill文件夹拷贝到目标位置。比如我用Claude Code全局安装就放到mkdir -p ~/.claude/skills cp -r awesome-skills/math-model-check ~/.claude/skills/如果是项目级的就放到项目目录下的.claude/skills里一样。第三步确认被识别。不同工具有不同的验证方式。最简单的做法是直接问Agent一个问题故意触发这个skill的使用场景看它有没有反应。比如装了代码审查skill就故意说“帮我审查一下src目录下的login.tsx”看它是否按SKILL.md的流程走。如果没反应检查目录位置和SKILL.md文件名是否正确有些工具要求文件名必须严格是SKILL.md大小写都不能错。3.3 安装后怎么验证生效我刚学skills那会儿最大的困惑是“怎么知道它生效了”。后来总结了一套验证方法执行顺序从快到慢先看文件系统。确认这个skill文件夹在Agent扫描的路径下。其次看提示。有些Agent在加载skill时会在界面里显示一个提示比如在输出里出现“已加载技能xxx”或触发框里出现对应的工具被选中了。再看行为是否变化。这一步最关键——同一个任务安装前后Agent的处理流程和输出格式应该明显不同。最后看调试信息。不少Agent工具都有verbose模式打开后能看到模型接收到哪些指令、加载了哪些skill这个是最实锤的证据。如果装了没变化九成不是模型的问题而是路径或者文件结构的问题。我自己踩过的坑有两个一个是把skill文件夹套了一层壳本该是profile/SKILL.md的变成了profile/profile/SKILL.md另一个是SKILL.md文件名大小写写错了写成了skill.md导致Agent死活不认。4. 自己动手写一个可用skill以数学建模检查为例4.1 选场景、定边界理论讲了这么多还是得动手写一个。我拿热度很高的“数学建模赛前数据检查”来演示因为这个场景需求明确、边界清楚、脚本逻辑也不复杂。写skill之前先定两个东西这个skill解决什么问题不解决什么问题。我的目标很窄当用户给出一个数据文件时自动生成一份数据体检报告包括缺失值统计、异常值检测、量纲一致性检查、数据分布概览、处理建议。它不负责建模、不负责写论文这些要明确写在description的“不适用”里防止模型乱触发。4.2 写SKILL.md的核心正文目录结构和SKILL.md文件头部如下math-model-check/ ├── SKILL.md └── scripts/ └── data_check.pySKILL.md的内容我习惯分四个部分任务概述、执行步骤、输出格式、注意事项。--- name: math-model-check description: 数学建模赛前数据检查技能。当用户提供数据文件CSV/XLSX并要求进行数据体检、缺失值分析、异常值检测、量纲检查时使用。本技能仅用于数据检查不负责建模和论文撰写。 --- # 数学建模赛前数据检查 ## 任务概述 对建模比赛提供的原始数据文件进行系统性体检输出结构化的数据质量报告帮助参赛团队在建模前发现并修正数据问题。 ## 执行步骤 1. 用脚本 scripts/data_check.py 读取目标数据文件生成统计结果。 2. 判断数据文件格式优先处理 CSV 和 XLSX。 3. 对脚本输出逐项解读 - 缺失率超过 5% 的字段给出处理建议删除、填充或标注 - 数值字段的极值是否合理是否存在明显录入错误 - 各字段单位是否一致量纲差异较大的需要特别提示 - 数据分布是否严重偏态是否适合直接用常规模型。 4. 最终输出报告按下方格式Markdown 输出。 ## 输出格式 markdown ## 数据体检报告 **文件信息**文件名、行数、列数 **缺失值概览**表格含字段名、缺失数、缺失率 **异常值概览**表格含字段名、异常值个数、疑似原因 **量纲检查**描述各数值字段的单位是否一致 **总体建议**3-5 条可执行建议注意事项如果脚本运行报错先检查文件路径和数据格式再考虑调整脚本参数。不要把推断性结论写成事实性结论比如“缺失值与目标变量相关”需要先做验证。### 4.3 配上可执行脚本 SKILL.md负责指挥脚本负责干力气活。data_check.py我写得很朴素只做基础统计不搞花活因为它的任务是“给模型提供可信的数字”而不是替模型做决策。 python import pandas as pd import sys def load_file(path: str) - pd.DataFrame: if path.endswith(.csv): return pd.read_csv(path) elif path.endswith(.xlsx): return pd.read_excel(path) else: raise ValueError(仅支持csv和xlsx格式) def main(path: str): df load_file(path) print(f文件信息: {df.shape[0]}行, {df.shape[1]}列) print(\n缺失值概览:) missing df.isnull().sum() missing_ratio missing / len(df) for col in df.columns: if missing_ratio[col] 0: print(f{col}: 缺失{missing[col]}个, 占比{missing_ratio[col]:.2%}) print(\n数值字段描述统计:) num_cols df.select_dtypes(include[number]).columns stats df[num_cols].describe().T print(stats.to_string()) if __name__ __main__: main(sys.argv[1])实际使用的时候模型会自己调用这个脚本并传入数据文件路径然后读取输出。注意脚本里print的内容要整洁、结构化最好每个部分都有小标题。因为模型是靠解析这些文字来做进一步判断的输出太乱它容易漏信息。4.4 本地测试的完整流程写完之后一定要测不能写完就算完。我的测试流程是三步第一步命令行直测脚本。先用一个样例数据在终端里跑一遍确认脚本本身没有bug输出格式符合预期。第二步在Agent对话里触发。故意说“帮我检查一下data/raw_data.csv”看Agent是否加载了math-model-check这个skill。第三步检查输出是否符合预期。如果Agent没有调用脚本而是自己在文本里“分析”数据说明SKILL.md里对脚本调用的强调还不够我会把执行步骤第一条改为“首先必须运行脚本所有统计数字以脚本输出为准”。还有一个屡试不爽的小技巧在SKILL.md里加一句“如果已有stats.json缓存文件直接读取缓存不要重新运行脚本”。这能让重复对话时不重复跑脚本既省时间又省token。5. 几个经典方向与避坑速查表5.1 值得收藏的skills类型实测下来我觉得以下这几类skills的性价比最高也是GitHub上目前最值得下载的第一类是代码审查类。适合团队统一代码规范把项目的历史约定写成skill每次提交前自动过一遍。第二类是数据体检类。数学建模、数据分析项目必备把缺失值、异常值、重复值这些脏活都交给脚本干。第三类是文档生成类。比如自动整理会议纪要、生成复盘报告、转写周报格式规范且省心。第四类是前端性能检查类。检查页面加载性能、图片尺寸、bundle体积让AI在开发过程中顺手就把性能问题发现了。第五类是AI漫剧脚本类。最近这个方向特别火把分镜脚本、台词格式、运镜描述规范写成skillAI生成的漫剧脚本会工整很多后面剪辑也更好处理。5.2 使用skills时容易踩的坑我把自己踩过的坑和身边朋友遇到的常见问题整理成了一张速查表问题原因分析解决办法装了skill但不生效目录路径不对或SKILL.md文件名大小写错误检查目录层级与文件名严格按工具要求的约定触发太频繁description写得太宽泛限定触发场景写明“不适用”的情况触发不到description里的关键词跟用户实际表述不一致多写几个同义词和变体说法覆盖用户常见表达脚本跑出乱码中文环境编码问题脚本内强制UTF-8输出必要时设置环境变量模型不按脚本结果走SKILL.md没强调“以脚本输出为准”执行步骤里明确要求“先跑脚本再基于脚本输出分析”多个skill功能重叠同一场景挂了多个相似skill保留一个高质量的其余的停用避免调度冲突这里面最值得展开说的是编码问题。我在Windows上跑数据检查脚本时pandas输出中文经常报错原因就是默认编码不是UTF-8。后来我在脚本开头加了两行import sys import io sys.stdout io.TextIOWrapper(sys.stdout.buffer, encodingutf-8)问题就解决了。这种细节不写进日志你根本不会意识到是这里出的问题。5.3 几个实用习惯建议从第一天就建立调用别人的skill之前进目录里把SKILL.md通读一遍理解它的使用边界别装上就无脑用。一个看不明白的skill大概率在关键时刻也不可靠。每个skill都尽量配一个scripts目录把计算逻辑从SKILL.md里剥出来。纯靠模型读文字做计算既慢又不稳定。好的分工是脚本负责精确计算模型负责判断和表达。对skill做版本管理。我自己是把所有自用skills放在一个Git仓库里每次修改都提交。时间久了你会发现某次“优化”可能反而让触发率下降了有历史版本可以回滚很重要。定期清理不用的skills。skill毕竟是会被模型扫描和匹配的装得太多太杂匹配效率会下降。每过一段时间把不用的或者已经合并的删掉保持库精简。toolibus那篇关于清理skills的文章我也看过核心就一句话技能数量少而精远好过多而杂。写在最后的使用体会说句实在话skills这东西初看像个文件夹加一个markdown文件实际操作起来才会发现它的门槛不在于写文件而在于“理解模型怎么使用这个文件”。我自己调了几十个skill之后最大的心得是把description当成一个搜索索引来写把SKILL.md正文当成给同事看的操作手册来写把scripts当成一个实习生去安排——索引要精准手册要清晰实习生的工具要可靠。还有一个小建议不要满足于下载别人写好的skills拿到手之后花半小时改一遍哪怕只是把自己项目的具体规范加进去效果都会立刻不一样。别人的skill解决的是通用问题你的项目里的实际问题只有你自己最清楚。这一步改造才是skills真正发挥威力的开始。 
长河君 · 2026/10/3 6:02:10 · 阅读 1.2k AI Agent Skills全解析：原理、安装与手写实战
最近我把工作流里的Agent又折腾了一遍起因很简单每天让Claude Code、Codex这类编程助手干活总觉得它们“懂技术但不懂业务”。同样是改一个前端页面它能把TypeScript类型修得整整齐齐却不知道我们这个项目的命名规范和历史包袱同样是跑一次数学建模的赛前检查它不会主动去看数据有没有量纲不一致。直到我把一些写好的skills塞进去这个问题才算真正解决。这篇就来聊聊skills这件事它到底是个什么东西为什么各家Agent都在推怎么把GitHub上别人写好的skills装到自己环境里以及更重要的——怎么动手写一个真正能用的skill。我会结合前端开发、数学建模、AI漫剧脚本这些我实际跑过的场景把安装、调试、踩坑的完整过程都摊开讲。1. 先搞清楚skills到底是什么为什么突然这么火1.1 从一段真实工作流说起先还原一个典型场景。我让AI助手“帮我整理一下这周提交的代码重点看有没有明显的逻辑漏洞”。如果没有skills模型会怎么做它会调用git相关工具把所有diff都翻一遍然后基于它内置的“代码审查常识”给你一顿输出。结果往往是常规问题说得头头是道但你项目里真正的隐患比如某个历史接口的兼容性约定、某张业务表的唯一键规则它一概不知道。加了skills之后就不一样。我提前写了一个“团队代码审查”技能里面有完整的分步流程先拉diff再对照项目自己的代码规范文档重点检查哪些容易踩坑的模式最后按固定格式输出报告。AI助手看到用户需求后会在合适时机加载这个skill然后按里面的步骤走。整个体验从“一个聪明但陌生的实习生”变成了“一个懂你项目规矩的老同事”。这就是skills的核心价值在不改变模型本身能力的前提下给它附加一层可复用、可共享、可维护的领域工作流和专业知识。1.2 skills、prompt、MCP到底有什么区别我经常被人问这不就是写个prompt吗跟MCP有什么区别这三者确实有重叠但定位完全不同。普通prompt是“一次性指令”你把它写进对话里这次有效下次还得重新写。哪怕你把prompt存成模板每次使用的时候本质上也还是在往上下文里塞大段文字既浪费token也容易让对话变乱。MCP是“给AI加工具”解决的是“AI能调用什么外部能力”的问题。比如接入一个数据库MCP模型就能查数据接入一个浏览器MCP模型就能操作页面。它侧重的是能力边界扩展。skills是“给AI加工作规范”解决的是“AI在特定任务里应该怎么按流程思考和执行”的问题。它不只是让模型“能做什么”更是告诉模型“这件事应该怎么做、按什么顺序做、验收标准是什么”。一个相对通俗的比方MCP是给厨师提供新食材和新厨具prompt是随口说一句“今天做清淡点”skills是直接给一本写好的标准菜谱里面连火候和装盘都给你排好了。对于需要稳定输出的重复性任务菜谱的威力远大于一句口头叮嘱。1.3 为什么说它是Agent的“肌肉记忆”我在调模型的时候越来越觉得纯粹靠模型“临场发挥”这件事效果方差非常大。同一个任务今天心情好上下文状态好它给你写得漂漂亮亮明天换个话题聊了一堆再来执行它可能连基本格式都不记得了。skills相当于把那些“稳定可靠的做法”固化下来让模型按图索骥。一次调通了以后每次都能复用。实际跑下来我觉得skills最大的三个收益是输出稳定性大幅提升。流程固定、格式固定、检查项固定不会今天给一种结果明天给另一种。领域知识可以沉淀。团队里踩过的坑、约定好的规范都可以写进skill不再依赖模型自己在网上瞎猜。上手成本低。新人来了把skills仓库拉下来AI助手立刻就能按团队标准干活。现在市面上主流的Agent工具比如Claude Code、Codex、OpenCode都对skills有一定支持。虽然各自的加载机制、目录约定略有差异但核心思路已经收敛得差不多了就是“一个技能一个文件夹里面有指令文件和可选脚本”。2. 一个Skill的标准结构与核心原理2.1 解剖SKILL.md先说最普遍的结构。一个标准的skill本质上就是一个文件夹里面必须有一个SKILL.md文件有时候还会有配套的脚本和资源文件。比如my-skill/ ├── SKILL.md ├── scripts/ │ └── check_data.py └── references/ └── team-rules.mdSKILL.md是整个skill的心脏。它通常分为两部分文件头部的元信息以及正文的指令内容。元信息一般用YAML格式包含name和description两个关键字段有些工具还会有version、author、license等附加信息。正文则是给模型读的Markdown格式说明书。以前端开发场景举个例子一个SKILL.md的头部可能长这样--- name: frontend-code-review description: 前端代码审查技能。在当前开发任务涉及React/Vue组件、样式规范、提交前检查时使用按照项目的编码规范与常见漏洞清单对代码进行逐项审查。 ---很多人会忽略description的重要性。实际上模型的“触发器”很大程度就是这个description。模型读取用户需求后会判断当前任务跟哪个skill的描述匹配匹配上了才加载。所以description写得越准确、越具体触发率越高。2.2 name和description才是真正的“触发器”我自己在写第一个skill时犯过一个错误description写得太泛比如“用于代码审查”结果AI在写代码的过程中动不动就触发审查流程烦得要命。后来我把触发条件写得非常具体限定到“涉及到React组件状态管理改动时”“提交前检查时”“明确要求审查时”才触发情况立刻就好转了。这里面有一条关键的逻辑skills不是常驻上下文的东西它是按需加载的。模型不会把所有skill都塞进上下文再慢慢挑而是靠匹配机制先选中一个或几个再把对应的SKILL.md内容加载进来。这样设计的好处是省token坏处是如果description写得不准确模型可能该触发时不触发或者不该触发时乱触发。实用的写法是在description里把“触发场景”和“不适用的场景”都写清楚。比如description: 用于数学建模赛前数据检查。当任务涉及数据清洗、缺失值处理、异常值检测、量纲统一时使用。如果是写建模论文或排版不要使用本技能。后面那句“不要使用”看着像废话但实测非常有效能显著降低误触发率。2.3 一条完整调用链是什么样的为了把原理说透我画一条文字版的调用链看一个skill到底是怎么被用起来的第一步用户在对话里发出请求比如“帮我检查一下这个CSV感觉数据有问题”。第二步Agent的调度层把请求跟所有已注册skill的description做匹配找到最合适的那个比如数学建模数据检查skill然后读取该skill目录下的SKILL.md。第三步模型把SKILL.md里的指令当作当前任务的工作规范再结合上下文里的具体数据文件开始按步骤执行。第四步如果SKILL.md里写了“需要运行scripts/check_data.py”模型就会调用本地的Python执行环境来跑这个脚本再把脚本输出结果纳入分析。最后模型按SKILL.md规定的输出格式给出结论。这条链路里最值得注意的点是脚本承担的是“确定性的计算工作”而模型承担的是“阅读理解、判断、生成结论”的工作。两者各干各擅长的事效果就很稳。我试过把整个数据检查逻辑全部写进SKILL.md指令文字里让模型“分析”缺失值比例。结果模型经常算错或者在不同轮次给出不一致的结论。后来改成脚本出统计数据、模型出分析和建议准确率一下就上来了。3. 手动安装GitHub上的skills的正确姿势3.1 准备工作先确定你的Agent支持哪种形式GitHub上现在有一大堆现成的skills仓库比如superpower skills、各类codex skills集合、数学建模专用skills库等等。安装方法跟你用的Agent工具有关系。以我常用的几个工具为例大方向上有三种形式一种是“项目内目录”你在项目的根目录下建立一个特定名称的文件夹比如.claude/skills然后把从GitHub下载的skill文件夹丢进去当前项目的Agent就能识别。一种是“全局目录”放在用户目录下的统一位置比如~/.claude/skills这样不管你打开哪个项目这些skill都可用。一种是“marketplace配置”通过一个marketplace.json或者plugins机制把远端仓库注册进来配置之后agent会自动去仓库里拉取和更新skills。不同工具的目录名称和配置文件名略有差异但大逻辑都逃不出这三种。安装前先花两分钟确认一下你用的工具是哪种能避免后面白折腾。3.2 手动安装的具体步骤手动安装GitHub上的skills说穿了就是三步下载、放对位置、确认能被识别。第一步到目标仓库看清楚目录结构。比如某仓库的目录是这样的awesome-skills/ ├── code-review/ │ ├── SKILL.md │ └── scripts/ ├── math-model-check/ │ ├── SKILL.md │ └── scripts/那你要的其实就是其中某个子文件夹。别图省事把整个仓库全clone到skills目录里那样Agent大概率识别不了因为你把多层级目录结构打乱了。第二步把对应的skill文件夹拷贝到目标位置。比如我用Claude Code全局安装就放到mkdir -p ~/.claude/skills cp -r awesome-skills/math-model-check ~/.claude/skills/如果是项目级的就放到项目目录下的.claude/skills里一样。第三步确认被识别。不同工具有不同的验证方式。最简单的做法是直接问Agent一个问题故意触发这个skill的使用场景看它有没有反应。比如装了代码审查skill就故意说“帮我审查一下src目录下的login.tsx”看它是否按SKILL.md的流程走。如果没反应检查目录位置和SKILL.md文件名是否正确有些工具要求文件名必须严格是SKILL.md大小写都不能错。3.3 安装后怎么验证生效我刚学skills那会儿最大的困惑是“怎么知道它生效了”。后来总结了一套验证方法执行顺序从快到慢先看文件系统。确认这个skill文件夹在Agent扫描的路径下。其次看提示。有些Agent在加载skill时会在界面里显示一个提示比如在输出里出现“已加载技能xxx”或触发框里出现对应的工具被选中了。再看行为是否变化。这一步最关键——同一个任务安装前后Agent的处理流程和输出格式应该明显不同。最后看调试信息。不少Agent工具都有verbose模式打开后能看到模型接收到哪些指令、加载了哪些skill这个是最实锤的证据。如果装了没变化九成不是模型的问题而是路径或者文件结构的问题。我自己踩过的坑有两个一个是把skill文件夹套了一层壳本该是profile/SKILL.md的变成了profile/profile/SKILL.md另一个是SKILL.md文件名大小写写错了写成了skill.md导致Agent死活不认。4. 自己动手写一个可用skill以数学建模检查为例4.1 选场景、定边界理论讲了这么多还是得动手写一个。我拿热度很高的“数学建模赛前数据检查”来演示因为这个场景需求明确、边界清楚、脚本逻辑也不复杂。写skill之前先定两个东西这个skill解决什么问题不解决什么问题。我的目标很窄当用户给出一个数据文件时自动生成一份数据体检报告包括缺失值统计、异常值检测、量纲一致性检查、数据分布概览、处理建议。它不负责建模、不负责写论文这些要明确写在description的“不适用”里防止模型乱触发。4.2 写SKILL.md的核心正文目录结构和SKILL.md文件头部如下math-model-check/ ├── SKILL.md └── scripts/ └── data_check.pySKILL.md的内容我习惯分四个部分任务概述、执行步骤、输出格式、注意事项。--- name: math-model-check description: 数学建模赛前数据检查技能。当用户提供数据文件CSV/XLSX并要求进行数据体检、缺失值分析、异常值检测、量纲检查时使用。本技能仅用于数据检查不负责建模和论文撰写。 --- # 数学建模赛前数据检查 ## 任务概述 对建模比赛提供的原始数据文件进行系统性体检输出结构化的数据质量报告帮助参赛团队在建模前发现并修正数据问题。 ## 执行步骤 1. 用脚本 scripts/data_check.py 读取目标数据文件生成统计结果。 2. 判断数据文件格式优先处理 CSV 和 XLSX。 3. 对脚本输出逐项解读 - 缺失率超过 5% 的字段给出处理建议删除、填充或标注 - 数值字段的极值是否合理是否存在明显录入错误 - 各字段单位是否一致量纲差异较大的需要特别提示 - 数据分布是否严重偏态是否适合直接用常规模型。 4. 最终输出报告按下方格式Markdown 输出。 ## 输出格式 markdown ## 数据体检报告 **文件信息**文件名、行数、列数 **缺失值概览**表格含字段名、缺失数、缺失率 **异常值概览**表格含字段名、异常值个数、疑似原因 **量纲检查**描述各数值字段的单位是否一致 **总体建议**3-5 条可执行建议注意事项如果脚本运行报错先检查文件路径和数据格式再考虑调整脚本参数。不要把推断性结论写成事实性结论比如“缺失值与目标变量相关”需要先做验证。### 4.3 配上可执行脚本 SKILL.md负责指挥脚本负责干力气活。data_check.py我写得很朴素只做基础统计不搞花活因为它的任务是“给模型提供可信的数字”而不是替模型做决策。 python import pandas as pd import sys def load_file(path: str) - pd.DataFrame: if path.endswith(.csv): return pd.read_csv(path) elif path.endswith(.xlsx): return pd.read_excel(path) else: raise ValueError(仅支持csv和xlsx格式) def main(path: str): df load_file(path) print(f文件信息: {df.shape[0]}行, {df.shape[1]}列) print(\n缺失值概览:) missing df.isnull().sum() missing_ratio missing / len(df) for col in df.columns: if missing_ratio[col] 0: print(f{col}: 缺失{missing[col]}个, 占比{missing_ratio[col]:.2%}) print(\n数值字段描述统计:) num_cols df.select_dtypes(include[number]).columns stats df[num_cols].describe().T print(stats.to_string()) if __name__ __main__: main(sys.argv[1])实际使用的时候模型会自己调用这个脚本并传入数据文件路径然后读取输出。注意脚本里print的内容要整洁、结构化最好每个部分都有小标题。因为模型是靠解析这些文字来做进一步判断的输出太乱它容易漏信息。4.4 本地测试的完整流程写完之后一定要测不能写完就算完。我的测试流程是三步第一步命令行直测脚本。先用一个样例数据在终端里跑一遍确认脚本本身没有bug输出格式符合预期。第二步在Agent对话里触发。故意说“帮我检查一下data/raw_data.csv”看Agent是否加载了math-model-check这个skill。第三步检查输出是否符合预期。如果Agent没有调用脚本而是自己在文本里“分析”数据说明SKILL.md里对脚本调用的强调还不够我会把执行步骤第一条改为“首先必须运行脚本所有统计数字以脚本输出为准”。还有一个屡试不爽的小技巧在SKILL.md里加一句“如果已有stats.json缓存文件直接读取缓存不要重新运行脚本”。这能让重复对话时不重复跑脚本既省时间又省token。5. 几个经典方向与避坑速查表5.1 值得收藏的skills类型实测下来我觉得以下这几类skills的性价比最高也是GitHub上目前最值得下载的第一类是代码审查类。适合团队统一代码规范把项目的历史约定写成skill每次提交前自动过一遍。第二类是数据体检类。数学建模、数据分析项目必备把缺失值、异常值、重复值这些脏活都交给脚本干。第三类是文档生成类。比如自动整理会议纪要、生成复盘报告、转写周报格式规范且省心。第四类是前端性能检查类。检查页面加载性能、图片尺寸、bundle体积让AI在开发过程中顺手就把性能问题发现了。第五类是AI漫剧脚本类。最近这个方向特别火把分镜脚本、台词格式、运镜描述规范写成skillAI生成的漫剧脚本会工整很多后面剪辑也更好处理。5.2 使用skills时容易踩的坑我把自己踩过的坑和身边朋友遇到的常见问题整理成了一张速查表问题原因分析解决办法装了skill但不生效目录路径不对或SKILL.md文件名大小写错误检查目录层级与文件名严格按工具要求的约定触发太频繁description写得太宽泛限定触发场景写明“不适用”的情况触发不到description里的关键词跟用户实际表述不一致多写几个同义词和变体说法覆盖用户常见表达脚本跑出乱码中文环境编码问题脚本内强制UTF-8输出必要时设置环境变量模型不按脚本结果走SKILL.md没强调“以脚本输出为准”执行步骤里明确要求“先跑脚本再基于脚本输出分析”多个skill功能重叠同一场景挂了多个相似skill保留一个高质量的其余的停用避免调度冲突这里面最值得展开说的是编码问题。我在Windows上跑数据检查脚本时pandas输出中文经常报错原因就是默认编码不是UTF-8。后来我在脚本开头加了两行import sys import io sys.stdout io.TextIOWrapper(sys.stdout.buffer, encodingutf-8)问题就解决了。这种细节不写进日志你根本不会意识到是这里出的问题。5.3 几个实用习惯建议从第一天就建立调用别人的skill之前进目录里把SKILL.md通读一遍理解它的使用边界别装上就无脑用。一个看不明白的skill大概率在关键时刻也不可靠。每个skill都尽量配一个scripts目录把计算逻辑从SKILL.md里剥出来。纯靠模型读文字做计算既慢又不稳定。好的分工是脚本负责精确计算模型负责判断和表达。对skill做版本管理。我自己是把所有自用skills放在一个Git仓库里每次修改都提交。时间久了你会发现某次“优化”可能反而让触发率下降了有历史版本可以回滚很重要。定期清理不用的skills。skill毕竟是会被模型扫描和匹配的装得太多太杂匹配效率会下降。每过一段时间把不用的或者已经合并的删掉保持库精简。toolibus那篇关于清理skills的文章我也看过核心就一句话技能数量少而精远好过多而杂。写在最后的使用体会说句实在话skills这东西初看像个文件夹加一个markdown文件实际操作起来才会发现它的门槛不在于写文件而在于“理解模型怎么使用这个文件”。我自己调了几十个skill之后最大的心得是把description当成一个搜索索引来写把SKILL.md正文当成给同事看的操作手册来写把scripts当成一个实习生去安排——索引要精准手册要清晰实习生的工具要可靠。还有一个小建议不要满足于下载别人写好的skills拿到手之后花半小时改一遍哪怕只是把自己项目的具体规范加进去效果都会立刻不一样。别人的skill解决的是通用问题你的项目里的实际问题只有你自己最清楚。这一步改造才是skills真正发挥威力的开始。