你有没有遇到过这种情况同样的任务今天让AI做的结果和昨天完全不在一个水平线换一个模型或工具之前调好的提示词直接失效遇到稍微复杂一点的多步骤任务AI做到一半就“失忆”跑偏方向。我最早用Claude和各类编程助手的时候几乎每天都在干同一件事——把一堆长到离谱的提示词反复粘贴然后祈祷这次效果能稳定。后来接触了技能库skills这个概念才意识到问题出在哪我一直在给AI“讲道理”却没有给它一套可复用、可维护的“作业指导书”。Skills说白了就是一套给AI模型用的“岗位手册”。它不是简单的一段提示词而是把某个领域比如数学建模、前端开发、AI漫剧制作的完整流程、判断标准、操作步骤、常用脚本全部固化成一个标准文件夹放到模型能读取的固定位置。当你的任务描述命中技能文件的触发条件时模型会自动加载这份手册按照里面的流程往下走。这篇文章我把自己的完整经验整理出来从原理、安装、手动配置、编写规范到场景实战和避坑指南全部讲透适合所有在用Claude Code、Codex、OpenCode这类AI编程工具又不满足于“只会聊天”的人。1. 技能库的整体设计与核心思路我在最开始接触skills时有个误解以为它就是“高级提示词集合”。用了一段时间后才明白技能库和提示词根本是两个维度的东西。1.1 为什么需要技能库而不是长提示词长提示词最大的问题是“一次性”和“不稳定”。你把50行提示词塞进对话里模型确实会照做但每次对话都要重新贴一遍换一个项目、换一个模型版本这些提示词可能就失效了。更麻烦的是长提示词会污染上下文窗口——每个任务都带着一大段背景说明真正有用的对话信息被挤到最后AI的处理质量自然下降。技能库解决的正是这个问题。它把知识、流程和工具封装在项目目录之外或者项目之内由模型按需加载。你在对话里不需要贴任何长文本只需要正常说出你的需求模型发现这个需求匹配某个技能文件的描述就会主动去读那个技能文件并按照里面的规定执行。这种方式有三个很实际的好处上下文更干净。技能文件只在被触发时才加载平时不占用对话空间。经验可沉淀。你在一个项目里调试好的方法可以固化成一个技能文件下次任何项目都能复用。行为可约束。你可以通过技能文件强制模型“先做A再做B做完必须输出检查清单”比在提示词里苦口婆心管用得多。1.2 技能库和AGENTS.md、MCP的分工很多人在配置AI开发环境时会同时听说三个东西AGENTS.md、MCP和skills。这三者经常被混为一谈但它们的分工完全不同。AGENTS.md是放在项目根目录下的规则文件它描述的是“这个项目是什么、代码结构如何、有哪些约定”。它属于常驻上下文模型一进入项目就会读取作用是维持“项目记忆”。MCPModel Context Protocol则是一个通道协议它让模型能调用外部工具比如查数据库、发请求、操作浏览器它提供的是“手和脚”。技能库处于两者之间它不常驻也不是调用工具而是“方法论的抽屉”。模型收到任务后判断这个任务属于哪个抽屉就抽出来看。抽屉里既写了怎么思考也可能带一些脚本和代码片段供模型直接调用。一句话总结——AGENTS.md管认知MCP管能力skills管方法论。三者配合才能真正把AI从一个“聪明但没规矩的实习生”变成一个“熟悉你工作流的老手”。1.3 技能文件的基本目录结构虽然不同工具对技能的加载路径有差异但技能文件本身的结构是统一的。一个标准的技能文件长这样my-skill/ ├── SKILL.md ├── scripts/ │ ├── analyze.py │ └── run.sh ├── references/ │ ├── checklist.md │ └── example-output.md └── assets/ └── template.mdSKILL.md是整个技能的核心必须有它定义了技能的元信息和主体内容。scripts、references、assets这些是辅助目录用来存放脚本、参考文档、模板让SKILL.md保持精简。这个结构本质上对应着一个好的作业指导书先看总则SKILL.md不懂再查附录references需要动手就用工具箱scripts。2. 安装与引入手动装上GitHub上的skills对大多数动手能力强的人真正的需求是把GitHub上别人写好的优秀技能装进自己的工具里。这个过程在Claude Code、Codex、OpenCode里面操作方法略有不同但底层逻辑是一致的。2.1 先搞清技能应该放在哪里以Claude Code为例全局技能目录是~/.claude/skills/也就是说你在终端里执行ls ~/.claude/skills能看到几个文件夹每个文件夹都是一个技能。Codex的目录是~/.codex/skills/OpenCode则可能用~/.config/opencode/skills/。Roo Code这类VSCode插件通常同时支持全局目录和项目级目录项目级目录一般是项目根目录下的.roo/skills/。一个容易忽略的点很多工具也支持项目级技能目录。如果某个技能只在这个项目中用比如公司内部规范、特定比赛模板放到项目里更合适这样不会污染全局环境。如果技能是通用的比如“数据清洗流程”“前端代码审查清单”就放到全局目录所有项目都能触发。2.2 手动安装三步走手动安装没有任何神秘的地方就是三步下载、放对目录、验证。第一步从GitHub上把技能仓库克隆下来。安装某个具体的技能时不要克隆整个聚合仓库到skills目录里那样会产生嵌套结构很可能导致技能无法被识别。正确做法是先把仓库克隆到临时目录再把其中真正是技能的文件夹复制到你的skills目录git clone https://github.com/xxx/awesome-skills.git /tmp/awesome-skills cp -r /tmp/awesome-skills/math-modeling ~/.claude/skills/如果某个技能是单独仓库直接克隆到skills目录就行。第二步检查目录结构是否正确。到skills目录下确认里面有SKILL.md文件位置在技能文件夹的根目录不要套一层多余目录。这一步出问题的情况特别多很多人下载完直接解压结果变成了~/.claude/skills/foo-main/SKILL.md这种结构少一层或多一层都会导致加载失败。第三步重新启动会话验证。大多数工具在启动时才扫描技能目录所以装完技能必须重启对话或者执行工具提供的刷新命令。验证时不要直接问“你有哪些技能”而是直接抛一个能触发技能的真实任务。比如刚装了一个“数学建模”技能就给它一个建模题目观察它是否按照技能文件里的步骤走比如先做数据预处理、再做模型选择、最后做灵敏度分析。如果它只是自由发挥说明技能没有被正确加载或者描述没有匹配上。注意从GitHub装技能时尽量选更新时间在半年内的仓库。AI工具迭代很快很多老技能文件里的命令、参数结构都是半年前的了用在今天的模型上轻则多余重则产生错误指导。2.3 几个值得常逛的技能源网上已经有不少人专门维护技能聚合仓库。有官方性质的Anthropic开源示例库里面都是经过验证的精品技能也有社区维护的awesome-claude-code、awesome-coding-agent-skills这类列表仓库会按场景分类整理出写文档、写代码、做测试的各种技能。逛这些仓库时我有个习惯只看两类技能。第一类是和自己工作强相关的直接拿来用第二类是结构写得特别好的我会拆开来研究它的SKILL.md是怎么组织步骤的研究完自己仿写。技能库这个东西没有统一标准看十份好的SKILL.md比看一百条“技能推荐”更能提升你自己的写作水平。2.4 不同工具的兼容性与差异同一份技能文件在不同工具里表现不完全一样原因是各工具对“技能何时被触发”的判定机制有差异。Claude Code更倾向于通过任务的语义描述来匹配技能描述OpenCode可能更依赖模型自身对技能目录的感知能力Codex则把技能作为一种“隐性指令”需要它主动读取技能目录才能生效。实操中我发现一个稳妥的做法在技能文件的description里不要只写一句“用于数学建模”而是写清楚“在用户提出数学建模相关需求、数据分析建模任务、竞赛题目求解时使用本技能”。description写得越像一段“任务场景描述”越容易被正确触发。2.5 superpower skills这类打包工具热词里反复出现“superpower skills”这其实是一套比较知名的技能打包方案本质就是一个包含大量子技能的聚合仓库。这类方案适合新手快速体验“技能库能干什么”但我个人建议不要直接全量安装原因很简单技能太多反而会让模型在每次决策时多一层“这个问题要不要用技能”的判断增加延迟且容易误触发。更好的用法是浏览它的技能清单挑三五个和你实际工作相关的子技能单独安装。3. 编写自己的SKILL.md自己动手写技能文件才是技能库的最终归宿。别人的技能解决的是“通用问题”你真正遇到的那些卡点——竞赛题里的特殊格式、你们团队的前端规范、你做漫剧时的角色人设——都得自己固化。3.1 SKILL.md的元信息与正文结构一个规范的SKILL.md以YAML格式的开头字段开始最重要的是name和description。--- name: math-modeling description: 在用户提出数学建模需求、分析竞赛题目、需要构建预测模型或完成建模报告时使用。适用于全国大学生数学建模竞赛、数据分析项目及科研建模任务。 --- # 数学建模工作流 ## 步骤一理解问题 ## 步骤二数据探索description是技能触发命中的关键这里绝不能偷懒。我见过很多失败的安装案例都是因为description写得太笼统写“数学建模技能”模型根本没概念什么时候该用。要写“在……时使用”把触发场景尽量列举完整。正文部分没有统一格式但好的技能文件都有一个共性步骤化且每个步骤都有明确的交付物。不是写“做数据预处理”这种一句话带过的废话而是写清楚“做数据预处理检查缺失值比例、异常值分布、数据类型输出三个表缺失值统计表、数值型字段描述统计表、类别型字段频次表”。AI模型看到一个具体的交付物清单才知道怎么执行。3.2 渐进式执行与检查点设计技能文件最核心的设计理念是渐进式执行。你不要指望模型一口气把整个流程跑完尤其建模这种多阶段任务中间一个环节出错后面全错。好的技能会把流程切成几个阶段每个阶段之间设置“检查点”让模型完成一个阶段后先停下来把结果呈现给你等你说“继续”再往下走。检查点的写法是直接命令式的比如在技能文件里写## 阶段二模型选择与训练 完成阶段一的数据探索后不要立即训练模型。先基于数据特征给出2到3个候选模型及理由等待用户确认后再进行模型训练代码编写。这种强制停顿看似降低了效率实际上大幅提高了成功率。AI模型在长链条任务的后期遗忘和偏离的概率会线性增长。主动打断它让它汇报阶段性成果是控制质量最有效的手段。3.3 在技能里内嵌脚本、模板与代码片段SKILL.md不需要包含所有细节那是references目录干的事。你可以在技能文件里写“如需生成图表参考 references/chart-templates.md 中的模板”或者在SKILL.md中明确让模型读取特定的脚本文件再执行。这里有个常见的坑有些模型在读取脚本路径时会凭想象力“猜”脚本内容而不是真的去读文件。解决办法是在技能文件里明确要求模型“先使用读取工具读取scripts/目录下的xx.py再基于文件内容执行”把读取动作写成硬性指令。3.4 实操示例一个数学建模技能的核心段落以数学建模场景为例我在SKILL.md里会写这样一段内容## 第四步模型求解与验证 对于选定的模型必须完成以下动作 1. 写出模型训练代码代码中包含参数说明。 2. 训练完成后输出验证集上的评估指标包括但不限于MSE、MAE、R²。 3. 进行误差分析随机抽取10个预测偏差最大的样本分析偏差原因。 4. 完成灵敏度分析调整关键参数±20%记录指标变化用表格呈现并说明模型对哪个参数最敏感。注意这里没有说“用随机森林”还是“用线性回归”而是规定了任何模型都必须经过的检验流程。这就是技能文件的价值——它不替你决策而是逼模型把该做的验证动作做完避免那种“模型训练完随手输出一个准确率就交差”的敷衍行为。3.5 实操示例前端开发的skills应该包含什么前端开发场景下最有用的技能不是“写页面”这种大而全的东西而是切中痛点的约束型技能。我写过一个用于代码审查的技能SKILL.md里规定审查时必须逐项检查组件是否拆分过细或过粗、状态管理是否存在不必要的外置、样式是否包含魔法数字、可访问性是否缺失aria标签、交互是否有focus态提示。每次审查完必须按优先级输出问题列表并给出对应修复示例。这种技能几乎不会让模型“创造新东西”但它能把AI审查代码的质量拉到和资深工程师同等的水平线。原因很简单资深工程师不是比AI更聪明而是脑子里有一套完整的检查清单而AI默认情况下没有。技能文件就是把这套检查清单喂给它的通道。3.6 实操示例AI漫剧场景的技能拆解“AI漫剧”是最近非常活跃的创作方向本质是用AI批量生成分镜脚本、画面提示词、对话文本再拼成短剧。这个场景中最难的技能不是“写台词”而是角色一致性控制和镜头语言复用。因为模型默认情况下每生成一段新的画面描述可能把主角外貌完全改写一遍。漫剧技能文件里我会要求模型在每次生成画面提示词之前先根据下面的人设基线检查人物形容的一致性角色的发型、瞳色、服装主色、标志性配饰必须在每一句提示词中出现且不矛盾。然后要求镜头语言的复用写清楚固定机位、景别和场景关键词让模型严格沿用。最后在阶段检查点要求产出一张角色一致性对照表把每个场景的画面主体描述列出来人工核对。这套流程不写进技能里AI几乎不可能自己稳定做到。4. 推荐技能清单与典型场景编排只讨论原理太虚接下来给几组我在实际项目中验证过靠谱的技能编排方案覆盖大家热搜里最常出现的几个场景。4.1 数学建模竞赛与科研场景这个场景最需要的是一组能够“标准化输出结果”的技能我常驻战斗力包含以下四个技能名称核心作用触发场景>
