2025年当你在搜索框输入“skills”得到的早已不是简历上的特长列表。这个词在AI代理Agent生态里被重新定义了前端开发skills、论文写作skills、分镜skills、GitHub上的各类技能仓库……如果说大模型本身是一台有知识但缺经验的“新员工”skills就是往这个新员工手里塞的成套作业指导书和工具箱。这篇文章想把我这一年多在实际项目中积累的AI agent skills经验完整梳理一遍——它解决什么问题、目录结构怎么搭、如何从零开发一个能复现的技能、安装配置的完整路径、下载第三方技能时的安全底线以及技能装上却不生效时怎么排查。无论你是刚在命令行里跑通代理的新手还是已经想自建技能库的老手这篇都值得存下来。1. 为什么大家突然都在搜“skills”词义迁移背后的三个信号1.1 从“简历关键词”到“代理扩展包”的转变之前写技术方案时提到“skills”同事默认是指人的软技能、硬技能要花半天讲沟通能力、编程能力。到2025年AI代理的使用者在社区里默认这是指一类结构化文件一个带说明、带脚本、带参考资料的文件夹放进固定目录后代理就能在对应任务里自动调用它。这个转变背后其实是分工方式的变化。早期用大模型办事靠的是“提示词工程”——把步骤、例子、约束全部塞进一次对话里。这种方式有两个死穴一是上下文窗口再大也有限放不下厚重的格式规范和长参考表二是流程没法复用换个人、换个项目同样的经验又得重新口述一遍。Skills做的是把“经验”从“对话”里抽出来变成独立于模型、独立于会话的实体。同一个分镜技能今天给短视频团队用明天给长剧团队用核心逻辑不用重写只要微调参考文件。这种从“对话式约定”到“文件式契约”的转移就是词义迁移的本质。1.2 信号一主流代理开始把技能作为一等公民观察各家的更新日志会发现它们不约而同地给“技能”留了正式位置Claude生态里有以SKILL.md为核心的技能目录Codex生态里也有基于.agents/skills目录的技能规范GitHub甚至把“skills”做成了互动式学习课程平台。生态位如此一致说明这不是某家公司的自嗨而是行业对“如何让模型执行专业工作流”达成的初步共识模型负责理解与生成技能负责提供过程知识和工具文件系统负责承载。我个人判断这个共识的分量不亚于当年插件体系的出现。插件解决的是“模型能不能调用外部工具”技能解决的是“模型知不知道怎么把一个活儿干完”。前者是能力扩展后者是流程固化两者在工程实践里是一对互补关系。1.3 信号二追踪真实热搜词里隐藏的项目场景我在刷社区热词时看到“前端开发skills”“分镜skills下载”“codex写论文的skills”“skills大全”“skills安装包下载”“怎么引入这些技能”——这些不是孤立的提问而是一个完整的需求链路有人发现了好用的技能想下载下载完不知道怎么装装完不知道在哪里找更多找到一堆之后又不知道哪个靠谱。这条链路其实是所有新生态必经的“基础设施缺失期”。所以这篇不是一个单点教程而是一张完整地图。看完之后你既能自己动手造技能也能在别人的技能堆里快速挑出能用的、规避有风险的还能在技能不生效时按图索骥找到问题根源。1.4 一个直觉例子提示词和技能的真实差别举个最直观的对比。用提示词让模型写营销文案你大概会写“你是一个资深文案请为这款咖啡写三版小红书风格文案要包含卖点、场景、情绪词字数控制在100字左右。”这段话里包含的是“目标”和“大致要求”但模型对于你到底要什么格式、什么调性、什么禁忌词只能靠猜。如果用技能目录里会有一份完整规范包括卖点卡片的字段结构、历史爆款样本、广告法违禁词清单、发布前自检清单。模型被技能触发后不是“凭感觉写”而是“按规范执行”。一个是让实习生自由发挥一个是给实习生发SOP再加流程图产出稳定性和专业度完全不在一个量级。这就是为什么我强烈建议团队把高频任务技能化而不是继续靠复制粘贴长篇提示词。2. 技能包的标准骨架SKILL.md、脚本、引用一个都不能乱2.1 SKILL.md是入口不是摆设文档一个能够被代理正确识别和执行的技能通常是一个自包含目录。无论来自哪个生态核心结构大同小异my-skill/ ├── SKILL.md ├── scripts/ │ ├── convert_timestamp.py │ └── validate_output.py └── references/ ├── style_guide.md └── sample_outputs.json其中SKILL.md是最关键的文件它不是给人看的项目说明而是“代理运行时读取的操作手册”。开头的YAML元信息告诉代理“我是谁、什么时候该用我、我能调用哪些工具”正文则用结构化Markdown描述执行步骤、输出规范和自检要求。很多新手把SKILL.md写成宽泛的“你好我是一个技能”这是完全错误的——它不是欢迎页是启动引导。2.2 frontmatter里的“描述”是技能的命根子SKILL.md开头的metadata决定代理在什么情况下会看到这个技能。以我常用的写法为例--- name: storyboard-expert description: 根据短视频脚本生成分镜表适合8-12镜的口播、剧情、测评类视频。当用户提供脚本并要求拆镜头、写画面描述、估镜头时长时使用。也适用于将长文改写成可拍摄脚本。 ---为什么这段描述这么重要因为代理的任务识别机制通常基于语义匹配。如果你的description写得过于笼统比如只写“生成分镜”代理在处理“帮我把这个口播稿拆成镜头”时可能识别不到它如果写得太死板比如只写“仅处理抖音口播”遇到B站视频就会漏触发。最好的写法是包含“任务动词对象适用场景边界条件”让描述像一段微型检索索引。2.3 脚本和引用让技能真正“干体力活”SKILL.md负责“告诉模型怎么做”但有些事不该交给模型做也做不好。典型就是精确计算、格式校验、批量文件处理。比如分镜技能里要算“这镜头的结束时间”模型心算容易出偏差但一个10行的Python函数可以稳定输出。把这类逻辑放进scripts/目录SKILL.md里写明“计算镜头时长时调用scripts/convert_timestamp.py”技能就从“建议”变成了“可执行”。references/目录则是用来存放“知道但不必全部塞进上下文”的材料。大模型的上下文窗口是宝贵资源你不能让每个会话都加载一本五万字的行业规范。把规范、样本、格式模板放到references下SKILL.md中只写“需要参照B站口播分镜样本时读取references/sample_outputs.json”模型按需读取既不撑爆上下文又能保证调用时有据可依。这套设计本质上是在模仿人类专家的案头工具大脑处理问题手册提供标准脚本负责算数——各司其职。3. 现场做一个分镜技能从脚本格式到可复用工作流3.1 先摸清任务里的“格式规律”分镜这个场景既有创意属性又有强格式属性。一份能落地的分镜通常包含镜号、景别、画面内容、台词/旁白、字幕、时长、备注。短视频平台还有自己的节奏规律比如前3秒要抓人每8到12秒一个信息点。在做分镜技能之前我习惯先看已有的优秀样本把格式规律抽出来。比如我收集了三种常用分镜格式竖屏口播版、剧情叙事版、图文混排版然后把它们整理成references/样本文件。这一步很关键因为技能质量的上限在整理阶段就已经决定了——你给的参考越具体代理输出的稳定性越高。如果只是泛泛地让代理“生成专业分镜”它每次输出的结构可能都不一样你就得反复改。有了固定样本它每次都会照着骨架填充内容至少结构不会跑偏。3.2 把分步流程写进指令让模型按SOP执行SKILL.md的正文部分我通常按“输入处理—逐步执行—输出格式—自检清单”四段来组织。以下是我实际用过的分镜技能核心片段# 分镜生成流程 ## 第一步解析输入 - 若用户直接提供拍摄脚本提取其中可视觉化的动作与台词。 - 若用户只给主题先询问目标平台抖音/B站/微信视频号和时长要求 再生成一版200字左右的拍摄脚本。 ## 第二步拆分镜头 - 每个自然段落拆成1-2个镜头保证单镜头时长不超过8秒。 - 开篇镜头必须使用“中景快速信息”结构前3秒画面不得出现空镜。 ## 第三步填写镜头信息 - 景别使用远景、全景、中景、近景、特写五级。 - 画面内容需要写明主体动作不是写情绪。 - 字幕内容与台词完全一致不能缩写。 ## 第四步输出与自检 - 输出表格包含镜号、时长、景别、画面、台词/字幕、备注。 - 自检是否存在一句台词超过20字是否存在同一景别连续3镜 若有在备注栏标出“建议重拍角度”。写这类指令时我最深的体会是“把潜规则显式化”。比如“前3秒不得空镜”“单镜不超过8秒”这些在实际拍摄里是常识但如果不在指令里写明模型很容易生成节奏拖沓的设计。技能的价值就是把老师傅脑子里那些“不用说你也懂”的规矩变成“白纸黑字每一条都列出来”的标准——这样即使换一个完全不了解短视频的模型使用也能产出符合要求的稿子。3.3 用脚本补上模型最不擅长的运算活分镜技能还有一个典型需求把文字描述的字数换算成口播时长。中文口播大概每秒4到5个字模型在估算“这段60字的台词要多少秒”时经常算出离谱结果但在scripts/里放一个计算脚本就稳了#!/usr/bin/env python3 import sys def estimate_duration(text: str, speed: float 4.5) - float: # 中文按字符计英文按单词计 char_count len([c for c in text if not c.isspace()]) return round(char_count / speed, 1) if __name__ __main__: # 示例python estimate_duration.py 大家好欢迎收看本期视频 text sys.argv[1] if len(sys.argv) 1 else print(estimate_duration(text))然后在SKILL.md里写明“计算台词时长时调用python scripts/estimate_duration.py “台词文本”并据此倒推镜头秒数。”这一步让技能从“文案型工具”升级成了“带计算能力的生产工具”。我见过有人把字幕断句、敏感词检测、发布时间换算全写成脚本整个技能就像一条小型流水线。记住一个原则模型的任务是理解和生成内容脚本的任务是算准和执行校验混合使用才是最高效的形态。4. 把技能装进代理目录、市场与配置的完整地图4.1 用户级还是项目级两个安置位置技能装到哪直接影响它能服务的范围。以Claude Code这类工具为例常见有两种位置用户级目录一般在~/.claude/skills/和项目级目录一般在项目下的.claude/skills/。用户级相当于“全局插件”任何项目都能调用适合放通用技能比如论文润色、代码审查、会议纪要整理项目级相当于“项目专用工具”跟着仓库走适合放绑定了业务上下文的技能比如“本项目的发布检查清单”“针对本仓库的测试规范”。Codex生态的约定类似OpenAI开源的Agent Skills规范通常把技能放在.agents/skills/目录也有实现支持在用户主目录下放全局技能。我建议不要同时塞太多全局技能因为每次代理启动都要扫描技能目录技能过多不仅拖慢启动还会让任务匹配产生干扰。我的经验是全局技能控制在5到8个项目技能按实际需要增删保持目录干净。注意不同版本对技能路径的实现有细微差异装之前优先查看当前版本的官方说明别用旧博客里的路径生搬硬套。我见过不少“装不上”的案例最后发现只是目录位置差了一层。4.2 官方市场与社区仓库技能分发的主战场到了2025年技能的分发基本形成了几条渠道。第一是官方技能市场很多主流代理客户端集成了浏览和安装入口你可以直接在界面里搜索“分镜”“论文”“测试”等关键词一键安装。第二是GitHub等代码托管平台搜索“skills”可以看到大量开源技能仓库有的仓库甚至收录了几百个技能的分类清单。第三是社区分享链接热词里那些“skills下载平台”“skills大全”多半指向这类聚合页。我个人的使用偏好是“官方市场优先、开源仓库复核”。官方市场里的技能通常经过了基础审核质量相对稳定开源仓库里的技能数量多、更新快但良莠不齐需要自己把关。下载时还要看清技能的版本兼容性有些技能是为老版本设计的新版本的代理可能不识别它的配置格式装上后不生效是很常见的事。4.3 什么时候需要手动配置清单多数场景下把技能文件夹放进正确目录就能被自动发现但有些代理需要手动“登记”技能比如在配置文件里增加一条路径或者用斜杠命令导入。如果你装好技能后代理对话里始终没有相关反应不要急着怀疑技能文件坏了先确认两件事第一技能目录是否在代理的扫描范围内第二是否需要手动执行“刷新技能列表”之类的操作。还有一类特殊情况是技能间的依赖。有些技能会引用其他技能的脚本或者要求特定版本的解释器/ffmpeg等外部工具。这类信息一般写在技能README里。我强烈建议下载后先打开README看一眼而不是直接用因为很多“技能装了没用”的问题就出在遗漏了依赖环境的配置。5. 从市场下载技能的安全底线与质量筛选5.1 技能的本质是可执行代码不是纯文档很多新手把技能当成“高级提示词”觉得下载了就是读一读的事。这是最大的误解。技能目录里的scripts/是实实在在的代码SKILL.md里的指令也可能让模型去执行终端命令、修改文件、调用网络接口。换句话说加载一个第三方技能约等于在你的开发环境里运行了一份不熟悉的代码。我对所有用第三方技能的朋友只有一个底线建议先审查再安装。不要因为一个技能在热词里很火就直接用。这和当年装npm包、装浏览器插件的道理一样——工具虽然方便但入口一旦放行能做的事就太多了。5.2 下载前的“三看”原则具体筛选时我常用三看原则。一看目录结构。一个正经技能通常只有SKILL.md、scripts、references、README这几个组成部分。如果发现异常庞大的二进制文件、被加密的脚本、明显与技能功能无关的隐藏文件直接放弃。二看脚本内容。打开scripts/里每个文件不需要懂得所有语法只看它到底在做什么操作。重点警惕有没有访问网络的操作、有没有删除或修改系统文件的操作、有没有把数据发送到外部服务器的代码。分镜技能里出现一个往远端传文件的脚本这绝对不正常。三看描述与行为是否一致。SKILL.md里写的功能和脚本实际干的事必须对得上。如果描述写着“字数估算”脚本里却在读写浏览器数据那就是伪装。实操建议无论多信任的来源第一次运行技能前最好在隔离环境或普通用户权限下执行不要用管理员权限直接跑。曾经有同事开箱即用了一个“效率增强”技能结果它自动改了代理配置折腾了大半天才恢复。不是所有技能都怀有恶意但未经审查的代码永远存在失控可能。5.3 如何判断技能的整体质量安全之外技能质量也有迹可循。我会看三个信号更新活跃度、单元示例、使用者反馈。一个技能如果半年没更新很可能已经和当前版本脱节如果自带测试示例说明作者至少做过验证如果使用者在评论里反馈了具体的场景效果比单纯的“好用”更有参考价值。还有一点技能描述里的承诺越夸张越要冷静。例如“一键生成完整院线级分镜”“零配置搞定一切XX”这类宣传通常意味着作者把复杂问题过度简化了。真正的生产级技能反而会在描述里写清楚适用范围和需要的人工介入点比如“适用于8-12镜短内容复杂剧情需要人工调整”。面对五花八门的下载平台我最后会优先选择有明确作者维护、能追溯到提交记录的仓库而不是网盘里流传的“打包全家桶”。6. 技能装了不会用agent skills测试的完整排查路径6.1 先分清“没被发现”和“被发现了但没调用”技能装完不生效是我在社群答疑里遇到最高频的问题。其实绝大多数情况不是技能坏了而是代理压根没把它当成可选项。排查第一步确认技能是否被代理扫描到。不同客户端通常都有一个列技能的功能Claude Code里一般是斜杠命令Codex生态里也有相应的列表指令。如果在列表里能看到技能名说明“加载成功”如果看不到先检查目录位置是否正确、文件命名是否为SKILL.md——注意大小写很多系统对文件名是敏感的。列表里能看到但对话中怎么都不触发这就是第二个层次的问题发现机制失效。代理是靠SKILL.md里的description做语义匹配的如果描述里写的关键词和用户实际表达的句式对不上技能就永远躺在列表里模型完全不碰它。6.2 描述性触发词审查最容易踩的坑我调试过的一个“论文润色技能”用户怎么问都不生效。技能描述写的是“适用于学术文本的语法修正与表达优化”听起来没毛病但用户的实际表达是“帮我把这段摘要改得像人写的”“我导师说这段写得不行”这类口语化请求。模型把“改得像人写的”和“学术润色”匹配上的概率并不高。解决方法是大量堆叠同义触发词和边界说明。把描述改成“适用于学术论文、摘要、会议报告的中文英文润色。包括语法修正、句式优化、语气调整、学术风格规范化。当用户说改摘要、润色段落、提升论文语言质量、让表达更学术时使用。不适用于日常口语文本的改写。”描述越贴着真实用户语言触发率越高。建议在写skill或修skill时做一次“冷启动测试”拿一个完全没看过技能内容的对话自然地问一句任务看代理是否会主动使用技能。如果三次都不触发说明描述和用户语言之间有断层优先改description而不是改正文指令。6.3 用最小化测试台拆问题当技能被触发了但执行结果不对这就进入第三层运行行为异常。我建议这时候不要直接在大任务里调试而是建一个最小复现测试台。把SKILL.md的正文简化成“只调用某个脚本并输出运行结果”先确认脚本单独执行是否正常。举个例子分镜技能一直报错我就把SKILL.md改成一个只做“用scripts/estimate_duration.py计算时长”的最小版丢给代理跑。结果发现脚本能独立运行问题出在SKILL.md里写命令时拼错了参数顺序。这就把问题从“扑朔迷离”缩小到了“命令行参数”。一个完整的技能测试流程我通常分四步走一是冷启动触发测试二是简化脚本调用测试三是全量流程测试四是换不同模型/代理实测。前两步能筛掉八成问题第三步验证流程完整性第四步确认兼容性。这套流程虽然听着繁琐但一旦你打算把技能放进生产环境前期的测试时间远比后期反复救火划算。6.4 关于“agent skills测试”的补充看法搜索热词里有个“agent skills测试”这其实已经是不少团队的正式工作项了。我给的建议是把技能测试当作代码测试一样对待给技能建一个独立测试目录里面放输入样例、期望输出、边界场景每次修改技能后跑一遍回归至少确保原有功能没有退化。技能是活的东西会随项目需求变化持续演进没有测试保护的技能改着改着就可能废掉。我自己会为高频技能写一页“测试记录”包含触发问题样例、预期行为、实际行为、修改时间。这个习惯帮我避免过不少“上次还能用改了一版就不行了”的尴尬。听起来很占时间但这一页纸在长期维护里的价值远超投入。7. 攒了技能库之后的几句实话从第一次把提示词塞进SKILL.md到如今手头攒了十几个稳定运行的技能我最大的体会是做好技能功夫在“整理”不在“写”。你花时间梳理的最优工作流、沉淀的格式规范、积累的避坑要点才是技能的真正价值脚本和Markdown只是把它们封装成机器可读的载体。反过来说如果某个任务连你自己都没有一套稳定流程就不要急着把它技能化否则封装的只是混乱。另一个体会是不要迷信“技能越多越好”。我最初也像囤资料一样囤了几十个技能结果代理扫描变慢、触发混乱、维护负担直线上升。后来我学会做减法只保留每周至少用一次、且流程已被验证稳定的技能把低频但必要的技能变成“按需安装”用时再装。如果你读完只带走一个行动项我建议是挑一个你团队里每周都会重复、却总靠口头交代格式的任务花一下午把它整理成一个最小技能。不用追求一步到位先从“能跑起来”开始然后在一周的真实使用中迭代指令细节。当你看到代理第一次按照你的职业标准稳稳当当交出成果时就会明白这几个月围绕“skills”的热度到底在热什么。