1. 从“skills”这个热词说起：它到底是什么，为什么突然火了
最近几个月，不管是在开发者社区还是各种技术群里，“skills”这个词出现的频率高得离谱。如果你只是偶尔刷到，可能会以为它又是哪个新出的前端框架或者构建工具。但真正接触过 Claude Code、Codex 这类 AI 编程助手的人会知道，这里的 skills 指的是一套让 AI 代理（agent）具备特定领域能力的扩展机制。简单说，它就像是给 AI 助手装上的“技能包”——你给它一个处理 PDF 的技能，它就能读懂 PDF；你给它一个操作数据库的技能，它就能帮你写 SQL 并执行查询。
我最早接触这个概念是在折腾 Claude Code 的时候。当时想让它在终端里帮我自动整理项目里的 Markdown 文档，但默认状态下它只能做很泛化的文本处理，遇到特定格式就抓瞎。后来发现官方和社区已经有一批现成的 skills 可以直接挂载，装上去之后效果立竿见影。从那以后我就开始系统性地研究这套机制，包括它的目录结构、加载逻辑、触发条件，以及怎么自己写一个能用的 skill。
这篇文章主要面向几类人：一是刚接触 Claude Code 或 Codex、还不清楚 skills 怎么用的新手；二是已经能用基础功能、但想通过 skills 提升效率的中级用户；三是想自己开发 skill 分享给别人的开发者。我会从设计思路讲到实操细节，再到常见坑的排查，尽量把我知道的都倒出来。文中涉及的具体操作基于我自己的实践和社区常见做法，不同版本的工具可能在细节上有差异，大家以实际环境为准。
2. skills 的整体设计与核心思路拆解
2.1 为什么需要 skills：通用模型的“最后一公里”问题
大语言模型的能力边界其实很模糊。你问它一个通用问题，它往往能答得头头是道；但一旦落到具体场景，比如“帮我按照公司内部规范生成一份 API 文档”，它就开始胡编乱造。这不是模型不够聪明，而是它缺少这个场景下的“操作手册”。skills 要解决的就是这个“最后一公里”的问题。
打个比方，模型本身像一个刚毕业的高材生，知识面广但不懂你们公司的具体流程。skills 就是那本员工手册，告诉他遇到什么情况该走什么流程、用什么模板、注意哪些禁忌。没有这本手册，他也能干活，但干出来的东西你得反复改；有了手册，他第一次上手就能做到七八十分。
从技术实现上看，一个 skill 本质上就是一组结构化文件的集合，通常包含一个描述文件（声明这个 skill 叫什么、什么时候触发、需要哪些权限）和若干执行逻辑（可能是提示词模板、脚本、参考文档）。AI 代理在运行时会根据当前任务去匹配可用的 skills，命中后就把对应的上下文加载进来，从而“学会”这项技能。
2.2 skills、agents、plugin 三者的关系与选型考量
热词里同时出现了 skills、agents、plugin，很多人搞不清它们的区别。我用自己的理解梳理一下：
- Agent是执行任务的主体，你可以把它理解为一个“虚拟员工”。它有自己的目标、记忆和行动能力。
- Skill是 agent 可以调用的能力单元，相当于员工的“技能证书”。一个 agent 可以挂载多个 skills。
- Plugin更偏向工程层面的扩展，通常指对宿主工具（比如编辑器、CLI 工具）本身的功能增强，它可能包含 skills，也可能包含其他东西。
选型的时候我的原则很简单：如果你只是想让 AI 在某个特定任务上表现更好，优先考虑写一个 skill；如果你要改变整个工具的行为方式，那才需要动 plugin 层面的东西。很多新手一上来就想搞 plugin，结果发现复杂度远超预期，其实一个几十行的 skill 就能解决他的问题。
2.3 目录结构与加载机制：skill 是怎么被找到的
不同工具的 skill 存放位置不太一样，但逻辑大同小异。以我常用的环境为例，通常会有几个层级的搜索路径：
- 全局级别：用户主目录下的配置文件夹，对所有项目生效。
- 项目级别：当前项目根目录下的特定文件夹，只对这个项目生效。
- 会话级别：临时加载的，重启就没了。
加载顺序一般是项目级覆盖全局级，这样你可以为不同项目定制不同的 skill 而不互相干扰。每个 skill 放在自己的子目录里，目录名通常就是 skill 的标识符。目录内至少有一个入口文件来描述元信息，比如名称、描述、触发关键词、依赖项等。
注意：目录名和入口文件里的名称最好保持一致，我踩过因为两者不一致导致 skill 死活加载不上的坑，排查了半天才发现是命名对不上。
理解这套机制之后，你就能明白为什么有时候 skill “装了但没生效”——要么是放错了目录，要么是元信息写错了，要么是触发条件没匹配上。后面我会专门讲排查方法。
3. 核心细节解析与实操要点
3.1 一个 skill 的最小构成：从零看懂关键文件
先看一个最简化的 skill 目录长什么样：
my-skill/ ├── skill.json ├── prompt.md └── examples/ └── sample.mdskill.json是元信息声明，大概包含这些字段：
{ "name": "my-skill", "description": "处理项目内的 Markdown 文档格式检查", "triggers": ["检查文档", "markdown lint", "格式检查"], "version": "1.0.0", "author": "your-name" }prompt.md是这个 skill 的核心逻辑，用自然语言描述 AI 应该怎么做。别小看这个文件，它写得好不好直接决定 skill 的可用性。我的经验是：把 AI 当成一个完全不懂你业务的新人，你需要把步骤拆到“傻瓜级”，每一步都明确输入是什么、输出是什么、遇到异常怎么办。
examples/目录放几个输入输出示例，帮助 AI 理解预期结果。这个不是必须的，但加上之后效果提升很明显，尤其是格式要求严格的场景。
3.2 触发条件的设计：让 skill 在该出现的时候出现
触发条件是很多人容易忽略的部分。你肯定不希望 AI 在处理任何任务时都把所有的 skill 都加载一遍，那样既浪费上下文又容易干扰。好的触发设计应该满足两个条件：该触发的时候准确触发，不该触发的时候绝不乱入。
我常用的触发策略有三种：
- 关键词触发：在 triggers 里列出明确的短语，用户输入包含这些短语时才激活。适合场景明确的 skill。
- 文件类型触发：当操作涉及特定扩展名的文件时激活。比如处理
.sql文件时激活数据库相关的 skill。 - 显式调用：用户直接点名要用某个 skill。这种方式最可靠，但需要用户知道 skill 的存在。
实际使用中我会把关键词和文件类型结合，比如“当用户提到‘生成报告’且当前目录有.csv文件时触发”。这样误触发的概率大大降低。
实操心得：triggers 里的词不要写太泛，像“处理”“生成”“检查”这种词单独出现时不要触发，一定要搭配领域词。我曾经写了个 triggers 包含“检查”的 skill，结果 AI 每次做代码审查都想加载它，烦不胜烦。
3.3 prompt.md 的写作技巧：把模糊需求变成可执行指令
这是整个 skill 开发中最考验功力的部分。我总结了一个“四段式”写法：
- 角色设定：一句话说明这个 skill 扮演什么角色。比如“你是一个严格的 Markdown 格式审查员”。
- 输入说明：明确告诉 AI 它会收到什么。是文件路径？还是直接粘贴的文本？还是某个命令的输出？
- 执行步骤：分步骤列出要做什么。每一步都要有明确的判断条件和动作。
- 输出格式：规定结果长什么样。用表格、列表还是 JSON？字段有哪些？
举个例子，一个检查文档格式的 skill，prompt 可以这样写：
你是一个 Markdown 格式审查员。 输入：用户会提供一个 Markdown 文件的路径。 执行步骤： 1. 读取文件内容。 2. 检查一级标题是否唯一，如果多于一个则记录问题。 3. 检查代码块是否都标注了语言类型，未标注的记录下来。 4. 检查是否有超过 80 字符的长行，记录行号。 5. 检查列表项缩进是否一致。 输出格式： 用表格列出所有问题，包含列：行号、问题类型、问题描述、建议修改。 如果没有问题，输出“格式检查通过”。这种写法看起来啰嗦，但实测下来 AI 的执行准确率比那种一句话描述高出一大截。原因很简单：模糊的指令会让模型自由发挥，而自由发挥的结果往往不是你想要的。
3.4 权限与安全边界：别让 skill 变成隐患
skills 可以调用脚本、读写文件、执行命令，这就带来了权限问题。我的原则是：最小权限。一个只做文本分析的 skill，就不要给它写文件的权限；一个只读数据库的 skill，就不要给它删表的权限。
在元信息里通常会有一个权限声明字段，你需要显式列出这个 skill 需要的能力。有些工具还支持在运行时向用户请求确认，比如“这个 skill 想要执行 shell 命令，是否允许？”这种机制一定要保留，不要为了图方便全部放行。
另外，从外部来源获取的 skill 一定要先审查再使用。看看它的 prompt 里有没有奇怪的指令，脚本里有没有可疑的网络请求或文件操作。这不是危言耸听，社区里确实出现过被人恶意篡改的 skill 包。
4. 实操过程与核心环节实现
4.1 环境准备：安装与配置的完整流程
假设你已经在使用 Claude Code 或 Codex 这类工具，第一步是确认版本支持 skills 机制。不同版本的配置方式有差异，我以较新的版本为例走一遍流程。
先找到配置目录。在类 Unix 系统上通常是~/.config/下的某个子目录，Windows 上则在用户目录的AppData里。你可以通过工具自带的命令查看当前配置路径，比如有些工具支持config path这样的子命令。
确认路径后，在里面创建 skills 目录（如果还没有的话）。然后把下载或自己写的 skill 文件夹整个复制进去。复制完之后，重启工具或者执行重新加载配置的命令。
验证是否加载成功，可以查看工具的日志输出，通常会打印出已加载的 skill 列表。如果没有看到你的 skill，先检查目录层级对不对，再检查元信息文件格式是否正确。
注意：有些工具对配置文件的编码有要求，建议统一用 UTF-8 无 BOM 格式保存。我用 GBK 保存过一次，结果中文描述全乱码，skill 直接加载失败。
4.2 从零写一个实用 skill：以“周报生成”为例
光讲理论没意思，我带你完整走一遍开发流程。需求是：根据本周的 Git 提交记录，自动生成一份结构化的周报。
第一步，创建目录结构。
weekly-report/ ├── skill.json ├── prompt.md └── scripts/ └── collect_commits.sh第二步，编写 skill.json。
{ "name": "weekly-report", "description": "根据 Git 提交记录生成周报", "triggers": ["生成周报", "weekly report", "本周总结"], "version": "1.0.0", "permissions": ["read_files", "execute_scripts"] }第三步，编写收集脚本。这个脚本负责把本周的提交记录拉出来：
#!/bin/bash # collect_commits.sh # 收集最近7天的提交记录 git log --since="7 days ago" --pretty=format:"%h|%an|%ad|%s" --date=short第四步，编写 prompt.md。这是核心：
你是一个周报生成助手。 输入：脚本 collect_commits.sh 的输出，每行格式为 哈希|作者|日期|提交信息。 执行步骤： 1. 解析每一行，提取作者、日期、提交信息。 2. 按作者分组，同一作者的提交归到一起。 3. 对每个作者的提交信息进行归纳，合并相似内容。 4. 识别提交类型（功能、修复、文档、重构），用前缀判断： - feat 开头归为功能 - fix 开头归为修复 - docs 开头归为文档 - refactor 开头归为重构 - 其他归为杂项 输出格式： ## 本周工作汇总 ### 成员A - 功能：xxx - 修复：xxx ### 成员B - ... ## 统计 - 总提交数：N - 参与人数：M第五步，测试。在项目目录下触发这个 skill，看看输出是否符合预期。如果归纳得太粗或者太细，调整 prompt 里的措辞。我一般会迭代三到五轮才能达到满意的效果。
4.3 参数调优与效果验证：怎么判断一个 skill 好不好用
写完只是开始，调优才是重头戏。我通常从三个维度评估一个 skill：
| 评估维度 | 具体指标 | 合格标准 |
|---|---|---|
| 触发准确率 | 该触发时触发、不该触发时不触发 | 误触发率低于 10% |
| 执行准确率 | 输出结果符合预期的比例 | 高于 80% |
| 稳定性 | 相同输入多次执行结果是否一致 | 主要结论一致 |
提升触发准确率靠调整 triggers 和描述；提升执行准确率靠细化 prompt 和增加示例；提升稳定性靠减少 prompt 里的模糊表述，把“尽量”“适当”这类词换成明确的规则。
我做过一个实验：同一个 skill，prompt 里用“简洁地总结”和“用不超过三句话总结，每句话不超过 30 字”，后者的输出稳定性明显更高。所以能写死的规则就不要留给模型去判断。
4.4 多 skill 协同：让 agent 自己选择合适的工具
当你有多个 skills 时，agent 需要根据任务自动选择。这时候要注意几点：
- 每个 skill 的职责边界要清晰，不要出现两个 skill 都能处理同一类任务的情况，否则 agent 会纠结。
- 在描述里写清楚适用场景和不适用场景，帮助 agent 做判断。
- 如果确实有重叠，可以在 prompt 里加一句“如果同时匹配多个 skill，优先使用更具体的那个”。
我目前维护着十几个 skill，覆盖文档处理、代码审查、数据整理、报告生成等场景。它们之间基本没有冲突，因为我在设计之初就刻意让每个 skill 的触发条件互斥。
5. 常见问题与排查技巧实录
5.1 skill 加载失败：从日志到目录的逐层排查
这是最常见的问题。我的排查顺序是这样的：
- 看日志。工具一般会输出加载过程中的错误信息，比如“invalid json”“missing field”之类的，直接定位问题。
- 检查目录结构。确认 skill 文件夹直接放在 skills 目录下，而不是多套了一层。
- 检查元信息文件。用 JSON 校验工具验证格式，确认必填字段都有。
- 检查编码。确认文件是 UTF-8 无 BOM。
- 检查权限。确认工具进程有读取这些文件的权限。
大部分加载失败都是前两步的问题。我见过有人把 skill 文件夹压缩包直接扔进去没解压，也见过目录名带了空格导致解析异常。
5.2 触发不生效：关键词、优先级与冲突排查
skill 加载成功了但从来不触发，通常有这几个原因：
- triggers 里的词和用户实际输入不匹配。比如你写的是“生成周报”，用户说的是“帮我写个周报”，虽然语义相近但字面不匹配。解决办法是增加同义词，或者用更宽松的匹配规则。
- 被其他 skill 抢了。如果另一个 skill 的触发条件更宽泛，它可能先被匹配到。
- 优先级设置问题。有些工具支持给 skill 设优先级，低优先级的会被高优先级的覆盖。
我的做法是给每个 skill 写一个测试用例集，包含应该触发的输入和不应该触发的输入，每次修改后跑一遍，确保没有回归。
5.3 执行结果不稳定：prompt 模糊与上下文干扰
同样的输入，两次执行结果差异很大，这通常是因为 prompt 里有太多让模型自由发挥的空间。解决办法：
- 把主观描述换成客观规则。比如“总结得简洁一些”改成“总结不超过 100 字”。
- 减少上下文中的干扰信息。如果 skill 加载了大量无关文档，模型容易被带偏。
- 增加 few-shot 示例。给两三个输入输出对，模型会模仿示例的风格。
还有一个容易被忽略的点：温度参数。如果工具允许调整，处理需要稳定输出的任务时把温度调低。
5.4 常见问题速查表
| 问题现象 | 可能原因 | 排查方法 | 解决方案 |
|---|---|---|---|
| skill 不加载 | 目录层级错误 | 检查 skills 目录下是否直接是 skill 文件夹 | 调整目录结构 |
| skill 不加载 | 元信息格式错误 | 用 JSON 校验工具检查 | 修正格式 |
| 触发不生效 | 关键词不匹配 | 对比 triggers 和实际输入 | 增加同义词 |
| 触发不生效 | 被其他 skill 抢占 | 查看日志中实际加载的 skill | 调整优先级或收窄触发条件 |
| 结果不稳定 | prompt 太模糊 | 审查 prompt 中的主观表述 | 改为明确规则 |
| 结果不稳定 | 上下文干扰 | 检查加载的参考文档 | 精简上下文 |
| 执行报错 | 权限不足 | 查看错误信息中的权限提示 | 补充权限声明 |
| 执行报错 | 脚本路径错误 | 检查脚本引用路径 | 使用相对路径或绝对路径 |
5.5 几个我踩过的坑和对应的经验
坑一：skill 名称用了中文。有些工具对非 ASCII 字符的目录名支持不好，导致加载失败。后来我统一用英文小写加连字符命名，再也没出过问题。
坑二：prompt 里写了“参考 examples 目录下的文件”。但 AI 并不知道 examples 目录在哪，它只能看到 prompt 的内容。正确做法是把示例内容直接写进 prompt，或者通过工具提供的机制显式加载。
坑三：过度依赖 skill 处理所有事情。有些任务其实用普通对话就能完成，硬套一个 skill 反而增加了复杂度。我的判断标准是：如果这个任务每周至少重复三次，且每次的流程基本固定，才值得做成 skill。
坑四：忘了版本管理。早期我改 skill 都是直接覆盖，结果改坏了想回滚都回不去。现在每个 skill 都放在 Git 仓库里，每次修改都有记录，还能对比不同版本的效果差异。
6. 进阶方向：skills 生态与个人效率体系的结合
6.1 从单点 skill 到 skill 组合：构建个人工作流
单个 skill 解决的是单点问题，但真正提升效率的是把多个 skill 串成工作流。比如我的文档处理流程是这样的：先用“格式检查”skill 扫描问题，再用“自动修复”skill 处理能自动修的部分，最后用“生成摘要”skill 产出变更说明。三个 skill 各司其职，串起来就是一个完整的流水线。
要实现这种组合，关键是让每个 skill 的输出格式能被下一个 skill 直接消费。我在设计时会让上游 skill 输出结构化数据（比如 JSON），下游 skill 直接解析，避免中间需要人工转换。
6.2 社区 skill 的筛选与本地化改造
社区里已经有不少人分享了自己写的 skill，质量参差不齐。我的筛选标准是：一看作者是否有持续维护的记录，二看 prompt 写得是否清晰，三看是否有测试用例。满足这三条的才会考虑使用。
拿来之后不要直接用，一定要根据自己环境做本地化改造。比如路径、命令、输出格式这些，别人的环境和你的大概率不一样。我一般会先跑一遍测试，把报错的地方逐个修掉，再根据自己的习惯调整输出格式。
6.3 团队协作中的 skill 共享与版本管理
如果是团队使用，建议建一个共享仓库来管理 skills。每个人都可以提交自己的 skill，但需要经过 review 才能合并。review 的重点是权限声明是否合理、prompt 是否有歧义、是否有潜在的安全风险。
版本管理方面，我建议每个 skill 独立打 tag，这样不同项目可以锁定不同版本，避免因为某个 skill 更新导致其他项目的行为发生变化。这个思路和依赖管理是一样的，稳定优先。
6.4 我个人的一些使用体会
用了大半年 skills 之后，最大的感受是：它把 AI 助手从“什么都能聊但什么都不精”变成了“在特定领域真正能干活”。但前提是你愿意花时间去设计和调试。一个随手写的 skill 和一个精心打磨的 skill，效果差距可能是天壤之别。
另外，不要追求 skill 的数量。我见过有人装了上百个 skill，结果互相干扰，反而降低了效率。我的建议是保持精简，每个 skill 都有明确的用途，定期清理不再使用的。质量比数量重要得多。
最后分享一个小技巧：每次写完一个新 skill，先别急着用在实际工作上，找几个边界情况测试一下。比如输入为空会怎样、输入格式不对会怎样、输入超长会怎样。把这些异常情况处理好了，skill 的可靠性会上一个台阶。
