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.pySKILL.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 取名与descriptionAgent认不认你全靠这两行很多人写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.pytemplates里放的是已经通过编译验证的LaTeX模板Agent可以直接复制使用。examples里放一个成品示例让Agent对最终输出效果有直观参考。scripts里放一个简单的语法校验脚本用来检查花括号是否配对、是否有未闭合的命令。import sys from pathlib import Path def check_tex(path): tex Path(path).read_text(encodingutf-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 其他值得“抄作业”的社区热门SkillsGitHub上有不少高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后立即报错SKILL.md Frontmatter格式错误检查YAML字段是否有误只在使用某个特定Skill时报错Skill文件路径错误/资源缺失确认resources目录和相对路径长时间任务中途终止上下文窗口满了精简SKILL.md减少冗余示例执行到脚本步骤报错脚本依赖的CLI工具未安装在Skill环境说明中列明依赖所有任务都报错Harness配置问题检查工具调用循环和模型API配置我遇到最典型的一次是一个数据可视化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测试时就要被优化掉。测试维度测试方式我的基准线触发率50条相关任务统计自动调用比例不低于80%完成率调用后人工评估输出质量不低于90%稳定性同一任务重复5次输出结构基本一致误触发用无关任务验证不高于5%我在实际测评中还发现一个细节好的Skill不仅能让Agent“按步骤走”还能让Agent在边界情况下知道“不该做什么”。这种防御性设计往往比一堆华丽的指令更体现真正水平。所以测评时我会有意考一些模糊的边界场景看Skill能否稳妥处理而不是把用户需求带偏。最后再分享一个小技巧。写Skill的时候别把它当成一次性交付的产物而是当成一个持续迭代的资产。我每用完一个Skill如果发现它输出了不符合预期的结果会顺手打开SKILL.md在对应的规则里追加一条新的约束。坚持迭代一个月之后那个Skills的质量会明显高出同期其他技能一大截。这种“经验资产化”的积累方式才是Agent Skills最值得你花时间投入的地方。