玩AI编程这段时间我踩过最大的坑就是每次新开一个项目都得把同样的背景、同样的规则、同样的工作流给AI重新讲一遍。直到我把目光投向了一个叫skills的东西情况才真正变了。GitHub上现在随手一搜就是一堆skills仓库前端开发的、数学建模的、AI漫剧脚本的整个生态已经热得发烫。但说实话网上关于skills的信息挺杂的教你怎么装的有教你怎么写的有但能把原理、实操、避坑串起来讲清楚的不多。这篇文章就是我自己的全套经验从概念到手动安装GitHub上的skills再到动手写一个能用的skill最后是常见的坑和清理维护方法一次说透。1. skills到底是什么它和提示词的区别在哪先说个结论skills在很大程度上是“提示词”的进化形态但它不是简单地把提示词攒成一个文件。早期我们用AI写代码习惯是把项目背景、技术栈、约束条件、期望输出格式一股脑写进system prompt或对话上下文里。这个做法在单次对话里没问题但只要换一个会话、换一个项目一切归零又得重新搬运一遍上下文。更麻烦的是提示词越长AI的理解就越容易跑偏有些规则会被稀释有些会被遗忘效果极其不稳定。skills解决的正是这个问题。它的本质是一套结构化的、可复用的“专业能力包”里面不仅有指令文本还可以附带示例、模板、检查清单、脚本工具甚至是决策流程。Claude Code、Codex CLI这类AI编程工具会通过一个约定的目录结构加载skills让AI在开始干活之前先“读一遍手册”然后带着这套手册去执行任务。换个更贴近生活的比喻提示词相当于你在咖啡馆口头交代店员“我要一杯少糖去冰的拿铁”而skills相当于给了店员一本完整的饮品SOP手册里面写着配方、杯型、温度标准、出品检查表。后者当然稳定得多。还有一个很关键的区别是触发机制。普通的提示词是你每次手动粘贴进去的而skills是可以被AI自动识别和调用的。很多工具支持在skill的元数据里写明“这个skill适用于什么场景”AI会先判断当前任务属于哪一类再决定要不要加载对应的技能包。这有点像给AI装了一抽屉的工具它自己看着办。你现在问我推荐哪个方向先入门我的意见很明确如果你是做前端开发的先去找几个前端相关skills来用如果你在备战华为杯这类建模比赛那数学建模skills是刚需。因为这类场景通常任务链路长、规范要求高最能体现出skills的价值。2. 一个skill的内部结构手把手拆给你看很多人在GitHub上看到一个skill仓库clone下来之后发现里面有几个目录和Markdown文件但不太清楚每个东西是干嘛的。这里我拿一个典型的skill目录结构来拆解所有基于Claude Code/Codex体系设计的skills万变不离其宗your-skill-name/ ├── SKILL.md # 技能主文件包含元信息与核心指令 ├── references/ # 参考资料可以是文档、论文、代码样例 ├── scripts/ # 可执行脚本辅助AI完成重复性工作 ├── templates/ # 输出模板约束最终交付物的格式 └── examples/ # 示例输出给AI一个“仿写”的参考这里最核心的就是SKILL.md这个文件。它一般分成两个部分YAML格式的frontmatter元数据和正文指令。frontmatter里常见字段有name技能名称、description这个技能干什么、适合什么场景、allowed-tools允许调用哪些工具这些字段是给AI的“索引卡片”决定了它在什么时候被想起。正文部分则是一段完整的操作指导AI会把这段内容当成最高优先级的工作手册。举个具体例子一个“代码审查skill”的SKILL.md可能是这样--- name: code-review description: 用于对代码变更进行系统性的审查发现逻辑错误、安全隐患与性能瓶颈适用于PR评审或提交前自检。 --- # 代码审查流程 1. 先阅读diff理解变更目标 2. 按以下维度逐项检查 - 逻辑正确性边界条件、异常分支 - 安全性注入、越权、敏感信息 - 性能循环嵌套、重复计算、不必要的IO 3. 每个问题按严重程度标注Critical / Warning / Suggestion 4. 输出审查报告采用 templates/review-template.md很多新手犯的错是只写了“请你审查代码”一句话剩下的全靠AI自由发挥。这当然也能用但不同会话里的发挥水平差距极大。好的SKILL.md必须把“怎么审、按什么顺序审、用什么格式输出”全部固定下来让AI每次的结果都稳定在一个水准线上这才是skill存在的意义。另外说一下references和scripts这两个目录它们是让skill从“会说话”变成“会干活”的关键。references里面放的是需要被引用的背景知识比如团队内部的编码规范、项目的架构文档AI会根据任务需要去查阅。scripts则更硬核比如一个“批量重命名文件”的skill可以在scripts里放一个Python脚本AI只需要生成调用命令脚手架和逻辑都在脚本里。这样就把AI的长处理解意图、分解任务和代码的确定性执行结果一致接合起来了。我个人的经验是写skill不要一开始就追求大而全。先从一个你每周都会重复的任务开始把它写成skill跑通一轮再慢慢加references和scripts。第一次就试图把复杂业务全塞进去只会得到一个臃肿又难调的东西。3. 手动安装GitHub上的skills其实就三步关于“Claude Code怎么手动装GitHub上的skills”这个问题我见过太多教程写得云里雾里实际上手你会发现特别简单核心就是“把仓库clone到工具能扫描到的目录”。不同的工具有不同的默认扫描路径但思路统一。以Claude Code为例项目级skills放在项目根目录下的.skills/文件夹里全局skills放在用户配置目录下的skills文件夹里。Codex这边的常见路径是~/.codex/skills项目级则是项目目录下的.codex/skills。操作流程如下找到你想安装的skill仓库复制Git地址打开终端进入对应生效目录执行clone命令并清理仓库外层文件夹检查skill目录下是否存在SKILL.md确认frontmatter格式正确实际命令大概是这样的# 进入项目级skills目录以Claude Code为例 cd /path/to/your/project/.skills # 克隆远程仓库 git clone https://github.com/某个用户/某个skill仓库.git # 有些仓库自带版本号或多余外层目录clone完确认一下结构 ls -la这里有个小坑很容易被忽略有些skill仓库clone下来之后顶层文件夹和URL后缀不一致或者里面嵌套了好几层目录结果工具扫描不到。你需要保证的是“在skills目录下的直接子目录里能找到SKILL.md”路径不能太深。比如.skills/superpower/learn-skill/SKILL.md这种就属于路径过深工具大概率识别不了需要手动整理目录结构。装完之后怎么确认成功了两个方式一是直接在对话里让AI“列出你当前可用的skills”它会把扫描到的技能包名字给你二是用这个skill实际跑一个任务看它的行为是否有明显变化。如果AI给出的回答和没装之前一模一样那大概率是没被加载优先排查路径和SKILL.md格式。对于opencode这类新工具安装逻辑大同小异。它们的配置中心化程度更高一般都支持在配置文件里显式声明skill路径。我的建议是一次性把所有工具的skills目录都统一到同一个文件夹然后在各自的配置文件里指向这个公共目录。这样你换工具的时候不用重装一遍维护成本低很多。还有一点要提醒从GitHub上装skill之前一定先看一眼仓库的星标和更新时间简单读一下SKILL.md确认质量。现在skills生态处于野蛮生长期有不少“看起来很厉害但实际就是几行废话”的劣质包装多了不仅占用上下文窗口还会干扰AI的正常判断。宁缺毋滥。4. 从0写一个skill以数学建模场景为例数学建模skills之所以火是因为建模比赛的项目周期极短、流程极标准化审题、问题分析、模型假设、建模求解、结果检验、论文写作每一环都有很强的套路。把这些套路沉淀成skill等于把一支冠军队伍的作战方式交给了AI。我用华为杯和国赛的需求来举例给你完整演示一个skill的开发过程。先定义这个skill的目标输入一道建模题目输出一套完整的“解题作战流程”——包括选题分析、模型匹配建议、数据预处理指引、求解工具推荐、论文大纲。这个目标已经足够具体可以开始写SKILL.md。frontmatter部分要写清楚触发场景--- name: mathematical-modeling description: 适用于数学建模竞赛国赛、华为杯等解题全流程规划包括问题重述、模型选择、求解策略、论文写作指导。 ---正文部分我按“先框架后细节”的原则来组织问题重述与分类判断题目属于优化类、预测类、评价类还是机理分析类不同类型的模型偏好不同数据预处理缺失值处理、异常值检测、标准化方法选择模型选择提供一张决策表把问题类型、数据量、精度要求映射到候选模型求解与验证敏感性分析、误差指标、可视化要求论文结构摘要、问题分析、模型假设、模型建立与求解、模型评价、改进方向写到这里你会发现好的SKILL.md其实是一份“决策树Checklist”。它不给AI一个死板的答案而是给它一套在不确定中做判断的规则。比如“当数据量小于200条时优先考虑统计模型而非神经网络”这比“请选择合适的模型”有用一百倍。如果要在实战中用这个skill还可以配合一个example文件放一份往年优秀论文的摘要让AI模仿它的句式结构来撰写摘要。AI写摘要的水平高度依赖样例的风格references目录里放三到五篇不同的摘要风格示例输出质量会明显稳定下来。开发完成之后一定要测试。我自己一般的做法是拿往年试题跑一遍流程看AI是否真的按SKILL.md里的步骤走。如果它跳过了某一步说明正文里那一步写得太含糊需要补细节。测试完记得把测试结果和调整过程写进CHANGELOG方便后续迭代。同理AI漫剧场景的skill也是这个套路只不过把“模型选择”“求解验证”换成“分镜脚本生成”“角色一致性描述”“画面提示词转换”。创意类skills的编写诀窍是给足格式模板让AI在固定的结构里发挥有限的创意而不是放飞自我。5. 常用的skills推荐按场景选不踩雷现在GitHub上的skill仓库数量已经多到看不过来了我按自己的实际使用频率给你整理一份按场景分类的清单作为选型参考。场景推荐方向作用前端开发组件生成、代码审查、重构建议保持代码风格一致减少重复劳动数学建模全流程作战、模型匹配、论文润色比赛周期压缩到极限时的救命稻草AI漫剧/短片分镜脚本、角色一致性、提示词转换把零散创意变成可执行的制片流程通用工程日志分析、Bug定位、性能优化处理跨项目的日常工作流学习型概念讲解、项目拆解、代码导读用AI辅助快速上手陌生技术栈这里要专门说一个热度很高的词superpower skills。它本质上是一套经过精细设计的skills集合强调不改变工具本身的能力而是通过skill给AI“加buff”比如让AI学会更聪明的追问、自动拆解复杂任务、自主检查输出质量。我的体验是这类通用型skill比较适合作为起步配置能明显提升AI的“默认发挥水准”但它解决不了垂直领域的专业问题所以垂直方向还是需要专门技能包。使用skills还有一个常见误区是装太多。AI编程工具的上下文窗口是有限的虽然现在各家都在扩大上下文但每个被加载的skill都会占用一定空间。当你同时加载了十五个skill后续对话的有效上下文就被挤压了AI反而容易变得迟钝。我目前的习惯是项目级只保留和当前任务强相关的3到5个全局级保留不超过10个其余的按需再装。如果你关注过“tibo关于清理skills”的思路你会发现他讲的核心其实是“技能库卫生学”定期检查哪些skill一周内没被触发过哪些skill输出的内容总是被删改哪些skill与其他skill存在指令重叠。这类skill直接禁用或删除不要心软。留着它们不会带来任何安全感只会让AI做判断时多出很多干扰信号。清理技能库和清理衣柜是一个道理把不穿的衣服全部送走剩下的每一件都是能打的。6. 踩坑实录与排查方法都是真金白银换来的最后聊聊实际操作里最常见的几个问题每一个我都自己碰到过而且都花了不少时间才定位到根因。先把它们整理成一张速查表现象可能原因处理方式skill完全没生效目录路径不对或SKILL.md不在直接子目录检查目录层级确保SKILL.md在skills目录的下一级只有部分指令生效frontmatter格式错误用YAML解析器验证元数据注意缩进AI输出质量比手动提示词还差skill内容与任务目标不匹配重写正文聚焦任务边界删掉废话加载后对话变卡同时加载太多skill精简技能数量只留强相关的与现有工具链冲突allowed-tools写得不合理检查元数据中的工具声明收窄权限先说说最坑的frontmatter解析问题。YAML格式对缩进和冒号空格极其敏感很多时候你看着没问题解析器直接静默失败或者把description字段读成了空字符串。我踩过一次description里写了一句很长的话但忘了加引号结果工具扫描时完全忽略了这个skill查了半天才发现是这个引号的问题。现在我的习惯是写完SKILL.md之后先在本地用Python跑一下yaml.safe_load确认能解析通过再放进skills目录。另一个高频问题是“skill与需求错位”。比如你装了一个“重构辅助”的skill它的description写着“适用于Python项目优化”你却在一个JavaScript项目里反复调用它。AI可能会尝试套用Python的编码规范来审查JS代码然后给出大量无用建议。这不是AI笨是skill的触发机制本身依赖description里的语义匹配你给的信息太宽泛它自然容易“拿错剧本”。所以选型时一定要看description写的是不是你的场景而不是看到“重构”两个大字就装进来。还有一类问题是上下文污染。有些skill写了一大堆套话AI每次加载都要先“读”一遍这堆没有营养的内容真正用于思考的空间就变少了。我在排查“AI变呆了”的问题时把skills逐个停用做对比测试最后发现就是其中某个大而全的通用skill在拖后腿。它的本意是让AI每次回复前做十项自查结果每一项自查都在消耗推理资源最后产出的答案反而更保守、更平庸。这个教训很深刻skill的设计目标应该是“让AI在正确的方向上少走弯路”而不是“让AI每一步都战战兢兢”。最后再说一个维护技巧学会看日志。Claude Code和Codex在运行时会输出诊断信息包括加载了哪些skill、每个skill的触发命中情况。养成定期查看日志的习惯你会对自己技能库的“使用率”有非常清楚的认识。那些三个月都不触发一次的skill在下次整理时直接清理掉这就是我在反复试错后验证过的最有效的管理方式。根据我个人经验skills这套玩法目前还处于快速迭代期工具支持的细节、目录规范、分发方式都在不停演进但这个方向不会变——给AI沉淀可复用的工作流程让它越用越贴合你的习惯。最值得投入时间的不是疯狂收藏别人的技能包而是把你手头重复了无数遍的那个流程拆成规则、写成SKILL.md、跑通它。这个过程本身比任何现成的技能包都值钱。