如果你最近在刷 Agent 相关的技术帖，大概率绕不开一个叫agent-skills的东西。GitHub 上以这个关键词命名的仓库越来越多，Claude、Codex CLI 这些主流 Agent 环境都开始把 Skills 当成一等公民来支持，社区里甚至冒出了 skills 下载平台、skills 推荐列表、自动生成 skills 的脚手架工具。它到底解决什么问题？一句话概括：让 AI 助手从“什么都会一点但经常办砸”变成“按你沉淀好的经验办事、越用越顺手”。这套机制对正在做 Agent 开发、前端开发自动化、个人知识库智能化的朋友尤其有用，几乎可以当成 Agent 能力的“外挂装备”来理解。

我先说清楚一个前提：本文不是某个官方文档的翻译，也不打算逐字复读官方教程。我想站在一个实际折腾过多个 Agent 框架、拿 Skills 写过真实技能包的人的角度，把这套东西的来龙去脉、内部结构、开发方式和踩坑记录一次性讲透。你不需要懂太多前置知识，只要用过 ChatGPT、Claude 这类对话产品，或者写过几行代码，就足够跟上后面的节奏。

1. 别把 Skills 当插件：先搞懂 agent-skills 到底解决什么问题

1.1 一次对话里的“临时工”现象

在 Skills 出现之前，Agent 的日常使用有个特别拧巴的体验。你让它帮你做一次代码审查，它确实能做，但每次发挥极不稳定：今天记得检查错误处理，明天可能全程在纠结变量命名；你让它帮你整理前端项目的组件结构，它会给出一个看起来合理、但跟你团队既有规范完全不搭的方案。

我把这个问题叫作“临时工现象”——模型每次都像是新入职的员工，有通用能力但没有岗位经验。传统的 System Prompt 可以灌入一些固定规则，但写长了之后，模型注意力容易分散，而且不同任务的需求混在一起，反而互相干扰。你总不能为每一个具体任务都维护一份几千字的系统提示词吧？那个维护成本很快就失控了。

这就是 agent-skills 想解决的原始痛点：把“怎么做好某一件具体事情”的经验、步骤、工具和参考模板，打包成一个独立、可安装、可被按需调用的模块。模型在会话开始后，会根据当前任务判断是否需要某个 Skill，需要才加载，不需要就完全不占用上下文。

1.2 Skills 的登场：把能力做成可安装、可复用的模块

我第一次接触这个概念，是看到一篇叫《Claude Agent Skills: A First Principles Deep Dive》的文章。那篇分析给了我一个很关键的视角：Skills 本质上是对“模型能力边界”的一次外包式扩展。什么意思？模型本身的知识截止日期、上下文窗口大小、工具调用能力都是固定的，但 Skills 允许开发者把模型不擅长记住、不擅长稳定执行的事情，拆成外部文件、脚本和提示词模板，在任务需要时动态注入。

举个最直白的类比：模型是一台刚出厂的数控机床，你给它 G 代码它能跑，但怎么加工一个特定形状的零件，它没有内置工艺卡。Skills 就是那些工艺卡——一个零件类型一张卡，卡上写好了用什么刀、什么转速、什么走刀路径，机床只要识别零件类型，抽出对应的卡就能稳定干活。

所以 Skills 的定位不是“插件”那种在软件层面加功能的概念，它更像给 Agent 增加“肌肉记忆”：每次调用同一个 Skill，模型执行的是一套已经被你验证过的流程，而不是从零现编。这也是为什么社区里有人把 Skills 叫“Agent 的岗位说明书”，我觉得这个比喻相当准确。

2. 第一性原理拆解：Skills、Tools、MCP、插件到底差在哪

2.1 Tool 是手，Skill 是完整动作

很长一段时间里，Agent 的能力扩展靠的是 Tool（工具）。Tool 的本质是一个函数：给它输入，它返回输出，比如搜索、计算、查天气、读文件、执行代码。模型只需要根据用户请求决定“该调用哪个函数、传什么参数”。这是 Agent 最基础的“手”。

但问题在于，Tool 解决的是单点动作，不解决完整流程。你让 Agent 做一个前端页面的可访问性审查，它需要：先读取 HTML 文件 → 分析结构 → 检查表单标签 → 输出一份分级报告 → 给出修复建议。这不是一个函数能搞定的，这是一套动作序列，而且每个环节都有判断标准。

Skill 就是把这一整套动作封装起来。它内部可以包含：自然语言级的操作指南、一个或多个脚本、参考模板、甚至子 Skills。模型加载 Skill 之后，不是去调用某一个工具，而是按照 Skill 里写的流程去编排多个工具、多段分析。Tool 是零件，Skill 是装配图，这么理解就通了。

2.2 与 MCP 的关系：不是一个赛道，是互补

很多人会问：MCP（Model Context Protocol）不是也在做工具标准化吗？Skills 和它是什么关系？我的理解很简单：MCP 解决的是“工具如何被标准化暴露给模型”，Skills 解决的是“一组工具和指令如何围绕一项任务被组织起来”。

你可以把 MCP 理解成 USB-C 接口标准——它让各种外设都能统一插到电脑上。但插上之后，你还是得自己知道“先插键盘还是先插显示器”吗？不用，因为你在做具体工作时使用的是一套工作流。Skills 更像是“工作流说明书”，它告诉你这些接口设备应该按什么顺序、以什么标准协作。

实际项目中两者是配合关系：一个 Skill 可以调用多个 MCP 工具，也可以使用普通函数式 Tool，还可以完全不调用工具、纯粹靠提示词模板驱动模型执行一个分析任务。它们不在同一层，所以不存在二选一的问题。

2.3 和传统插件、Codex Skills 等同类方案的横向对比

我把容易混淆的几个概念整理过一张对比表，直接看这张表最省脑子：

这里特别说下 Codex Skills。OpenAI 的 Codex CLI 是命令行编码 Agent，它提供了一种类似机制：你可以给 Agent 配置个性化的命令和技能定义，让它针对具体语言、框架或团队规范执行定制化操作。社区里管这个叫 codex skills，本质思路和 Claude 的 Skills 是一致的——都是把“应该怎么做”从模型默认行为里拆出来，固化成外部可复用文件。

所以你看，各大厂虽然叫法不同、文件格式不同，但方向出奇地一致。这说明 Skills 不是一个拍脑袋的营销概念，而是 Agent 工程演化到一定阶段后的必然产物：模型本身越来越同质化，真正的差异化价值来自你给它配备的操作经验。

3. Skills 的内部结构与工作机制

3.1 Skill 的三层结构：名称、描述、脚本（或提示词）

虽然各家格式有细微差异，但一个标准 Skill 在文件层面通常长这样：

my-skill/ ├── SKILL.md # 技能定义文件，相当于说明书 ├── scripts/ # 可选，辅助脚本 │ └── analyze.py └── assets/ # 可选，参考模板、示例文件

最核心的 SKILL.md 通常包含两部分。第一部分是frontmatter 元信息，至少两个字段：name和description。第二部分是正文指令，详细告诉模型这个 Skill 适用于什么任务、按什么步骤执行、输出格式是什么、有哪些注意事项。

我用一个简化示例来说明，假设你做一个“前端组件代码审查”的 Skill：

--- name: frontend-component-review description: 审查 React/Vue 组件代码质量，检查 props 设计、状态管理、可访问性、性能隐患，并输出分级修改建议。 --- # 前端组件审查流程 当你需要审查一个前端组件文件时，按以下步骤执行： 1. 读取目标组件文件，识别其框架类型（React 或 Vue）。 2. 检查 props/对外接口： - 是否有默认值？ - 类型定义是否完整？ - 是否有不必要的内部状态？ 3. 检查可访问性： - 交互元素是否有清晰的语义标签？ - 是否依赖颜色单独传达信息？ 4. 检查性能： - 是否存在重复渲染风险？ - 列表渲染是否有稳定 key？ 5. 输出报告，格式为： - 问题等级（P0/P1/P2） - 问题描述与代码位置 - 修改建议（附示例代码） 注意事项： - 不要修改原始文件。 - 如果文件超过 500 行，优先关注公共逻辑和高风险区域。

这就是一个完整 Skill 的雏形。模型在需要审查前端组件时，会读取这套指令，按里面定义的流程执行，而不是漫无目的地自由发挥。

3.2 为什么描述（Description）是 Skills 的灵魂

我在写 Skill 的时候犯过最大的错误，就是低估了description的作用。很多教程都会说“描述要写清楚”，但没解释为什么这么重要。

Agent 的模型调度机制通常是这样的：一次会话开始后，系统会把所有已安装 Skill 的**元信息（主要是 name 和 description）**发给模型，模型基于当前用户请求，在这些描述中选出最匹配的一个或几个，然后加载对应的完整 SKILL.md。也就是说，模型判断“要不要用你这个 Skill”，只看 description，不看正文。

这就像招聘软件里，HR 在你提交完整简历之前，只先看你的求职意向那一栏。如果那栏写的是“技术岗”，那后面的项目经验再牛，想投运营岗也匹配不上。所以 description 必须包含三样东西：适用场景、输入是什么、输出是什么。

我一般会把 description 写成“当用户需要做什么事情时使用，输入是 XX，输出是 XX”的句式，顺带加上一两个最关键的约束词。比如上面那个示例里如果写成“审查代码”就太弱了，改成“审查前端 React/Vue 组件，输出分级报告”之后，被模型正确调用的概率会明显上升。

3.3 Skills 的发现与调用机制：模型如何“看到”并“选择”

为了更直观地解释调用链路，我画一个文字版流程：

用户输入任务 ↓ Agent 收集所有已安装 Skill 的 name + description ↓ 模型判断：哪个 Skill 匹配当前任务？ ↓ 选中 Skill → 加载完整 SKILL.md 到上下文 ↓ 模型按 SKILL.md 指令逐步执行 ↓ 执行完毕 → 输出结果并结束 Skill 上下文

这里有个很重要的工程细节：被加载的 Skill 指令只在该 Skill 执行期间占用上下文，执行结束后会被释放。这意味着你可以安装几十个上百个 Skill，但任何一个任务进来时，上下文里只会多出几 KB 的指令开销，而不是把所有 Skill 的完整内容全部常驻。我管这叫“按需注入”，它是 Skills 机制能大规模扩展而不把模型上下文撑爆的根本原因。

不过你也要注意，描述词本身写得再好也有一个上限——当已安装 Skill 数量超过一定阈值（比如 50 个以上），模型在做选择时可能产生注意力分散。我自己实践中，一个 Agent 实例里安装 10 到 20 个常用 Skill 是甜点区，超过 30 个就该考虑分组管理或者精简描述。

3.4 上下文窗口、Token 与 Skills 的取舍

每次聊到上下文，一定有人问 Token 怎么算。这里给一个非常务实的答案：Skill 的元信息按数量计，正文按需计，脚本不占上下文。

元信息阶段，每个 Skill 的 name 加 description 大概也就 100 到 300 Token，50 个 Skill 也就是 1.5 万 Token 以内。正文阶段，一个写好的 SKILL.md 大概 500 到 1500 Token，被调用时才注入。相比动辄几万 Token 的长文档，这个开销完全可以接受。

但这里有一个反向陷阱：有些开发者喜欢把 SKILL.md 写成百科全书，恨不得把二十种边缘情况全写进去。结果就是正文太长，模型执行时反而抓不住重点，该按流程走的地方被大段补充说明干扰。我的经验是：SKILL.md 的正文应该像手术清单，而不是医学教科书。只写大概率路径、关键判断标准和绝对不可以踩的雷，剩下的交给模型的通用能力去处理。细节越少，执行越稳，这是个反直觉但无比真实的结论。

4. 从零开发一个自己的 Skill：以“前端开发 Skills”为例

4.1 定义场景与边界：先想清楚“为什么模型自己做不好”

很多人的第一个 Skill 都做得太大，比如“帮我做一个网站”——这个描述就该直接枪毙。Skill 的粒度应该是“一件具体且重复出现的事情”，而不是“一个大目标”。

我建议按这个标准来选第一个 Skill 场景：你最近一周内，有没有让 Agent 做过两次以上的同类任务？如果有，且每次都需要额外补充背景和规范，那就是一个值得固化的 Skill。

以我自己做前端开发为例，团队里经常需要做新页面的基础骨架。每次让 Claude 或 Codex 帮写一个带响应式布局、暗黑模式支持、基础 SEO 标签的页面时，它老忘加 viewport meta，偶尔漏掉 lang 属性。这些不是模型能力问题，是“默认行为不符合我们的团队规范”。于是我做了第一个前端 Skill：frontend-page-starter。

定义边界时，我明确让它只管“静态页面的初始骨架”，不负责后端逻辑、不负责 UI 设计探索、不负责复杂的交互状态管理。边界清晰之后，Skill 的指令才能有约束力，模型不会干着干着就跑偏去做别的。

4.2 编写 SKILL.md 与辅助资源：先流程后脚本

我写 SKILL.md 的顺序和别人可能不太一样：先写流程，再写脚本，最后回头精简描述。纯粹的提示词能解决的问题，就别上脚本；脚本能标准化的，就别让模型自由发挥。

以页面骨架这个 Skill 为例，真正的核心其实是几个固定模板文件。我创建了三个模板：

• templates/html-base.html：带语义化结构、meta 标签、响应式 viewport、基础 SEO 的空页面模板
• templates/css-vars.css：CSS 变量定义，品牌色、间距、字体族的统一规范
• templates/page-starter.md：给模型看的说明页，明确在什么情况下使用上述两个模板

然后写进 SKILL.md 的正文里：取目标页面类型（落地页/列表页/详情页），选择对应模板，填充内容时遵循 CSS 变量规范，最后检查响应式断点。

这里有个经验：能用模板文件解决的，不要全塞进提示词里。模板文件是静态资源，不占上下文、不会被模型篡改；提示词是每次都要注入的活文本，能短则短。把“静态知识”从“动态指令”里拆出来，是 Skill 工程化的重要一步。

4.3 安装到本地 Agent 平台：两种主流路径

不同 Agent 平台的安装路径略有区别，但逻辑高度相似：找到 Agent 的 skills 目录 → 把整个 Skill 文件夹丢进去 → 重启或重新加载会话。

以我主力使用的几个环境为例，大致是这样：

具体目录路径在不同操作系统上不一样，这点不必死背。我自己的排查技巧是：直接在 Agent 的配置目录里搜一下已经存在的 Skill 文件夹，照着现有结构放进去，基本不会错。如果没有现成目录，创建一个也行，但要确认 Agent 框架确实会扫描那个路径。

安装完成后，第一步验证不是急着跑完整任务，而是打开一个新的会话，直接问 Agent：“你有哪些可用的 Skills？”如果它能列出你刚装的 Skill，并且 description 一字不差，说明发现机制正常工作。

4.4 实测与迭代：从“能用”到“好用”

Skill 做好之后的第一轮实测，通常不会太好看。我拿frontend-page-starter实测时，第一次给它的输入是“帮我写一个落地页”，结果它确实用了模板，但把 CSS 变量全部内联进了 style 标签，而不是引用外部变量文件。原因不是模型笨，是我 SKILL.md 里没写清楚“组件样式必须通过 var() 引用变量，禁止硬编码颜色值”。

这个教训特别典型：Sikll 的迭代过程，本质上是把“你想当然觉得模型会做”的事情，显式写出来的过程。每冒出一次不符合预期的输出，就往 SKILL.md 里加一条明确约束。三轮迭代之后，这个 Skill 生成的页面骨架我基本可以直接用，不用人工返工。

另一个重要心得是：给 Skill 配一个“自测命令”或“自测清单”。例如我的前端 Skill 输出完代码后，会自动跑一遍检查项：有没有 lang 属性、有没有 viewport meta、CSS 变量是否完整、断点是否覆盖移动端。这个自测清单写在 SKILL.md 末尾，让模型交付前自己检查。用了这个招之后，交付质量上了一个大台阶。

5. Skills 的安装、分发与生态盘点

5.1 目前主流获取与安装方式

现在社区里安装 Skills 的方式，大致分成四类。我给它们排个序，按我推荐的优先级：

1. 官方市场或平台内置目录：Claude 生态里有官方 Skills 市场，Codex 生态里也有官方推荐的技能模板仓。这种来源最稳，格式保证兼容，而且会持续维护。
2. GitHub 公开仓库：一个仓库放一个 Skill 或一个 Skill 合集，按 README 说明安装。这是目前最主流的方式，但质量方差极大，需要自己判断。
3. skills 下载平台/导航站：社区出现了一些专门收集 Skills 的站点，类似“应用商店”的逻辑，按前端、写作、数据分析、创意分镜等分类陈列。下载前多看几眼 stars 数和更新日期。
4. AI 生成后人工校正：用提示词让 Agent 自己生成一个 Skill，你审查后放入目录。

我不太建议一上来就装几十个来源不明的 Skills。你装的每一个 Skill，都等于给 Agent 增加一套“可能被执行”的指令和脚本。装得越多，出问题的排查面就越大。先用少量精挑细选的，跑顺了再扩展。

5.2 生态里的典型 Skills 分类

我陆陆续续装了拆、拆了装，现在保留下来并真正高频使用的，基本集中在下面这几类：

• 开发辅助类：前端页面生成、代码审查、React/Vue 组件模板、Git 提交信息规范化、接口文档生成。这类最适合刚入门的人体验，因为验证成本低，效果好。
• 内容创作类：博客文章框架、短视频分镜脚本、海报文案、跨平台内容改写。社区里常说的“分镜 skills”就在这一类，很受做短视频的朋友欢迎。
• 个人知识库类：笔记整理、PDF 摘要、Obsidian 工作台集成。我自己就把一个“知识卡片自动生成”的 Skill 挂到了笔记工作流里，配合第三方 Agent 工作台使用。
• 自动化测试与安全测试类：测试用例生成、边界条件扫描、代码安全基线检查等。

不过要提醒一句，现在 GitHub 上很多 Skills 仓库本质上是“Prompt 合集”，并没有真正的脚本和校验逻辑。不是说 Prompt 合集不好，但你要清楚自己装的是什么。一个带脚本、带模板、带自测清单的 Skill，和一个只有几句话提示词的 Skill，执行稳定性完全不是一个级别。

5.3 社区与市场现状：为什么说现在是入局好时机

作为一个观察者，我明显感觉到 Skills 生态正处于“基础设施已经铺好、应用层还没洗牌”的阶段。主流平台都开始原生支持类似机制，但好用的、经过充分打磨的 Skills 仍然稀缺。大部分仓库停留在“作者自己能用”的水准，距离“下载即用、文档清晰、边界明确”还有距离。

这会带来两个机会。对使用者来说，只要你会筛选，很容易找到一批处于“够用”状态的小众 Skills，提前吃到红利；对开发者来说，任何一个垂直领域里做出一个真正标准化、带测试、带文档的 Skill，放到社区里，竞争力都相当强。现在开始积累 Skills 开发和维护的经验，一年之后再回看，你大概率会比同龄人多出一整套方法论，而不是只多了一堆工具。

6. 高频故障与排查实录

6.1 运行时报错：“execution terminated due to error”

我做 Skill 过程中碰到最多的报错，就是类似agent execution terminated due to error这类提示，字面意思是“Agent 执行因错误中止”。新手一看到这个就慌了，觉得是不是自己的 Skill 写崩了。我拆解下来，这类报错其实主要来自三个层面：

• 脚本层：SKILL.md 引用的辅助脚本抛异常，比如文件路径写错、Python 环境缺依赖、传参类型不匹配。排查时先手动执行一次脚本，看能不能单独跑通。
• 模型调用层：Agent 在 Skill 执行中请求了不存在的工具，或者工具返回格式不合法。排查时打开调试日志，重点看工具调用记录。
• 资源配置层：上下文超限、输出 token 超限、文件读写权限不足。这类通常发生在处理超大文件时。

我自己的固定排查套路是：先不看日志正文，先确认它是在“哪个动作”之后挂的。是读完文件之后挂的？还是执行完脚本之后挂的？把报错缩小到具体的动作上，问题就解决了一半。

6.2 Skills 没被调用，或调用错了

比起报错，更让人恼火的是“装上 Skill 了，但 Agent 就是不调用”。十次里有八次，问题出在 description 上。

我踩过的最典型坑是：description 写得太偏“技术视角”，没写“用户任务视角”。比如我写过一个“根据用户需求生成自动化测试用例”的 Skill，description 写的是“Test generation skill based on requirement analysis”，结果模型经常不选它。改成“当用户需要为某个功能编写测试用例时使用，输入功能描述或代码文件，输出覆盖正常和异常路径的测试用例”之后，被调用频率直线上升。

核心原则是：description 要从“模型听到用户说什么话时该想起你”的角度来写，而不是从“你的 Skill 做了什么”的角度来写。这两个视角差别非常大，值得反复打磨。

还有一种情况是同时装了多个描述相近的 Skill，模型选错了。我处理的办法是：分类前缀。比如所有前端相关的 Skill 描述开头都统一带一个“Frontend:”标记，让模型在扫描时能快速分组识别，选中率明显提升。

6.3 安全与权限相关的坑

最后必须提安全。Skills 的本质是让外部脚本和指令进入 Agent 的执行链，这意味着你安装一个 Skill 时，实际上是在给 Agent增加一条“可能照做”的指令来源。如果这个 Skill 来自不可信渠道，它可能在“帮你整理笔记”的同时，诱导模型读取你的密钥文件，然后把内容拼进某个输出结果里泄露出去。

我自己有几个比较硬的安全习惯：

• 只从官方市场或明确维护的 GitHub 仓库安装 Skills，来源不明的个人网盘资源一律先人工审查再安装。
• 安装后第一件事读一遍 SKILL.md 全文，重点关注它有没有要求读取敏感路径、有没有要求联网执行不明命令。
• 尽量用“最小权限”运行 Agent 会话，比如不给整个主目录的读写权限，只给工作区目录权限。
• 定期清理不用且不再维护的 Skill。一个 Skill 长期不更新，就意味着它的脚本可能在新版本环境中出现兼容性问题，甚至成为安全隐患。

这套安全习惯我在另一个项目里也反复验证过，真的能挡住绝大多数“看似无害实则夹带私货”的问题。别嫌麻烦，Agents 的能力越强，越要在权限边界上保守。

我在实际折腾这些 Skills 的过程中，最大的一个感受是：它真正改变的，不是“模型能做什么”，而是“你如何定义模型该做什么”。以前我们跟 Agent 协作，是把希望写在对话里，靠临场发挥；现在有了 Skills，你可以把希望写成工程资产，反复打磨、迭代、共享。如果你还没亲手写过第一个 Skill，我建议你从自己工作里最常重复的 20 分钟任务开始，把它固化成一个 200 行以内的 SKILL.md——做完之后你就会发现，原来给 Agent 配上“肌肉记忆”这件事，真的会上瘾。