拓冰网站定制 
1. 从“skills”这个热词说起它到底是什么为什么突然火了最近几个月不管是在技术社区还是各种开发者群里“skills”这个词出现的频率高得离谱。很多人第一次看到它会以为是某种新出的编程语言或者框架其实不是。这里的skills指的是围绕 Claude 生态尤其是 Claude Code、Claude Desktop 这类工具构建的一套可复用的能力模块。你可以把它理解成给 AI 助手装的“插件包”或者“技能卡”——每一张卡定义了一类具体任务的做法AI 在需要的时候自动调用不需要你每次从头解释一遍。我最早接触这个概念是在折腾 Claude Code 的时候。当时我一直在想一个问题每次让 AI 帮我做代码审查、写单元测试、生成文档都要重复描述一遍要求效率太低了。后来发现社区里已经有人把这类重复性的指令封装成了SKILL.md文件放在特定目录下AI 就能自动识别并加载。这就是 skills 的雏形。再往后发展skills 不再局限于代码场景数学建模、内容创作、数据分析、甚至日常办公流程都有人在做对应的技能包。那它到底解决了什么问题核心就一个字复用。传统用法下你和 AI 的交互是“一次性”的这次教它怎么做下次换个会话它又忘了。skills 机制把“怎么做”这件事从对话里抽出来变成文件系统里的一个结构化定义。只要文件在AI 每次都能按同样的标准执行。对于需要反复做同类任务的人来说这省下的时间非常可观。适合谁来了解这个东西我的判断是三类人第一类是日常高频使用 AI 辅助编程的开发者skills 能帮你把代码规范、审查流程、测试模板固化下来第二类是做数学建模、数据分析的研究者或学生社区里已经有针对建模比赛的 skills 推荐能省掉大量重复劳动第三类是对 AI 工作流感兴趣的产品或运营人员理解 skills 的设计思路有助于你设计自己团队的 AI 协作流程。哪怕你只是刚装好 Claude Code 的新手了解 skills 也能让你少走很多弯路。接下来我会从设计思路、核心细节、实操过程、常见问题几个维度把 skills 这件事讲透。内容会涉及SKILL.md的写法、目录结构、安装方式、调试技巧以及我在实际使用中踩过的坑。你不需要有很深的编程背景只要能看懂基本的文件操作就能跟着做。2. skills 的整体设计与核心思路拆解2.1 为什么是“文件定义”而不是“对话记忆”要理解 skills 的设计先得理解它为什么选择用文件来定义能力而不是靠对话历史或者模型微调。这个选择背后有几个很实际的考量。第一对话记忆不可靠。不管你用的是哪个 AI 工具上下文窗口都是有限的。一次会话里聊了几十轮之后早期的指令很可能被截断或者稀释。你前面说的“代码要用 4 空格缩进”到后面 AI 可能就忘了。而文件是持久的只要不被删除每次加载都是完整的。第二微调成本太高。想让模型稳定掌握一套流程微调是最彻底的办法但普通人根本玩不起——需要大量标注数据、算力资源而且改一个细节就要重新训练。skills 用提示词工程的方式达到了类似效果成本却低得多。第三可版本控制。SKILL.md本质上是文本文件可以放进 Git 仓库可以 diff可以回滚。团队协作时谁改了什么一目了然。这一点对于工程场景特别重要。第四可组合。一个 skill 可以调用另一个 skill或者多个 skill 在同一任务中协同。这种模块化设计让能力可以像积木一样拼装而不是每次都要写一个巨大的提示词。提示skills 的本质是“把提示词工程产物化”。你写的每一份SKILL.md其实就是在沉淀一套可复用的提示词方案。2.2 SKILL.md 的结构逻辑元数据加指令体一份标准的SKILL.md通常由两部分组成元数据区和指令体。元数据区用 YAML 格式写在文件开头用---包裹声明这个 skill 的名字、描述、触发条件等信息。指令体则是 Markdown 正文写清楚具体要做什么、怎么做、输出格式是什么。为什么要有元数据因为 AI 需要先知道“这个 skill 是干什么的”才能判断当前任务要不要调用它。如果所有信息都混在正文里模型解析起来效率低也容易误判。元数据相当于一个索引卡片让 AI 快速筛选。元数据里最关键的是description字段。这个描述写得好不好直接决定了 skill 能不能被正确触发。我见过很多人把描述写得很泛比如“帮助处理代码”结果 AI 根本不知道什么时候该用它。好的描述应该包含动作和场景比如“当用户要求审查 Python 代码风格时检查 PEP8 合规性并给出修改建议”。指令体部分我建议遵循“目标—步骤—约束—输出”的四段式结构。先说清楚这个 skill 要达成什么目标然后列出执行步骤接着说明有哪些限制条件比如不能修改业务逻辑、必须保留原有注释最后定义输出格式。这样 AI 执行起来有章可循不会跑偏。2.3 触发机制AI 是怎么“想起”某个 skill 的很多人好奇AI 是怎么知道该用哪个 skill 的这里涉及一个“匹配—加载—执行”的流程。当你在 Claude Code 里提出一个需求时系统会先扫描已安装的 skills 目录读取每个 skill 的元数据。然后根据你的需求描述和各个 skill 的description做语义匹配。匹配度高的 skill 会被加载到当前上下文AI 再按照它的指令体来执行任务。这个机制意味着两件事。第一描述要准确否则匹配不上。第二skill 不是越多越好。如果你装了几十个 skill每次扫描和匹配的开销都会增加而且相似描述之间可能互相干扰。我的经验是常用 skill 控制在 10 到 15 个以内比较合适不常用的可以放在备用目录需要时再启用。还有一个细节有些 skill 支持显式调用也就是你在对话里直接点名比如“用 code-review 这个 skill 帮我看看”。这种方式不依赖语义匹配适合你对某个 skill 特别熟悉、想精确控制的时候。2.4 和传统插件、脚本的区别在哪有人会问这不就是插件吗和 VS Code 插件、浏览器扩展有什么区别区别还挺大的。传统插件是代码级的用编程语言写成运行在特定的宿主环境里能力受限于宿主提供的 API。skills 是提示词级的本质上是自然语言指令不依赖特定 API理论上只要 AI 能理解就能执行。这意味着 skills 的适用范围更广写起来门槛也更低——你不需要会写代码只要能把流程说清楚就行。另一个区别是灵活性。插件的行为是固定的输入输出都有严格定义。skills 则允许 AI 根据实际情况做判断比如“如果代码里有异步操作额外检查竞态条件”。这种条件分支用自然语言表达起来很自然用代码写就麻烦得多。当然skills 也有局限。它依赖模型的理解能力复杂逻辑可能执行不稳定它没有沙箱隔离安全性需要自己把控它的执行结果不如代码可预测。所以我的建议是确定性强的任务用脚本需要灵活判断的任务用 skills两者配合使用效果最好。3. 核心细节解析与实操要点3.1 目录结构skill 放在哪里才能被识别这是新手最容易卡住的地方。skill 文件放错位置AI 根本找不到。不同工具的目录约定不太一样我分别说一下。Claude Code 的情况下skills 通常放在项目根目录的.claude/skills/下每个 skill 一个子目录子目录里放SKILL.md。比如项目根目录/ .claude/ skills/ code-review/ SKILL.md unit-test/ SKILL.md doc-gen/ SKILL.md如果是全局 skill想在所有项目里都能用可以放在用户主目录下的.claude/skills/。这样就不需要每个项目都复制一份。Claude Desktop 的 skills 目录位置又不一样通常在应用数据目录下。具体路径可以在设置里查看或者看官方文档。我建议第一次配置的时候先用一个最简单的 skill 测试确认能被识别之后再批量添加。注意目录名和 skill 名最好保持一致虽然不强制但能减少混乱。另外SKILL.md的文件名是固定的大小写敏感写成skill.md在某些系统上可能识别不了。3.2 元数据字段怎么写才有效元数据区虽然字段不多但每个都有讲究。我拿一个实际例子来说明--- name: code-review description: 当用户要求审查代码质量、检查编码规范或寻找潜在 bug 时使用。适用于 Python、JavaScript、TypeScript 等主流语言。 version: 1.0.0 author: your-name tags: - code-quality - review ---name是 skill 的唯一标识建议用英文小写加连字符不要用空格或中文。description是最重要的字段我前面强调过要包含动作和场景。version用于版本管理改动了就升版本号。tags是辅助匹配用的可以写多个。有个坑要注意description不要写得太长。有些模型对元数据长度有限制超过一定字符数会被截断。我的经验是控制在 100 到 150 字之间把最关键的信息放前面。另外如果你的 skill 有依赖关系比如需要先运行某个脚本可以在元数据里加一个requires字段说明。虽然不是所有工具都支持但写上没坏处至少给人看的时候清楚。3.3 指令体的四段式写法指令体是 skill 的灵魂。我总结了一个四段式模板实测下来效果比较稳定。第一段目标声明。用一两句话说明这个 skill 要达成什么。比如“本 skill 用于对指定代码文件进行静态审查识别风格问题、潜在 bug 和性能隐患”。第二段执行步骤。把流程拆成有序步骤。每一步都要具体不要写“检查代码质量”这种模糊表述要写“逐行检查缩进是否一致函数命名是否符合 snake_case 规范”。第三段约束条件。说明哪些事情不能做。比如“不要修改业务逻辑”“不要删除原有注释”“遇到不确定的问题时先询问而不是自行决定”。约束能防止 AI 过度发挥。第四段输出格式。定义结果长什么样。可以用 Markdown 表格、列表或者 JSON。格式定义得越清楚输出越稳定。我举个完整的例子是一个简化版的代码审查 skill## 目标 对用户指定的代码文件进行审查输出问题清单和改进建议。 ## 步骤 1. 读取目标文件内容 2. 检查缩进、命名、注释等风格问题 3. 检查空指针、越界、资源泄漏等潜在 bug 4. 检查循环嵌套、重复计算等性能问题 5. 按严重程度排序输出 ## 约束 - 不修改代码只给出建议 - 不确定的问题标注为“待确认” - 每条问题必须给出具体行号 ## 输出格式 | 行号 | 严重程度 | 问题类型 | 描述 | 建议 | |------|----------|----------|------|------|这个结构看起来简单但实际用起来比一大段自由文本稳定得多。AI 知道每一步该干什么输出也规整。3.4 参数化让 skill 适应不同场景固定写死的 skill 只能用于特定场景。想让一个 skill 处理多种情况就需要参数化。做法是在指令体里用占位符比如{{language}}、{{file_path}}然后在调用时传入具体值。参数化有两种方式。一种是显式参数在元数据里声明parameters字段列出参数名和说明。另一种是隐式参数直接在指令体里写“根据用户提供的语言类型调整检查规则”让 AI 自己从对话里提取。显式参数更可控但需要工具支持。隐式参数更灵活但依赖 AI 的理解。我的建议是关键参数用显式辅助信息用隐式。比如语言类型这种影响检查规则的最好显式声明文件路径这种 AI 能从上下文推断的隐式就行。3.5 版本管理与迭代skill 不是写完就完事了需要持续迭代。我建议每个 skill 都建一个独立的 Git 仓库或者至少放在项目的版本控制里。每次修改都提交写清楚改了什么、为什么改。迭代的时候有个技巧保留变更日志。在SKILL.md末尾加一个## 变更记录段落记录每个版本的变化。这样当 skill 行为异常时你能快速定位是哪次改动引入的。另外重大改动前建议先复制一份备份。我吃过亏有一次改一个审查 skill 的约束条件结果改过头了AI 变得过于保守什么都不肯判断。回滚之后重新小步调整才好。4. 实操过程与核心环节实现4.1 从零开始写第一个 skill假设你是一个 Python 开发者想做一个自动生成单元测试的 skill。我带你走一遍完整流程。第一步创建目录。在你的项目根目录下执行mkdir -p .claude/skills/unit-test第二步创建SKILL.md文件写入元数据--- name: unit-test description: 当用户要求为 Python 函数或类生成单元测试时使用。基于 pytest 框架覆盖正常路径和边界条件。 version: 1.0.0 tags: - testing - python - pytest ---第三步写指令体。这里要注意单元测试生成有几个关键点要覆盖哪些情况、用什么断言风格、mock 怎么处理。我把这些写进约束里。## 目标 为指定的 Python 函数或类生成 pytest 单元测试。 ## 步骤 1. 分析目标代码的输入输出和依赖 2. 识别需要 mock 的外部依赖 3. 为每个公开方法生成测试用例 4. 覆盖正常路径、边界条件和异常路径 5. 运行测试确认通过 ## 约束 - 使用 pytest 风格不用 unittest - mock 使用 unittest.mock 或 pytest-mock - 测试函数命名遵循 test_方法名_场景 - 不修改被测代码 - 如果依赖无法 mock标注说明 ## 输出格式 输出完整的测试文件内容用 python 代码块包裹。第四步测试。在 Claude Code 里打开一个 Python 文件输入“帮我为这个文件生成单元测试”。如果 skill 被正确加载AI 会按照你定义的流程执行。4.2 安装社区 skill 的正确姿势社区里已经有很多现成的 skill比如 GitHub 上搜 “claude skills” 或者 “agent skills” 能找到不少。安装方式通常是克隆仓库然后把 skill 目录复制到你的 skills 目录下。但直接复制有个问题你不知道这个 skill 的质量如何也不知道它会不会和现有 skill 冲突。我的做法是先审查再安装。打开SKILL.md看三样东西描述是否准确、约束是否合理、有没有可疑的操作比如执行外部命令、访问网络。审查通过后我建议先放在一个临时目录测试确认没问题再移到正式目录。测试方法是找一个典型任务分别用 skill 和不用 skill 各做一次对比结果。如果 skill 带来的提升不明显或者引入了奇怪的副作用就不装。提示安装第三方 skill 时注意检查它是否包含脚本文件。有些 skill 会附带 Python 或 Shell 脚本这些脚本会在执行时被调用。如果你不信任来源就不要安装带脚本的 skill。4.3 多 skill 协同的编排技巧单个 skill 能力有限真正强大的是多个 skill 协同。比如一个完整的开发流程可能涉及需求分析 skill、代码生成 skill、代码审查 skill、测试生成 skill、文档生成 skill。编排的关键是定义清楚 skill 之间的接口。比如代码审查 skill 的输出格式要能被测试生成 skill 直接消费。我通常会在项目里维护一个workflow.md说明各个 skill 的调用顺序和数据流转方式。另一个技巧是用主 skill 调度子 skill。写一个dev-workflowskill它的指令体里说明“先调用 code-review再调用 unit-test最后调用 doc-gen”。这样你只需要触发一个 skill后面的流程自动走完。不过要注意skill 嵌套层数不要太深。超过三层之后调试会变得很困难而且 AI 容易在中间环节丢失上下文。我的经验是控制在两层以内。4.4 调试 skill 的实用方法skill 不生效或者行为异常时怎么排查我总结了一套流程。首先确认 skill 被加载了。在 Claude Code 里可以用/skills命令查看当前加载的 skill 列表。如果列表里没有你的 skill说明目录位置不对或者元数据格式有问题。其次检查描述匹配。如果你的需求描述和 skill 的description语义差距太大AI 可能匹配不上。这时候可以尝试显式调用看 skill 本身是否正常。然后看指令体是否有歧义。AI 执行偏离预期很多时候是因为指令写得不够明确。比如“检查代码问题”这种表述AI 可能只检查了语法没检查逻辑。改成“检查语法错误、逻辑漏洞和性能问题”就明确多了。最后用最小案例测试。如果 skill 在复杂场景下表现不稳定先用一个最简单的输入测试。确认基础功能正常后再逐步增加复杂度。4.5 性能优化让 skill 跑得更快更准skill 多了之后加载和匹配会变慢。优化方向有几个。一是精简元数据。description控制在 100 字以内tags不要超过 5 个。元数据越短扫描越快。二是分类存放。把 skill 按领域分到不同子目录比如coding/、writing/、analysis/。需要时只加载相关目录减少匹配范围。三是定期清理。三个月没用过的 skill要么删掉要么移到archive/目录。我每季度会做一次清理把不常用的 skill 归档保持活跃 skill 列表精简。四是合并相似 skill。如果两个 skill 功能重叠度超过 70%考虑合并成一个。比如“Python 代码审查”和“JavaScript 代码审查”可以合并成“代码审查”用参数区分语言。5. 常见问题与排查技巧实录5.1 skill 不生效的六种原因这是我被问得最多的问题。根据我的排查经验skill 不生效通常是以下六种原因之一。现象可能原因排查方法解决方法完全没反应目录位置错误检查.claude/skills/是否存在创建正确目录并移动文件列表里没有元数据格式错误检查---是否成对修正 YAML 格式匹配不上描述太模糊对比需求和 description重写描述加入场景词执行偏离指令有歧义逐条检查步骤细化步骤和约束时好时坏上下文冲突检查是否有相似 skill合并或删除冲突 skill报错退出依赖缺失查看错误信息安装依赖或移除依赖我重点说一下“时好时坏”这种情况。这通常是因为你有两个 skill 的描述很接近AI 在匹配时摇摆不定。比如你同时装了“代码审查”和“代码质量检查”这两个描述几乎一样AI 每次可能选不同的。解决办法就是合并成一个或者把其中一个的描述改得更具体明确区分适用场景。5.2 描述写得好不好的判断标准怎么判断一个description写得好不好我有个简单的测试方法把描述单独拿出来问一个不了解你项目的人看对方能不能说出这个 skill 什么时候该用。如果对方说不出来说明描述太模糊。好的描述通常包含三个要素触发场景、处理对象、预期动作。比如“当用户提交 Pull Request 需要审查时对变更的代码文件进行风格和逻辑检查”。触发场景是“提交 PR”处理对象是“变更的代码文件”预期动作是“风格和逻辑检查”。三个要素齐全匹配就准。坏的描述通常是泛泛而谈比如“帮助处理代码相关任务”。这种描述几乎匹配所有编程场景反而导致 AI 无法精确判断。5.3 指令体写太长的处理办法有些人写 skill 的时候恨不得把所有细节都塞进指令体结果文件几千字AI 执行时反而抓不住重点。我的建议是分层组织。核心流程放在指令体主体用简洁的步骤描述。细节规则可以放到单独的参考文件里在指令体中用链接引用。比如## 步骤 1. 读取代码文件 2. 按照 rules/style.md 中的规范检查风格 3. 按照 rules/security.md 中的清单检查安全问题这样指令体保持精简细节规则单独维护修改起来也方便。AI 在执行时会按需读取参考文件不会一次性加载所有内容。5.4 团队协作中的 skill 管理团队里多人使用 skill 时管理就成了问题。我的做法是建一个共享 skill 仓库所有人从这里拉取。仓库里分两个目录stable/放经过验证的 skillexperimental/放还在测试的 skill。每个人可以有自己的local/目录放个人 skill但提交到共享仓库的必须经过 review。review 的重点是描述是否准确、约束是否合理、有没有安全风险。另外团队里要约定命名规范。比如统一用领域-功能的格式code-review、doc-gen、> Claude Skills 实战指南：从 SKILL.md 到 AI 工作流复用
1. 从“skills”这个热词说起它到底是什么为什么突然火了最近几个月不管是在技术社区还是各种开发者群里“skills”这个词出现的频率高得离谱。很多人第一次看到它会以为是某种新出的编程语言或者框架其实不是。这里的skills指的是围绕 Claude 生态尤其是 Claude Code、Claude Desktop 这类工具构建的一套可复用的能力模块。你可以把它理解成给 AI 助手装的“插件包”或者“技能卡”——每一张卡定义了一类具体任务的做法AI 在需要的时候自动调用不需要你每次从头解释一遍。我最早接触这个概念是在折腾 Claude Code 的时候。当时我一直在想一个问题每次让 AI 帮我做代码审查、写单元测试、生成文档都要重复描述一遍要求效率太低了。后来发现社区里已经有人把这类重复性的指令封装成了SKILL.md文件放在特定目录下AI 就能自动识别并加载。这就是 skills 的雏形。再往后发展skills 不再局限于代码场景数学建模、内容创作、数据分析、甚至日常办公流程都有人在做对应的技能包。那它到底解决了什么问题核心就一个字复用。传统用法下你和 AI 的交互是“一次性”的这次教它怎么做下次换个会话它又忘了。skills 机制把“怎么做”这件事从对话里抽出来变成文件系统里的一个结构化定义。只要文件在AI 每次都能按同样的标准执行。对于需要反复做同类任务的人来说这省下的时间非常可观。适合谁来了解这个东西我的判断是三类人第一类是日常高频使用 AI 辅助编程的开发者skills 能帮你把代码规范、审查流程、测试模板固化下来第二类是做数学建模、数据分析的研究者或学生社区里已经有针对建模比赛的 skills 推荐能省掉大量重复劳动第三类是对 AI 工作流感兴趣的产品或运营人员理解 skills 的设计思路有助于你设计自己团队的 AI 协作流程。哪怕你只是刚装好 Claude Code 的新手了解 skills 也能让你少走很多弯路。接下来我会从设计思路、核心细节、实操过程、常见问题几个维度把 skills 这件事讲透。内容会涉及SKILL.md的写法、目录结构、安装方式、调试技巧以及我在实际使用中踩过的坑。你不需要有很深的编程背景只要能看懂基本的文件操作就能跟着做。2. skills 的整体设计与核心思路拆解2.1 为什么是“文件定义”而不是“对话记忆”要理解 skills 的设计先得理解它为什么选择用文件来定义能力而不是靠对话历史或者模型微调。这个选择背后有几个很实际的考量。第一对话记忆不可靠。不管你用的是哪个 AI 工具上下文窗口都是有限的。一次会话里聊了几十轮之后早期的指令很可能被截断或者稀释。你前面说的“代码要用 4 空格缩进”到后面 AI 可能就忘了。而文件是持久的只要不被删除每次加载都是完整的。第二微调成本太高。想让模型稳定掌握一套流程微调是最彻底的办法但普通人根本玩不起——需要大量标注数据、算力资源而且改一个细节就要重新训练。skills 用提示词工程的方式达到了类似效果成本却低得多。第三可版本控制。SKILL.md本质上是文本文件可以放进 Git 仓库可以 diff可以回滚。团队协作时谁改了什么一目了然。这一点对于工程场景特别重要。第四可组合。一个 skill 可以调用另一个 skill或者多个 skill 在同一任务中协同。这种模块化设计让能力可以像积木一样拼装而不是每次都要写一个巨大的提示词。提示skills 的本质是“把提示词工程产物化”。你写的每一份SKILL.md其实就是在沉淀一套可复用的提示词方案。2.2 SKILL.md 的结构逻辑元数据加指令体一份标准的SKILL.md通常由两部分组成元数据区和指令体。元数据区用 YAML 格式写在文件开头用---包裹声明这个 skill 的名字、描述、触发条件等信息。指令体则是 Markdown 正文写清楚具体要做什么、怎么做、输出格式是什么。为什么要有元数据因为 AI 需要先知道“这个 skill 是干什么的”才能判断当前任务要不要调用它。如果所有信息都混在正文里模型解析起来效率低也容易误判。元数据相当于一个索引卡片让 AI 快速筛选。元数据里最关键的是description字段。这个描述写得好不好直接决定了 skill 能不能被正确触发。我见过很多人把描述写得很泛比如“帮助处理代码”结果 AI 根本不知道什么时候该用它。好的描述应该包含动作和场景比如“当用户要求审查 Python 代码风格时检查 PEP8 合规性并给出修改建议”。指令体部分我建议遵循“目标—步骤—约束—输出”的四段式结构。先说清楚这个 skill 要达成什么目标然后列出执行步骤接着说明有哪些限制条件比如不能修改业务逻辑、必须保留原有注释最后定义输出格式。这样 AI 执行起来有章可循不会跑偏。2.3 触发机制AI 是怎么“想起”某个 skill 的很多人好奇AI 是怎么知道该用哪个 skill 的这里涉及一个“匹配—加载—执行”的流程。当你在 Claude Code 里提出一个需求时系统会先扫描已安装的 skills 目录读取每个 skill 的元数据。然后根据你的需求描述和各个 skill 的description做语义匹配。匹配度高的 skill 会被加载到当前上下文AI 再按照它的指令体来执行任务。这个机制意味着两件事。第一描述要准确否则匹配不上。第二skill 不是越多越好。如果你装了几十个 skill每次扫描和匹配的开销都会增加而且相似描述之间可能互相干扰。我的经验是常用 skill 控制在 10 到 15 个以内比较合适不常用的可以放在备用目录需要时再启用。还有一个细节有些 skill 支持显式调用也就是你在对话里直接点名比如“用 code-review 这个 skill 帮我看看”。这种方式不依赖语义匹配适合你对某个 skill 特别熟悉、想精确控制的时候。2.4 和传统插件、脚本的区别在哪有人会问这不就是插件吗和 VS Code 插件、浏览器扩展有什么区别区别还挺大的。传统插件是代码级的用编程语言写成运行在特定的宿主环境里能力受限于宿主提供的 API。skills 是提示词级的本质上是自然语言指令不依赖特定 API理论上只要 AI 能理解就能执行。这意味着 skills 的适用范围更广写起来门槛也更低——你不需要会写代码只要能把流程说清楚就行。另一个区别是灵活性。插件的行为是固定的输入输出都有严格定义。skills 则允许 AI 根据实际情况做判断比如“如果代码里有异步操作额外检查竞态条件”。这种条件分支用自然语言表达起来很自然用代码写就麻烦得多。当然skills 也有局限。它依赖模型的理解能力复杂逻辑可能执行不稳定它没有沙箱隔离安全性需要自己把控它的执行结果不如代码可预测。所以我的建议是确定性强的任务用脚本需要灵活判断的任务用 skills两者配合使用效果最好。3. 核心细节解析与实操要点3.1 目录结构skill 放在哪里才能被识别这是新手最容易卡住的地方。skill 文件放错位置AI 根本找不到。不同工具的目录约定不太一样我分别说一下。Claude Code 的情况下skills 通常放在项目根目录的.claude/skills/下每个 skill 一个子目录子目录里放SKILL.md。比如项目根目录/ .claude/ skills/ code-review/ SKILL.md unit-test/ SKILL.md doc-gen/ SKILL.md如果是全局 skill想在所有项目里都能用可以放在用户主目录下的.claude/skills/。这样就不需要每个项目都复制一份。Claude Desktop 的 skills 目录位置又不一样通常在应用数据目录下。具体路径可以在设置里查看或者看官方文档。我建议第一次配置的时候先用一个最简单的 skill 测试确认能被识别之后再批量添加。注意目录名和 skill 名最好保持一致虽然不强制但能减少混乱。另外SKILL.md的文件名是固定的大小写敏感写成skill.md在某些系统上可能识别不了。3.2 元数据字段怎么写才有效元数据区虽然字段不多但每个都有讲究。我拿一个实际例子来说明--- name: code-review description: 当用户要求审查代码质量、检查编码规范或寻找潜在 bug 时使用。适用于 Python、JavaScript、TypeScript 等主流语言。 version: 1.0.0 author: your-name tags: - code-quality - review ---name是 skill 的唯一标识建议用英文小写加连字符不要用空格或中文。description是最重要的字段我前面强调过要包含动作和场景。version用于版本管理改动了就升版本号。tags是辅助匹配用的可以写多个。有个坑要注意description不要写得太长。有些模型对元数据长度有限制超过一定字符数会被截断。我的经验是控制在 100 到 150 字之间把最关键的信息放前面。另外如果你的 skill 有依赖关系比如需要先运行某个脚本可以在元数据里加一个requires字段说明。虽然不是所有工具都支持但写上没坏处至少给人看的时候清楚。3.3 指令体的四段式写法指令体是 skill 的灵魂。我总结了一个四段式模板实测下来效果比较稳定。第一段目标声明。用一两句话说明这个 skill 要达成什么。比如“本 skill 用于对指定代码文件进行静态审查识别风格问题、潜在 bug 和性能隐患”。第二段执行步骤。把流程拆成有序步骤。每一步都要具体不要写“检查代码质量”这种模糊表述要写“逐行检查缩进是否一致函数命名是否符合 snake_case 规范”。第三段约束条件。说明哪些事情不能做。比如“不要修改业务逻辑”“不要删除原有注释”“遇到不确定的问题时先询问而不是自行决定”。约束能防止 AI 过度发挥。第四段输出格式。定义结果长什么样。可以用 Markdown 表格、列表或者 JSON。格式定义得越清楚输出越稳定。我举个完整的例子是一个简化版的代码审查 skill## 目标 对用户指定的代码文件进行审查输出问题清单和改进建议。 ## 步骤 1. 读取目标文件内容 2. 检查缩进、命名、注释等风格问题 3. 检查空指针、越界、资源泄漏等潜在 bug 4. 检查循环嵌套、重复计算等性能问题 5. 按严重程度排序输出 ## 约束 - 不修改代码只给出建议 - 不确定的问题标注为“待确认” - 每条问题必须给出具体行号 ## 输出格式 | 行号 | 严重程度 | 问题类型 | 描述 | 建议 | |------|----------|----------|------|------|这个结构看起来简单但实际用起来比一大段自由文本稳定得多。AI 知道每一步该干什么输出也规整。3.4 参数化让 skill 适应不同场景固定写死的 skill 只能用于特定场景。想让一个 skill 处理多种情况就需要参数化。做法是在指令体里用占位符比如{{language}}、{{file_path}}然后在调用时传入具体值。参数化有两种方式。一种是显式参数在元数据里声明parameters字段列出参数名和说明。另一种是隐式参数直接在指令体里写“根据用户提供的语言类型调整检查规则”让 AI 自己从对话里提取。显式参数更可控但需要工具支持。隐式参数更灵活但依赖 AI 的理解。我的建议是关键参数用显式辅助信息用隐式。比如语言类型这种影响检查规则的最好显式声明文件路径这种 AI 能从上下文推断的隐式就行。3.5 版本管理与迭代skill 不是写完就完事了需要持续迭代。我建议每个 skill 都建一个独立的 Git 仓库或者至少放在项目的版本控制里。每次修改都提交写清楚改了什么、为什么改。迭代的时候有个技巧保留变更日志。在SKILL.md末尾加一个## 变更记录段落记录每个版本的变化。这样当 skill 行为异常时你能快速定位是哪次改动引入的。另外重大改动前建议先复制一份备份。我吃过亏有一次改一个审查 skill 的约束条件结果改过头了AI 变得过于保守什么都不肯判断。回滚之后重新小步调整才好。4. 实操过程与核心环节实现4.1 从零开始写第一个 skill假设你是一个 Python 开发者想做一个自动生成单元测试的 skill。我带你走一遍完整流程。第一步创建目录。在你的项目根目录下执行mkdir -p .claude/skills/unit-test第二步创建SKILL.md文件写入元数据--- name: unit-test description: 当用户要求为 Python 函数或类生成单元测试时使用。基于 pytest 框架覆盖正常路径和边界条件。 version: 1.0.0 tags: - testing - python - pytest ---第三步写指令体。这里要注意单元测试生成有几个关键点要覆盖哪些情况、用什么断言风格、mock 怎么处理。我把这些写进约束里。## 目标 为指定的 Python 函数或类生成 pytest 单元测试。 ## 步骤 1. 分析目标代码的输入输出和依赖 2. 识别需要 mock 的外部依赖 3. 为每个公开方法生成测试用例 4. 覆盖正常路径、边界条件和异常路径 5. 运行测试确认通过 ## 约束 - 使用 pytest 风格不用 unittest - mock 使用 unittest.mock 或 pytest-mock - 测试函数命名遵循 test_方法名_场景 - 不修改被测代码 - 如果依赖无法 mock标注说明 ## 输出格式 输出完整的测试文件内容用 python 代码块包裹。第四步测试。在 Claude Code 里打开一个 Python 文件输入“帮我为这个文件生成单元测试”。如果 skill 被正确加载AI 会按照你定义的流程执行。4.2 安装社区 skill 的正确姿势社区里已经有很多现成的 skill比如 GitHub 上搜 “claude skills” 或者 “agent skills” 能找到不少。安装方式通常是克隆仓库然后把 skill 目录复制到你的 skills 目录下。但直接复制有个问题你不知道这个 skill 的质量如何也不知道它会不会和现有 skill 冲突。我的做法是先审查再安装。打开SKILL.md看三样东西描述是否准确、约束是否合理、有没有可疑的操作比如执行外部命令、访问网络。审查通过后我建议先放在一个临时目录测试确认没问题再移到正式目录。测试方法是找一个典型任务分别用 skill 和不用 skill 各做一次对比结果。如果 skill 带来的提升不明显或者引入了奇怪的副作用就不装。提示安装第三方 skill 时注意检查它是否包含脚本文件。有些 skill 会附带 Python 或 Shell 脚本这些脚本会在执行时被调用。如果你不信任来源就不要安装带脚本的 skill。4.3 多 skill 协同的编排技巧单个 skill 能力有限真正强大的是多个 skill 协同。比如一个完整的开发流程可能涉及需求分析 skill、代码生成 skill、代码审查 skill、测试生成 skill、文档生成 skill。编排的关键是定义清楚 skill 之间的接口。比如代码审查 skill 的输出格式要能被测试生成 skill 直接消费。我通常会在项目里维护一个workflow.md说明各个 skill 的调用顺序和数据流转方式。另一个技巧是用主 skill 调度子 skill。写一个dev-workflowskill它的指令体里说明“先调用 code-review再调用 unit-test最后调用 doc-gen”。这样你只需要触发一个 skill后面的流程自动走完。不过要注意skill 嵌套层数不要太深。超过三层之后调试会变得很困难而且 AI 容易在中间环节丢失上下文。我的经验是控制在两层以内。4.4 调试 skill 的实用方法skill 不生效或者行为异常时怎么排查我总结了一套流程。首先确认 skill 被加载了。在 Claude Code 里可以用/skills命令查看当前加载的 skill 列表。如果列表里没有你的 skill说明目录位置不对或者元数据格式有问题。其次检查描述匹配。如果你的需求描述和 skill 的description语义差距太大AI 可能匹配不上。这时候可以尝试显式调用看 skill 本身是否正常。然后看指令体是否有歧义。AI 执行偏离预期很多时候是因为指令写得不够明确。比如“检查代码问题”这种表述AI 可能只检查了语法没检查逻辑。改成“检查语法错误、逻辑漏洞和性能问题”就明确多了。最后用最小案例测试。如果 skill 在复杂场景下表现不稳定先用一个最简单的输入测试。确认基础功能正常后再逐步增加复杂度。4.5 性能优化让 skill 跑得更快更准skill 多了之后加载和匹配会变慢。优化方向有几个。一是精简元数据。description控制在 100 字以内tags不要超过 5 个。元数据越短扫描越快。二是分类存放。把 skill 按领域分到不同子目录比如coding/、writing/、analysis/。需要时只加载相关目录减少匹配范围。三是定期清理。三个月没用过的 skill要么删掉要么移到archive/目录。我每季度会做一次清理把不常用的 skill 归档保持活跃 skill 列表精简。四是合并相似 skill。如果两个 skill 功能重叠度超过 70%考虑合并成一个。比如“Python 代码审查”和“JavaScript 代码审查”可以合并成“代码审查”用参数区分语言。5. 常见问题与排查技巧实录5.1 skill 不生效的六种原因这是我被问得最多的问题。根据我的排查经验skill 不生效通常是以下六种原因之一。现象可能原因排查方法解决方法完全没反应目录位置错误检查.claude/skills/是否存在创建正确目录并移动文件列表里没有元数据格式错误检查---是否成对修正 YAML 格式匹配不上描述太模糊对比需求和 description重写描述加入场景词执行偏离指令有歧义逐条检查步骤细化步骤和约束时好时坏上下文冲突检查是否有相似 skill合并或删除冲突 skill报错退出依赖缺失查看错误信息安装依赖或移除依赖我重点说一下“时好时坏”这种情况。这通常是因为你有两个 skill 的描述很接近AI 在匹配时摇摆不定。比如你同时装了“代码审查”和“代码质量检查”这两个描述几乎一样AI 每次可能选不同的。解决办法就是合并成一个或者把其中一个的描述改得更具体明确区分适用场景。5.2 描述写得好不好的判断标准怎么判断一个description写得好不好我有个简单的测试方法把描述单独拿出来问一个不了解你项目的人看对方能不能说出这个 skill 什么时候该用。如果对方说不出来说明描述太模糊。好的描述通常包含三个要素触发场景、处理对象、预期动作。比如“当用户提交 Pull Request 需要审查时对变更的代码文件进行风格和逻辑检查”。触发场景是“提交 PR”处理对象是“变更的代码文件”预期动作是“风格和逻辑检查”。三个要素齐全匹配就准。坏的描述通常是泛泛而谈比如“帮助处理代码相关任务”。这种描述几乎匹配所有编程场景反而导致 AI 无法精确判断。5.3 指令体写太长的处理办法有些人写 skill 的时候恨不得把所有细节都塞进指令体结果文件几千字AI 执行时反而抓不住重点。我的建议是分层组织。核心流程放在指令体主体用简洁的步骤描述。细节规则可以放到单独的参考文件里在指令体中用链接引用。比如## 步骤 1. 读取代码文件 2. 按照 rules/style.md 中的规范检查风格 3. 按照 rules/security.md 中的清单检查安全问题这样指令体保持精简细节规则单独维护修改起来也方便。AI 在执行时会按需读取参考文件不会一次性加载所有内容。5.4 团队协作中的 skill 管理团队里多人使用 skill 时管理就成了问题。我的做法是建一个共享 skill 仓库所有人从这里拉取。仓库里分两个目录stable/放经过验证的 skillexperimental/放还在测试的 skill。每个人可以有自己的local/目录放个人 skill但提交到共享仓库的必须经过 review。review 的重点是描述是否准确、约束是否合理、有没有安全风险。另外团队里要约定命名规范。比如统一用领域-功能的格式code-review、doc-gen、>