Agent Skills实战指南：从Prompt到可复用技能包

1. Skills到底补上了Prompt的哪块短板1.1 提示词工程的终点正是技能的起点如果你最近和我一样被“skills”这个词刷屏——从Claude Code到Codex从GitHub上的superpower skills到各种skills推荐帖——很容易产生一个困惑这东西和写prompt有什么区别我不就是在对话里多描述几句需求吗说实话我以前也是这么想的。直到我连续折腾了大概半个月的Agent工作流把同一个代码审查任务在三种工具里反复跑才意识到根本差别在哪prompt是一次性指令而skill是一套可复用的操作手册。想象一下你让一个新同事“去把线上项目的代码质量看一下”。他可能会愣住看什么怎么看标准是什么输出什么格式于是你得从头解释一遍。可如果是给一份写好的SOP里面有步骤、有检查项、有验收标准、还配了一个统计脚本他上手就能干活而且每次干出来的活质量都稳定。Skills干的就是这件事。它把完成某类任务的完整方法——指令、脚本、参考资料、输出规范——打包成一个可命名的“技能单位”。大模型Agent不再需要你每次重复灌注背景它自己会根据任务描述去检索并加载对应的技能。1.2 为什么现在才火起来这个思路其实很早就有人提过但真正形成生态是最近大模型Agent工具集体发力后的结果。以前我们写提示词是把“如何做”一股脑塞进上下文窗口里。可窗口越塞越满有效信息反而被稀释。而且提示词的复用性极差——换个项目、换台机器、换个会话全部归零又得重新写一遍。Agent普及之后问题更明显了。一个Agent要执行复杂任务光靠对话式引导根本稳不住。它会忘、会偏、会在某一步自作主张。于是各家开始把“稳定的执行逻辑”从对话中抽出来做成独立的技能文件。Anthropic在前段时间公开了Agent Skills的格式约定后续OpenAI的Codex、社区里的opencode等工具也快速跟进。整个链条就通了定义一个标准格式让技能可以跨会话、跨项目、甚至跨工具复用。1.3 一个技能包到底改变了什么改变最直观的一点能力沉淀。以前我积累的“干活经验”全在聊天记录里散落各处无法系统调用。现在我把它们整理成一个个skill比如“前端代码审查”“项目结构分析”“数据库索引诊断”——每个skill里有明确的步骤、检查清单和配套脚本。Agent需要哪个就自动加载哪个。命令也从原来的长篇提示词变成了一句极短的话npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y一行命令装好一套视频生成技能包agent立刻会用了。这就是skills带来的实际体感变化从“教它做”变成“给它装好能力”。2. 拆开一个Skill看内部结构2.1 标准目录布局不管是大模型厂商官方的Agent Skills还是GitHub上各种coding skills仓库核心结构基本是一致的。一个标准的skill目录长这样my-skill/ ├── SKILL.md ├── scripts/ │ └── analyze.py └── resources/ └── templates/别被这结构吓到实际上核心只有一个文件SKILL.md。这就是技能的“大脑”所有让Agent理解“何时调用、怎么执行”的信息都写在这一个文件里。scripts/目录放的是可执行脚本处理那些纯文本指令搞不定的活儿——比如统计代码行数、扫描依赖版本、解析JSON数据。resources/目录放的是静态参考资料和模板比如代码风格规范、报告模板。如果说SKILL.md是操作手册那scripts/就是工具箱resources/是资料库。三样东西凑齐一个技能才算真正完整。2.2 frontmatter与description的艺术打开SKILL.md最上面是一段YAML格式的元信息这是Agent判断“什么时候该用这个技能”的关键--- name: frontend-review description: 用于前端项目代码审查分析组件设计、状态管理、样式规范等问题输出结构化审查报告。当用户要求审查前端代码、检查React/Vue项目质量或做Code Review时使用。 ---很多人在写description时容易犯一个错误写得太虚。比如写“这是一个强大的前端审查技能”Agent看了毫无感觉。它不知道什么时候该触发你。你要把触发场景写进description里——用户说什么话、面对什么类型任务时这个技能最合适。这样Agent才能在合适的时机把它加载出来。从我实测的经验看description写得越具体技能被正确调用的概率越高。这一条直接决定了你的skill是“装了等于没装”还是“一钓一个准”。2.3 SKILL.md正文的写法要点frontmatter下面是正文这部分是Agent执行任务的“剧本”。和想象中不同正文不应该是大段的散文描述而应该是步骤化的操作指令。我总结过一套比较稳妥的写法先写目标用两三句话说清这个技能要达成什么结果。再写执行步骤把任务拆成原子步骤每一步都写清楚“做什么、怎么做、做到什么程度算完成”。附上验收清单任务完成后必须逐条核对防止Agent漏步骤。标注边界哪些情况不该用这个技能、哪些数据源不可信、哪些操作需要人工确认。这就像给Agent一份“作业要求评分标准”。有评分标准在它输出的结果才稳定不会自由发挥。2.4 scripts与resources为什么Skill需要“手脚”纯文本指令最大的问题是大模型的输出有随机性。让它“统计一下项目里每个目录的文件数量”它可能真的会去数但更可能说出一串差不多的数字。这时候就需要脚本兜底。我习惯在skill里放一个Python脚本用确定性的代码完成统计、解析、校验这类工作然后把结构化结果交给Agent去分析和呈现。脚本输出格式要稳定最好是JSON或固定字段的文本这样Agent才能准确读取。resources/目录则适合放那些“每次执行都要参考但不该写进正文”的内容比如一个项目的编码规范、一份报告模板。正文里只需要写一句“读取resources/templates/下的报告模板并填充”既节省了上下文又保持了流程清晰。3. 从Claude Code到Codex主流Agent的Skills挂载方式3.1 Claude Code目录即技能目前生态最完整的当属Claude Code。它的skills挂载逻辑很直观一个目录就是一个技能。全局技能放在~/.claude/skills/下对所有项目生效项目级技能放在.claude/skills/下只对当前仓库生效。你把包含SKILL.md的目录丢进去重启Claude Code技能就注册成功了。除了目录挂载还可以在CLAUDE.md里用路径的方式直接引用某个技能目录。这种方式适合那种“只在特定项目里临时用一下”的技能不需要复制到全局目录整个项目团队共享一份配置谁clone下来都能用。3.2 一行命令安装远程技能包现在社区里最流行的安装方式是npx skills add。以文章开头那条命令为例npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y各项参数的作用参数含义sandai-org/vidmuse-skillsGitHub仓库路径指定要安装的技能包--agent claude-code目标Agent类型工具会按对应格式安装-g全局安装不加这个默认装到当前项目-y跳过交互确认自动化场景必备这个命令背后做的事情很简单拉取GitHub仓库解析里面的技能目录复制到目标Agent的技能目录下。原理不复杂但把这层封装出来之后安装门槛确实低了很多。很多人问“npx skills怎么源码安装skill”其实核心就是两条git clone下来然后把技能目录复制到对应的skills目录。有install.sh或者Makefile的仓库优先按仓库说明操作没有就直接手拷。3.3 Codex与opencode的Skills形态OpenAI Codex对skills的处理方式稍有不同它更倾向于用一个skills.md文件把一组技能集中管理起来每个技能以Markdown卡片的形式声明。好处是文件数量少、便于阅读坏处是复杂技能的可执行脚本不太好塞进去。opencode这类社区Agent走的则是Claude Code类似的“目录即技能”路线。社区里已经有不少针对opencode设计的skills集合本质上和Claude Code的技能包没有太大区别只是安装时指定的--agent参数不同。给个对比表快速理解Agent技能存放位置安装方式复杂技能支持Claude Code~/.claude/skills/或.claude/skills/目录复制 / npx skills add脚本资源完整支持Codexskills.md集中文件直接编辑文件以指令为主脚本支持有限opencode技能目录目录复制 / npx skills add脚本资源完整支持选哪个工具不重要重要的是理解一个共同点skills的本质都是“结构化目录说明文件”理解了这个哪个工具都能上手。4. 社区热门的Skills包长什么样4.1 Superpowers把工程方法打包最近社区里讨论度很高的一组技能包是Superpowerssuperpower skills。它的思路很有意思不只是解决单个任务而是把一整套软件工程方法论打包进技能里。比如它会定义一个“编码前先拆解任务”的技能Agent在执行开发任务前先输出任务拆解清单逐条确认后再动手。还会定义“写代码后必须自查”的技能让Agent对自己生成的内容做一轮审查减少低级错误。这种“方法论型技能包”最大的价值不是解决了某个具体问题而是改变了Agent的工作习惯。很多人装完Superpowers后体感“Agent变聪明了”其实是工作流程被流程化、被约束了。4.2 前端与编码类Skills开发者日常最需要的就是编码类技能。前端开发skills是其中最热门的品类。典型的技能内容包括分析项目的依赖版本和兼容性、审查组件拆分是否合理、检查状态管理方案是否合适、定位样式覆盖问题等。拿我见过的一个前端审查技能来说它的SKILL.md里写清楚了审查顺序先看依赖配置文件再看组件结构最后看状态管理和样式。每一步都有对应的检查项比如“Hooks是否按规范放在组件顶部”“样式是否使用了硬编码像素值”。Agent照单执行下来产出的审查报告质量相当稳定。如果你平时用TypeScript比较多关注一下Matt Pocock开的那个skills集合它把TS类型体操、泛型设计那些容易出错的点做成了检查清单技能挂在Codex或者Claude Code里都合适。4.3 垂直应用型Skills视频、数学建模、安全研究除了编码类垂直领域的技能包也在快速丰富。视频生成方向的vidmuse-skills是典型代表它把分镜设计、提示词组织、素材整理这一套流程封装成技能前文那条npx skills add命令装的就是这类技能。数学建模skills在竞赛群体里很受欢迎。它通常涵盖三块选题分析、模型选型建议、论文结构模板。Agent拿到赛题后会自动按技能里的流程走一遍先拆解问题类型再推荐可用的数学模型最后生成带有标准章节的报告框架。还有安全研究方向的技能包做渗透测试相关工作的朋友会关注。需要强调一句这类技能包的使用场景应该是授权范围内的安全评估和教学研究任何时候都不应该被用于未授权的测试。4.4 怎么从一堆Skills里选出靠谱的GitHub上技能包越来越多挑选时我一般看四个维度维度怎么判断仓库活跃度最近是否有commit、是否有issue回复description质量触发场景写得是否具体还是泛泛而谈脚本完整度是否包含可执行脚本还是纯文本描述文档覆盖有没有安装说明、示例输出、维护记录一个连README都写不清楚的技能包里面的SKILL.md大概率也写不好。反过来如果一个技能包的示例输出很清晰、还有维护日志那这个作者多半是真的在用的可信度就高很多。5. 从零开发一个自己的Skill5.1 需求定义选一个“你重复最多”的任务不要一上来就想着做一套“万能技能包”没有意义。最值得做的是你自己工作中重复次数最多的那件事。我做的第一个技能是“项目代码结构分析”。起因是我经常要接手不熟悉的老项目每次都要花时间梳理目录、找入口文件、定位模块关系。这活重复、机械、又有固定套路非常适合技能化。需求定义阶段我列了几个问题这个任务的输入是什么项目路径、目标目录输出是什么一份结构说明文档中间步骤有哪些列目录、读配置文件、找入口、分析依赖哪些环节需要脚本辅助文件统计、依赖解析这四个问题想清楚技能的骨架基本就出来了。5.2 写入SKILL.md让Agent一眼看懂何时调用我的SKILL.md长这样--- name: project-structure-analysis description: 分析一个项目或目录的整体结构识别技术栈、入口文件、模块划分和依赖关系。当用户要求分析项目结构、快速了解代码库、接手新项目时使用。 ---正文部分我按照“目标-步骤-验收-边界”四段式组织。特别注意把步骤写成原子化的操作使用scripts/scan_tree.py递归扫描目标目录获取文件和目录树。读取package.json / requirements.txt / go.mod 等清单文件识别技术栈。根据技术栈定位入口文件如src/main.tsx、src/index.py。输出包含目录结构、技术栈、入口说明、模块列表的Markdown文档。每一条后面都补充了判断标准。比如“入口文件如何确定”“模块边界怎么划分”这些琐碎但关键的细节正是Agent最容易出错的地方。5.3 编写辅助脚本稳定输出比聪明更重要脚本部分的经验是不要让脚本做复杂判断让它做确定性输出。我写的扫描脚本只干两件事递归列目录、提取关键配置文件的信息。输出固定为JSON结构#!/usr/bin/env python3 扫描项目目录结构输出JSON格式的树形结构 import json import os import sys def scan_directory(path): result { name: os.path.basename(path) or path, type: directory, children: [] } try: for entry in sorted(os.listdir(path)): if entry.startswith((., node_modules, dist)): continue full_path os.path.join(path, entry) if os.path.isdir(full_path): result[children].append(scan_directory(full_path)) else: result[children].append({name: entry, type: file}) except PermissionError: pass return result if __name__ __main__: if len(sys.argv) 2: print(json.dumps({error: 需要提供扫描路径}, ensure_asciiFalse)) sys.exit(1) print(json.dumps(scan_directory(sys.argv[1]), ensure_asciiFalse, indent2))这里有几个细节是踩过坑之后才加上的忽略常见目录防止node_modules把JSON撑爆。输出必须ensure_asciiFalse避免中文路径变成乱码。请求失败时输出error字段并设置非零退出码Agent能感知到异常并决定是否需要人工介入。脚本不追求面面俱到能把Agent最不擅长的、最需要确定性的部分扛住就已经完成了使命。5.4 本地测试与版本迭代技能写完不要急着发布。先在自己常用的Agent里跑几轮真实任务。第一轮测试我踩了个很典型的坑Agent调用了技能但完全没执行脚本直接自己读完SKILL.md就开始“分析”输出结果当然漏洞百出。原因出在SKILL.md里“使用scripts/scan_tree.py”这句话写得太温和。Agent认为这是可选项。改成“第一步必须执行scripts/scan_tree.py如不执行则任务失败”效果立刻好了。这也验证了一个原则skills的正文要用强制性语言描述必须步骤把“可做可不做”的空间尽量压缩。技能的价值恰恰在于“稳定”而不是“灵活”。6. 开发与调优过程中踩过的坑6.1 装完不生效完整排查链路这是最常见的坑排除思路有固定套路。我总结成一条链路1. 检查目录位置是否放对。Claude Code认~/.claude/skills/和.claude/skills/放错位置等于没装。Codex则是编辑skills.md文件。每个工具认的位置不一样先去看对应文档。2. 检查目录结构是否完整。技能目录下必须有一级SKILL.md文件这个文件没写对其他东西都白搭。3. 检查frontmatter格式。YAML解析失败时整个skill会被忽略。尤其注意description不能换行缩进要用空格不要用Tab。4. 重启Agent会话。大部分工具的技能列表是在会话启动时加载的装完不重启自然不生效。5. 验证description是否触发。用测试语句直接试探“请使用xxx技能”。如果直接点名能触发、自然描述不触发说明description写得不够“像用户说话”。这条链路走一遍90%“装完不生效”的问题都能定位。6.2 Agent调用了Skill却“答非所问”如果说“不生效”是第一大坑第二大坑就是“生效了但效果不理想”。我之前写过一个“数据库索引诊断”技能步骤写得也算清楚但Agent执行结果总是偏离目标该看执行计划不看该测索引不测。后来逐个环节对比发现问题出在正文结构上我把很多背景知识写在了步骤前面Agent读了一大段背景反而模糊了重点输出。调整方案是文章最顶上用一句话写明“最终输出是一份诊断报告包含xx、xx、xx三部分”。步骤按“采集信息→执行分析→生成结论→输出报告”四段组织。每步末尾标注前置条件和完成标准。把“最终要交什么”放在最前面Agent在执行过程中的每一步都会朝着这个终点靠拢。这是优化效果最明显的一次调整。6.3 脚本与环境问题timeout、路径与退出码技能脚本出问题比正文更隐蔽因为报错信息不一定反馈得出来。我遇到过的典型情况问题表现解决方式脚本执行超时Agent在等脚本结果死等脚本内部设置超时或者自查循环次数硬编码路径换台机器就报找不到文件统一用相对路径把根目录作为参数传入退出码不设置脚本报错但Agent认为成功正常退出返回0异常返回非0并输出stderr有一回我在技能脚本里硬编码了一个Windows风格路径当场没问题过了几天在另一台部署环境上跑就报错。这个教训让我定了条规矩技能脚本里不允许出现任何绝对路径涉及路径的参数一律从命令参数传入。6.4 上下文与性能权衡最后说一个容易被忽略的问题——技能太多、正文太长。每个技能平时并不会全部加载进上下文Agent是根据任务描述动态调用的。但一旦被调用该技能的全部正文和资源说明都会占住上下文窗口。如果某个技能正文有上万字一次调用就吃掉大量上下文空间影响Agent后续推理质量。我的优化思路SKILL.md正文只放执行流程和验收标准。需要详细参考的内容丢进resources/目录正文里写“读取resources/xx文件获取详细规则”。description里主动提示“本技能会调用外部脚本需要较长上下文”让使用者有预期。还有一个小技巧给正文按模块拆分让Agent只在需要时读取具体模块而不是一股脑加载全文。7. Skills和Prompts的关系会怎么走7.1 社区正在讨论什么最近看到不少关于“rethinking skills and prompts”的讨论甚至有人开始琢磨下一代模型该怎么把skills做进模型层。讨论核心绕不开一个问题skills会不会取代prompts我的理解是不会取代但分工会更清晰。Prompts负责的是这一次对话的意图它灵活、即时、随用随抛Skills负责的是一类任务的执行方法论它稳定、可复用、有版本。两者本质上是不同粒度的东西。7.2 我的判断分工而不是替代一个技能内部其实也离不开prompt——SKILL.md本身就是一段高度结构化的prompt技能脚本文本、资源说明本质上也是prompt的一部分。Skills真正改变的是prompt的组织和传递方式。它让原本散落在对话里的任务执行知识变成可以独立维护、安装、升级的模块。这就好比一个厨师以前手里攥着一堆菜谱便签prompt现在把常用菜的做法整理成了一本标准化菜谱库skills便签还在用但核心做法沉淀进了菜谱。该手写笔记的时候还是写但一日三餐的稳定性靠谱多了。7.3 给新手的行动建议如果你也想把skills用起来我的建议是从“抄”开始。先去GitHub找几个热门技能包装上跑体会再从你重复度最高的任务里挑一个照着前文的目录结构写个最简版本。不用追求完美先让Agent能稳定执行再逐步往里加细节。我的体会是技能库和代码库一样需要持续维护。经常用的技能会越来越好用不用的技能要及时删除否则它会在Agent上下文里占着位置还可能造成误调用。我现在的日常已经离不开自己的技能库了。接手新项目、做代码审查、理清依赖关系都是直接让Agent调用对应skill效果比之前反复写prompt稳定太多。这套东西还在快速演进但核心方法论不会变把你要重复做的事情沉淀成可复用的能力然后交给Agent去执行。这件事越早做后面的累积效应越明显。