先说个有意思的现象过去半年里skills这个单词在 AI 编程圈子里出现的频率已经快要赶上prompt了。如果你最近刷 GitHub、逛 X推特或者混 V2EX一定见过类似这样的帖子《Claude Agent Skills: A First Principles Deep Dive》《Codex 好用的 Skills 推荐》《学会了 Skills打开新世界》……说实话Skills这个说法本身不是什么新技术GPT 的 Custom Instructions、Claude 的 System Prompt、各种 Agent 的 Tool Calling本质上都是在做同一件事——给模型说明书。但为什么偏偏Skills这个概念今年火起来了它到底和之前那些方案有什么区别作为一个从 2015 年就开始折腾智能客服机器人、这几年又一直在搞 AI Agent 的老兵我想用一篇动手实践为主的文章把这件事彻底讲透。这篇文章不会堆概念。我会从Skills 到底是什么讲起然后拆解它的文件结构、编写规范、部署方式最后用几个能直接上手的案例带大家走一遍完整流程。重点是——我会把我踩过的坑、琢磨出来的捷径、还有那些文档里不会明确写出来的细节一并交代清楚。适合三类人看一是已经在用 Claude Code / Codex 但总觉得能力不够的开发者二是想给团队内部 Agent 快速统一技能规范的工程负责人三是纯粹好奇AI Agent 的能力边界到底怎么扩展的技术爱好者。无论你是哪一类读完这篇文章你应该能自己动手写一个像样的 Skill而不是只会复制粘贴别人做好的。1. 概念拆解Skills到底在解决什么问题1.1 为什么叫Skills而不叫Plugins或Tools最早做 Agent 能力扩展的时候大家习惯说插件或者工具。MCPModel Context Protocol火起来之后又开始流行连一个 MCP Server。这些方案都有各自的道理但也各有各的别扭插件意味着一段写死的代码你得维护接口、处理依赖、考虑版本兼容MCP Server 更灵活但光是起服务、配鉴权、调试连通性这一套就能劝退一大批非后端出身的人。Skills 的定位很微妙——它是一套以 Markdown 文档为中心的能力封装。核心只有一个文件SKILL.md。里面写清楚这个 Skill 能做什么、在什么场景下触发、需要模型的哪些行为、有哪些注意事项。就这么简单。模型在运行的时候会读取这份文档然后按照文档里的指引调整自己的行为方式。没有繁重的代码编译没有独立的进程没有任何网络服务。本质上Skills 是在**给模型写说明书这个维度上做到极致**而不是**给模型接外部工具**。这就不难理解为什么 2025 年这个方案突然冒头了——因为 Claude 的上下文窗口已经足够大模型本身的代码能力也已经足够强。与其费劲接一堆外部工具不如把怎么做这个领域的事情直接写进文档里喂给模型。人怎么带新人给一份新人手册。模型怎么学会一个新技能给一份 SKILL.md。逻辑一模一样。1.2 一套 Skills 体系的适用范围Skills 不是只属于某一家公司的封闭协议。实际上用 Markdown 文档描述能力边界这个思路是非常通用且开放的。我做过的实验里同样一份 SKILL.md在 Claude Code、Codex、开源的 OpenHands、甚至自己写的 Agent 框架里都能直接复用。区别只在于各家对如何引入这份文档的路径命名不同——有的叫.claude/skills/有的叫.codex/但文档内容本身是可以互通的。这给了整个开发者社区一个很大的想象空间那就是技能本身可以脱离某个具体工具而存在。GitHub 上已经出现了大量 Skills 仓库分类整理着前端开发、论文写作、分镜脚本、爬虫、安卓逆向脱壳、安全测试等各种各样的技能包。你要做的只是找到一个对口的技能包下载下来放到你的 Agent 配置目录里。想象一下以前装软件的体验——只不过这次装的不是软件装的是模型的一项新能力。这里我补充一个个人观点Skills 尤其适合那些模型本来就会但总是做不好的任务。比如写分镜脚本模型知道分镜是什么但往往写出来缺乏镜头感比如写论文模型知道学术论文的结构但总写得像高中生作文。这些任务的特点就是能力模型已经具备缺的只是高手的心法。而 SKILL.md 恰好就是一个可以无限堆心法的地方。1.3 Skills、MCP 和系统提示词三者的核心差异对比很多人会把 Skills 和 MCP 混为一谈这是最容易被绕晕的地方。我做了一张对比表把三条路线放在一起看差异就一目了然了维度SkillsMCP Server系统提示词System Prompt核心载体Markdown 文档SKILL.md独立服务进程纯文本指令是否需要代码通常不需要纯文档即可必须需要写服务器逻辑不需要迭代成本极低改文档即可较高需要重启/重发服务极低但无法结构化能力边界引导模型已有的能力为模型新增工具和外部数据约束模型行为基线适合场景特定任务的专家模式需要实时数据/外部系统联动全局人设和规则发布与复用复制文件夹即可共享需要部署服务和鉴权通常只能复制文本从这张表可以看出来这三者并不是互斥关系而是在不同层面做事情。我目前用得比较顺手的一套组合是系统提示词定人设和基础规则Skills 定义不同任务下的最佳实践需要外部数据的时候再按需接一个 MCP Server。各管一摊互不冲突。很多人会问既然系统提示词也能干活为什么还要多一层 Skills答案在于模块化和按需加载。如果你把几十个技能的说明书全塞进系统提示词里每次都全部读取一是浪费 Token二是会让模型注意力涣散。Skills 则能做到平时不占窗口用的时候才会被检索到并加载。2. 深入解析SKILL.md 是怎么做到给模型写心法的2.1 一份标准 SKILL.md 的文件结构与分层逻辑虽然各家平台对 Skills 的目录位置有不同要求但SKILL.md的核心结构基本是一致的。我以自己写过的、也是目前社区里接受度比较高的格式为例拆解一份合格技能文档应有的骨架Frontmatter 元信息区。YAML 格式写清楚技能名称、描述、适用模型、触发关键词。这一段非常重要因为 Agent 在判断当前任务要不要加载这个技能时靠的就是这一段描述与用户请求的语义相似度。关键词写得太窄技能永远不会被触发写得太宽每个任务都会优先加载它反而拖慢响应。触发条件与禁用条件。明确写清楚什么时候用和什么时候不要用。这里有个很容易被忽略的细节好的 SKILL.md 必须写禁用条件。例如一个前端代码审查技能如果用户只是问什么是 React就不该触发如果用户说帮我看看这个组件有没有内存泄漏就一定要触发。模型对边界越清楚行为就越可靠。核心执行步骤。这是整份文档的灵魂把任务的执行流程、分析思路、判断标准逐步写清楚。要具体到模型每一步应该做什么、做到什么程度算合格。比如写代码审查技能我会写先检查 props 类型定义再检查 useEffect 依赖数组最后检查事件监听器是否清理。这些指令看起来简单但模型执行出来的效果完全不同——因为之前它不知道审查这个词到底该看什么、按什么顺序看。输出格式要求。决定最终交付物的样子。是输出纯文本报告还是 Markdown 表格还是直接给出可运行的代码块有没有必须包含的章节有没有必须避开的表达方式这些都要写死。模型非常吃这一套只要输出格式约束得足够明确结果就从杂乱变成专业。示例与反例。一个正面示例比几百字描述效果都好。正面示例展示完美答案长什么样反例展示绝对不能这么写的原因。很多社区的 Skill 作者偷懒不写示例这个其实是最不应该省的部分尤其对于写作类、设计类这种主观性强的技能示例就是模型最好的老师。元认知提示。这一部分可以理解为指导模型如何思考。比如在开始之前先列出你打算审查的代码文件清单如果发现不确定的地方标记为待确认而不是直接下结论。这类提示能显著提升模型在复杂任务中的稳定性。这部分的本质是把人类专家做事的思维链过程沉淀成了文档。2.2 核心设计原则渐进式披露Progressive Disclosure我前面提到过SKILL.md 是一份文档但文档也有文档的学问。你不可能把所有细节全部塞进一个文件里——那样的 Skill 会变得臃肿读取效率低下而且模型在长文本里容易迷失重点。这里要引入一个在 UI 设计领域非常经典、用在 Skills 设计上同样适用的概念渐进式披露。简单说就是刚开始只给最必要的信息更深的细节在模型需要的时候再让它自己去翻。实现方式很直接SKILL.md主文件只写核心思路和关键步骤然后通过引用链接指向若干个子文档。例如## 执行流程 1. 先阅读 [检查准备](preflight.md)确认环境配置 2. 接着按 [漏洞分析手册](vuln_analysis.md) 中的清单逐项排查 3. 最后参考 [报告模板](report_template.md) 输出结果这种设计最直接的好处是让模型在需要哪个知识的时候才去加载哪个文件不用整个技能包几十 K 的文本一次性全读完。它的理解开销和 Token 消耗都能被控制在合理范围内。我自己实测过一个带完整子文档的技能触发后首次决策的速度比一坨超大文档快大约 30%。这在日常用 Claude Code 这种即时交互场景里体感差别还是很明显的。除了效率渐进式披露还带来一个额外的好处可维护性。你想更新某一个环节的操作规范只需要改对应的子文档不用动主文件。多技能之间的公共部分还能抽出来共享比如安全性检查这个子文档可以被前端审查、代码审查、渗透测试三个 Skill 同时引用。2.3 为什么 SKILL.md 必须是文本文件 这件事是核心优点我看过不少人的疑惑搞个 JSON 配置文件不是更结构化吗 这里面的取舍我多说两句。当你面对的是模型而不是传统编程语言的编译器时易读性远比严格的类型结构重要。模型在文本上的理解能力极强而且对于自然语言的歧义是有容忍度的——组件是否清理了事件监听和cleanup_listeners: true相比前者反而更容易被模型转化为具体的代码检查动作。JSON 虽然工整但从模型理解的角度来说它反而是一种编码过的信息需要模型先解析再执行。所以 SKILL.md 选择 Markdown 是一个非常聪明的决定。Markdown 本身就是给人类设计的最轻量级的富文本格式但同时模型对 Markdown 的解析能力也已经足够成熟。在这两者之间Markdown 是平衡点。当然如果你要写的技能涉及复杂参数传递比如给模型提供 API 调用的 schema那在子文档里嵌入 JSON 区块是完全可以的。但主文件用自然语言 Markdown 结构来激活模型行为始终是最优解。3. 实操准备环境搭建与目录规范3.1 Claude Code、Codex 的 Skills 目录结构对比先明确一个基本事实Skills 虽然语义通用但各家 Agent 的放技能包的位置还是不一样的。我当前主要的使用环境是 Claude Code 和 Codex就以这两个为代表做个说明。对于 Claude Code技能目录在项目根目录下的.claude/skills/或者在用户级目录~/.claude/skills/这会让技能对所有项目生效。目录内每个技能一个文件夹结构大致如下.claude/skills/ └── memory-leak-review/ ├── SKILL.md ├── preflight.md ├── checklist.md └── examples/ ├── good_report.md └── bad_report.md而 Codex 的姿势和 Claude Code 有一点不同它主要用的是~/.codex/skills/而且对SKILL.md的 frontmatter 有稍微具体的要求description 字段得好驱动 agent 判定的核心就在里面。不过大致模式一样都是一个文件夹一个技能以SKILL.md为入口。这里建议小团队先统一标准主文件固定叫SKILL.md辅助资料用自己的文件名命名并通过主文件引用。没必要完全照搬其他人的目录结构只要你自己清楚、模型能够通过主文件路径寻到即可。3.2 写第一个 Skill 之前的准备工作清单我拿自己做过的一个前端组件代码审查 Skill举个例带大家过一遍写技能之前该备齐哪些材料。目标任务的详细流程。你得先把前端审查这个动作拆成可执行的步骤入口文件读取、组件结构分析、props 类型检查、Hooks 依赖审查、事件监听清理确认、潜在内存泄漏标记、最终报告输出。如果没有提前拆解过流程后面写文档时会发现漏洞百出。这个领域的优秀答案样例和常见错误样例。从实际项目中挑一份你非常满意的代码审查报告把好的部分拆开看好在哪里是语气专业是问题定位准还是建议给得具体再挑一份劣质输出把模型容易犯的毛病都整理一遍——太笼统、没有具体行号、只提问题不给修改建议、语气过于确定没有留有余地。这些都是写反例的绝佳素材。边界情况清单。什么时候必须触发、什么时候坚决不触发、遇到不确定的依赖该怎样处理。把这些边界情况想清楚然后在 SKILL.md 里写清楚。准备好这三样就可以动手写 SKILL.md 了。在写之前再打开一个 Claude Code 会话把这三个问题的答案发给模型请它帮你生成一版框架草稿——比自己从空白开始写效率高很多。注意草稿必须经过人工修改不能直接用。模型写出的指令往往过于通用缺少你个人的经验和取舍。Skills 的核心价值恰恰就在那些专属心法里。3.3 编写一个可直接落地的 前端代码审查 Skills 示例下面这个示例我是按社区普遍接受的格式写的。大家看的时候不用逐字复制关键在于体会写清楚到什么程度才算到位。--- name: frontend-review description: 执行前端代码审查重点检查 React 组件中是否存在内存泄漏、 不合理的状态管理、props 类型缺失以及事件监听器未清理等问题。 当用户要求审查前端代码/推荐改进/排查卡顿或内存问题时触发。 当用户只是询问前端概念或语法解释时不要触发。 --- # React 前端代码审查 ## 触发条件 - 用户请求查看组件代码并给出优化建议 - 用户提到内存泄漏卡顿性能优化等关键词 - 代码中涉及 useEffect、addEventListener、setInterval 等异步资源 ## 禁止触发 - 用户要求解释某段代码的含义 - 用户要求生成新代码而非修改现有代码 ## 执行步骤 1. 先读取所有待审查的源文件确认组件类型函数组件/类组件 2. 逐项检查 - 是否存在 addEventListener 或全局订阅且没有在 useEffect return 中清理 - 是否存在 setInterval / setTimeout 且未在组件卸载时清除 - 是否存在大对象被直接放入 state 且无 memo 化 - 是否存在 props 缺少 PropTypes 或 TypeScript 类型定义 - 是否存在 useEffect 的依赖数组不完整可参考 eslint-plugin-react-hooks 规则 3. 输出报告时每个问题需要写清楚 - 所在文件和行号 - 问题现象和潜在影响能用用户能感知到的卡顿/崩溃来描述不要只写理论 - 可执行的修复建议和示例代码 4. 如果发现不确定的问题标记 [待确认] 而不是直接断言 ## 输出格式 使用 Markdown 表格按严重程度从高到低排列 | 严重度 | 文件位置 | 问题说明 | 修复建议 | |---|---|---|---| | 高 | src/hooks/useChat.js:42 | setInterval 未清理 | 在 useEffect 返回函数中 clearInterval | ## 示例 好的审查报告 发现 useChat.js 第 42 行存在 setInterval但 useEffect 的清理函数未清除该定时器。 这会导致聊天组件反复挂载/卸载时定时器持续堆积最终造成内存占用不断上涨。 建议在清理函数中调用 clearInterval。 坏的审查报告 这段代码有内存泄漏风险建议优化。 没有定位到具体行号也没有给出可执行的修改方案第一次写 skill 的朋友我强烈建议把这个坏报告的反例原样保留。我自己坐在电脑前实测过这个反例对模型的纠偏效果非常明显。很多模型严格审查后默认输出的就是第二种正确的废话但你把反例摆在它面前之后它的输出质量会立即上一个台阶。4. 核心环节从零到一构建一个真正好用的 Skill4.1 需求定义如何把一个抽象领域拆成模型能执行的步骤到了实战环节第一个挑战往往不是怎么把指令写清楚而是我居然连自己的领域该怎么拆解都说不太清楚。这里我分享一个拆解方法论我在构建多个技能的过程中反复使用屡试不爽。假设我们要做一个论文写作 Skill。大多数人第一反应是写帮用户写论文——这个描述太笼统模型执行时就只能靠自由发挥了效果可想而知。正确做法是往下拆一篇论文从选题到成稿至少可以拆成六个阶段——文献检索、论文大纲、论点论证、语言润色、引用管理、格式校对。每个阶段有不同行为标准拆完之后你把每个阶段对应的任务写清楚这个 Skill 的基本框架就成形了。再往下每个阶段还要继续细化该看什么、该问什么、该输出什么。比如大纲阶段先确定论文类型是实证研究、综述还是观点性文章再按学科惯例构建 outline 层级结构。文献检索阶段要收集哪些字段作者、年份、期刊、核心结论检索结果的整理格式是什么。这些细节就是区别于通用模型的地方。我个人的建议是拿一张纸把这些阶段和操作全部写出来。这一步不需要任何技术含量但它是整个 Skills 工程中最重要的工作。你甚至可以把它看作是在给一个人写工作手册想清楚这个问题之后你离写一个专业技能包就只差最后一步——把他的操作转换成模型的指令语言。4.2 交互式引导设计让模型在任务不明确时主动追问好的 Skill 除了能处理清晰任务还得在任务信息不足时会向用户主动提问。很多新手写的 SKILL.md 有个通病——假设模型面对的用户需求总是足够清楚的但现实中完全不是这样。比如用户说帮我写个策略——什么策略用户说做一下安全测试——测哪个系统测试范围多大有没有授权这些信息不明确时如果模型硬干结果往往差强人意。好的做法是在 SKILL.md 里明确写一条当用户意图存在歧义或者关键参数缺失时列出你最需要的三个信息向用户提问后再继续而不是直接假设。这一点在自动挖洞 Skills、安全审计这类高风险高不确定性任务里尤为重要。没有边界确认就乱扫轻则输出一堆没用的东西重则碰到诡异系统甚至误操作。我写这类技能时都会在文档里固定一个输入确认的环节先列出需要用户提供的资产范围、授权情况、时间窗口确认完毕再往下走。更好的做法是提供几个预设的问题模板让模型直接选用而不是自然发挥。比如我需要确认以下信息后才能开始1被测目标地址和范围2是否具有测试授权3测试的时间窗口和允许的测试深度。项目背景我不太确定您希望我按照哪种格式输出最终交付报告类还是表格类这种交互式设计还有个副产品——模型会更像人。因为它在接触一个新任务时会表现出接手一个活后先问清楚的素养而不是瞎猜一通后交出一份自作主张的结果。真实用户体验差异非常大。4.3 技能版本管理与多人协作Git 仓库、Code Review 与灰度发布现在很多团队已经不止一个人在做 Skills 了甚至已经出现了团队的技能仓库。这时候就得考虑工程化管理。我的做法是主技能库放在一个独立的 Git 仓库里每个技能一个目录README.md里记录这个技能的负责人、变更历史和适用场景SKILL.md 自身的 frontmatter 里还加一个last_updated字段。多人协作时最关键的是 Code Review。Skill 文档虽然不写代码但 review 起来和代码 review 一个套路这个技能的行为边界是否清晰有没有过度触发的情况示例是否容易误导模型一个好的 PR 通常包含更新的 skill 文档、三个以上的测试样例记录、以及一个验证报告说明改完之后模型干活的输出对比。这个习惯能极大减少直观感觉挺好但实际一用就翻车的情况。灰度发布同样重要。我在正式给团队全量推送某个新技能之前习惯先准备一个影子目录只让少数几个开发者用新版本其他人沿用旧版本。等收集到足够的使用反馈、跑通核心路径之后再通过 Git 发布公告把改动合并。而这个影子目录的实现很简单就是让测试人员在自己项目下的.claude/skills/里单独复制一份新技能主仓库的版本暂时不动。这种玩法几乎零成本但能规避大量潜在线上事故。4.4 优化细节如何给 Skills 写高质量的触发描述和禁用条件触发描述好坏的差异我直接用一个对比来说。不推荐description: 用于代码审查推荐description: 用于 React 组件代码审查重点检查内存泄漏、性能瓶颈、状态管理不合理、props 类型缺失等问题。当用户请求对前端 React 代码进行优化、排查卡顿或内存问题时触发。当用户仅要求解释代码含义时不触发。差别在哪前者的描述会让模型在用户问一个不具备明确审查性质的代码问题时也会想办法加载技能最后带来的是 Token 浪费和输出跑偏后者不但把触发场景写清楚了还把最重要的不触发场景也写进去了。模型对禁令的敏感度远高于指令。一条描述精准的技能在执行时不打扰用户的频次才会低使用体验才会有本质提升。这里再分享一个技巧写触发描述时多想想用户在什么情况下会想要这个技能。是遇到了具体报错是想要一个特定格式的交付物还是想开启一轮特定思维模式的头脑风暴把这些具体情境写进描述里模型的匹配精度会高很多。如果拿不准写完描述后拿几个会不会触发的测试问题去实测看模型的加载日志微调描述。这个过程多搞两三轮描述质量就基本到位了。5. 好用的技能来源去哪里找现成的 Skills5.1 主流开源仓库与下载平台盘点自己从零写 Skill 很爽但更多时候大家的第一步大概率是找一个现成技能装上试试。那么问题来了去哪找目前主流渠道有这几类GitHub 开源技能库。搜索关键词skills、claude-skills、codex-skills能找到大量聚合仓库有的已经做到了几百个技能的规模。这些库通常按领域归类看 README 就能大概判断技能质量。比较妙的经验是别光看 star 数要看最近 commit 时间以及是否有人提 issue 反馈某一类场景失效。AI 领域的文档时效性极强半年不更新的技能大概率已经跟不上模型版本。官方市场和内置集成。部分 Agent 服务商开始支持官方技能市场下载安装可以走官方命令或 Web 界面。这类技能通常维护较好、兼容性高但数量有限且比较偏大众场景。如果需求小众大概率还是得去开源社区找。个人博客与技术社区分享。很多一线开发者会把写在生产环境里验证过的技能包发到个人博客或者技术社区并附上实际使用效果截图。这类来源的质量往往两极分化明显要重点看作者的使用场景跟你的相似度有多少。他自己验证过的场景可能压根不是你的场景只凭他写得不错就直接拿到生产环境容易踩坑。这里我给大家一个安全准则任何来源的技能包第一件事是读一遍 SKILL.md而不是立刻扔进配置目录。读懂这份文档之后重点关注两件事——它建议的触发条件是否会误伤到你的正常使用它的执行步骤里有没有在你的业务域里明显不合理的假设你应该极少看到完全满足要求的文档改一改很正常直接改完再用就好。5.2 如何判断一个现成 Skill 的质量高低既然现在技能包市场鱼龙混杂学一眼看出这个 Skill 到底行不行就很有必要。我的经验一般看这五条描述是否窄而深。好的技能描述只聚焦一个足够的领域而不是大而全的万能模板。看到适用于各种代码审查这种描述基本可以判断是粗制滥造。有无反面示例。前面反复强调过一个高质量技能必然包含不该怎么做的示例如果没有大概率作者只是把自己的一些思路草草转述并没有在真实场景中反复打磨过。步骤是否可验证。每个核心执行步骤是否给出了做到什么程度算合格的检验标准如果一个技能的全流程只是分析问题、给出方案、输出报告这种空话那你装了它和没装几乎没区别。是否提供了追问机制。我不只一次说过好的技能在信息不足时知道先提问。如果整个文档通篇都是他会很聪明地自己搞明白一切的暗示这种文档就是把你当外行。有无版本更新记录。有没有历时多个版本的自然演进痕迹再结合更新时间判断作者是否还有持续维护。结合这五条基本能筛掉 80% 的垃圾技能包。剩下的也会比较自然地进入你愿意在它身上投入时间再去二次定制的候选名单。5.3 我已经用过的、确实能提高效率的几个技能示例这里不卖关子直接说三个我已经在生产环境中长期用的技能包以及它们带给我的具体收益。第一个是代码审查类。我自己改造过的前端 React 审查技能用了大半年。它并不是什么黑科技但每一次审查输出的报告都非常稳定它会自动标出问题所在文件和行号、给出修复方向有的还会附上它实际检测到的代码片段供我快速跳转确认。最重要的是——它不会在高危问题上含糊其辞每次确认到内存类问题都会写得格外详细让我这个常年救火的人觉得非常省心。第二个是分镜脚本类。社区里有个做短视频分镜的技能包非常精巧。它会按景别、运镜、时长、画面描述、音频、字幕这样的结构输出分镜表。写完 SKILL.md 的过程中我对分镜脚本到底该包含哪些必要信息做了一次系统性梳理这个价值甚至超过了技能本身的使用价值。在使用效果上之前模型直接生成的脚本总会漏掉运镜逻辑但套上这个技能之后每一版输出都规规整整。第三个是论文写作辅助类。这个技能在 WorkBuddy 和 Codex 上都有适配版本它把论文拆成了摘要撰写、引言逻辑、相关工作、方法论、结论、参考文献管理等环节并且为每个环节制定了具体的输出约束。我拿它写过一篇技术综述从框架生成到最终润色全程的产出质量比较稳定减少了先写一段看看不行再改的来回拉锯。客观讲这几个技能都不算神乎其神但它们的共同特点很突出——就是把一个有经验的人本该知道的窍门全部显性化地写在了文档里。这恰恰是 Skills 最有价值的地方。6. 常见问题与避坑经验6.1 技能不触发或者误触发的原因排查很多新手装完技能后发现明明按照说明放了文件夹但模型就是不用。排查思路是这样的第一步检查目录结构和命名。SKILL.md是否拼错了文件夹层级是否正确有没有把技能错误地放到了某个不读取的位置这些基础问题占了 70% 的故障来源。第二步检查 frontmatter 的description字段。你有没有写上足够明确的触发条件和不触发条件单纯一个用于代码审查让模型很难对任务和技能做高精度匹配。试着把描述改得更具体多提关键词和用户场景。第三步看模型的加载日志。绝大多数 agent 都会在调试模式下打印出来已加载技能还是未加载技能以及对应的评分。这个日志是定位问题的最关键手段。如果你用的工具没有日志就主动在会话里问一句你现在加载了哪些技能——多数模型会如实回答。反过来如果技能过度触发比如用户只是随口问个前端概念它就要进入审查模式多半是禁用了条件没写。老老实实把什么时候不要触发写在描述里这个问题能解决一大半。6.2 技能生效了但输出质量不稳定的原因与优化技能已经加载输出却不稳定这通常不是模型坏了而是我们的描述还是太模糊。举几个我自己踩过坑的例子。第一种输出格式约束不彻底。你说请输出审查报告模型可能会输出大段大段的叙述型报告。你要的是表格还是列表报告中是否需要行号按严重度怎么排序这些如果没写死模型每一次输出风格都可能不一样。解法把格式要求写成一整段强制指令一个示例。第二种步骤顺序过于随意。如果 SKILL.md 里写的是分析组件 - 给出建议模型可能上来先写总结再往回倒推细节这会破坏执行逻辑。解法把步骤写成先 X再 Y最后 Z的强制顺序并且说明每一步的输出物是什么。第三种没有终止判据。模型经常会在你已经满意之后还反复提出修改建议甚至自问自答。解法在文档里写明报告输出完成且用户未提出进一步需求时停止生成等待用户反馈。就这一句能砍掉很多不必要的后续输出。第四种也是最重要的一点——上下文污染。如果你在一个已经长对话很久的会话里换用技能模型很可能被更早的上下文风格带偏这时候技能的作用会被明显削弱。切记测试技能一定要开一个新的会话用全新姿态去验证效果否则你收获的判断都是错误的。这一点我在实际工程里反复踩坑后已经写进了团队的使用规范。6.3 一份避坑速查表新手最容易犯的五个错误错误类型具体表现正确做法描述过度宽泛触发器永远命中不了写具体场景和禁用条件没有输出模板每次生成风格漂移固定输出格式配示例步骤顺序模糊模型跳步、回退强制顺序写清阶段产物不设终止判据输出冗余话题不断写明结束条件保留等用户确认忽略跨会话污染技能效果随对话变差新会话测试避免上下文干扰写到这里我其实特别想再强调一件事Skill 是一个活的文档不是一次写完就一劳永逸。模型底层升级了、任务场景变了、用户反馈的问题多了都需要回过来改文档。我自己的习惯是每个月花一个下午把所有在用技能整体过一遍把它们在使用中遇到的又没按预期走的情况记下来试着在文档里补充或修正对应指令。这有点像调菜谱——盐放多少火候多大全是在一次次实际翻炒中试出来的。Skills 体系的出现侧面印证了一件事在 AI Agent 这条路上光靠模型本身大而全是不够的真正的差异开始来自于你能不能给模型一份足够专业、足够具体、足够可执行的心法。而这份心法可以是一个人独自积累的经验也可以是一个团队共同维护的资产。下一个半年我相信会有越来越多的组织和开发者进入这个领域把自己的独门绝技封装成一个个规范、收敛、可复用的技能包。如果你还没有动手试过这篇文章之后不妨找一个最常做的领域先写一份 SKILL.md再让模型按你的方式试一试——你可能会有意外惊喜。