Agent Skills是什么？从原理到实战，手把手教你写技能包

最近这半年，我几乎把所有跟 AI 编程助手、Agent 生态相关的关键词都翻了个遍。去年大家还在比谁的 prompt 写得长、写得玄，今年风向已经彻底变了：所有人都在聊 skills。前端开发要用 skills，写论文要用 skills，分镜脚本有人做成了 skills 下载包，连安全测试领域都有人分享自动挖洞 skills。热度高归高，但大多数人是被“skills 大全”“skills 推荐”“skills 下载平台有哪些”这些热搜带进来的，对它的理解还停留在“一个高级一点的 prompt”。

这篇文章我想从一个真实用过、也自己写过 skills 的人的角度，把这件事讲透：Agent skills 到底是什么、和插件有什么区别、怎么安装和引入、怎么写一个属于自己的 skill，以及哪些坑我替你踩过了。内容覆盖 Claude Agent Skills、Codex skills、GitHub 上流传的各种技能包，也会聊到论文写作、前端开发、分镜脚本、安全测试这些具体场景。无论你是刚听说 skills 的新手，还是已经在用但想自己开发的人，都应该能从这里找到能直接抄作业的东西。

1. 为什么“skills”突然成了 Agent 生态里的高频词

1.1 从“会聊天的模型”到“会干活的 Agent”

要理解 skills 为什么火，得先看 AI 产品形态的变化。过去我们用大模型，本质是在和“一个很聪明但记性很差、手也不听使唤的专家”对话。你问他问题，他能答；你要他干活，他就只能给你一份计划，然后等你自己执行。所以最早大家拼命优化 prompt，本质是在想办法让这个“专家”在纯对话模式下多做一点事。

但 Agent 的出现改变了这件事。Agent 有工具调用能力，能读写文件、执行命令、访问网页、调用其他程序。这时候问题就不再是“模型蠢不蠢”，而是“模型知不知道该怎么用这些工具、按什么顺序用、什么时候停下来检查结果”。Skills 恰好就是解决这个问题的。

你可以把 skills 想象成给 Agent 的岗位手册。不是让它自由发挥，而是针对某类任务提前写好一套标准作业流程：先做什么、后做什么、中间可能要调用哪些脚本、最后输出什么格式。Agent 拿到这个手册之后，就知道自己“在这个场景下应该像个熟手一样干活”，而不是每次都在现场瞎试。

我最早被 skills 打动，是因为一个真实对比。同样让 AI 写一份前端页面重构方案，直接用普通对话，它给了一堆正确的废话；挂上项目专属 skill 之后，它会先去读现有组件库、检查代码规范、按项目历史习惯去改代码。差别非常明显。

1.2 Skills 和插件、Prompt、工具调用的边界到底在哪

我发现很多人把 skills 和插件、工具函数、普通 prompt 混为一谈。这里必须做个区分，否则后面安装和使用的时候很容易走弯路。

关键区别在于：工具是“手”，skill 是“大脑里的操作流程”。比如一个“代码搜索工具”只是给 Agent 一个搜索接口，但一个“代码重构 skill”会告诉它：先定位被影响的文件，再搜索所有变量引用，再修改，再跑测试，最后按项目规范生成变更说明。这个流程本身不是代码，而是指导模型如何组合使用代码和工具的文字逻辑。

所以 skills 本质上仍然是一段被结构化、可复用、可被 Agent 按需加载的提示词。但它和普通 prompt 的差异在于：普通 prompt 是一次性的，skill 是可以沉淀、版本化、分享的。这也解释了为什么 GitHub 上会出现越来越多人维护的 skills 集合，最典型的就是社区里流行的 Superpowers 这类技能包——它把不同工作阶段拆成多个 skill，用数字前缀控制加载顺序，让 Agent 强制按“先规划、再执行、后复盘”的节奏干活。

搞清楚这个概念之后，再去看各种“skills 大全”“skills 推荐”就不会晕了。它们推荐的其实不是某一个单一工具，而是一整套可组合的岗位手册。

2. 安装与引入：我实测过的三种 skills 使用方式

2.1 官方市场安装：最省心的入口

现在主流的 Agent 客户端基本都内置了 skills 管理入口。Claude 有官方市场，Codex CLI 也能从 GitHub 拉取 skills，Reasonix 这类偏重研究笔记的客户端通常也在设置页里提供 skills 安装选项。虽然入口名字不一样，底层逻辑都是同一套：把 skill 下载到本地指定目录，然后在对话或任务中按名字加载。

以我常用的 Claude 环境为例，官方市场的安装路径很直接：在客户端里打开技能市场，搜索你需要的场景关键字，点击安装，它就会自动放到对应的 skills 目录。装完之后直接新开对话，输入 skill 名称或者在任务描述里提到它，Agent 就会自动匹配。整个过程不需要写一行代码。

如果你第一次装完发现 Agent 没“变聪明”，先别急着怀疑 skill 没用。大概率是两种原因：一是安装后没有新开对话，旧会话没有重新加载技能描述；二是同一个会话里装了太多 skill，Agent 只根据用户指令选了其中一个。官方市场的好处是维护方会定期更新，description 写得比较规范，匹配准确率明显高于那些零散下载的压缩包。

2.2 GitHub 手动安装：看懂目录结构就够了

很多热门的 skills 并没有进官方市场，而是以 GitHub 仓库形式存在。比如你在 GitHub 搜 skills、frontend skills、paper skills，能找到大量开源项目。手动安装其实不难，关键就一件事：看懂 skill 的目录结构。

一个标准 skill 目录通常长这样：

my-skill/ ├── SKILL.md └── scripts/ ├── check.py └── data/

SKILL.md是灵魂，里面用 Markdown 写清楚了这个 skill 在什么场景下用、具体步骤是什么、需要哪些输入、输出什么格式。scripts/是可选的辅助脚本，Agent 在执行过程中会根据需要调用它们。

安装时，把整个目录复制到客户端约定的 skills 目录下，或者用软链接指过去，重启会话就能用。不同客户端的目录位置不一样，有的是~/.claude/skills，有的是项目根目录下的.skills，还有的是插件配置里指定路径。如果不确定，直接看客户端文档里“skills 存储位置”这一节，比在设置页里乱点快得多。

我在 GitHub 上手动装过不少 skills，有一类特别值得注意：名字起得很花哨，比如 “Superpowers”“Nature Skills”，但里面其实就是几十个 SKILL.md 的组合。所以当你看到一个很大的技能包，不要慌，它不是一款“巨型软件”，而只是很多独立小手册的集合。

2.3 第三方下载平台：先看 description 再看 star 数

“skills 下载平台有哪些”是我被问得最多的问题。除去官方市场，实际可用的来源无非这几类：GitHub 仓库、技术博客附带的开源包、以及某些客户端生态里的第三方索引站。极少有像软件商店一样规范的 skills 商店，所以“下载平台”这个词容易给人误导。

从第三方下载 skill 时，我的筛选顺序是：先看 SKILL.md 里的 description 写得是否具体。如果一个技能描述是“帮助 AI 表现得更好”这种废话，基本不用装；真正有用的描述会写明适用对象和产出物，比如“根据会议记录生成带责任人、截止时间的待办清单”。其次看目录里有没有可执行的验证脚本，有的话说明作者至少跑过测试。最后才是 star 数和更新时间。

另外提醒一句，GitHub Skills 是 GitHub 官方的交互式课程平台，用来学 Git 和 CI/CD 的，和 Agent Skills 完全是两码事。搜索时别把两者混在一起，否则你会找到一堆教你用 GitHub 的教学仓库，而不是能装进 Agent 的技能包。

3. 拆一个 skill 的底：SKILL.md 为什么是灵魂

3.1 一个最小 skill 的目录结构

如果你只想自己写一个最简单的 skill，不碰脚本、不搞复杂依赖，只需要一个SKILL.md文件。我自己的最小模板是这样的：

--- name: changelog_generator description: 根据 git log 生成面向用户的更新日志。当用户要求整理最近更新时使用。 --- ## 使用场景 适用于项目发布前整理 changelog，输入是 git 提交记录，输出是 Markdown 格式的更新日志。 ## 执行步骤 1. 运行 `git log --oneline -10` 获取最近提交。 2. 将提交消息按 feat / fix / docs / refactor 分类。 3. 将分类结果整理为 Markdown 列表。 4. 如果存在 breaking change，单独放在最上方提醒。

这个文件足够让 Agent 在绝大多数情况下“照着干活”。你会发现它其实没有写死逻辑，而是告诉模型一个流程和标准。模型的理解能力会帮忙补全那些没写进去的细节，所以 SKILL.md 的写作质量，直接决定了 skill 的实际表现。

3.2 让模型能“照着干活”的步骤写法

写 SKILL.md 最容易犯的错，是把步骤写成“正确但没操作信息”的废话。比如“分析用户需求并设计方案”——模型看了之后仍然不知道该干嘛。合格的步骤要做到两点：有动作、有判断条件。

举个例子：

• 不合格写法：检查代码质量。
• 合格写法：读取src/下所有.ts文件，如果某个函数超过 80 行，拆分为多个小函数，并保持出口参数不变。

另外，一定要在 SKILL.md 里说明“什么情况下不要用这个 skill”。这个点很多人忽略，但它比说明什么情况下用更重要。因为 Agent 的技能匹配依赖 description，如果 description 写得太宽泛，它会在不合适的场景调用，反而拖慢任务。我的经验是 description 里明确写“当用户提到 A 时使用，当遇到 B 时不使用”，匹配准确率能提升不止一个档次。

3.3 从 first principles 看 skill 的内部机制

很多人问我：“skill 是模型微调出来的吗？”不是。Claude Agent Skills、Codex skills 的原理，本质上都是“上下文工程”。当任务触发某个 skill 时，Agent 会把对应的 SKILL.md 内容拼接到上下文里，让模型在进行推理时多了一份操作手册。

这就能解释为什么同一个 skill 放在不同模型上表现不一样：因为模型的理解力、指令遵循能力和长上下文注意力不同。SKILL.md 写得再好，交给一个弱模型也可能执行歪楼。所以个人开发者做 skills，不需要追求把每句话写死，而是给模型足够的约束和空间。这有点像给新人写工作文档：太细了他会被绑住手脚，太粗了他依然一脸茫然。

理解了这个机制，你就明白为什么 skills 和“插件市场”不一样。插件是在宿主程序里注入功能，skill 只是在推理时改变模型的注意力分配。它没有魔法，是把一份高质量经验压缩成文本，再在需要时递给模型。

4. 真实场景实战：写论文、前端、分镜与安全测试

4.1 论文写作：workbuddy 这类技能包的用法

论文写作是 skills 被讨论最多的场景之一。原因很简单：写论文不是一个单一动作，而是一条很长的流水线——定题、文献综述、大纲、逐节写作、核对引用、调格式。普通人用 AI 写论文容易翻车，正是因为让模型一口气干完整条流水线，它会在中间某一步开始幻觉。

我在用 workbuddy 这类论文技能包时的体会是，它的价值不在于“写得快”，而在于强制分段。skill 会要求 Agent 先做文献检索，再生成大纲，每写一节都要对照大纲检查，最后统一整理参考文献。这样即使模型某一段发挥不行，也不至于整篇文章逻辑崩掉。

如果你下载的论文 skill 只是简单地“输入题目输出全文”，那它基本就是套了一层 prompt 的普通模板，没发挥 skills 的真正优势。你自己动手时也可以按这个思路设计：把写论文拆成“确认问题、收集证据、组织论点、落笔、检查”五个阶段，每个阶段一个问题，而不是一个命令。

4.2 前端开发：让 skills 帮你改代码而不是只生成页面

前端的 skills 现在多到眼花缭乱，有人用来做页面原型，有人用来做代码审查，还有人把团队代码规范做成了 skill。我自己试下来的感受是：对前端开发来说，最值得装的不是“生成页面”型 skill，而是“按项目规范改代码”型 skill。

原因很直接：单次生成页面，模型凭通用知识已经够用；但改一个真实项目的代码，需要它先理解现有组件库、状态管理方式、样式约定，否则生成的东西根本合不进去。一个合格的 frontend skill 会要求 Agent 先读目录结构、找现有组件、确认命名风格，再动手写代码。用完之后你会发现，AI 补的代码终于像“这个项目里的人写的”，而不是外援乱入。

如果你在 IntelliJ IDEA 这类 IDE 里用 AI 编程插件，也可以把 skills 目录挂到项目里。这样 Agent 不只是读当前文件，而是会先翻你的团队规范文件，再生成代码。挂一次之后，整个项目组都受益。

4.3 分镜脚本：把创意流程固化进 skill

分镜 skills 是我最近觉得最有“打开新世界”感觉的一类。分镜脚本看起来是创意工作，但拆开看依然有很强的流程：先拆剧本场景、再确定镜头数、给每个镜头写景别/运动/时长、标注画面内容和台词。Creative 的部分只占其中一小部分，剩下的全是重复劳动。

所以有人把分镜流程做成了 skill 下载包，输入剧本段落，输出一张分镜表。这类 skill 的价值不是替代导演，而是把导演从重复劳动里解放出来。我看到有分镜 skill 甚至会绑定绘图脚本，直接为每个镜头生成参考画面。

我自己用的时候发现，这类 skill 对“格式约束”要求很高。输出如果不强制统一字段，模型会每轮给出不同顺序的列。所以如果你自己做分镜 skill，一定在 SKILL.md 里用表格模板锁定输出结构，比如“镜号、景别、运镜、画面内容、时长、台词”，这比在对话里反复强调格式管用得多。

4.4 自动挖洞和安卓脱壳：安全测试 skills 的授权边界

安全测试领域也开始出现所谓的自动挖洞 skills、安卓脱壳 skills。这类技能的思路是：把信息收集、指纹识别、目录扫描、端点分析这些重复性很强的工作自动化，让 Agent 按照渗透测试的固定流程去跑。

但这里我必须把边界说清楚：这种自动化只能用于你拥有书面授权的系统。无论 skill 描述写得多漂亮，它只是把流程固化了，不会替你判断授权范围。没有授权的情况下跑自动挖洞，本质就是未授权扫描，属性上是违规甚至违法的。安全 skill 的价值应该体现在授权渗透测试里缩短前期侦察时间，而不是制造“一键挖洞”的幻觉。

安卓脱壳 skills 同理。脱壳本身是逆向分析流程里的一个技术环节，只能用于你从合法渠道拿到、并且有权限分析的样本。这类 skill 通常需要配合隔离环境运行，落地到实际使用，你必须自己额外配置沙箱，别指望 Agent 帮你判断样本安全性。

5. 自己开发一个 skill 的完整流程

5.1 先写场景和检查清单，不要急着写代码

我第一次写 skill 的时候，上来就写 SKILL.md，结果写了一版“自己觉得很全、模型用起来很废”的说明书。后来我换了做法：先用文字写一个使用场景，再列检查清单。

具体来说，先写一段话回答三个问题：

• 这个 skill 给谁用？是给 Agent 用，还是给一个非技术用户通过 Agent 间接用？
• 输入是什么？文件路径、用户需求、还是脚本输出？
• 成功产出是什么？一份报告、一段代码、还是一张表？

然后写出“完成标准”，比如“所有的 JSON 文件都必须通过jq解析测试”“更新日志必须包含版本号”。这些后面全部会写进 SKILL.md。代码和脚本反而是最后的事，因为大部分 skill 并不需要自定义脚本，只需要精确的步骤描述。

5.2 编写 SKILL.md 与辅助脚本

等场景和检查清单清楚了，再写 SKILL.md 就很快。我一般沿用三段式结构：frontmatter 里的 name/description、正文里的步骤、末尾的验收清单。

--- name: release_check description: 发布前检查项目状态。当用户说“准备发版”或“检查能不能发布”时使用。 --- ## 输入 本地 Git 项目，已标好版本 tag。 ## 步骤 1. 检查 git status，确认工作区干净。 2. 对比上一个 tag 与当前分支的提交，列出 feat/fix/breaking 变更。 3. 运行测试命令，收集通过/失败数量。 4. 检查 changelog 是否包含本次所有 breaking change。 ## 验收清单 - [ ] 工作区无未提交文件 - [ ] 测试全部通过 - [ ] changelog 覆盖全部 breaking change - [ ] 版本号符合语义化版本规范

辅助脚本不是必选项。只有当某个步骤靠“描述”无法稳定完成时才需要写脚本，比如解析复杂日志、调用第三方 API、批量处理文件。脚本放在scripts/目录下，SKILL.md 里写明调用方式。别为了显得专业硬塞脚本，脚本越多，维护成本越高，Agent 出错的可能性也越大。

5.3 测试与版本迭代：agent skills 也要有验收用例

“Agent skills 测试”不是玄学，而是必须做的环节。我的测试方法是三个固定关卡：单次执行、故意打断、换输入重跑。

单次执行是最基础的：新开一个对话，用真实需求触发 skill，看它能不能走通流程。故意打断是指中途改需求，比如“先不看测试，先加一个功能”，看 skill 能不能让 Agent 保持流程意识，而不是把你新指令盲目插入错误位置。换输入重跑则是换一个差异很大的输入，验证 skill 不会只对某个样例有效。

每轮测试完了，回到 SKILL.md 改步骤。我发现大多数问题出在步骤描述有歧义，而不是脚本有 bug。模型误解了“检查文件”这四个字——它可能只是看一眼内容，而不是验证文件存在且非空。所以后来我写步骤会尽量带上验证动作：“用test -s确认文件存在且非空”。

6. 我踩过的坑：skills 不是越多越好

6.1 技能加载过多会把上下文吃满

这是我最想提醒新手的一点。skills 能提升能力，但它不是无限免费的。每个被加载的 skill 都会占用模型上下文窗口，技能包越大，留给真正任务内容的 token 就越少。

我就犯过这个错。看到社区推荐的 Superpowers 技能包，整包装了十几个 skill，结果对话刚开始还能按流程走，越到后面模型越“健忘”，经常忘记前面步骤的输出。一查才发现，上下文里塞满了各种 SKILL.md，真正干活的空间被挤没了。

正确的做法是：按需装载。每个项目或任务只装最相关的 2 到 3 个 skill。官方市场的客户端通常会在匹配到 skill 时才往上下文里注入，但如果你手动在系统提示里引用所有技能，等于自己把上下文堵死了。用我之前的话说，手边常备三五个 skill 就够了，其余用的时候再装。

6.2 别迷信 skill 里写死的步骤

skills 的好处是稳定，副作用是它会“冻结”一套做法。如果你直接下载别人的 skill 而不改，很容易把我们之前说的“操作手册”变成“教条”。比如某个安全测试 skill 假设目标是 Linux 服务器，你拿去测一个容器环境，流程里很多命令不仅无意义，还会浪费大量 token。

所以拿到别人的 skill，第一件事不是立刻用，而是通读一遍 SKILL.md，把明显不适用的默认路径删掉。尤其是从第三方平台下载的“skills 大全”，里面大概率塞了很多通用场景的流程，对你的实际项目来说反而是噪音。

我自己的习惯是：把下载的 skill 当成模板，fork 一份改成自己的。保留骨架，替换项目相关的路径、命名、规范。改完之后再跑一遍测试，确认它匹配的是你的真实项目。

6.3 从“最小可用版本”开始迭代

最后分享一个我沉淀下来的经验：开发 skill 一定从最小可用版本开始。第一版只解决“当前最痛的那一个动作”，哪怕一个 SKILL.md 只有十个步骤都行。跑通之后，再往里面加异常处理、验收清单、辅助脚本。

原因在于，Agent 的行为很难一次性预判准。你花一天时间写了一个十全的 skill，可能跑一次才发现最基础的步骤顺序有误，前面的精细设计全得推倒。而最小可用版本能让你快速验证“这个 skill 的路子对不对”，再逐步把复杂场景补进去。

我现在维护的几个个人 skills，版本号都维持在 0.x。我甚至会在 SKILL.md 的 frontmatter 里加一个 changelog 字段，记录每次改动的原因。等哪天改动变得很有规律，再考虑打包分享到 GitHub。这种迭代节奏不性感，但确实稳。

最后再说一个小技巧：给每个 skill 都取一个名字，并且保证名字和 description 里没有“通用万能”这类词。因为模型是按 description 做匹配的，描述越精确，调用越果断。我的changelog_generator就比“帮助生成文档”好用得多——前者能在正确场景被触发，后者会在所有场景都蠢蠢欲动。