1. 从“skills”这个热词说起：它到底是什么

最近几个月，不管是在技术社区、开发者群聊，还是在各类工具的使用讨论中，“skills”这个词出现的频率突然变得极高。很多人第一次看到它的时候会有点懵——这个词本身太通用了，字面意思就是“技能”，但在当下的语境里，它指的是一套非常具体的机制：给AI智能体（Agent）挂载可复用的能力模块。

你可以把它理解成给一个刚入职的实习生配了一本“操作手册合集”。这个实习生本身很聪明，但不知道你们公司内部的流程、工具怎么用、代码规范是什么。你把这本手册给它，它就能按照你定义好的方式去干活。skills就是这本手册的标准化封装形式——每个skill是一个独立的文件夹，里面包含说明文档、脚本、资源文件，Agent在需要的时候会自动读取并执行。

这件事之所以值得单独拿出来聊，是因为它解决了一个非常实际的痛点：你不想每次都把同样的指令、同样的上下文、同样的操作步骤重复粘贴给AI。比如你每次让AI帮你做代码审查，都要写一大段“请检查命名规范、请检查边界条件、请检查错误处理……”；每次让它帮你写周报，都要重新描述格式和语气要求。有了skills，这些都可以固化下来，变成一次编写、反复调用的能力单元。

目前围绕skills已经形成了几个比较明确的生态方向。一个是Google Cloud相关的Agent Skills体系，它把skills和云端服务、GKE（Google Kubernetes Engine）这些基础设施做了整合，让Agent能直接操作云资源。另一个是围绕npx分发的skills包管理方式，类似npm的体验，一条命令就能安装一个skill。还有各种社区维护的skills市场、skills大全、skills推荐列表，覆盖了从代码开发、论文写作、分镜设计到自动化测试等各种场景。

这篇文章适合几类人看：如果你已经在用Claude、Codex或者其他支持Agent机制的AI工具，想把自己的工作流沉淀下来，那skills是你必须掌握的；如果你是团队里的技术负责人，想让团队成员的AI使用方式统一化、标准化，skills提供了一套可管理的方案；如果你只是好奇“为什么大家都在聊这个”，那看完这篇你至少能明白它在解决什么问题、值不值得投入时间。

下面我会从设计思路、核心机制、实操步骤、常见坑几个维度，把skills这件事拆开讲清楚。内容会涉及具体的目录结构、配置方式、调试技巧，也会分享一些我在实际使用中踩过的坑和总结出来的经验。

2. skills的整体设计思路与核心机制拆解

2.1 为什么是“文件夹+说明文档”这种形式

skills最核心的设计决策，是它没有搞一套复杂的API或者SDK，而是选择了文件夹加Markdown说明文档这种极其朴素的形式。这个选择背后有很实际的考量。

AI模型在读取上下文的时候，最自然的方式就是读文本。你把一个skill做成一个文件夹，里面放一个SKILL.md作为主说明文件，再放一些辅助脚本和资源，模型在需要的时候直接读这个文件就行了。不需要额外的编译、打包、注册流程。这意味着任何人都能创建skill，不需要会写代码——你只要能把一件事的步骤用文字写清楚，它就是一个可用的skill。

这种设计还有一个好处是可移植性极强。一个skill文件夹可以在不同工具之间迁移，只要目标工具支持读取本地文件系统。你不会被锁定在某个特定平台里。对比一下那些需要注册、需要审核、需要走API调用的方案，文件夹形式的门槛低了一个数量级。

当然，这种自由也带来了一个问题：质量参差不齐。因为没有强制的格式校验，有人写的skill非常精细，有人写的就几句话。这就引出了下一个设计要点。

2.2 SKILL.md的元数据与触发机制

一个规范的skill，它的SKILL.md文件开头会有一段YAML格式的元数据（frontmatter），用来告诉Agent这个skill叫什么、什么时候该用它。典型的结构长这样：

--- name: code-review description: 对代码进行系统性审查，检查命名规范、边界条件、错误处理和性能隐患 ---

name是skill的标识符，description是关键——Agent就是靠这段描述来判断当前任务是否需要调用这个skill。所以description写得好不好，直接决定了skill能不能被正确触发。

我见过很多人在这里犯的错误是：description写得太笼统，比如“帮助处理代码相关的事情”。这种描述会导致两个问题：一是该触发的时候不触发，因为Agent觉得“代码相关”太模糊，不确定是否匹配；二是不该触发的时候乱触发，因为几乎所有编程任务都“和代码相关”。

好的description应该包含具体的动作、具体的检查项、具体的适用场景。比如上面那个code-review的例子，它明确说了“检查命名规范、边界条件、错误处理和性能隐患”，Agent一看就知道这是针对代码审查场景的，不会在写新功能的时候误触发。

元数据下面就是正文部分，用Markdown写清楚这个skill具体要做什么、怎么做、有哪些注意事项。正文可以引用同目录下的其他文件，比如references/checklist.md或者scripts/validate.py，Agent会按需读取。

2.3 渐进式加载：为什么skills不会撑爆上下文

这是很多人第一次接触skills时最大的疑问：如果装了几十个skill，每个都有详细的说明文档，那Agent的上下文窗口岂不是瞬间就被塞满了？

答案在于渐进式加载机制。Agent在启动时只会读取所有skill的元数据部分（就是那段YAML），这部分非常短，几十个skill加起来可能也就几百个token。只有当Agent判断当前任务需要某个skill时，它才会去读取那个skill的完整正文和相关文件。

这个机制用生活化的类比来解释就是：你书架上放了几十本操作手册，你不需要全部背下来，只需要知道每本书的标题和目录。真正要用哪本的时候，再抽出来翻到具体章节。这样既保证了能力覆盖，又不会造成信息过载。

理解这一点很重要，因为它意味着你可以放心地安装大量skill，不用担心性能问题。真正需要花心思的是把每个skill的description写准确，让Agent能在正确的时机找到正确的skill。

2.4 与MCP的关系：互补而非替代

经常有人把skills和MCP（Model Context Protocol）搞混，或者觉得它们是竞争关系。实际上它们解决的是不同层面的问题。

MCP解决的是连接问题——让Agent能够访问外部工具和数据源，比如数据库、API、文件系统。它定义的是通信协议，是“怎么连”的问题。

skills解决的是知识问题——告诉Agent在特定场景下应该怎么做，步骤是什么，注意事项有哪些。它定义的是操作流程，是“怎么做”的问题。

一个典型的组合场景是这样的：你用MCP让Agent能访问你的代码仓库，然后用一个code-review的skill告诉它审查代码时应该遵循什么标准。MCP负责把代码拿过来，skill负责指导怎么审。两者配合，才能完成一个完整的任务。

所以你在规划自己的Agent能力体系时，这两个方向都要考虑，但不要指望用一个去替代另一个。

3. 从零开始写一个skill：完整实操流程

3.1 环境准备与目录结构规划

动手写skill之前，先确认你的工具支持skill机制。目前主流的支持方式有两种：一种是工具自带skill目录，你往里面放文件夹就行；另一种是通过npx安装skill包，类似npx skills install <skill-name>这样的命令。

不管哪种方式，一个标准的skill目录结构是这样的：

my-skill/ ├── SKILL.md # 主说明文件，必须存在 ├── scripts/ # 可执行脚本，可选 │ └── helper.py ├── references/ # 参考文档，可选 │ └── checklist.md └── assets/ # 静态资源，可选 └── template.txt

SKILL.md是唯一必须的文件，其他目录按需创建。我个人的习惯是，如果一个skill的逻辑超过50行说明文字，就会把详细内容拆到references/下面，主文件只保留核心流程和索引。这样Agent读取的时候层次更清晰。

注意：目录名和文件名尽量用英文小写加连字符，避免空格和特殊字符。虽然很多工具支持中文路径，但在跨平台迁移时容易出问题。

3.2 编写高质量的SKILL.md

写SKILL.md是整个流程里最需要花心思的环节。我的经验是把它当成“给一个聪明但完全不了解你工作习惯的新同事写操作指南”。你不能假设对方知道任何背景信息，但也不用解释基础概念。

一个实用的结构模板是这样的：

--- name: weekly-report description: 根据本周的git提交记录和任务清单，生成结构化周报，包含完成事项、进行中事项和风险项 --- ## 用途 当用户要求生成周报、工作总结时使用此skill。 ## 输入要求 - 本周的git log（通过MCP获取或用户提供） - 任务管理工具中的任务状态 ## 生成步骤 1. 从git log中提取本周的commit信息，按模块分类 2. 从任务清单中筛选本周有状态变更的条目 3. 按以下结构组织内容： - 本周完成：列出已关闭的任务和对应的代码变更 - 进行中：列出仍在处理的任务，标注当前进度 - 风险与阻塞：列出遇到问题的任务，说明具体卡点 4. 语气要求：简洁客观，不夸大成果，不回避问题 ## 输出格式 使用Markdown，每个部分用二级标题，条目用无序列表。 ## 注意事项 - 不要编造git log中不存在的提交 - 如果某类信息缺失，明确标注“信息未提供”而不是跳过

这个模板里的几个关键点值得展开说。输入要求部分明确了skill依赖哪些数据，这样Agent在调用前会先确认数据是否齐全。生成步骤是核心，要写到“照着做就能出结果”的颗粒度。注意事项是很多人会忽略的，但它恰恰是保证输出质量的关键——它告诉Agent哪些事情绝对不能做。

3.3 调试与迭代：怎么知道skill写对了

skill写完之后，不要指望一次就完美。我的做法是先用一个具体的任务去测试它，观察Agent的行为是否符合预期。

测试的时候重点看三个东西：触发时机、执行步骤、输出质量。

触发时机不对，通常是description的问题。如果该触发没触发，说明description里的关键词和用户实际表述之间的匹配度不够，需要补充同义词或者更具体的场景描述。如果不该触发却触发了，说明description太宽泛，需要收窄适用范围。

执行步骤出问题，通常是SKILL.md正文的逻辑有歧义。Agent可能会跳过某一步，或者把顺序搞反。这时候需要把步骤写得更明确，必要时加上“必须先完成X再执行Y”这样的约束。

输出质量不达标，就要检查注意事项部分是否覆盖了你关心的所有质量维度。比如你发现Agent生成的周报总是漏掉风险项，那就在注意事项里明确写“风险项即使为空也要保留标题并标注‘本周无风险’”。

迭代的过程通常是：写一版，跑一个任务，发现问题，改一版，再跑。一般迭代两到三轮就能达到比较稳定的状态。

3.4 通过npx安装和管理第三方skill

如果你不想从零写，或者想先用现成的skill体验一下，npx是最方便的途径。基本命令格式是：

npx skills install <skill-name>

这个命令会从配置的源（可能是官方市场，也可能是社区维护的仓库）拉取skill包，解压到本地的skill目录。安装完成后，Agent下次启动时就能识别到。

管理已安装的skill，常用的命令包括：

npx skills list # 列出已安装的skill npx skills remove <name> # 移除某个skill npx skills update # 更新所有skill到最新版本

提示：安装第三方skill之前，建议先看一下它的SKILL.md内容，确认没有奇怪的指令或者不安全的操作。尤其是那些包含可执行脚本的skill，要确认脚本做的事情是你允许的。

我自己的习惯是，对于社区来的skill，先在一个隔离的测试环境里跑一遍，确认行为符合预期之后再放到日常使用的环境里。这个习惯帮我避免过几次意外——有些skill的脚本会修改系统配置或者发送网络请求，这些都应该在你的知情范围内发生。

4. 典型应用场景与实战案例拆解

4.1 代码审查skill：把团队规范固化下来

代码审查是最适合用skill来标准化的场景之一。每个团队都有自己的规范：命名用驼峰还是下划线、错误处理是抛异常还是返回错误码、日志打什么级别、注释写不写、测试覆盖率要求多少。这些规范如果只存在于文档里，实际执行时总会打折扣。

把代码审查做成skill之后，Agent在审查时会自动按照你定义的检查项逐条过。我见过一个团队的做法很值得参考：他们把审查项分成“必须通过”和“建议改进”两级，必须通过的项包括安全漏洞、空指针风险、资源泄漏；建议改进的项包括命名风格、注释完整性、函数长度。Agent在输出审查意见时会明确标注每一条属于哪个级别，这样开发者知道哪些必须改、哪些可以讨论。

这个skill的SKILL.md里有一个细节设计得很好：它要求Agent在指出问题时，必须同时给出修改建议和修改后的代码片段。这比单纯说“这里有问题”有用得多，开发者可以直接参考。

4.2 论文写作skill：结构化输出学术内容

用AI辅助写论文一直是个有争议的话题，但不可否认的是，在文献整理、结构梳理、语言润色这些环节，AI确实能帮上忙。codex写论文的skills这个热搜词也反映了这个需求的存在。

一个实用的论文写作skill，它的核心不是“让AI替你写”，而是“让AI按照学术规范帮你组织内容”。具体来说，它应该包含这些能力：根据研究问题生成论文大纲、检查论证逻辑是否连贯、统一术语和引用格式、识别过度断言和模糊表述。

我实际操作过的流程是这样的：先让Agent读几篇参考文献，提取每篇的核心论点和研究方法；然后基于这些信息生成一个对比表格；再根据对比结果帮我梳理出研究空白和本文的定位。整个过程Agent都在skill的指导下工作，输出格式统一，不需要我反复调整。

注意：学术写作中对事实准确性的要求极高，skill里一定要加上“不确定的信息必须标注来源或标记为待确认”这样的约束。我见过因为AI编造引用而导致返工的案例，这个坑完全可以避免。

4.3 自动化测试skill：从用例生成到执行报告

测试环节的skill化也很有价值。一个完整的测试skill应该覆盖：根据代码变更生成测试用例、执行测试、分析失败原因、生成测试报告。

npx playwright install失败是热搜里出现过的词，说明很多人在用Playwright做端到端测试时遇到过环境问题。把这类问题的排查步骤写进skill里，下次遇到类似情况Agent就能直接给出解决方案，不用再从头查资料。

我自己的测试skill里有一个“失败分类”的逻辑：把测试失败分成环境问题、用例问题、产品缺陷三类。环境问题（比如浏览器没装好、端口被占用）直接给出修复命令；用例问题（比如选择器过期、断言条件不对）给出修改建议；产品缺陷则生成缺陷报告模板。这个分类逻辑让测试结果的处理效率提高了不少。

4.4 内容创作skill：分镜与结构化写作

分镜skills下载这个热搜词说明内容创作者也在用skill机制。分镜设计是一个典型的“有固定流程但需要创意”的工作，正好适合用skill来承载流程部分，把创意空间留给创作者。

一个分镜skill通常会定义：镜头编号规则、景别标注方式、运镜描述格式、时长估算方法、转场类型。Agent按照这些规则把你的一段文字描述转换成结构化的分镜表格。你拿到表格之后，再根据实际拍摄条件做调整。

结构化写作也是类似。比如公众号文章的skill会定义：标题字数范围、开头钩子写法、段落长度限制、小标题格式、结尾行动号召的写法。这些规则固化下来之后，Agent产出的初稿就已经符合基本规范了，你只需要在内容层面做打磨。

5. 常见问题与排查技巧实录

5.1 skill不触发或误触发怎么办

这是最高频的问题。排查思路按优先级排列：

我遇到过一次很隐蔽的情况：skill的description里用了一个生僻的英文缩写，而用户实际表述时用的是中文全称，导致匹配不上。后来我把中英文表述都写进description，问题就解决了。这个经验告诉我，description要覆盖用户可能使用的所有表述方式，不要假设用户会用和你一样的词汇。

5.2 脚本执行权限与路径问题

包含可执行脚本的skill，最常见的坑是权限和路径。在Linux或macOS上，脚本文件需要有执行权限：

chmod +x scripts/helper.py

路径问题更隐蔽。skill脚本里如果用了相对路径，它的基准目录可能不是skill目录，而是Agent的工作目录。稳妥的做法是在脚本开头就切换到skill目录：

import os os.chdir(os.path.dirname(os.path.abspath(__file__)))

这样不管从哪里调用，脚本都能正确找到同目录下的资源文件。

提示：如果你的skill需要在Windows和Unix系统上都能运行，脚本里不要硬编码路径分隔符，用os.path.join或者pathlib来处理。

5.3 上下文冲突：多个skill同时生效时的处理

当你安装了很多skill之后，可能会遇到两个skill给出矛盾指令的情况。比如一个skill说“输出用JSON格式”，另一个skill说“输出用Markdown表格”。Agent夹在中间会不知所措。

解决这个问题的原则是明确优先级。在SKILL.md里可以加一条规则：“当与其他skill的输出格式要求冲突时，以本skill为准”或者“本skill仅在不与其他skill冲突时生效”。更彻底的做法是在设计阶段就划分清楚每个skill的职责边界，避免功能重叠。

我自己的做法是维护一个“skill清单”文档，记录每个skill的职责范围和优先级。当新增skill时，先检查是否和现有skill有重叠。如果有，要么合并，要么明确分工。

5.4 安装失败与网络问题的排查

npx安装skill时可能遇到各种失败。常见的排查步骤：

# 检查npx是否可用 npx --version # 清除npx缓存后重试 npx clear-npx-cache npx skills install <name> # 如果是从特定源安装，检查源地址是否可达 curl -I <registry-url>

如果公司网络有代理限制，可能需要配置npm的代理设置。这部分的具体配置方式取决于你的网络环境，核心思路是确保npx能正常访问skill包的托管地址。

还有一个容易忽略的点：Node.js版本。有些skill包要求较新的Node版本，版本过低会导致安装失败。用node --version确认一下，必要时升级。

5.5 skill更新后行为变化的处理

第三方skill更新后，行为可能发生变化。你之前依赖的某个输出格式可能被改了，或者新增了你不想要的步骤。这种情况的应对策略是：

第一，锁定版本。如果工具支持指定版本号安装，就固定在一个经过验证的版本上，不要盲目追新。

第二，保留变更记录。每次更新skill后，跑一个标准测试任务，对比更新前后的输出差异。如果差异在可接受范围内就继续用，如果影响到了你的工作流就回滚。

第三，fork后自维护。对于核心工作流依赖的skill，可以考虑复制一份到自己的目录下，自己控制更新节奏。这样既能享受原始skill的基础能力，又不会被上游的变更打乱节奏。

6. 关于skill生态的一些个人观察

skills这个机制从出现到现在，生态变化的速度比我预想的要快。早期大家还在讨论“这东西有没有用”，现在已经在讨论“怎么管理几十个skill之间的依赖关系”了。这个转变说明它确实解决了真实的问题。

我观察到的一个趋势是，skill正在从单点工具向工作流编排演进。早期的skill都是独立完成一件事，比如“生成commit message”。现在的skill开始互相引用，一个“发布新版本”的skill可能会调用“运行测试”“更新changelog”“打tag”这几个子skill。这种组合能力让Agent能处理更复杂的任务。

另一个值得关注的方向是skill的质量评估。现在社区里的skill数量增长很快，但质量参差不齐。未来可能会出现类似“skill评分”“skill测试覆盖率”这样的机制，帮助用户筛选出真正可靠的skill。在那之前，我的建议是：对于关键工作流，不要完全依赖第三方skill，核心逻辑自己写一遍，心里更有底。

还有一个实际体会是，写skill的过程本身就是对工作流的梳理。很多时候你以为自己很清楚某个流程怎么做，但真正动手写下来的时候才发现有些步骤是模糊的、有些判断标准是不明确的。写skill强迫你把这些模糊地带想清楚，这本身就是一种收获。我现在养成了一个习惯：每当发现自己在重复给AI解释同一件事，就停下来想想“这个能不能做成一个skill”。这个习惯帮我节省了大量重复沟通的时间。

最后分享一个小技巧：如果你不确定一个skill该怎么写，可以先手动做一遍任务，把每一步的操作和判断都记录下来，然后把这个记录整理成SKILL.md。这种“先做后写”的方式比“先写后做”更容易写出实用的skill，因为你是从实际经验出发的，而不是从想象出发的。