从提示词到可复用技能：Agent Skills 的安装、编写与维护指南

前阵子换了一台新电脑，装好 Claude Code 后我干的第一件事不是配 API Key，而是打开 GitHub 把收藏夹里几十个 skills 仓库挨个 clone 下来。有朋友笑我太折腾，但我真吃过亏——最早我攒了一堆“神级 prompt”，散落在各种对话记录、备忘录和网页剪藏里，换台电脑等于全部清零，重新调教 AI 的成本高得吓人。后来接触到 Agent Skills（也就是大家常说的 skills），我才意识到提示词工程已经从“会话级”进化到了“资产级”：以前是每次对话都手写指令，现在是写一次、存下来、到处用。

这篇内容就围绕 skills 展开，适合三类人：刚听说 skills 这个概念、想搞明白它到底是什么的小白；已经在用 Claude Code 或 Codex、但只会从 GitHub 上装现成 skill 的普通用户；以及打算自己写 skill、把它变成生产力工具的进阶玩家。我会把自己手动安装、踩坑、写 skill、清理维护的完整过程都写出来，争取让你看完就能直接上手。

1. Skills 到底是什么：从一段复制粘贴的咒语到一个可复用的“外挂大脑”

先讲一个类比。以前用 AI 干活，就像每次请一个临时工，你得从头交代背景、流程、输出格式、注意事项。遇到复杂的活儿，比如“帮我审查前端代码规范”，你每次都要写一大段指令，说清楚要看哪些文件、按什么标准审、输出什么格式的 report。写多了你会发现，这段指令本身才是真正的生产力——AI 模型就在那里，谁给的指令质量高，谁拿到的结果就好。

1.1 我的第一个 skill：从“糊墙”到“贴瓷砖”

我第一次真正理解 skills 的价值，是在处理一个重复性任务的时候。当时我需要 AI 帮忙把一批 Markdown 文档统一转成项目周报格式，包括标题层级、表格栏位、措辞风格、敏感信息标注方式，每次手工写提示词都要花十来分钟，而且稍微漏掉一个要求，输出就变样。

后来我照着社区里的做法，把这段提示词写进一个文件夹，里面放一个SKILL.md文件，再用几句话描述这个 skill 是干什么的，AI 就能在我需要的时候自动“想起”它。这个词叫什么不重要，重要的是它让我第一次感觉到：AI 的使用方式从“每次现写”变成了“随取随用”。就像装修从“每次现和水泥糊墙”变成了“预制好瓷砖，按尺寸贴上去”，效率完全不是一个量级。

1.2 SKILL.md 的结构：一段 YAML 头信息加一堆“作业指导书”

一个标准的 skill，本质上就是一个文件夹加一个SKILL.md主文件。文件夹的名字就是 skill 的名字，SKILL.md是这个技能的说明书。说明书开头有一段 YAML 格式的 frontmatter，用来声明这个 skill 的名字、描述、可用的工具，后面跟着的是正文——也就是你希望 AI 在执行这个技能时遵循的完整指导。

拿一个最简单的 hello world 举例：

--- name: weekly-report description: 将零散的 Markdown 笔记整理成项目周报格式。当用户提到“生成周报”“整理周报”或给出多篇笔记时使用。 --- # 周报生成流程 1. 读取用户提供的所有 Markdown 文档。 2. 按“本周进展 / 风险与阻塞 / 下周计划”三部分整理内容。 3. 每条进展必须注明对应负责人与完成度，格式为 `任务名（负责人，完成度%）`。 4. 遇到不确定的信息，用 `[待确认]` 标记，不要自行编造。

这段内容看起来平平无奇，但一旦放进~/.claude/skills/weekly-report/SKILL.md，Claude Code 启动后就会自动加载它。当你说“帮我把这周这几篇笔记整理成周报”，AI 会把这个 skill 当成一份“岗位说明书+SOP”，严格按照里面的流程执行，而不是临时猜你想要什么。

1.3 为什么 skills 现在才火：从“会话级提示词”到“资产级技能”

之前不是没有类似的方案，比如自定义 system prompt、保存 prompt 模板、用 MCP 挂外部工具，但它们各自都有问题。自定义 system prompt 只对一个会话有效，换个项目就得重新贴；prompt 模板只是个文本文件，AI 不会自动识别“什么时候该用”；MCP 解决的是“AI 能不能操作外部工具”的问题，管不了“AI 该怎么干活”的流程问题。

skills 把几件事一次性解决了：它有自动匹配机制，靠 description 里的语义描述判断何时启用；它有标准目录规范，换台电脑同步一下就能恢复；它还能携带脚本和资源文件，不只是纯文本提示词，而是把“知识”和“执行”合在了一起。

我做了个表格，方便你理解 skills 和传统方案的差异：

理解到这个层面，你就知道为什么社区对 skills 的热情这么高。它不是换了个名字炒冷饭，而是真正把“怎么用 AI”这件事从临场发挥变成了基础设施。

2. 手动安装 GitHub 上的 Skills：文件结构、路径规则与常见失败原因

先说结论：手动安装一个 skill 的完整流程就三步——把仓库弄到本地、放进指定目录、重启会话。但我实际操作下来，这三步每一步都有坑，而且很隐蔽，尤其是第一次装的时候，很容易掉进“明明放进去了却加载不出来”的困境。

2.1 从仓库到本地的三步搬运

第一步是获取 skill 文件。最常见的做法是把整个 GitHub 仓库 clone 下来。比如你看到一个叫awesome-claude-skills的仓库，里面有code-review、doc-generator等子文件夹，你可以只 clone 整个仓库，也可以单独下载某个子文件夹。

第二步是找到目标路径。Claude Code 里默认读取两个位置：用户全局目录~/.claude/skills/和项目本地目录<项目根目录>/.claude/skills/。全局目录里放的是所有项目通用的技能，本地目录放的是只属于当前项目的技能。两者的加载优先级有差异，本地目录会覆盖全局同名 skill，所以同一个技能在不同项目里可以有不同版本，这个特性后面会细说。

第三步是验证加载。装好后重启当前会话，输入/skill命令，看列表里有没有出现你刚加的技能名称。有的话就说明加载成功了。这一步看起来简单，但很多人恰恰是卡在“重启了也没出现”上。

2.2 路径到底放哪里：不同工具的目录差异

不同终端工具对 skills 的目录约定不完全一样，我实际试过的有这么几种，给你做个对照：

这里有个容易弄混的点：有些老教程会把 skills 放到~/.claude/commands/或者~/.claude/plugins/下面，这些目录是 slashes 命令或者插件用的，规则不同。我第一次装的时候就是照着网上一个旧帖子，把 skill 放到了~/.claude/commands/底下，折腾了半天，用/skill怎么都看不到，后来才发现是目录搞错了。所以动手前先确认一下你用的工具版本对应的官方文档，别用旧消息指导新版本。

2.3 我遇到的三次加载失败

第一次加载失败，原因是“目录套娃”。GitHub 上很多 skill 仓库为了展示，会把子技能放在skills/xxx路径下，比如skills/code-review/SKILL.md。如果你直接把整个仓库 clone 到~/.claude/skills/下面，目录结构就变成了~/.claude/skills/repo-name/skills/code-review/SKILL.md，一级目录是仓库名，二级目录才是code-review。Claude Code 只扫描一级目录下的技能文件夹，这样嵌套两层就识别不到了。解决办法是把skills/code-review这个文件夹整个复制出来，放到~/.claude/skills/的根目录下，保证结构是~/.claude/skills/code-review/SKILL.md。

第二次失败是 frontmatter 里面的name字段缺失。有个技能文件夹的名字叫pdf-summary，但 SKILL.md 开头的name写成了pdf_reader，和文件夹名对不上，加载的时候报了警告，AI 匹配时也出现了混乱。后来统一改成文件夹名和name一致才正常。

第三次是description写得太空洞。我装了一个技能，描述只有一句话：“Handle file operations.”。结果实际用的时候，我说“把这个 PDF 转成文字提取关键信息”，AI 根本没想到要用它，因为描述里没有提到 PDF、提取、关键信息这类触发词。后来我参照社区建议，把 description 改成包含多个同义触发词的版本，准确率立刻上来了。

提示：description 决定 AI 什么时候“想起”这个 skill。写得越具体，触发越准。只写“Handle file operations”等于告诉 AI 这个技能只能处理“文件操作”这种宽泛话题，实际场景根本匹配不到。

2.4 验证 skill 被加载的快速方法

除了用/skill看列表，还有一个更直接的验证方法：在 skill 的SKILL.md里加一行特殊的输出标记，比如让 AI 在执行完任务后回复“已按 skill 流程执行”，然后触发一次，看是否有这句话。如果回复里出现了，说明 skill 被完整加载并生效了；如果没出现，说明 AI 只是按照普通对话模式在回答，你就要回头检查目录和 frontmatter 了。

还有一个判断技巧是问 AI“你现在能使用哪些技能”，不同工具的回答方式不同，但多数会把已加载的 skill 名字罗列出来。注意因为模型本身的差异，它未必能准确记住所有技能名，所以最可靠的还是/skill命令的输出。

3. 手写一个自己的 Skill：以“前端开发规范审查”为例拆解格式与设计

装别人的 skill 只是第一步，真正让 skills 产生巨大价值的，是把自己手头重复性、流程化的工作沉淀成自己的技能。毕竟每个人面对的团队规范、项目结构、输出要求都不同，通用技能只能解决通用问题，最贴合自己工作流的一定是自己写的。

3.1 写之前先想清楚“边界”

很多人第一次写 skill 容易犯一个错误：把什么都塞进去，恨不得写一个“万能 AI 助手”。这是不对的。skill 不是系统提示词，它的定位是“特定场景下的专业工作流”，边界越清晰，效果越好。

拿“前端开发规范审查”来说，你要先想清楚几个问题：这个 skill 只审查 JavaScript/TypeScript 代码，还是也管 CSS 和 HTML？审查的依据是什么——是你们团队自己写的规范文件，还是业界通用规范？输出格式是直接在对话里给建议，还是生成一份完整的审查报告文件？输入是什么——是让 AI 自己读项目代码，还是用户粘贴代码片段？

我把这些问题整理成一个“功能边界表”，然后再动手写：

有了这个表，写起来就有的放矢，不会写着写着就跑偏。

3.2 一份能直接改来用的 SKILL.md 示例

下面是一份我实际在用的前端审查 skill 的简化版本。你可以直接复制，改成你们团队的规范再使用：

--- name: fe-code-review description: 对前端 TypeScript/React 代码进行规范审查。当用户要求“审查前端代码”“review 组件”“检查 tsx 文件规范”或给出 .tsx/.ts 文件路径时使用。 allowed-tools: - Read - Glob - Grep --- # 前端代码规范审查 ## 审查前准备 1. 先检查项目根目录是否存在 `FE_LINT.md`，存在则优先以该文件中的规则为准。 2. 使用 Glob 查找用户指定路径下的 .ts / .tsx 文件，或读取用户粘贴的代码。 3. 限定单次审查文件数量不超过 10 个，避免上下文溢出。 ## 审查维度 按以下顺序逐项检查： 1. **组件结构**：是否将业务逻辑与 UI 分离，自定义 Hook 是否独立封装。 2. **状态管理**：props 是否超过 5 个，是否需要拆分组件或使用 context。 3. **样式方案**：是否混用 CSS Modules 和 Tailwind，类名是否语义化。 4. **类型安全**：是否存在 `any` 类型，公共函数是否缺少返回类型注解。 5. **性能隐患**：是否存在不必要的 `useMemo` / `useCallback` 依赖，列表渲染是否有稳定 key。 ## 输出格式 按以下三级列出问题，并给出修改建议： - `[阻塞]` 会导致功能异常或明显性能问题的问题。 - `[建议]` 不符合规范但可运行的问题。 - `[风格]` 仅影响可读性的小问题。 每条问题必须包含：文件路径、行号范围、问题描述、具体修改方式。 ## 注意事项 - 只做审查，不要直接改代码。 - 用户未提供规范文件时，使用内置通用规则并明确说明依据来源。

3.3 从“能用”到“好用”的迭代：加示例、加检查清单、加工具限制

第一版 skill 通常只能说“能用”，距离“好用”还有距离。我的迭代经验有三条。

第一，加真实案例。在 SKILL.md 里放进一两个你们团队真实出现过的典型问题示例，AI 在审查时就能对照示例来判断。这比抽象描述几十条规则有效得多，因为大模型对“例子”的参考能力比对“规范性条文”的执行能力强很多。

第二，加检查清单。把每个审查维度拆成可勾选的清单项，让 AI 按照清单逐项确认，避免遗漏。比如状态管理这一项，可以拆成“props 数量是否超标”“是否有未使用的 setState 调用”“context 是否在组件外部解构取值”。这样 AI 的执行路径更清晰，输出也更稳定。

第三，用好allowed-tools。在 frontmatter 里显式声明允许使用的工具，等于给 AI 划定了工作范围。比如上面例子我只允许 Read、Glob、Grep 三个工具，AI 就不会自作主张调用执行类工具去改代码。这一步很多人忽略，但实际上是 skill 安全性控制的重要防线，尤其是当你准备把 skill 分享给团队其他人用时，更要限制工具权限。

3.4 命名与描述的艺术：description 决定 AI 什么时候想起你

skill 的name和description看似只是两行元信息，实际上决定了这个 skill 的生命力。name最好是“动词+对象”结构，比如fe-code-review、weekly-report-generator，一看就知道是干什么的。description则要包含三部分：适用场景、触发词、执行效果。

我见过很差的 description 是“This skill handles code review.”，这种描述基本等于没有。好的描述应该像这样：“审查前端 TypeScript/React 代码规范，按阻塞/建议/风格三级输出结果。当用户要求审查前端代码、检查 tsx 文件规范、提到组件质量问题或给出 .tsx/.ts 文件路径时使用。”这里面既有场景描述，又有明确的触发词，AI 匹配的准确率明显更高。

写 description 的时候还有个技巧：把你和同事日常对话中常说的词都放进去。比如你们的说法是“帮我看看这段代码干不干净”，那“看看代码”“干净不干净”就可以写进触发词。大模型匹配描述用的是语义相似度，口语化表达和书面表达它都能理解，但明确写进去的触发词命中率总是最高的。

4. 高热度场景下的 Skills 实战推荐：数学建模、AI 漫剧与日常 Coding

光会写还不够，还得知道哪些场景最值得投入。我翻了近期社区里高热度的 skills 讨论，主要集中在三个方向：数学建模竞赛、AI 内容生产（特别是 AI 漫剧）、以及日常前端/Coding 提效。这几个方向的热度不是没道理的，因为它们都有“流程固定、重复度高、模板化输出”的特点，正好是 skills 的强项。

4.1 数学建模：从“生成论文模板”到“全流程提效”

数学建模相关的 skills 在竞赛季特别火，尤其是华为杯、国赛这类比赛前，不少人会专门去找现成的建模 skill 来辅助。我自己也看过几个，发现它们解决的核心痛点是三块：模型选择、写作规范、数据分析。

先说模型选择。建模比赛里很多队伍卡在“不知道用什么模型”，一个model-selector类的 skill 可以把常见的评价模型（层次分析法、熵权法）、预测模型（回归、时间序列、灰色预测）、优化模型（线性规划、遗传算法）根据问题特征快速匹配。写这种 skill 的关键是把每个模型的适用条件、数据需求、局限性写明，否则 AI 容易推荐一些花哨但不实用的模型。

再说写作规范。论文排版是建模比赛里最容易丢分也最耗时的地方。一个paper-formatter类的 skill 可以封装 LaTeX 模板、公式编号规范、图表标签规则。你只要把论文初稿扔给它，它按照规范帮你整理结构、统一格式、检查公式编号。这种技能节省的时间非常可观，往年一群人熬夜调格式，现在几分钟搞定。

最后是敏感性分析。这类 skill 我建议自己写，因为不同赛题的变量不同，通用模板很难直接用。但核心套路是一致的：固定分析哪些变量、变化范围多大、输出什么形式的图表。写一次，以后所有比赛都能复用。

注意：建模 skill 辅助的是流程和表达，不能替你做模型推导。我见过有的队伍过于依赖 AI 生成结果，最后论文里模型和数据对不上，反而吃了大亏。把 skill 定位成“提效工具”而不是“代写工具”，才是正路。

4.2 前端开发 skills：代码审查、组件生成、样式一致

前端方向是目前 skills 生态里最卷也最成熟的领域。热度最高的是代码审查类，也就是我上一章示例里的那种技能。这类技能的核心价值不是替代人眼，而是当一个“不厌其烦的规范检查员”，把团队规范从口头传递变成自动执行。

另一个很实用的是组件生成类。比如你团队定义了 Button、Modal、Table 等基础组件的标准写法，写一个component-generator的 skill，要求 AI 在生成组件时必须遵循团队约定，包括目录结构、样式方案、props 命名、测试用例位置。这样每次新开页面都从标准组件开始，代码一致性好很多，review 成本也直线下降。

还有样式一致性审查。这个需求往往隐性问题居多：有人用内联样式，有人用 CSS Modules，有人直接写 Tailwind class，混合在一起项目就乱了。写一个专门检查样式方案的 skill，输出“混用情况清单”，比靠人眼翻代码高效得多。

我见过有人在团队里把这几个 skill 组合在一起，形成一套“前端技能包”：新代码用组件生成 skill 起步，提交前用代码审查 skill 自检，定期用样式审查 skill 清理技术债。这种做法很值得参考，因为单个 skill 改进的是某个环节，组合起来改善的是整个开发流程。

4.3 AI 漫剧与内容生产：把“角色设定”和“分镜脚本”变成规范产物

AI 漫剧是今年内容创作圈绕不开的热词。这类内容的特点是高度模板化：固定角色设定、固定画风描述、固定分镜脚本格式、固定节奏控制。每一集的内容不同，但生产的流程几乎完全一致，特别适合用 skills 来标准化。

实际用下来，最有价值的漫剧 skill 有三类。第一类是角色一致性设定，封装了“角色外貌、性格、语气、代表性动作”的字段规范，让 AI 在生成每集剧本时保持同一角色的设定不变，避免出现上一集黑发下一集棕发的尴尬。第二类是分镜脚本生成，把“场景描述、镜头运动、景别、台词、时长、转场方式”这类格式固定下来，AI 生成的分镜脚本可以直接喂给绘图工具使用。第三类是画风描述词封装，因为漫剧的画风描述往往是一长串风格关键词，写成一个 skill 之后，不用每次手动复制那串咒语。

这类 skill 有个特别大的好处：你可以让 AI 按固定格式批量生成多集脚本，然后人工只做筛选和微调。相比每集都从零开始写，整体产能拉升一个量级，而且风格一致性也更有保证。内容平台对原创度的要求越来越严格，模板化作业在这里反而能保证基底质量，后续人工二创的空间也更清晰。

4.4 推荐几个我长期在用的开源技能源和筛选方法

GitHub 上 skills 仓库多如牛毛，但质量参差不齐。我踩过不少坑，也沉淀出一些筛选方法。首先看仓库的更新日期，长期不维护的仓库里的技能大概率滞后于当前 API 能力变化，建议谨慎使用。其次看 SKILL.md 里的 description 写得是否具体——一个随手写完 description 的仓库，里面的技能质量通常也不高。最后看是否有独立的测试样例或使用示例，这能说明作者真的跑通过。

我长期在用的几个源包括：社区里流行的高质量技能合集，比如Superpowers系列——它是一整套面向不同场景的子技能集合，适合先整体安装再按需裁剪；还有各类按领域整理的 awesome 列表，从数学建模到前端开发都有，适合新手快速搜索。另外typesafe skills这类企业级示例也值得关注，它的 skill 文件结构更规范，可参考性很高，适合想学习“如何把技能写到生产可用”的人。

不过我想强调的是，别人的 skill 只能提供通用解法，真正适合你工作流的版本，大概率要自己改一遍。我的习惯是：先装一个开源的，跑一次真实任务，再按自己的需求改 SKILL.md 里的规则和示例。这个过程本身就是 skill 开发能力成长最快的方式。

5. 用久了才会遇到的几件事：清理、冲突、版本管理与维护心得

Skills 装多了之后，你会进入一个新的阶段——不再是为“没有 skill”发愁，而是为“skill 太多”头疼。这个阶段的问题很少有人提前讲，但几乎所有重度用户都会遇到。今天就说说我在清理和维护过程中的实际经验。

5.1 skill 装多了会怎样：上下文膨胀与匹配混乱

很多人以为 skill 装得越多越强，实际上不是这样。每个 skill 加载后都会占用上下文窗口，虽然单个 skill 可能只有几千个 token，但装上几十个之后，累积起来就是一个不小的开销。更重要的是，AI 在每轮对话里都要把你的意图和几十个 skill 的 description 做语义匹配，描述相似的 skill 多了，就容易触发错乱。

我自己就遇到过：装了一个pdf-summary和一个document-analyzer，两个描述里都提到了“文档分析”。结果我让它处理 PDF，AI 同时加载了两个技能，输出格式反而变得混杂，不如只用其中一个的时候干净。后来我把它们合并成了一个doc-insight技能，问题才解决。

判断 skill 是否该留，我有一个简单标准：看最近两周有没有实际触发过。如果一个技能两周内从没被匹配到，说明它对你的工作流没有帮助，要么是描述写得不够准，要么是场景太窄。这时候应该优先改 description 而不是直接删掉，但改完之后再观察两周仍没触发，就果断清理掉。

5.2 清理方法论：删除、归档、重新评估的完整流程

社区里关于清理 skills 的讨论很多，我记得有人（tibo）推荐过一套“清理方法论”，核心思路是先归档再删除，给每个 skill 一个“观察期”。我实践下来非常有效，具体流程是这样的：

第一步，把当前所有 skill 列出来，按“高频使用 / 偶尔使用 / 从未触发”三档分类。第二步，把“从未触发”的 skill 移动到归档目录，比如~/.claude/skills_archive/，不要直接删除——因为你可能会在某个项目里突然需要它，到时候从归档里找回来比重新从 GitHub 下载更省事。第三步，观察两周，如果归档的 skill 里有被频繁翻找、或者实际需要启用的，就把它移回来，同时精简它的 description。第四步，归档超过一个月的，直接删掉，GitHub 上有原版的就记下仓库链接，没有原版但以后可能用到的，单独提交到自己的备份仓库。

这套流程走完，我的 skills 目录从七十多个降到了二十多个，日常使用的匹配准确率和加载速度都有了明显提升。更重要的是，留下来的每个技能我都清楚它是干什么的、为什么留，而不是稀里糊涂装了一大堆。

5.3 版本管理：把 skills 变成“可迁移的资产”

清理完剩下的 skill，就是真正值得长期维护的资产了。既然是资产，就得有版本管理。我强烈建议把 skills 目录纳入 Git 管理，可以把整个~/.claude/skills/变成一个独立的 Git 仓库，也可以放在你的 dotfiles 仓库里统一管理。

具体的做法很简单：

cd ~/.claude/skills git init git add . git commit -m "init: 初始技能库"

然后把仓库推到你的私有远程仓库，以后换电脑、换团队、甚至换工具（比如从 Claude Code 迁移到 Codex）的时候，只需要 clone 回来就能恢复全部技能。我用这个办法已经跨了三台设备同步技能库，体验非常顺手。

版本管理还有个额外的好处：你可以放心大胆地改技能。改坏了用git diff看改了什么，git checkout回退旧版，不会因为一次实验性修改就丢掉之前调好的版本。我建议每次对 SKILL.md 做大改时都提交一次，提交信息里写清楚改动原因，比如“扩展触发词，修复与 doc-analyzer 冲突”，这样后续回溯时一目了然。

5.4 我的最终建议：先用手抄，再收藏，最后自己写

skills 生态现在还处于快速演化期，工具的目录约定、加载机制、甚至名词本身都可能调整。有几件事大概不会变：一是流程标准化带来的效率提升是真实的，二是可复用的技能资产会越来越值钱，三是最贴合自己需求的技能必须自己动手磨。

如果你刚开始接触 skills，我的建议很简单：先别急着收藏一堆仓库。找一个你每周都会做的重复性任务，手动用 AI 做一遍，把中间用到的指令、注意事项、输出格式记录下来，然后花一个下午写成SKILL.md。这个从“手抄”到“封装”的过程，比下载一百个现成的 skills 都有价值。等你写过一个完整的 skill，再回头看别人的技能库，你会迅速判断出哪些能直接拿来用、哪些需要改、哪些只是花架子。到那个时候，skills 就不再是别人的概念，而是你自己的生产力工具了。