1. 从“skills”这个标题说起：它到底指什么
第一次看到“skills”这个项目标题，很多人会以为是某个技能培训课程或者简历模板合集。但结合热搜词里的 Google Cloud、Agent Skills、npx、GKE 这些关键词，方向就很清楚了——这里说的 skills，是围绕 AI Agent 能力扩展的一套机制，尤其是 Claude 生态里的 Agent Skills，以及 Codex 相关的 skills 体系。
简单说，Agent Skills 就是给 AI 助手加装“技能包”的一套约定。一个 skill 通常是一个文件夹，里面包含一份说明文档（SKILL.md）、可选的脚本、参考资料和资源文件。AI 在遇到匹配的任务时，会按需加载这个技能包，从而获得原本不具备的专业能力，比如生成特定格式的文档、执行某类代码审查、按固定流程处理数据等。
它能解决什么问题？最直接的就是把“每次都要重新解释一遍的流程”固化下来。比如你每次让 AI 帮你写周报都要重复格式要求，那就可以做成一个 skill；你团队有一套固定的代码规范检查流程，也可以做成 skill。适合谁来参考？前端开发者、AI 工具重度用户、需要把重复工作流自动化的工程师，以及想了解 Agent 能力扩展机制的爱好者。
我最初接触这个概念时也踩过坑，以为 skills 就是插件市场里点一下安装的东西。实际用下来才发现，它更像是一套“约定大于配置”的目录规范，理解了这个约定，你就能自己写 skill，也能看懂别人分享的 skill 为什么那样组织。
2. Agent Skills 的整体设计与思路拆解
2.1 为什么是“文件夹 + 说明文档”这种形态
Agent Skills 选择用文件夹加 Markdown 说明文档的形式，而不是打包成二进制插件或者走远程接口，背后有几个很实际的考量。
第一是可读性。Markdown 是纯文本，任何人打开就能看懂这个技能是干什么的、怎么用、有哪些限制。你不需要反编译，也不需要查 API 文档。对于需要快速判断“这个 skill 能不能用”的场景，纯文本的优势非常明显。
第二是可版本控制。文件夹形式的 skill 可以直接放进 Git 仓库，改动有记录，多人协作时能 review。团队内部共享技能包时，直接 clone 仓库就行，不需要搭建额外的分发服务。
第三是按需加载。AI 不会一次性把所有 skill 的内容都塞进上下文，而是先读取 skill 的元信息（名称、描述、触发条件），判断当前任务是否需要这个技能，需要时才加载完整内容。这个设计直接决定了 skills 机制在 token 消耗上是可控的。
第四是可组合。一个 skill 可以引用另一个 skill 里的脚本或参考文件，也可以和 MCP Server 配合使用。这种松耦合让技能包之间既能独立维护，又能按需拼装。
注意：不要把 skill 理解成“提示词模板”。提示词模板通常只是一段文字，而 skill 是一个包含说明、脚本、资源的完整目录，AI 可以执行其中的代码，也可以读取其中的参考文件。
2.2 和 MCP Server 的关系与边界
热搜词里同时出现了 Agent Skills 和 MCP Server，这两个概念经常被混在一起。我刚开始也分不清，后来实际用下来才理清它们的边界。
MCP Server 解决的是“AI 能调用什么外部能力”的问题。比如让 AI 能查数据库、能调某个 API、能操作某个本地工具。它更像是一个能力接口层，通过标准协议把外部系统暴露给 AI。
Agent Skills 解决的是“AI 在特定任务上应该怎么做”的问题。它更偏向流程、规范、领域知识的封装。比如“写论文时应该遵循什么结构”“做代码审查时应该检查哪些点”“生成分镜时应该按什么格式输出”。
两者是互补的。一个 skill 里可以调用 MCP Server 提供的能力，一个 MCP Server 也可以被多个 skill 复用。实际项目里，我通常先用 MCP Server 打通外部能力，再用 skill 把使用这些能力的流程固化下来。
| 维度 | Agent Skills | MCP Server |
|---|---|---|
| 核心作用 | 封装流程与领域知识 | 暴露外部能力接口 |
| 形态 | 文件夹 + Markdown + 脚本 | 服务进程 + 协议接口 |
| 加载方式 | 按需读取，渐进式加载 | 启动后常驻或按需连接 |
| 典型场景 | 论文写作、代码审查、分镜生成 | 数据库查询、API 调用、文件操作 |
| 复用粒度 | 任务级 | 能力级 |
2.3 渐进式加载：token 控制的关键设计
Agent Skills 最让我觉得巧妙的设计是渐进式加载。它把 skill 的内容分成三个层次：
第一层是元信息，包括 skill 的名称和描述。这部分内容很短，AI 在启动时就能全部读取，用来判断哪些 skill 和当前任务相关。
第二层是主说明文档，也就是 SKILL.md 的正文。当 AI 判断某个 skill 相关时，才会读取这部分内容，了解具体的使用方法和步骤。
第三层是附加资源，包括脚本、参考文档、模板文件等。只有在执行过程中真正需要时，才会去读取或执行。
这个设计的好处是，你可以安装几十个 skill，但每次对话实际消耗的 token 只和当前任务相关的 skill 有关。我实测下来，即使装了二十多个 skill，日常对话的上下文占用也没有明显增加，因为大部分 skill 的元信息加起来也就几百个 token。
提示：写 skill 描述时要把触发条件写清楚。描述写得太模糊，AI 可能在该用的时候不用；写得太宽泛，又可能在不该用的时候误触发。我一般会在描述里明确写“当用户需要做 X 时使用”。
3. 核心细节解析与实操要点
3.1 一个标准 skill 的目录结构
虽然不同平台和工具对 skill 的具体要求略有差异，但核心结构是相通的。下面是我实际使用中总结出来的一个典型结构：
my-skill/ ├── SKILL.md # 主说明文档，必需 ├── scripts/ # 可执行脚本，可选 │ ├── process.py │ └── validate.sh ├── references/ # 参考文档，可选 │ └── format-spec.md └── assets/ # 模板、资源文件，可选 └── template.docxSKILL.md 是整个技能包的核心。它通常包含几个部分：技能名称和描述、适用场景、使用步骤、注意事项、以及可选的示例。描述部分要简洁准确，因为这部分会被 AI 用来判断是否加载该技能。
scripts 目录放的是可执行脚本。这里有个细节：脚本应该是自包含的，尽量不要依赖外部环境里不确定存在的库。如果确实需要依赖，要在 SKILL.md 里写清楚依赖项和安装方法。
references 目录放的是参考文档，比如格式规范、领域知识、检查清单等。这些内容通常比较长，不适合直接写在 SKILL.md 里，但 AI 在执行任务时可能需要查阅。
assets 目录放的是模板文件、图片、字体等资源。比如一个生成 PPT 的 skill，可以把模板文件放在这里。
3.2 SKILL.md 的写法要点
SKILL.md 写得好不好，直接决定这个 skill 能不能被正确触发和有效使用。我踩过几次坑之后，总结了几个要点。
描述要具体，不要抽象。比如“帮助处理文档”这种描述就太模糊了，AI 不知道什么时候该用。改成“当用户需要把 Markdown 转换为带目录的 Word 文档时使用”，触发就准确多了。
步骤要可执行，不要写原则。不要写“注意格式规范”，而要写“标题使用二级标题，正文使用小四号宋体，行距 1.5 倍”。AI 需要的是可操作的具体指令，不是抽象原则。
限制条件要写清楚。比如“本技能仅适用于 10 页以内的文档”“需要 Python 3.9 以上环境”“不支持包含宏的模板”。这些限制能避免 AI 在不合适的场景下强行使用该技能。
示例要真实。给一个完整的输入输出示例，比写十句解释都有用。示例能让 AI 快速理解预期的输出格式和质量标准。
下面是一个简化版的 SKILL.md 示例：
--- name: weekly-report description: 当用户需要根据工作记录生成周报时使用。适用于需要固定格式周报的场景。 --- # 周报生成技能 ## 使用步骤 1. 读取用户提供的工作记录文件 2. 按“本周完成、下周计划、风险与问题”三个板块整理内容 3. 每个板块使用无序列表，每条不超过 50 字 4. 输出为 Markdown 格式，标题使用二级标题 ## 输出格式 ## 本周完成 - 事项一 - 事项二 ## 下周计划 - 事项一 ## 风险与问题 - 事项一 ## 注意事项 - 如果工作记录中没有明确的风险项，写“暂无” - 不要编造工作记录中不存在的内容3.3 脚本编写的注意事项
skill 里的脚本是让 AI 真正“动手”的关键。但脚本写不好，轻则执行失败，重则产生错误结果。以下几点是我实际踩坑后总结的。
输入输出要明确。脚本应该从标准输入或命令行参数读取数据，把结果写到标准输出。不要依赖交互式输入，因为 AI 执行脚本时通常是非交互环境。
错误处理要完善。脚本要对常见错误给出明确的错误信息，而不是直接抛异常堆栈。AI 看到清晰的错误信息，才能判断下一步该怎么做。
不要做危险操作。脚本里不要包含删除文件、修改系统配置、发送网络请求等操作，除非这个 skill 的用途就是做这些事，并且在 SKILL.md 里明确说明了。
依赖要最小化。尽量用标准库，少用第三方库。如果必须用第三方库，要在 SKILL.md 里写清楚安装命令。
注意：脚本的执行环境可能和你的开发环境不一样。我遇到过本地跑得好好的脚本，在 AI 执行时因为缺少某个环境变量而失败。所以脚本里要尽量不依赖环境变量，或者在使用前检查并给出明确提示。
4. 实操过程与核心环节实现
4.1 环境准备与工具安装
要使用 Agent Skills，首先需要有一个支持 skills 机制的 AI 工具环境。目前比较常见的是 Claude 相关的工具链，以及 Codex 相关的环境。这里以通用的命令行工具为例，说明安装和配置过程。
首先确认本地有 Node.js 环境。大部分 skills 工具链都依赖 Node.js，建议使用 18 以上的 LTS 版本。
node --version npm --version如果版本过低，建议先升级。升级方式取决于你的操作系统，这里不展开。确认 Node.js 可用后，可以通过 npx 来运行 skills 相关的命令行工具。
npx skills --help如果这是你第一次运行，npx 会提示下载对应的包。下载完成后会显示帮助信息，说明工具可用。
接下来需要配置 skills 的存放目录。不同工具的默认目录不一样，但通常可以在配置文件中指定。我一般会在项目根目录下建一个.skills文件夹，把项目相关的 skill 放在这里，全局通用的 skill 放在用户目录下的默认位置。
mkdir -p .skills然后把写好的 skill 文件夹放进去，或者在.skills目录下直接创建。
4.2 安装和验证一个现成的 skill
刚开始不建议自己从零写 skill，先安装一个现成的、结构清晰的 skill 来研究，理解它的组织方式，再动手改。
从社区或官方市场获取 skill 的方式通常有几种：直接 clone Git 仓库、通过包管理器安装、或者手动下载压缩包。以 clone 仓库为例：
git clone https://github.com/example/some-skill.git .skills/some-skill安装完成后，需要验证 skill 是否被正确识别。大部分工具提供了列出已安装 skill 的命令：
npx skills list如果能看到刚安装的 skill 名称和描述，说明识别成功。接下来可以做一个简单的触发测试：在对话中提出一个该 skill 应该处理的任务，观察 AI 是否加载了对应的 skill。
我实测下来，验证环节最容易出问题的地方是目录结构不对。比如 SKILL.md 没有放在 skill 文件夹的根目录，而是多套了一层；或者文件名大小写不对，SKILL.md写成了skill.md。这些细节看起来小，但会导致 skill 完全不被识别。
4.3 从零写一个 skill 的完整流程
下面以“代码审查”这个场景为例，走一遍从零写 skill 的完整流程。
第一步：明确技能边界。这个 skill 只做一件事：对 Python 代码进行静态审查，检查命名规范、函数长度、注释覆盖率、明显的逻辑问题。不做运行时测试，不做性能分析。
第二步：创建目录结构。
mkdir -p .skills/code-review/scripts mkdir -p .skills/code-review/references第三步：编写 SKILL.md。
--- name: python-code-review description: 当用户需要对 Python 代码进行静态审查时使用。检查命名规范、函数长度、注释覆盖率和明显逻辑问题。 --- # Python 代码静态审查 ## 使用步骤 1. 读取用户指定的 Python 文件 2. 运行 scripts/check.py 进行基础检查 3. 根据 references/checklist.md 中的清单逐项人工复核 4. 按严重程度分类输出问题列表 ## 输出格式 ### 严重问题 - 文件:行号 - 问题描述 ### 一般问题 - 文件:行号 - 问题描述 ### 建议改进 - 文件:行号 - 建议内容 ## 注意事项 - 只做静态审查，不执行代码 - 不检查第三方库的代码 - 对于不确定的问题，标记为“待确认”而不是直接判定为问题第四步：编写检查脚本。
#!/usr/bin/env python3 """基础代码检查脚本""" import ast import sys def check_file(path): with open(path, 'r', encoding='utf-8') as f: source = f.read() tree = ast.parse(source) issues = [] for node in ast.walk(tree): if isinstance(node, ast.FunctionDef): if len(node.body) > 50: issues.append(f"{path}:{node.lineno} - 函数 {node.name} 过长") if not ast.get_docstring(node): issues.append(f"{path}:{node.lineno} - 函数 {node.name} 缺少文档字符串") return issues if __name__ == '__main__': for filepath in sys.argv[1:]: for issue in check_file(filepath): print(issue)第五步：编写参考清单。
references/checklist.md 里列出人工复核时要检查的项目，比如变量命名是否使用蛇形命名法、是否有未使用的导入、是否有裸 except 等。
第六步：测试。找一个真实的 Python 文件，让 AI 使用这个 skill 进行审查，观察输出是否符合预期。如果 AI 没有触发这个 skill，检查描述是否足够具体；如果触发了但输出格式不对，检查 SKILL.md 里的输出格式说明是否清晰。
4.4 参数选择与性能考量
skill 的数量和大小会影响 AI 的响应速度和 token 消耗。我做过一个简单的测试：在同一个对话中，分别安装 5 个、15 个、30 个 skill，观察首次响应时间和上下文占用。
| skill 数量 | 元信息 token 估算 | 首次响应感受 |
|---|---|---|
| 5 个 | 约 200-400 | 几乎无感知 |
| 15 个 | 约 600-1200 | 轻微延迟 |
| 30 个 | 约 1200-2400 | 可感知延迟 |
这个测试说明，skill 数量在合理范围内时，对体验的影响很小。但如果每个 skill 的描述写得很长，累加起来就会明显增加开销。所以描述要精炼，把详细信息放在 SKILL.md 正文里，让渐进式加载发挥作用。
另一个考量是脚本的执行时间。如果 skill 里的脚本需要跑几十秒，AI 的响应就会明显变慢。我一般会把耗时操作拆分成多个小步骤，或者让脚本支持增量处理。
5. 常见问题与排查技巧实录
5.1 skill 不被识别怎么办
这是最常见的问题。排查顺序如下：
首先检查目录结构。skill 文件夹必须直接放在 skills 目录下，SKILL.md 必须在 skill 文件夹的根目录。我见过有人把 skill 文件夹多套了一层，导致工具扫描不到。
其次检查文件名。SKILL.md的大小写要完全匹配，有些系统对大小写敏感。同时确认文件扩展名是.md而不是.txt或.markdown。
然后检查元信息格式。如果 SKILL.md 开头有 YAML front matter，确认name和description字段都存在且格式正确。缺少 description 字段会导致 AI 无法判断何时加载该 skill。
最后检查工具版本。有些 skills 机制是较新版本才支持的，旧版本可能不识别。用npx skills --version确认版本，必要时升级。
5.2 skill 被误触发或该触发时不触发
误触发通常是描述写得太宽泛。比如描述写“帮助处理文档”，那任何和文档相关的任务都可能触发。解决办法是把描述改具体，明确写出触发条件。
该触发时不触发，通常是描述写得太窄，或者和用户实际表述的用词差异太大。比如描述里写“生成周报”，但用户说的是“写工作总结”，AI 可能就匹配不上。解决办法是在描述里补充常见的同义表述。
我一般会在描述里同时写清楚“什么时候用”和“什么时候不用”。比如“当用户需要生成固定格式的周报时使用。不适用于自由格式的工作总结。”
5.3 脚本执行失败的排查思路
脚本执行失败的原因很多，按以下顺序排查效率最高：
先看错误信息。如果错误信息是“command not found”，说明脚本依赖的命令不存在，需要在 SKILL.md 里补充安装说明，或者改用其他实现方式。
如果是“permission denied”，说明脚本没有执行权限。在 skill 里，脚本的执行权限可能不会被保留，所以最好在 SKILL.md 里写明用解释器执行，比如python scripts/check.py而不是直接./scripts/check.py。
如果是“module not found”，说明缺少 Python 依赖。尽量用标准库重写，或者把依赖安装命令写进 SKILL.md。
如果是脚本逻辑错误，那就要在本地复现。把脚本单独拿出来，用相同的输入跑一遍，看输出是否符合预期。
提示：脚本里加一些调试输出很有帮助。但要注意，调试输出不要写到标准输出里，否则会干扰 AI 对结果的理解。可以写到标准错误，或者通过环境变量控制是否输出。
5.4 常见问题速查表
| 问题现象 | 可能原因 | 排查方法 | 解决方式 |
|---|---|---|---|
| skill 不被识别 | 目录结构错误 | 检查 SKILL.md 位置 | 调整目录结构 |
| skill 不被识别 | 文件名大小写错误 | 确认文件名 | 改为 SKILL.md |
| skill 不被识别 | 缺少 description | 检查 front matter | 补充描述字段 |
| 误触发 | 描述过于宽泛 | 检查描述文本 | 收窄触发条件 |
| 不触发 | 描述过于狭窄 | 对比用户表述 | 补充同义表述 |
| 脚本找不到 | 路径写法错误 | 检查脚本路径 | 使用相对路径 |
| 脚本无权限 | 执行权限丢失 | 检查文件权限 | 用解释器执行 |
| 脚本缺依赖 | 环境不一致 | 查看错误信息 | 补充安装说明 |
| 输出格式不对 | 格式说明不清 | 检查 SKILL.md | 补充输出示例 |
5.5 几个我踩过的坑
第一个坑是在 SKILL.md 里写了太多背景知识。我一开始觉得写得越详细越好，结果 SKILL.md 变得很长，每次加载都消耗大量 token。后来我把背景知识移到 references 目录，SKILL.md 只保留核心步骤和输出格式，效果好多了。
第二个坑是脚本里用了绝对路径。本地测试没问题，换到 AI 执行环境就找不到文件。后来全部改成基于脚本所在目录的相对路径，问题解决。
第三个坑是没有考虑并发执行。有一次我写了一个 skill，脚本会写临时文件，结果多个任务同时执行时临时文件冲突。后来改成用随机文件名，或者用标准输入输出传递数据，避免共享文件。
第四个坑是描述里用了太多专业术语。AI 匹配时用的是语义相似度，如果用户用的是日常用语，而描述里全是术语，就可能匹配不上。后来我在描述里同时保留术语和日常表述，触发准确率明显提升。
6. 进阶用法与扩展思路
6.1 skill 之间的组合调用
单个 skill 的能力有限，但多个 skill 组合起来就能完成复杂任务。比如一个“论文写作”skill 负责整体结构，一个“参考文献格式化”skill 负责处理引用，一个“图表生成”skill 负责画图。AI 在执行论文写作任务时，可以依次调用这三个 skill。
组合调用的关键是职责边界清晰。每个 skill 只做一件事，输入输出格式明确，这样 AI 才能正确地在 skill 之间传递数据。如果两个 skill 的职责有重叠，AI 就可能不知道该用哪个，或者重复执行。
我一般会在主 skill 的 SKILL.md 里写明“本技能需要配合 X 技能使用”，并在步骤里说明调用顺序和数据传递方式。
6.2 把团队规范固化成 skill
团队内部有很多重复性的规范，比如代码提交信息格式、文档模板、会议纪要结构等。这些规范写成文档没人看，但做成 skill 就能在 AI 辅助工作时自动生效。
具体做法是：把规范拆解成可执行的步骤，写成 SKILL.md，把模板文件放在 assets 目录，把检查脚本放在 scripts 目录。然后把这个 skill 放进团队的共享仓库，每个人 clone 下来就能用。
这样做的好处是，规范不再是“写在文档里但没人遵守”，而是“AI 在执行任务时自动应用”。我所在的团队用这种方式统一了周报格式和代码审查标准，效果比之前发文档好得多。
6.3 skill 的版本管理与分发
skill 是纯文本和脚本，天然适合用 Git 管理。我一般会为团队建一个 skills 仓库，每个 skill 一个子目录，用分支管理不同版本，用 tag 标记稳定版本。
分发方式有几种：直接 clone 仓库、通过 npm 包分发、或者打包成压缩文件。clone 仓库最简单，适合内部使用；npm 包适合公开分发，有版本管理和依赖解析；压缩文件适合离线环境。
不管用哪种方式，都要在 SKILL.md 里写清楚版本号和兼容性说明。我遇到过 skill 更新后行为变化，导致之前能用的任务失败的情况。后来我在 SKILL.md 里加了版本历史，每次改动都记录，方便排查问题。
6.4 从“用 skill”到“写 skill”的思维转变
刚开始用 skill 时，我的思维是“找现成的来用”。但用了一段时间后发现，最贴合自己工作流的 skill 往往需要自己写。因为每个人的工作习惯、团队规范、常用工具都不一样，通用 skill 只能覆盖共性部分。
写 skill 的过程，其实也是梳理自己工作流的过程。把“我平时是怎么做这件事的”拆解成明确的步骤，写下来，本身就是一种提升。我写第一个 skill 时，才发现自己有些步骤是凭感觉做的，写下来之后才意识到可以优化。
所以我的建议是：先用现成的 skill 理解机制，然后从自己最重复、最耗时的工作开始，尝试写一个简单的 skill。不用一开始就追求完美，先跑通流程，再逐步完善。
7. 一些实际使用中的体会
我在实际使用 Agent Skills 的过程中，最大的感受是它把“提示词工程”从一次性对话变成了可积累的资产。以前每次和 AI 协作都要重新解释背景，现在把常用流程写成 skill，下次直接调用就行。这种积累效应在长期项目中特别明显。
另一个体会是，skill 的质量比数量重要。我一开始装了很多 skill，但常用的就那么几个。后来我把不常用的删掉，把常用的反复打磨，整体效率反而更高。一个写得好的 skill，能顶十个写得一般的。
还有一点是关于调试。skill 出问题时，不要只看 AI 的输出，要去看 skill 的加载日志和脚本的执行日志。大部分问题都能从日志里找到线索。我习惯在 SKILL.md 里加一个“调试”小节，记录常见问题的排查方法，这样下次遇到同样问题就不用重新想了。
最后分享一个小技巧：写 skill 时，先写一个最简版本，只包含核心步骤，跑通之后再逐步添加细节。不要一开始就追求大而全，那样很容易卡在细节里，迟迟跑不通。先让它能用，再让它好用。
