skills 这个词最近在 AI 编程圈里几乎天天有人提。你刷视频能看到 superpower skills翻 GitHub 能翻到一大堆 claude skills、codex skills 的合集连 opencode 和各类插件生态也把 skills 当成标配。我最早也是一头雾水——这不就是一堆 markdown 吗为什么大家当个宝真正用上之后才明白skills 解决的是 AI 编程助手“记不住事、干活没套路”的痛点把一套成熟的流程固化下来让模型碰到对应任务时自动按步骤执行。这篇文章是我自己从零折腾 skills 的记录从 GitHub 手动装、验证、选型到写自己的第一个 skill再到数学建模、前端开发这些具体场景的配置最后把踩过的坑和排查方法一并整理出来。适合刚接触 skills 但被各种教程绕晕的朋友也适合已经装了一堆技能但觉得不好用、想自己动手重写的人。我会尽量把每一步怎么操作、为什么这么做讲清楚少讲虚的概念多给能直接上手的方案。1. 先说清楚AI 编程工具里的 skills 到底是什么1.1 不是提示词也不是插件skills 的定位先纠正一个最常见的误解skills 不是一段提示词也不是一个插件。提示词是一次性的你说完就没了下次还得重新组织语言而 skill 是一个结构化的文件或一个目录里面有指令、有示例、甚至还有配套的脚本和模板模型每次用到它时都会读到完整的流程说明。插件呢插件通常运行在工具外部负责调用 API、操作文件系统这些“动手”的事。skill 的重心不一样它首先是给模型看的“说明书”。当然一个完整的 skill 也可以附带脚本让模型在执行时调用所以它俩的边界会有一点重叠但定位完全不同。打个比方提示词像是你临时交代同事“帮我把这个表格整理一下”而 skill 是一份标准作业指导书里面有整理步骤、格式要求、检查清单同事模型下次再遇到类似活就知道直接按这套流程走不用你重新讲一遍。这背后其实是一个很大的痛点大模型的上下文是“一次性”的每次新开对话它就把之前的事忘光了。你上次手把手教它怎么写的代码规范、怎么处理数据、怎么排版这次全不记得。skills 就是把这些经验固定成文件相当于给 AI 配了一个可复用的“第二大脑”。1.2 Skills 在 Claude Code、Codex、opencode 里的存在形式目前市面上主流的 AI 编程工具对 skills 的支持方式不太一样我按实际使用频率说一下。Claude Code 是做得最完整的一个。它规定每个 skill 是一个文件夹里面必须有一个 SKILL.md 文件YAML 头里写 name 和 description正文写具体的操作指令。技能放在两个位置项目级的是.claude/skills/个人级的是~/.claude/skills/。工具启动时会自动扫描这些目录把每个技能的 description 加载进模型模型根据任务判断要不要调用。CodexOpenAI 的编程助手走的是另一条路它主要靠 AGENTS.md 这类项目说明文件来约束模型行为。社区里很多 codex skills 其实是把 Claude 的 skill 格式转成 markdown 指令或者做成一个可以被引用的文档让 Codex 在项目里读取。你可以理解为“技能内容一样外壳不同”。opencode 作为开源社区很活跃的工具插件机制是它的特色skills 一般以插件或者 preset 的形式存在原理同样是“把一套指令持久化模型按需读取”。所以别被各种工具的名字吓到核心思路就一条把可复用的流程写进文件让模型在合适的时候读出来执行。你在 Claude Code 里学会了怎么写 SKILL.md到了别的工具只是改改放文件的路径而已。1.3 为什么 2025 年大家都在聊 skillsskills 突然火起来我觉得有三个原因。第一是模型能力够了但“默认行为”不可控。模型很强什么都会一点可实际干活时经常不按你的项目规范来。你让它写代码它写得通但是风格和你团队完全不一样。skills 正好能把“团队规范”“个人偏好”固化下来让模型输出稳定在一个预期范围内。第二是经验无法跨会话复用。开发者每天花大量时间在对话里教模型各种细节这些对话关掉就没了。以前只能靠维护一个巨大的 AGENTS.md 或者提示词文件越写越乱。skills 提供了更清晰的模块化方式一个技能管一件事按需加载。第三是社区生态起来了。superpower skills 这种成体系的技能框架一出来大家发现原来技能还能这么写——不只是“做什么”还包括了“怎么思考”“怎么规划”“怎么验证”。再加上 Anthropic 自己也开源了官方 skills 仓库把 PDF、Word、Excel 这些文档处理能力做成了标准技能直接给整个生态定了一个模板。后来越来越多的人开始“技能化”自己的工作流前端开发、数学建模、内容创作几乎每个领域都能看到对应的 skills 合集。2. 从 GitHub 手动装 skills绕开一切平台的硬核姿势2.1 先搞懂 skills 的目录结构在动手安装之前强烈建议你先打开一个 skill 仓库看看里面长什么样。以 Claude Code 的官方 skills 仓库为例每个技能就是一个文件夹比如skills/docx/SKILL.md。有的技能除了 SKILL.md 还有子目录比如scripts/、references/里面放着这个技能要用的辅助脚本和参考资料。SKILL.md 是核心它的格式非常固定。开头是一段 YAML frontmatter里面至少要写 name 和 description 两个字段。然后是正文正文里是详细的步骤、规则、示例。模型拿到这个文件后会先读 frontmatter 里的 description判断当前任务是否匹配匹配了才会继续读正文按里面的流程执行。所以 description 写得好不好直接决定这个技能会不会被正确触发——这个后面写技能的部分我会展开说。一个常见的坑是很多人以为把 SKILL.md 随便丢进项目里就行结果完全不生效。其实 Claude Code 扫描的是固定目录你放在别的地方它根本看不到。一定要放在.claude/skills/技能名/SKILL.md或者~/.claude/skills/技能名/SKILL.md这个结构下。2.2 手动安装的完整步骤虽然现在很多工具和平台提供了“一键安装” skills 的功能但手动装依然是最稳的方式尤其是遇到需要特定版本的场景。步骤其实很简单在 GitHub 上找到目标仓库复制仓库地址执行git clone把整个仓库拉到本地。如果仓库很大又只想装其中某个技能也可以不带历史记录拉取用git clone --depth 1只拉最新内容。打开仓库目录找到 skills 子目录有的仓库把所有技能放在skills/下有的直接放在仓库顶层需要自己看一下。把你要装的技能文件夹复制到目标位置。个人全局技能就放到~/.claude/skills/项目内技能放到项目的.claude/skills/下。重启当前 Claude Code 会话让工具重新扫描技能目录。输入/skills或对应工具的技能列表命令检查技能是否被加载出来。这里要提醒一个细节复制的时候目录名就是技能名。如果仓库里的技能目录叫superpower-brainstorming你复制到本地后不要随手改成brainstorm否则可能出现技能名和内部指令不一致的问题。保持原名是最省心的。2.3 装完怎么验证生效装完不是结束验证才是关键。我自己踩过很多次“装完发现根本没加载”的坑所以现在每次装完都会做三步检查。第一步用技能列表命令确认加载。Claude Code 里输入/skills会列出当前可用的技能看到名字就说明目录放对了、frontmatter 解析成功。第二步做一个最小触发测试。比如装了一个 React 组件生成技能就新开一个会话直接说“帮我在当前项目里建一个 button 组件按项目规范来”。如果模型真的调用了技能它通常会在回复里明确提到“我将使用 xxx 技能来完成”或者行为明显符合技能里写的步骤。如果模型完全没提技能名、输出风格也和技能定义的不一样那大概率是没生效或者没被触发。第三步看一下日志。Claude Code 的调试日志里会记录技能加载和调用的信息。遇到技能相关的问题开着--debug跑一遍能看到它到底有没有扫描到技能文件、description 是什么、最终是否触发。这个信息比肉眼猜要准得多。2.4 安装路径选择全局还是项目级这是很多人容易纠结的问题。我的原则很简单通用技能放全局项目技能放项目。像代码审查、前端组件生成、LaTeX 排版这类跟具体项目无关的技能放~/.claude/skills/这样所有项目都能用不用重复装。但要注意全局技能越多模型每次会话要扫描的 description 就越多误触发的概率也会变高所以全局目录里只放高频使用的技能。项目级的.claude/skills/则适合放跟这个项目强绑定的内容这个项目的代码规范、这个项目的技术栈约定、这个项目的文档格式。因为项目级技能会跟着 git 仓库走团队里每个人 clone 下来都能用是团队协作的最佳载体。有一个场景要特别提一下如果你同时配了全局和项目级同名技能不同工具的处理方式不一样有的会报冲突有的会用项目级覆盖全局级。我建议规则是“项目内明确存在同名技能时优先用项目级把全局那份删掉或改名”避免出问题的时候不知道是哪个在起作用。3. 值得装进工具箱的 skills 清单3.1 Superpower Skills一套成体系的协作框架如果你只打算装一个合集我大概率会推荐 superpower skills。它不是零散的几个技能而是一套完整的“如何与 AI 协作”的方法论包含头脑风暴、方案细化、执行规划、编码、测试、调试等多个环节。它的核心理念是把大任务拆成小步骤每个步骤有专门的技能负责。比如最开始它会引导你和模型做 brainstorming把需求聊清楚然后是计划技能把任务拆成可执行清单最后才是写代码和验证。这套流程对复杂任务特别有用因为它解决了模型“拿到大需求就直接开写”的毛病。安装方式就是标准的 GitHub 流程clone 之后把技能目录放到~/.claude/skills/。它的一个特点是依赖较新的模型版本因为里面的技能会要求模型执行一些高级的规划步骤老版本模型理解不了。装完建议先用小任务跑一遍确认流程能走通再拿它去干真正的活。3.2 前端开发常用 skills前端是我自己用得最多的场景这类技能在 GitHub 上数量也最多我筛选下来常用的有这么几类。第一类是组件生成。给它一个组件的需求描述它按你预设的技术栈React/Vue、TypeScript、Tailwind 等生成完整组件代码同时附带必要的 props 定义、样式方案和基础测试。这类技能的价值在于“输出风格可预期”同一个技能生成的所有组件结构一致代码风格统一。第二类是代码审查和重构。技能里定义了审查清单模型按清单逐项检查比如类型安全、可访问性、性能隐患、命名规范输出格式化的审查报告和修改建议。第三类是样式和设计规范类技能。把 Tailwind 的配置规则、设计系统的色板、间距规范做成技能模型写出来的 UI 就不会跑偏。用这类技能需要注意一个点不同团队的技术栈差异很大别人写的技能不一定适合你。我在实际操作中的体会是前端 skills 最适合的用法不是“直接用”而是“当模板改”——下载一个组件生成技能把它里面的技术栈、代码风格改成你们团队的再用起来就非常顺手。3.3 数学建模 / 华为杯场景的 skills 组合数学建模比赛是 skills 的一个很有意思的应用场景。以华为杯这类研究生数学建模竞赛为例整个比赛流程其实非常固定读题、理解数据、建模、求解、结果分析、写论文。每一步都有大量重复性工作非常适合技能化。我见过不少人自己整理数学建模用的 skills核心是三个方向。一个是数据分析类技能负责数据清洗、缺失值处理、统计描述省去每次比赛都要重复写的样板代码一个是模型求解类技能里面写好常见模型的代码模板比如回归、分类、聚类、优化问题以及对应的参数调优思路还有一个是论文写作类技能定义好 LaTeX 排版规范、图表格式、公式风格让模型直接按竞赛规定输出论文片段。在 Codex 这类工具里用数学建模 skills 时我建议按“流程分段”来组织而不是一个技能管到底。读题阶段用一个分析技能建模阶段用一个建模技能写论文阶段用另一个写作技能。每个技能只管一段指令清晰模型不容易被长流程带偏。3.4 AI 漫剧制作的 skills 思路AI 漫剧用 AI 生成漫画、动画剧情内容这两年也是一大热门这里面的 skills 思路很有意思因为它主要不是写代码而是做内容生产。漫剧制作最大的痛点是角色一致性。同一个角色在不同画面里要保持样貌统一这光靠提示词很难稳定实现。技能可以做的事情是把一个角色的外貌描述、LoRA 触发词、画风参数固化成一个标准模块生成每个分镜时都调用它保证角色描述一致。分镜脚本生成技能可以按剧情自动切分镜头、写动作描述、决定景别提示词生成技能则把分镜描述转成文生图模型的完整提示词带上画风、光照、质量后缀这些固定参数。虽然这类技能不是传统意义上的编程技能但它们完美体现了 skills 的本质——把可复用的流程固化下来。我自己写过一个给漫画生成用的“角色描述卡”技能里面存了每个角色的详细特征描述和负面提示词后面每次生成相关画面时都让模型先读这张卡效果比手写提示词稳定很多。3.5 找 skills 的常用源头最后说说去哪找。我自己常用的几个方向第一是 Anthropic 官方仓库里面的 docx、pdf、pptx、xlsx 这几个文档处理技能质量非常高属于“官方出品、经过大量测试”的类型第二是各类聚合列表比如 Awesome Claude Code里面有人整理的技能清单第三是直接在 GitHub 上搜claude skills、codex skills、opencode skills这些关键词按 star 数和最近更新时间排序。不少技能库还提供网页版浏览界面可以先把技能的说明和示例看一遍决定要不要装再回到命令行装对应的目录。社区里还会冒出各种名字的合集仓库比如 codex nature、cola skills、typesafe ai skills 这一类。这些合集质量参差不齐我一般用三个标准判断description 写得是否具体有没有配套的示例和使用文档最近一个月有没有更新。三条都不满足的直接跳过省得装完一堆没用的技能污染你的环境。4. 自己写一个 AI skill从零到可用的完整流程4.1 SKILL.md 的基本格式和 frontmatter会装 skills 之后下一步就是写自己的 skill。千万不要觉得这是很高级的事情一个最小可用的 skill 就是一个带 frontmatter 的 markdown 文件。我先给一个最常见的模板--- name: react-component description: 在需要生成 React 组件时使用。根据描述创建组件文件、类型定义、样式和测试。 --- # React 组件生成 ## 流程 1. 分析需求确定组件名称和 props 接口。 2. 创建组件文件使用 TypeScript 定义 props。 3. 添加 Tailwind 样式禁止使用内联 style。 4. 生成对应的测试文件覆盖主要交互逻辑。 ## 输出要求 - 所有文件放到 src/components/组件名/ 目录下。 - 组件使用函数式写法导出默认组件。frontmatter 里name是必须要的格式一般为小写加连字符description也是必须要的它是模型判断触发时机的唯一依据。其他的字段像version、allowed-tools属于可选刚开始不用管。正文就是普通的 markdown但写法和写给人看的文档很不一样。你要假设读者是一个记忆力很差但执行能力很强的实习生它不会脑补你没写的任何规范但只要你写清楚了它就会严格照做。所以指令必须具体、可验证。4.2 写指令时的关键细节第一个关键细节是 description 的写法。很多人不理解它有多重要模型在会话开始时就扫了一遍所有技能的 description但它不会把正文全部读进去——只有当 description 命中当前任务时它才去读正文。所以 description 至少要包含两层信息什么时候用触发条件、它能干什么能力边界。拿我前面那个 react-component 例子来说“在需要生成 React 组件时使用”是触发条件“根据描述创建组件文件、类型定义、样式和测试”是能力边界。这样模型遇到“帮我写一个表单组件”时就会触发遇到“帮我修一下登录页的 bug”时就不会误触发。第二个关键细节是指令的具体程度。像“注意代码质量”“保证代码风格”这种话等于没说模型本来就会这么做。真正有效的指令是让模型执行可检查的动作“组件文件放到 src/components/ 下”“props 必须用 TypeScript interface 定义”“每个组件至少有一个测试文件”。这些要求模型能逐条执行你也能逐条验证。第三个关键细节是给示例。模型擅长模仿格式你给它一个“输入-输出”的示例它就能稳定复现。示例不用长一段代码加一段注释说明就够但一定要覆盖典型的边界情况。4.3 给 skill 配套脚本和模板当 skill 的指令变得复杂时纯 markdown 就不够用了。这时可以给 skill 加辅助文件。常见的做法有两个。第一个是scripts/目录放一些模型在执行过程中可以调用的脚本。比如你写了一个项目结构生成 skill可以放一个generate-structure.sh脚本指令里写明“执行 scripts/generate-structure.sh --name xxx 来生成目录结构”。这样模型就不仅是照着文档写代码还能真正执行操作。第二个是references/目录放参考资料。比如写代码规范技能时把团队的 ESLint 配置、代码范例、架构说明放进去指令里写明“在审查代码前先阅读 references/code-style.md 了解团队规范”。模型会按需读取这些材料比全部塞进 SKILL.md 正文干净得多。这里要注意一个容易踩的坑辅助文件的引用路径。SKILL.md 里的相对路径是相对于技能目录的引用的时候不要写成绝对路径也不要开头加多余的目录层级。比如技能目录是.claude/skills/react-component/里面有个references/example.tsx那在 SKILL.md 里就写references/example.tsx而不是写/Users/xxx/.claude/skills/react-component/references/example.tsx。4.4 一个前端组件生成 skill 的完整示例理论讲太多没意思我直接放一个我实际在用的精简版技能。这个技能的目标是模型在生成任何新的前端组件时自动遵循我们团队的项目规范。--- name: frontend-component description: 在项目里新建或重构 React 组件时使用。按团队规范生成组件、类型、样式与测试。 --- # 前端组件规范 ## 适用场景 - 新建页面组件或通用组件 - 重构已有组件 ## 执行步骤 1. 确认组件用途和 props先用中文写一段组件职责说明给用户确认。 2. 在 src/components/组件名/ 下创建目录。 3. 生成 index.tsx函数式组件使用 TypeScriptprops 接口定义在组件同文件顶部。 4. 生成 index.module.css使用 CSS Modules类名语义化禁止内联 style。 5. 生成 index.test.tsx用 Vitest Testing Library覆盖渲染和主要交互。 6. 在 src/components/index.ts 中导出该组件。 ## 注意 - 组件文件名统一为 index.tsx目录名即组件名。 - 涉及异步数据时在组件内部使用自定义 hook不要在组件中直接写请求逻辑。 - 所有组件必须处理加载和错误状态。写好之后放到.claude/skills/frontend-component/SKILL.md里重启会话然后随便让它建一个“用户列表组件”试试。你会发现它生成的目录结构、文件命名、样式方案全都符合规范不需要你反复提醒。一次写清楚后面无限次复用这就是 skills 的杠杆效应。4.5 写好后的测试与迭代第一次写出来的 skill 大概率不会完美这是正常的。我的迭代流程是这样的新开一个干净会话用最典型的场景测试观察模型有没有正确触发、有没有严格按步骤执行然后针对失败点修改——如果模型老是漏掉某个要求就把那个要求放到步骤列表的前面或者加上一个“最后必须检查”的清单项再测直到稳定。一个很重要的经验测试的时候不要用复杂任务用最小场景。比如测试组件生成 skill就让它生成一个最简单的 Button 组件。小场景最容易暴露执行链路的问题等链路通了再上复杂案例。5. 数学建模场景实战把 codex skills 用起来5.1 数学建模需要哪些能力落到比赛场景我先分析一下数学建模到底需要什么能力这样才能理解技能该怎么配。数学建模比赛是一个典型的“时间紧、任务重”的场景通常只有几天时间要完成从读题到成稿的全流程。拆开来看核心能力就四块数据能力清洗、探索、可视化、建模能力把实际问题转化成数学模型、求解能力写代码跑数值实验、写作能力把结果按论文格式组织起来。这四个能力对应到 AI 编程助手正好是四类 skills 的用武之地。难点在于这四类技能要能在一个项目中协同工作——数据清洗技能处理完的数据建模技能要能直接用建模技能跑出来的结果写作技能要能引用。所以配置技能的时候不能只看单个技能要看它们之间的接口。5.2 推荐的 skills 组合与分工基于上面的分析我推荐的组合是“一个流程一个技能”每个技能只干一件事输出格式固定方便衔接。数据分析技能负责最前面的脏活累活。技能里定义数据探索的标准步骤先看数据形状、缺失值比例、字段类型再决定清洗策略所有统计结果统一输出成表格方便后续引用。这个技能的好处是逼着模型每一步都汇报结果不会自己埋头跑半天然后丢给你一个结果。建模与求解技能是核心。技能里存了常用模型的模板和选择标准比如回归、决策树、聚类、整数规划分别适用于什么场景每个模型的代码模板长什么样调参的基本思路是什么。比赛时你不用临时教模型什么是 0-1 规划它直接按技能里存的模板来。论文写作技能负责格式化输出。技能里定义了竞赛论文的章节结构、LaTeX 模板的位置、图表编号和引用的写法、公式的排版要求让模型直接生成可直接编译的论文片段。5.3 用 skill 加速“读题-建模-求解-写作”全流程把这套组合用起来之后实际流程会变成这样拿到赛题先调用数据分析技能做数据探索模型会自动输出数据质量报告你花十分钟看完就知道数据有哪些坑接着调用建模技能把你对问题的理解告诉它它会按技能里的模型模板搭出求解框架你只需要修正模型假设求解结果出来后调用写作技能模型按论文模板生成对应章节图表引用和公式排版都是现成的。我实际测试下来最花时间的反而是“读题和建模”的部分因为需要人的判断而最花力气的“数据处理和格式化写作”部分技能能省掉大量时间。这也是我个人的一个体会skills 不能替代思考但能把你从重复劳动里解放出来让你把时间砸在真正需要人的地方。6. Skills 的维护与清理装多了怎么办6.1 为什么 skills 会“装废”skills 装多了之后第二个隐藏问题就会出现不生效了或者乱触发。很多人以为是工具坏了其实往往是技能库太乱导致的。原因很简单。第一模型在每个会话开始时都会扫描所有技能的 description技能多了description 之间的边界就容易模糊。两个技能都写着“生成 React 组件”模型就不知道该用哪个或者干脆都不触发。第二技能目录里堆了一大堆过时的、废弃的技能这些技能里的指令可能和当前项目规范冲突模型调到哪个算哪个行为自然不稳定。第三技能描述写得含糊触发条件太宽模型遇到什么任务都想套一下结果干活风格完全错乱。6.2 社区分享的清理思路关于清理 skills我留意到 tibo 之前在分享里讲过一套思路核心就四个字定期淘汰。大意是不要把所有技能都当宝贝留着每隔一段时间就回头看一遍自己的技能库哪些技能是最近两周真正用过的、哪些装完就再也没碰过长期不用的要么删要么归档到一个单独的目录里别让它继续参与扫描。这个思路我很认同和我自己清理电脑上软件的习惯一模一样——装的时候觉得“以后可能用得上”实际上三个月都不会打开一次留着只是增加噪音。基于这个思路我自己的清理动作更具体一些。每个月会做一次技能盘点列出所有已安装技能按“高频使用”“偶尔使用”“从不使用”分类从不使用的一律删掉偶尔使用的看是否被高频技能覆盖覆盖了也删然后审视每个高频技能的 description看有没有和别的技能重叠有重叠就精简。6.3 我的个人维护习惯除了定期清理我还有几个从实践中养成的维护习惯。命名尽量语义化且唯一。技能名就是触发时的标识不要用skill1、new-skill这种名字也不要用含义太宽泛的词。我习惯用“领域-用途”的格式比如frontend-component、math-data-analysis一眼就知道它是干什么的也方便在列表里辨认。新技能先试用再转正。新下载的技能我先放到全局目录用一两个星期确定好用且没有副作用才保留如果发现它和现有的技能冲突或者产出质量不稳定直接删掉别指望它以后会变好用。最后项目级技能要跟着代码一起 review。项目级技能是团队资产改的时候要像改代码一样慎重最好在 PR 里一起提。技能里的指令变了所有成员的行为都会变这件事要有流程约束。7. 常见问题与排查技巧实录7.1 Skills 不生效怎么办这是被问得最多的问题。我的排查顺序是先确认目录位置对不对再看文件结构对不对再看 description 是否触发。具体操作第一用/skills列表命令看技能有没有被扫描到如果列表里根本没有这个名字说明目录位置错了或者 frontmatter 解析失败了返回去检查路径和 YAML 格式比如 name 拼写、缩进问题。第二如果技能在列表里但任务不触发问题几乎一定出在 description 上——它写得太模糊或者触发条件和你的真实任务对不上。改 description 比改正文更有效。第三开--debug看日志确认模型是否真的读取了技能文件如果读到了但没执行说明正文指令不够具体模型执行时无法判断该怎么做。7.2 多个 skill 冲突怎么处理技能多了之后最典型的冲突是“两个技能都能处理同一个任务”。处理方法我在清理那节说过重新梳理每个技能的边界让它们的 description 尽量不重叠。比如一个技能管“生成新组件”另一个技能管“审查现有组件”边界就很清晰如果两个都写着“处理组件”那必然冲突。另一个冲突场景是项目级和全局级同名技能。这种我建议保留项目级的把全局的重命名或删除避免工具加载时不确定用哪个。处理好之后在日常使用中要留意模型的表现一旦出现行为和以前不一致优先怀疑技能冲突。7.3 模型不按 skill 走怎么办有时候技能明明加载了模型也提了技能名但执行到一半自己“自由发挥”不按技能里的步骤来。这种情况在复杂技能上特别容易出现。我的经验是把指令写得更“可验证”一些。每一步都给一个明确的输出物或检查点比如“每一步执行完后输出一行说明当前进度的注释”。这种要求让模型的执行过程变得更透明偏离流程时你能及时看出来。另外在技能开头加一行强约束比如“必须严格按照本技能定义的步骤执行不得跳过或自行调整顺序”对多数模型是有效果的。如果还是不行就是模型版本太旧对长指令的遵循能力不够升级模型或者简化技能文本。7.4 其他高频问题速查表我把其他几个常见问题整理成一张表方便对照现象可能原因处理方法技能列表里找不到技能目录位置错误或 frontmatter 格式错误检查路径是否为.claude/skills/name/SKILL.md检查 YAML 头技能能加载但不触发description 触发条件太模糊重写 description明确触发场景和能力边界触发了但执行结果不像技能定义的正文指令不够具体细化步骤加输出格式要求补充示例两个技能行为互相干扰description 边界重叠精简技能数量重新划分职责边界改了技能文件但没生效会话未重启或修改后没保存重启会话确认文件保存项目级技能影响其他项目不该放在项目级却放了移到全局或个人目录或按项目拆分最后再分享一个小技巧如果你对某个技能的行为不满意先别急着删试试改它的 description 而不是正文。很多时候模型不按你的预期走不是因为执行能力不行而是因为它根本没意识到“这个任务该用这个技能”。description 就是那个“意识的开关”把开关调准了很多问题迎刃而解。我自己折腾 skills 这段时间最大的体会是别一次装几十个技能先精挑细选两三个真正用顺了再扩展。技能库和衣柜一样在精不在多。你真正高频使用的技能可能就那么五六个把它们维护好比装 50 个吃灰的技能有用得多。
