Agent Skills深度解析：从Prompt到可复用技能，手写与平台安装指南

最开始接触Agent Skills这个概念，我是有点不屑的。那阵子朋友圈里到处都在聊“Skills”，从Claude Code到Codex，从Superpower到CodeBuddy，几乎每个Agent框架都要蹭一下。我当时的第一反应是：这不就是“升级版Prompt”吗，换个名字炒冷饭。但真正把手头一个重复性很高的项目流程拆成Skill之后，我承认之前判断下早了。你别说，这东西确实是Agent落地过程中少数能被验证“有实际价值”的设计之一。

如果你最近也在折腾Agent开发，或者被“agent skills”“superpower skills”“claude code skills安装”这些热搜词绕得有点晕，那我这篇就把自己从概念理解、边界梳理、手写Skill到安装排查的完整过程掰开揉碎讲一遍。里面有不少是我实际操作中踩过的坑和验证过的结论，希望能帮你少走点弯路。

1. Agent Skills到底是什么：一次需求侧的范式转移

1.1 从“每次重复劝”到“打包成技能”

先说一个我自己的真实场景。之前我在项目里维护一份技术周报，每周末要做的事情高度相似：拉取本周的代码提交记录、按模块归类、统计变更量、生成Markdown格式的周报。最初我用Agent处理这个需求，每次都得在对话里反复强调格式要求：“按模块分组，每个模块下面列出提交ID、标题、影响范围，最后按总量做个汇总”。第一次Agent照做了，第二次换了个会话它又忘了，第三次我换了模型，又得重新教一遍。

这个痛点的本质在于：Prompt是跟着单次会话走的，是无状态的。每次对话，模型看到的还是那一段“临时指令”，没有形成可复用的资产。而Agent Skills解决的就是这个问题——它把某一类任务的完整执行方案，包括背景信息、操作步骤、约束规则、输出格式，甚至示例和校验脚本，统一打包成一个标准化的模块。Agent在遇到对应任务时，可以主动去“翻阅”这个模块，按里面的流程执行，而不是依赖用户在每一轮对话里重新描述需求。

这也是为什么社区里会有人开始重新思考“Rethinking Skills and Prompts”这个问题。在一些新模型的讨论中，大家逐渐意识到，Skills并不是Prompt的简单替代，而是把Prompt从“每次都要写”变成“写一次，长期复用”，并且还能附带资源文件、脚本、模板这些Prompt带不动的重型资产。

1.2 一个合格Skill的目录长什么样

我对Skills的态度转变，很大程度上是因为它的目录结构足够干脆。一个标准Skill本质上就是一个文件夹，里面至少包含一个SKILL.md文件，以及一个可选的resources资源目录。

my-skill/ ├── SKILL.md └── resources/ ├── templates/ │ └── report_template.md ├── examples/ │ └── sample_output.md └── scripts/ └── validate_report.py

SKILL.md是整个技能的核心说明书，通常采用Frontmatter加正文的结构。Frontmatter区域用YAML格式声明技能的name和description，正文部分则详细描述技能的适用场景、执行步骤、规则约束和输出格式。

--- name: weekly_report_generator description: 根据Git提交记录自动生成技术周报。适用于周报/月报/项目进展汇总，当用户要求整理本周提交、生成汇报Markdown时使用。 --- # 周报生成技能 ## 适用场景 - 周报、月报、项目进展汇总 - Git提交记录整理与分类 ## 工作流程 1. 读取指定仓库的提交日志 2. 按模块和提交类型分类 3. 统计变更量与风险项 4. 按模板输出Markdown

这样的结构看起来简单，但实际价值很大。因为描述字段写得好不好，直接决定了Agent在什么场景下会“想起”这个技能；而正文步骤则决定了Agent能不能稳定地输出结果。后面我会在开发实操部分详细展开，这里先有个整体印象就行。

2. Skill、Agent、Harness、Prompt：四者到底怎么分

2.1 Skill vs Prompt：一次性指令 vs 可复用方案

我见过不少朋友在讨论Skills时，最常问的一个问题就是：这不就是Prompt吗？说实话，我在深入使用之前也是这么认为的，但实际操作两三个Skill之后，二者的差异就非常清晰了。

Prompt是你在每次对话中给模型的一段直接指令，它随请求发送，用完即走。哪怕你保存了一个很长的系统提示词，它本质上仍然是一段静态文本，无法附带复杂的模板文件，也无法内置校验脚本。而且Prompt的效果高度依赖当次上下文的语义对齐，换个模型、换个时间，输出结果可能千差万别。

Skill则是一个可执行的包。它不仅有SKILL.md这段“指导文本”，还可以有resources目录下的模板、示例、脚本等多文件资源。Agent加载Skill时，不仅读到规则，还能拿到一个完整的“工具包”。比如我写的LaTeX排版Skill，在Prompt阶段我只能说“请生成一个规范的LaTeX文档”，模型能不能想起正确的宏包配置全看运气；而做成Skill之后，resources/templates里放着可直接套用的论文模板，模型直接复制模板再替换内容，出错的概率就小了很多。

2.2 Skill vs Agent：执行主体 vs 能力模块

还有一个高频问题：“Skill和Agent的区别是什么？”这俩确实容易混淆，尤其是很多Agent框架里，Skills看起来就像是一个个“小Agent”。

我的理解是这样的：Agent是执行主体，它由模型推理能力驱动，负责理解用户目标、规划任务步骤、调用合适的工具，并且拥有记忆和上下文管理能力。而Skill是这个Agent可以调用的“能力模块”，它本身不会思考，也不做决策，只是一份非常详细的“操作手册”。Agent决定在什么场景下使用这份手册，Skill负责告诉Agent具体怎么干到位。

放到生活里类比，Agent像一个厨师，而Skill是厨师手边的菜谱。菜谱不会自己炒菜，但它决定了红烧肉是先焯水还是先煎糖色。Agent的决策能力负责判断“这个任务应该查哪本菜谱”，查到了就按步骤执行，执行中如果遇到意外，还是要靠Agent本身的判断力来调整。

所以一个Agent可以挂载几十个Skills，它就像一个拥有几十个专项能力的工作台；而一个Skill也可以被多个Agent重复使用，它是高度解耦、可插拔的。

2.3 Harness、Agent与Skill：运行环境、大脑和工具书的协作

热搜词里还有一组很有意思的对比：“harness和agent区别”。这个在技术上确实值得聊清楚。

Harness是Agent运行的外壳和基础设施，它定义了Agent怎么思考、怎么调用工具、上下文窗口怎么管理、工具执行结果怎么回传。可以理解成一个工作台，台面上有各种接口和插槽。Agent是工作台上那个真正的操作者，它负责理解任务，做出决策，一步一步推进。Skill则是放在台面上的工具书和模板盒，Agent在需要的时候抽取出来使用。

在实际框架中，Harness会提供工具调用循环（agent loop）、上下文组装机制、错误处理逻辑，它会决定模型每轮看到什么信息。Agent在Harness里运行，通过Harness暴露的工具接口去读取Skill文件、执行Skill内附带的脚本。也就是说，Skill并不直接跟模型对话，它先被Harness读取成上下文内容，再由Agent消化执行。

所以你要是看见“harness和agent区别”这种搜索词，别慌。简单概括就是：Harness管运行环境，Agent管决策，Skill管特定任务的执行知识。三者配合，才是完整的Agent应用形态。

2.4 边界模糊时的判断标准

概念看再多也会有模糊地带，这里分享一个我实际用来判断“到底该做成Prompt、Skill还是Agent”的经验标准。

如果一段指令只需要在当前会话里生效，用完就丢，那就写Prompt，没必要搞复杂。如果这个任务会反复出现，且执行流程相对固定，那就值得做成Skill。如果这个任务需要跨步骤规划、需要多轮跟用户交互确认、需要记忆历史信息，那可能单独写成一个专用Agent更合适。

我自己的习惯是：同一任务连续出现两三次之后，就会把最稳定的那部分流程拆出来做成Skill。不是所有东西都要一上来就技能化，过度设计反而是初学者的常见问题。

3. 从零手写一个LaTeX排版Skill：完整实操

3.1 取名与description：Agent认不认你，全靠这两行

很多人写Skills，第一版上来就闷头写正文，写完发现Agent根本不调用。这个问题十有八九出在description写得不够“显眼”。

我以热搜里出现过的“LaTeX排版Skills”为例来拆解。假设我想要一个能生成符合学术规范的LaTeX文档的技能，最笨的description是这样写的：

--- name: latex_skill description: LaTeX排版能力 ---

你看，这么写Agent完全不知道什么时候该用它。“LaTeX排版能力”这句话太泛了，模型无法判断一个写作任务是否属于这个技能的范畴。我后来反复调整，最终用了这样一个描述：

--- name: latex_document_builder description: 根据用户需求生成符合学术规范的LaTeX文档。适用于论文、技术报告、简历、Beamer幻灯片等场景。当用户要求排版、论文模板、学术格式、PDF输出、简历制作时使用。不适用于普通Markdown文档和纯文本笔记。 ---

这个描述里明确写了几件事：技能能做什么、适用于什么场景、触发关键词是什么、负向排除什么。模型在匹配技能时，靠的就是这种语义含混度低的描述。负向条件也很重要，它能避免Agent把“帮我写个笔记”这种无关任务也错误地挂到这个技能上。

3.2 SKILL.md正文：把“专家做法”结构化

description决定Agent认不认你，SKILL.md正文则决定Agent干得好不好。很多人容易在这部分写得太抽象，比如“生成规范的LaTeX文档”——这跟没写一样。我写正文时坚持一个原则：把步骤细化到每一步都有明确产出。

# LaTeX 文档排版技能 ## 适用场景 - 学术论文、课程报告、技术文档排版 - 简历、求职信 - Beamer幻灯片制作 ## 工作流程 1. 确认文档类型，优先从 article、report、book、beamer 中选择 2. 选择模板文件：根据文档类型在 resources/templates/ 下找到对应 .tex 模板 3. 替换模板中的标题、作者、摘要、正文内容 4. 检查是否包含中文字符，如果有则确保使用 ctex 宏包 5. 输出完整可编译的 .tex 文件，并给出编译命令建议 ## 规则 - 默认使用 XeLaTeX 编译，支持中文 - 图片统一放在 figures/ 目录，使用相对路径引用 - 引用文献使用 BibTeX，不手动编号 - 正文中禁止出现占位符样式文本，如 lorem ipsum - 输出代码块必须标注语言类型 latex

每一步都指向一个明确动作，模型照着做就不会偏太远。特别是“检查是否包含中文字符”这种步骤，它是基于实际经验补进去的——我早期生成的LaTeX文档，经常因为用了默认pdflatex导致中文乱码，后来在Skill里写明默认走XeLaTeX，问题才彻底消失。

3.3 resources目录：模板、示例、校验脚本

Skill和Prompt拉开差距的地方，主要就在resources目录上。这个目录里可以放模板、示例、脚本，它们共同组成一个“即拿即用”的工作包。

以LaTeX排版Skill为例，我的resources目录这样组织：

latex_document_builder/ ├── SKILL.md └── resources/ ├── templates/ │ ├── article_cn.tex │ ├── report_cn.tex │ └── beamer_cn.tex ├── examples/ │ └── sample_article.pdf └── scripts/ └── check_tex_syntax.py

templates里放的是已经通过编译验证的LaTeX模板，Agent可以直接复制使用。examples里放一个成品示例，让Agent对最终输出效果有直观参考。scripts里放一个简单的语法校验脚本，用来检查花括号是否配对、是否有未闭合的命令。

import sys from pathlib import Path def check_tex(path): tex = Path(path).read_text(encoding="utf-8") pairs = { "{": "}", "[": "]", "\\begin{": "\\end{", } # 简单统计花括号是否配对 left_braces = tex.count("{") right_braces = tex.count("}") print(f"左花括号数量: {left_braces}") print(f"右花括号数量: {right_braces}") if left_braces != right_braces: print("[警告] 花括号数量不匹配，请检查") sys.exit(1) else: print("[OK] 花括号数量匹配") if __name__ == "__main__": check_tex(sys.argv[1])

这里要注意一个关键细节：脚本路径在Skill里必须以相对路径或统一约定路径来引用。我见过不少Skill在本地工作，换台机器就报错，就是因为脚本里写了绝对路径，导致其他环境上根本无法加载。使用相对路径并约定好执行目录，才能保证Skill可迁移。

3.4 验证闭环：在真实Agent里跑一遍

写完Skill之后，最关键的一步是验证它能否被真实Agent正确加载和执行。很多新手写完SKILL.md就直接发布，结果在Agent里怎么调都不生效，问题往往出在路径放错、命名不一致、或者Frontmatter格式有误。

我个人的验证流程是这样：先把Skill放到对应平台的目录下，然后给Agent发送一个目标明确的测试任务，比如“帮我生成一份中文技术报告模板”。观察Agent是否主动调用了这个Skill，而不是凭默认知识硬写。确认调用后，检查输出结果里有没有按照SKILL.md里的规则走，比如是否使用了XeLaTeX、是否导入了ctex宏包、是否使用了BibTeX。

如果Agent没有调用，我一般优先检查description的表述。有些场景下，我会故意把测试任务描述得跟description里的触发词高度重合，来确认匹配机制本身没问题。这样一轮轮调试下来，基本一个下午就能把Skill调到可用的状态。

4. 几个已经被验证过“很能打”的Skills方向

4.1 前端开发Skills：从“会写”到“写得符合规范”

在社区里，前端开发Skills的热度一直很高。原因很直接：前端任务的“结果好不好”跟代码规范、组件结构、样式方案高度相关，这正好是Skills能发挥优势的地方。

我早期做前端任务时，经常遇到一个问题：Agent生成的React组件能跑，但风格跟团队代码库完全不一致。比如团队约定函数组件用箭头函数，它给我生成function声明；团队约定样式用CSS Modules，它给我写内联style。每一次都要在Prompt里补一大堆规则，效果还不稳定。

后来我把这些约定全部整理成一个前端开发Skill，放进CLAUDE_CODE或Codex的技能目录里。SKILL.md里写清楚组件的命名规则、样式方案、状态管理选型、hooks使用约束。resources里放两个团队已有的组件示例，作为范式参考。从那以后，Agent生成的前端代码，至少第一版就不会跑偏太多，修改成本大幅降低。

4.2 结构图与图片生成Skills：视觉输出的标准化

另一个我强烈推荐的方向是结构图Skill。你如果经常让Agent帮忙画架构图、流程图、系统拓扑，一定会遇到一个痛苦：同一个需求，不同时间点给Agent发，它可能给你生成Mermaid、PlantUML、ASCII Art三种完全不同格式的东西。直接后果就是后续处理非常麻烦。

做一个结构图Skills，核心任务就是锁定格式规范。在你的Skill里明确声明：默认使用Mermaid语法，节点命名使用驼峰或特定前缀，泳道按模块划分，颜色使用统一主题。这样Agent就不再需要“灵感发挥”，而是按照既定的结构框架输出。对团队协作来说，这个价值比话术优化大得多，因为输出直接可以被下游工具消费了。

图片生成Skill方向也类似。虽然底层模型能力很强，但在特定的业务场景里，往往需要固定风格、固定比例、固定提示词结构。做一个“图片生成Skill”，把提示词后缀、负面提示词、输出比例、风格关键词都预设好，生成的一致性会有肉眼可见的提升。

4.3 其他值得“抄作业”的社区热门Skills

GitHub上有不少高Star的Skills仓库，比如Superpower Skills和PowerBot系列的预置技能包。它们的Skills覆盖面很广，从代码审查到技术写作、从数据分析到项目管理都有。我建议新手不要自己闷头造轮子，先抄一批成熟的，看看别人的SKILL.md是怎么组织步骤的，description是怎么写的，资源文件是怎么安排的。

我刚开始学时，把一个成熟Skill的SKILL.md逐行读了一遍，最大的收获是发现了“防御性描述”的写法。好的Skill会在描述里写明“不适用场景”，还会在执行步骤里写清楚“如果遇到xxx情况，应该怎么做”。这种边界意识，正是新手Skills和资深Skills之间的分水岭。社区里还有一些针对Codex、Claude Code的专用Skills合集，直接拉到本地就能用，拿来做参考模板再好不过。

5. 主流平台Skills安装与使用手记

5.1 Claude Code Skills：几秒钟挂上

我主要使用的Agent环境之一就是Claude Code。它支持将Skills放在用户目录或项目目录下，启动时自动扫描。

# 用户级技能目录 mkdir -p ~/.claude/skills # 项目级技能目录（出现在项目根目录） mkdir -p .claude/skills

把Skill文件夹丢进这两个目录之一，重启Claude Code就能被识别。使用过程中，如果你不确定Skill有没有被加载，可以直接问Agent“你有哪些技能可用”，它通常会列出当前可用的Skills列表。如果没有出现，大概率是目录结构不对，或者SKILL.md的Frontmatter缺少必备字段。

实际操作中我还有个经验：在项目级目录里放的Skill，作用范围仅限于当前项目，适合做团队级规范；在用户级目录里放的Skill，对所有项目生效，适合放通用型的技能。这个区分看似不起眼，却能帮你避免“跨项目误触发”的尴尬。

5.2 Codex Skills与CodeBuddy：平台之间的微妙差异

Codex类的工具和CodeBuddy也支持Skills，基本目录结构类似，但细节上有些差异。在Codex中，Skills目录一般位于~/.codex/skills/，格式上同样要求每个Skill至少包含一个SKILL.md文件。

我在Codex上踩过的坑是：它对SKILL.md的Frontmatter字段要求更严格一些。如果description字段为空或者格式不规范，Codex不是“忽略”，而是直接报错，甚至可能导致Agent执行中断。而Claude Code对格式的容忍度相对高一些，最多就是Skill不生效，不会影响其他任务。

所以我在不同平台间迁移Skill时，会先做一个格式检查，确认name和description字段都存在且为合法YAML，再复制过去。平台差异是实际存在的，别指望一个Skill在哪儿都能“原样跑通”。

5.3 Superpower Skills与社区生态

Superpower Skills是当下社区里比较流行的一套技能包，它本身不是平台，而是一组可以直接导入Agent环境的高级Skills集合。安装方式通常是通过git clone或者下载release包，把Skills目录放到对应平台的技能目录下即可。

这套技能包的价值在于，它提供了很多“打磨过的”通用技能，比如高效代码审查、需求拆解、技术方案撰写等。我在导入之后，直接拿着它的几份SKILL.md当学习材料，比自己从零摸索快很多。另外它的Resources组织方式也很有借鉴意义，它不是简单堆模板，而是把示例、约束、输出格式都做了体系化设计。

这里要提示一下：从社区下载的Skills，安装前最好人工审查一遍里面的脚本内容。毕竟Skill本质上是可执行文件，里面的脚本拥有当前用户权限，盲目运行存在安全隐患。我在实战中会先打开每个Skill的resources/scripts目录，确认没有可疑操作，再决定是否启用。安全习惯要前置，尤其是跟Agent相关的执行链。

6. 常见报错排查与Skills测评方法

6.1 “agent execution terminated due to error”排查实录

在Agent开发过程中，最让人恼火的错误之一就是“agent execution terminated due to error”。这个报错信息很笼统，没有任何上下文帮你判断是哪里出了问题。我第一次遇到时真的是一头雾水，花了不少时间才整理出几类高频原因。

根据我的排查经验，常见的诱因有这么几类：

我遇到最典型的一次，是一个数据可视化Skill在本地验证没问题，但放到Codex环境就报“execution terminated”。排查到最后，发现原因特别低级：Skill的scripts目录下用了Node脚本，而运行环境里根本没安装Node。从那以后，我会在SKILL.md头部用“依赖环境”字段列明运行脚本所需的全部工具，避免Agent稀里糊涂走到一个跑不通的步骤。

6.2 如何判断一个Skills是真好用还是花架子

社区里Skills越来越多，质量也参差不齐。判断一个Skill是真好用还是花架子，我会用一套自己的“四维测试法”，这里分享给你。

第一，触发率。我准备50条与该Skill场景相符的任务描述，一条条喂给Agent，统计它自动调用这个Skill的比率。如果触发率低于80%，说明description写得有问题；要么太宽泛导致Agent拿不准，要么太狭窄导致很多场景漏掉。

第二，完成率。对所有成功触发的任务，逐一检查输出质量是否符合SKILL.md里的规则要求。如果输出经常偏离规范，说明正文步骤写得不够细致，或者缺少必要的约束条款。

第三，稳定性。拿同一个任务重复跑5次，看输出结构和内容差异有多大。如果每个版本都长得不一样，说明Skill的规范约束力太弱，模型还是在自由发挥。

第四，误触发。拿一批跟该Skill完全无关的任务去测，看它会不会被错误加载。误触发率过高会严重干扰Agent的主任务流程，这类Skill测试时就要被优化掉。

我在实际测评中还发现一个细节：好的Skill不仅能让Agent“按步骤走”，还能让Agent在边界情况下知道“不该做什么”。这种防御性设计，往往比一堆华丽的指令更体现真正水平。所以测评时我会有意考一些模糊的边界场景，看Skill能否稳妥处理，而不是把用户需求带偏。

最后再分享一个小技巧。写Skill的时候，别把它当成一次性交付的产物，而是当成一个持续迭代的资产。我每用完一个Skill，如果发现它输出了不符合预期的结果，会顺手打开SKILL.md，在对应的规则里追加一条新的约束。坚持迭代一个月之后，那个Skills的质量会明显高出同期其他技能一大截。这种“经验资产化”的积累方式，才是Agent Skills最值得你花时间投入的地方。