最近和一个做前端的朋友吃饭聊着聊着他就掏出电脑给我演示同一个AI助手平时就是个话痨聊天框但装上一个叫前端审查的技能包之后让它看一个项目页面它居然能按照W3C语义化规范、Lighthouse性能指标、团队代码规范逐项输出检查报告连截图都自己拍了。他跟我说了句让我印象很深的话——这玩意儿才是AI真正开始像员工而不是工具的分水岭。这个技能包就是今天要聊的Skills。简单说Skills是一份结构化的能力模块装进Claude、Codex这类智能体之后AI会在合适的任务场景中自动调用这套模块用你定义好的流程、规范、脚本去完成任务。它能解决的核心问题是通用AI很强但不够听话、不懂行业里的专业流程、每次输出的质量也不稳定Skills恰好补上了这一课。这篇文章的内容不是一份产品说明书而是我从看到别人分享Skills到自己动手开发、再给团队落地的完整记录。我会先把Skills是什么、怎么运作讲清楚然后介绍现在主流的生态资源和下载渠道再给出一套可以直接抄作业的开发流程最后把实践里踩过的坑和排查经验整理成速查表。适合所有想真正动手用AI干活的人——不管是写代码、写文案、做设计还是搞研究的都能从这里找到用得上的部分。1. Skills是什么Agent的专业执照1.1 从手机App类比讲起先给完全没接触过的朋友说一个最直白的理解。手里的AI智能体本质上像一台刚开箱的智能手机系统很流畅、算力很猛、什么都能干一点但出厂时并没有预装那些真正让你离不开它的App。你让它帮我做个晚饭它大概率会背出两百道菜谱但不会真的按照你家冰箱里还剩什么、你有什么忌口、今晚要控制在多少预算给你排出一份能直接执行的三菜一汤计划。Skills就是给这台手机安装的专精App。装上一个家庭晚餐规划技能AI在听到今天晚饭吃什么的时候会走一套固定流程先确认冰箱剩余食材、再询问忌口和用餐时间、接着按营养和预算约束生成菜谱、最后输出采购清单和烹饪顺序。它不再天马行空地聊而是按流程做。放到开发场景里也是一回事。前端工程师装上一个代码审查SkillAI就不只是简单地看看这段代码有什么问题。它会先读取项目技术栈、找到lint配置、执行一遍测试命令再按你团队规定的打分卡逐项输出审查结论。Skills的本质就是把一个具体岗位的最优工作流程变成AI随时能调用的肌肉记忆。1.2 它到底解决了什么问题第一类问题是专业知识的工程化复用。以前大家也靠Prompt让AI干活但Prompt是一次性的——每次都要重新写写长了容易漏写短了AI抓不住重点团队里也没法共享。Skills做成标准化的包之后结构固定、描述清晰、可以版本管理、可以分发给团队里的每一个人。同样一份审查标准不用每次复制粘贴几十行字装一次所有人随时能用。第二类问题是输出稳定性。用过AI的人都有体会同一个问题今天问和明天问结果经常不一样这种随机性在生产环境里是很头疼的。Skills把执行过程拆成明确的步骤序列和判定条件AI的自由发挥空间被压缩到合理范围内。就好比连锁店的汉堡为什么全球一个味道——不是因为厨子稳定而是因为操作手册写得足够细致。第三类问题是和外部系统的连接。Skills可以内置脚本和命令调用逻辑让AI不只会输出文字还能真正动手执行——跑测试、改文件、调接口、处理数据。它是把AI从顾问变成执行者的关键一环。1.3 和MCP、Prompt、Function Calling到底怎么区分这是我被问得最多的问题也是很多人装了Skills却不生效的根源——概念混淆。我直接用一张表说明。维度PromptFunction CallingMCPSkills本质一段输入文本模型输出的结构化调用指令工具互联协议可复用的能力包粒度一次对话一次调用系统级连接流程级封装典型例子帮我写一个正则模型决定调用search()连接数据库、浏览器等完整的SEO文章写作流程复用性低中高高维护成本低中较高中一句话版总结MCP解决的是AI的手和眼睛——它能操作什么外部工具Skills解决的是AI的工作方法和经验——它知道一个任务应该按什么步骤做才算专业。两者是互补关系不是替代关系。你的Skill里完全可以写着先通过MCP调用浏览器工具抓取页面再执行后续分析步骤。很多教程喜欢把它们混在一起讲实际用起来你会发现分工非常清楚。MCP更像管道负责连接Skills更像SOP手册负责流程。1.4 为什么这波Skills热潮发生在现在Skills这个东西的原理并不复杂但为什么2025年前后才集中爆发我理解有几个前提条件终于凑齐了。第一模型上下文窗口大幅扩容。Skill触发时要把SKILL.md和辅助材料注入上下文早期模型上下文只有几K token塞一份操作手册再加一份脚本输出就满了根本玩不转。现在大上下文成了标配注入一整个技能包压力小很多。第二Agent执行能力成熟了。让AI读完流程再执行这件事需要模型具备稳定的多步推理能力还要有可靠的工具调用基础。这两年在Claude和Codex上已经相对成熟Skills才从玩具变成生产力工具。第三行业需要可复现的专家经验。大家逐渐发现大模型博学但每个行业真正的竞争力恰恰是那些老师傅知道、文档里没有的工作流程。Skills提供了一种把这些经验编码下来、标准化分发的方式。2. 拆解Skills的运行原理从触发到执行的完整链路2.1 一次Skills调用是怎么发生的以Claude Agent Skills为例Codex的机制类似只是路径和格式略有差异一个技能就是一个目录目录里必须有SKILL.md文件。当用户和模型对话时客户端会把当前对话上下文和所有已安装技能的索引信息——主要是每个SKILL.md里声明的name和description——放到模型能读到的位置。模型拿到这个索引先判断当前任务是否匹配某个技能一旦匹配就把对应技能包里的完整SKILL.md内容注入上下文然后按里面的指令展开工作。我把这个过程比作一个公司模型是能力极强但缺少行业经验的实习生它的手机上装着一套目录Skills索引。你派给它一个任务它先翻目录找标题发现某本手册最合适就把那本手册抽出来加载SKILL.md然后一页页照着做。手册里如果说这一步要用专用工具它就打开工具箱scripts目录把对应的脚本拿出来运行。这个理解到位了后面所有排查工作都有方向技能不生效绝大多数问题出在索引环节——description没写好或者路径放得不对模型根本看不到索引。2.2 SKILL.md内部到底长什么样SKILL.md是整个技能包的大脑。一个标准文件分两大部分。第一部分是YAML frontmatter。关键字段有三个name技能名称一般是短横线分隔的英文小写比如frontend-perf-reviewdescription技能描述起招聘启事的作用决定模型什么时候会想到用这个技能有的实现还有version、license、dependencies等字段看具体工具的支持情况第二部分是Markdown正文。正文没有强制的模板但成熟技能一般都会包含这些小节技能的目标和适用范围、执行步骤清单通常是有顺序的编号列表、输出格式要求比如必须以JSON返回、必须包含摘要和结论、规则与禁忌也就是不要做什么的约束、一两个输入输出示例。我见过有的SKILL.md写成长达两千行的百科全书这其实是误区。模型在推理时读的是一份操作规程不是一本参考书。写得越聚焦执行越顺。参考类的大块内容应该单独放到data目录让SKILL.md保持主干清晰。2.3 description写作才是Skills的核心技术如果只让我给一个提升Skills命中率的忠告我会说把80%的精力花在写description上。description写得差主要有两种病。一种是兜底病。比如用于处理各种前端相关问题这种描述等于没说。模型一看什么都能往里套最后在所有技能里随机挑选一个去执行结果哪个都不贴切。另一种是说明书病。把执行步骤全部塞进description写了一大堆模型在索引阶段要快速扫描全部技能根本没法细看长description反而稀释了关键词密度。我现在写description用的模板是当用户[具体场景描述]或者提出[具体任务关键词]时使用此技能。 不适用于[明确不覆盖的场景]。正面说什么情况用反面说什么情况别用最后控制在3到5句话内。这句话是跟很多社区高下载量技能学的实测下来命中率比原来那种单句描述高出一大截。2.4 多文件组织SKILL.md是入口不是全部一个成熟技能包往往长这样my-skill/ ├── SKILL.md ├── scripts/ │ ├── analyze.py │ └── parse_data.js ├── data/ │ ├── template.json │ └── examples.md ├── assets/ │ └── reference/ └── requirements.txtscripts目录放可由AI执行或直接调用的辅助脚本。data目录放模板、词典、示例库。assets里是辅助素材。requirements.txt或package.json声明运行时依赖。为什么需要这些外围文件因为模型的计算和文件系统操作是两个维度。它可以直接生成代码但如果要分析一份几万行的日志靠模型一个个读上下文既慢又容易超限跑脚本去处理会稳得多。所以成熟的Skills一定是SKILL.md定规则、scripts做执行、data供参考的组合拳。2.5 为什么Skills是程序性知识的最佳载体认知科学把知识分成两类陈述性知识是知道是什么程序性知识是知道怎么做。大模型的训练语料决定了它更擅长前者——你问它什么是CDN它能讲三天三夜但按你们团队的发布流程把版本上线这种程序性知识基本不在语料里只存在于团队规范、行业经验和老师傅的脑子里。Skills这种设计最聪明的地方就是把程序性知识外置成明文文件让模型在需要的时候临时加载而不是试图把一切塞进模型参数。这带来两个直接好处一是内容可控你可以随时修改操作规程不用等模型重新训练二是可审计AI到底按什么步骤做的、每一步的依据是什么全在SKILL.md里出了问题查得到。3. 主流生态里Skills已经玩出花了3.1 Claude Agent Skills标准制定者和社区爆发的起点Anthropic在推进Agent Skills标准上动作比较早。官方发布过Skills格式说明也给了一些很不错的示例技能。Claude的客户端和Claude Code都支持把技能包放到~/.claude/skills目录应用启动时自动扫描索引。社区响应非常快GitHub上已经出现了大量awesome-claude-skills类的集合仓库收纳了几百个社区技能。从技能类型看大致可以分成四类工作流类周报生成、会议纪要整理、PR描述撰写、知识库问答编码类代码审查、重构建议、框架脚手架、测试生成内容创作类文章润色、分镜脚本、文案撰写、SEO写作数据处理类日志分析、CSV清洗、数据可视化、脚本生成其中最受欢迎的一批基本都满足一个共性把原本需要多轮对话人工协调才能完成的任务压缩成了一步。比如会议纪要技能收到会议录音转写稿之后会自动按决议事项、待办任务、风险项三个板块输出格式粒度都是行话。3.2 Codex Skills程序员群体的另一个重镇OpenAI的Codex也推出了自己的Skills机制整体思路和Claude的风格很像但实现细节和目录规范不一样。Codex Skills放在~/.codex/skills目录同样以SKILL.md为核心不同客户端版本对文件命名与格式要求有差异装之前先看官方文档语法上吸收了社区的经验。Codex技能生态里编码相关是绝对主力。我见过比较有代表性的包括技术栈迁移助手读取项目依赖给出逐步迁移方案并自动改代码测试用例补全工具根据源码和覆盖率报告补测试前端组件生成器按设计稿描述输出组件代码和样式有意思的是Codex的生态里还有一个不小的学术分支。codex写论文的skills能成为热词不是没道理的很多研究生用技能来自动整理文献、格式化参考文献、按期刊模板重排论文结构。这类技能把一个本来特别繁琐、重复性极高的体力活变成了拖进文件、等输出的自动化流程。3.3 现成的Skills去哪找目前找技能的渠道大概就三条。第一是官方市场。Claude官方有一些内建或市场化的技能目录Codex也在逐步完善自己的技能仓库。官方市场的优点是安全和兼容性好缺点是数量相对有限、质量分层明显。第二是GitHub。这里才是目前最大的集散地。搜索awesome claude skills、awesome codex skills这类主题仓库能按图索骥翻到一大堆社区里流传较广的superpower主题技能、各种storyboard分镜技能也多以这种方式分发。另外有些技能以单独repo形式存在star数高的通常验证过的人多踩坑信息也全。第三是npm等包管理工具。部分技能会以工具包形式发布装完顺便把技能文件也部署到系统目录对开发者比较友好。但这种方式的前提是你熟悉命令行和文件路径。前两条渠道覆盖了绝大多数需求。我的习惯是先在GitHub搜一下有没有现成可改的再去官方市场补缺最后才自己写。Skills这东西能站在别人肩膀上就不要从零开始。3.4 热词背后Skills正向非程序员人群扩散从最近的热度和搜索趋势看Skills早就不只是程序员的玩具了。前端开发skills、自动挖洞skills、分镜skills、写作skills、论文skills……这些需求都有一个共同点大家希望AI在自己的垂直领域按照行里的规矩办事。我接触过做短视频的朋友他们对分镜skills的需求是刚需——视频脚本不是随便写写就好分镜要按景别、运镜、时长、转场这些镜头语言去设计AI默认的输出风格跟你需要的完全不是一回事。封装成分镜Skills之后AI的输出就天然带着行业语感出来就能用改起来也快。自动挖洞skills这类安全方向的需求也在增多但我必须强调一句任何安全测试都只能在授权范围和合规前提下进行自动化工具不是用来绕过边界和规则的而是帮安全人员在授权的测试环境里提升效率。做安全技能包的思路同样是把侦察、验证、清理、复盘的标准流程固化下来而不是替人去做不该做的事。3.5 给刚入坑朋友的一个生态判断现在Skills生态还在快速演化中今天看到的某个最佳实践可能下个月就变了。我的建议是选定一个工具链为主线比如你日常工作主要在Claude Code就先吃透它的技能机制把另一个作为参考对比。不要两套生态一起追不然光目录规则和格式差异就够你折腾半天。先把一个平台用透你要的技能思维自然就建立起来了迁移到另一套只是换路径的事。4. 手把手开发一个自己的Skills4.1 开发前先做需求拆解别急着写文件很多人第一次开发Skills上来就写SKILL.md结果出来个四不像。我的建议是开发前先回答三个问题这个技能要解决的具体任务是什么要具体到输入什么、输出什么。这个任务有没有明确、可复用的流程如果任务本身就是发散性的帮我想想办法那不适合Skills适合普通对话。流程里的每一步AI能不能自己判断并执行如果某一步依赖人工决策或外部权限就要拆出去或写成需要用户确认的交互点。我开发一个前端性能审查技能时目标非常明确让AI按我们团队的性能规范对指定前端项目输出一份结构化报告。拆出来的流程是读取项目的package.json判断技术栈与框架版本找到入口文件和路由配置确认主要页面执行构建命令观察产物体积和警告检查关键指标页面首屏相关配置、资源请求数、chunk体积按团队评分卡逐项打分输出Markdown报告每一条都可执行、可判断、有明确结果这才是适合做成Skills的任务。4.2 创建技能目录与SKILL.md骨架在~/.claude/skills下创建目录我一般用短横线命名比如frontend-perf-review。然后创建SKILL.md。骨架示例--- name: frontend-perf-review description: 用于前端项目的性能审查。当用户提供一个前端项目目录路径或者要求评估页面加载性能、检查资源体积、分析构建产物时使用此技能。当用户只需要代码逻辑审查时不使用此技能。 --- # 前端性能审查 ## 目标 按团队性能规范对指定前端项目执行审查并输出结构化报告。 ## 执行步骤 1. 读取 package.json识别框架、构建工具与关键依赖版本。 2. 查找项目的路由配置列出主要页面。 3. 执行 npm run build记录产物路径与构建警告。 4. 运行 node scripts/collect_bundle_report.js读取输出结果。 5. 按性能打分卡逐项评分。 6. 输出 Markdown 报告。 ## 输出格式 报告包含项目概况、资源分析、性能得分、改进建议按优先级排序。 ## 注意事项 - 只读审查不修改项目源码。 - 构建失败时记录错误日志不要静默跳过。注意这里description里我特意写了当用户只需要代码逻辑审查时不使用此技能这就是前面说的负向约束实测能明显降低误触发率。4.3 用辅助脚本把能说变成能干如果只靠模型读代码性能审查难免偏主观。我加了一个scripts/collect_bundle_report.js干三件事解析构建产物中的stats信息按体积从大到小输出所有chunk计算每个资源的原始体积与gzip后体积SKILL.md执行步骤里写明构建完成后运行 node scripts/collect_bundle_report.js参数为构建产物目录路径。这样模型就有客观数据可用了不会出现我觉得这个页面加载应该很快吧这种拍脑袋结论。写辅助脚本有几个经验第一路径要写绝对或相对于SKILL.md的路径别依赖当前工作目录。模型执行任务时的工作目录往往是用户当时所在的目录不在你的技能目录里。第二脚本必须是纯命令行、非交互式的。不要写那种请按回车继续的脚本自动化执行环境处理不了交互。所有结果通过stdout用纯文本、JSON或Markdown输出。第三依赖要声明清楚。用Python就放requirements.txt用Node就放package.json并标注版本。SKILL.md里最好加一句执行前检查运行环境版本让AI先自查再干活。4.4 测试与迭代把Skills当代码来调试Skills写完一定要测而且要按三个层级测基础用例一个明显命中描述的任务比如请审查 /home/me/demo-project 的前端性能边界用例模糊任务比如帮我看看这个项目行不行观察它是否错误触发无关用例完全不相干的任务比如帮我写封请假邮件它不应该调用这个技能三个用例各跑一遍基本能定位大部分问题。我自己的调试习惯是开着调试模式跑观察模型是否在日志里输出loaded skill xxx。如果没加载先看目录路径加载了但执行不对看SKILL.md步骤描述执行报错看脚本和依赖。迭代改什么也很有讲究。命中率低——改description执行顺序不对——改正文章节顺序和编号输出格式不合要求——强化输出格式这节的措辞必要时给一个标准示例。4.5 完整实录一个分镜脚本生成器从0到1为了让过程更具体我把一个服务短视频创作者的分镜Skills开发全过程记下来。需求来源是朋友的一句话我每次要把文案变成分镜表然后用AI逐镜头生成画面提示词太乱了。这就是典型适合Skills的场景——输入是文案输出是标准分镜表中间有固定流程。目录结构storyboard-generator/ ├── SKILL.md ├── scripts/ │ └── format_storyboard.py └── data/ └── examples.mddescription最终定稿是当用户要求生成短视频分镜脚本、为一段文案设计镜头画面、或需要按景别/运镜/时长输出分镜表时使用。不适用于长片剧本、小说改编等完整叙事创作。执行步骤依次是向用户确认视频目标时长、画幅比例、内容主题如果用户没给主动提问将文案按语义切分为镜头单元为每个镜头标注景别远景/全景/中景/近景/特写、运镜推/拉/摇/移/跟、画面内容、台词或旁白、预估时长调用format_storyboard.py把结构化数据转成Markdown表格校验总时长是否与目标时长匹配如差距超过10%提示调整format_storyboard.py的作用是格式化和校验。它接收结构化镜头数据自动累加总时长检查每个镜头是否有运镜和景别字段缺失就打警告然后输出一个标准Markdown分镜表。测试中真踩了个坑AI自动切镜头时切得太碎15秒的视频给出16个镜头平均不到1秒一个外行人看了都觉得乱。我在SKILL.md里补了规则单镜头时长建议不低于1.5秒、不超过4秒总镜头数控制在视频秒数的0.3倍到0.5倍之间。若切分过碎自动合并连续动作。补上这条之后输出明显像业内人士做的了。这类规则哪里来就是从一次次实测反馈里捞出来写进去的。5. 安装和使用别人发布的Skills5.1 安装的两种路径界面操作和手动部署先说通过界面安装。Claude客户端里有技能或市场相关入口可以在可视化界面里搜索技能、点安装操作上跟装手机应用差不多。Codex也有类似机制直接在界面上搜技能名安装即可。这种方式的优势是路径、索引、版本都由客户端替你管理不用记一堆目录结构。第二种是手动部署也是社区里最常见的方式。从GitHub把仓库clone或下载解压放到对应目录Claude Code / Claude桌面端放到 ~/.claude/skills 下的子目录Codex放到 ~/.codex/skills 下的子目录包括你现在在用的其他类似工具原理大同小异目录路径和命名规范以对应官方文档为准社区教程经常混着写照搬可能就错了。装完之后要重启会话或重新加载让客户端重新扫描技能。这一步经常被忽略我见过有人复制完直接问技能呢其实只是没重载而已。不同客户端的目录规范可能存在差异最稳妥的做法是装之前先看一眼官方文档中关于Skills目录的规定。5.2 从GitHub等平台挑技能的标准GitHub上Skills鱼龙混杂我的挑选顺序是这样的看更新时间。超过半年没更新的基本淘汰模型能力和开发范式迭代太快旧写法很可能已经失效。看SKILL.md是否存在且规范。这是硬指标仓库里根本没有SKILL.md文件的多半只是把一堆Prompt文档包装成了Skills装上也不会被索引。看description和结构。description含糊的触发效果大概率差结构里有没有scripts、data能看出作者是不是真的做过完整技能。看scripts里的命令安不安全。出现不明来源的命令执行、可疑网络请求、无注释的清理命令我都不装。看issue区和讨论区。别人踩坑的信息都在这里比README里吹的功能信息实在得多。我见过很多收藏破千的技能合集仓库点进去发现就是个Markdown链接列表根本不是可安装的标准技能包。把注意力放在那些结构完整的单个技能仓库上收益高得多。5.3 装完怎么验证它真的生效了验证方法有三个直接在会话里问你当前可用的技能有哪些如果回复里列出了刚装的技能名说明索引到了用一个和技能描述高度匹配的任务去触发观察输出有没有走技能里的步骤而不是泛泛地回答开着调试模式看日志Claude Code和Codex在调试时都会输出技能加载信息如果没生效按优先级排查目录路径是不是错了技能文件是否多套了一层目录技能目录名和SKILL.md里的name是否一致部分客户端要求目录名匹配前端有缓存时是否确实重启了会话或刷新了技能列表SKILL.md文件编码或格式是否有问题比如frontmatter漏了结尾的---这些排查点覆盖了九成以上的装完不生效问题。5.4 修改别人的Skill三个地方最值得动下载的Skills很少完全贴合修改是常态。我不建议大改建议只动三个地方description改成自己工作场景的触发词和约束条件执行步骤里的模板和示例换成你团队的规范格式scripts里的参数比如输出路径、命名规则、依赖版本改的时候有两条纪律。第一不要在别人的SKILL.md里随意追加全局性约束比如所有输出必须用中文这会影响技能在非预期场景下的行为。第二不要为了兼容而随便升级脚本依赖版本可能引入不兼容行为。每次改动后在文件里留一行changelog注释方便日后复盘这是团队协作里很有价值的习惯。5.5 技能也要做版本管理当你开始维护自己的技能库之后版本管理就很重要。我的做法是每个技能仓库独立维护用Git做版本控制SKILL.md里的frontmatter里写version字段。每次改动提交一次commitcommit message写清楚改了哪个部分、为什么改。这样做的收益在团队协作时特别明显。我会把技能仓库当作普通代码库来review有精力的话让团队成员试用一批技能、集中提反馈然后统一更新版本。技能的演化其实和产品迭代没有本质区别。6. 常见问题与排查技巧实录6.1 装完了但技能从来不被调用这是出现频率最高的求助。症状很简单技能在目录对但AI输出就是素颜状态完全没走技能流程。先明确一点Skills的触发靠模型判断不是规则的精确匹配所以不存在100%的命中。减少漏触发的手段有两个方向。一是优化description。检查有没有写清什么场景用有没有负向约束长度是否控制在3到5句话。这是最常见的原因。二是明确指令。如果你的任务就必须用某个技能可以加一句请使用xxx技能执行或按xxx技能的要求来做。这就相当于手动指定绕过了模型自己的判断。还有一种容易被忽略的情况你同时装了太多技能索引太庞大模型扫描时注意力被稀释了。这时候把明显不用的技能先移出目录再测试命中率往往会回升。6.2 技能加载了但执行过程中报错技能被加载了说明索引没问题问题出在执行环境或步骤描述。常见报错类型脚本找不到因为当前工作目录不是技能目录脚本用了相对路径。解决办法是SKILL.md里写cd到技能目录或使用绝对路径。依赖缺失脚本要用的Python包或Node模块没装。解决办法是在requirements.txt或package.json里声明并在SKILL.md里写明执行前检查依赖。版本不兼容脚本在某版本能跑换环境就不行。所以SKILL.md里一定要写前置条件比如需要Node 18以上。我现在的写法是在每个SKILL.md开头放一个环境与依赖小节里面明确列出运行时要求和检查命令。AI执行前会自动读这段先自查环境再开始干活报错率大幅下降。6.3 多个技能互相抢活选错执行者技能一多description的触发词就会重叠。比如前端代码审查和前端性能报告两个技能都提到前端项目用户只说了一句看看这个前端项目AI就可能选错。解决思路是错位竞争把每个技能描述里的正向触发场景尽量区分开然后给每个技能加明确的不适用说明。这句话的作用是把AI的选择范围收窄。还可以在设计时做一层上位技能规划如果两个技能确实有很多重叠场景可以考虑合并成一个技能内部通过判断分支来分流任务而不是让两个技能抢。我有个内容创作技能内部按文章/脚本/分镜/文案做分支效果比三个独立小技能稳定得多。6.4 安全边界Skills的权限是把双刃剑这一点必须反复强调。一个技能包里的scripts脚本本质上拥有你运行它的账号的操作权限。社区下载的技能没法保证100%可信。我现在的安全习惯是新下载技能先通读SKILL.md和scripts里的所有代码再安装对脚本中出现的外部网络请求尤其是往未知地址上传数据的直接剔掉对应功能陌生技能先在隔离目录或低权限账号下跑一次冒烟测试验证行为定期清理不用的技能包减少API密钥、本地文件等敏感信息的暴露面这跟装手机App要审权限是一个道理。工具是拿来提升效率的不是拿来给自己埋雷的。别因为嫌麻烦跳过这一步。6.5 一个残酷但真实的观察最后想聊点技术之外的东西。Skills不是魔法它不能凭空让AI变得更强它的作用是把你已经验证过的工作流程以很高的保真度交给AI去执行。如果你的工作本身没有流程、没有规范、没有什么是对的的判断标准那Skills顶多让AI输出得更礼貌一点不会让结果本质变好。我见过一些朋友一口气部署了十几个Skills最后真正高频使用的只有两三个。这不算失败——开发过程帮他们想清楚了哪些事儿其实不该交给AI。Skills开发的价值一半在最终技能包一半是在梳理自己专业经验的过程中。抱着装个技能AI就会帮我搞定所有事期望来的人大概率会失望抱着把我知道的流程写下来让AI照着跑心态来的人大概率收获很大。最后分享一个特别实用的小技巧。如果你刚开始接触Skills别一上来就憋大招做一个通用性极强的大技能。挑一个你几乎每天都做的重复事——比如整理会议纪要、写周报、给PR写描述——先做个最小可用的版本用一两周你会对AI怎么理解我的工作产生特别直观的感受。等这段经验内化之后再去开发那些复杂的跨工具技能你写description、定步骤、设计脚本的能力会完全不一样因为你已经知道AI在哪类任务上听话、在哪类任务上跑偏了。我自己现在每开一个新项目第一件事就是翻一遍技能库——能直接用的就装上能改造的就改造实在没有的先不急着写观察真实需求出现两次以上再动手。Skills这个玩法真的只有自己装一个、跑一遍、改一轮才算真正入坑。
AI Agent Skills实战指南：从原理到开发，让AI真正成为员工
最近和一个做前端的朋友吃饭聊着聊着他就掏出电脑给我演示同一个AI助手平时就是个话痨聊天框但装上一个叫前端审查的技能包之后让它看一个项目页面它居然能按照W3C语义化规范、Lighthouse性能指标、团队代码规范逐项输出检查报告连截图都自己拍了。他跟我说了句让我印象很深的话——这玩意儿才是AI真正开始像员工而不是工具的分水岭。这个技能包就是今天要聊的Skills。简单说Skills是一份结构化的能力模块装进Claude、Codex这类智能体之后AI会在合适的任务场景中自动调用这套模块用你定义好的流程、规范、脚本去完成任务。它能解决的核心问题是通用AI很强但不够听话、不懂行业里的专业流程、每次输出的质量也不稳定Skills恰好补上了这一课。这篇文章的内容不是一份产品说明书而是我从看到别人分享Skills到自己动手开发、再给团队落地的完整记录。我会先把Skills是什么、怎么运作讲清楚然后介绍现在主流的生态资源和下载渠道再给出一套可以直接抄作业的开发流程最后把实践里踩过的坑和排查经验整理成速查表。适合所有想真正动手用AI干活的人——不管是写代码、写文案、做设计还是搞研究的都能从这里找到用得上的部分。1. Skills是什么Agent的专业执照1.1 从手机App类比讲起先给完全没接触过的朋友说一个最直白的理解。手里的AI智能体本质上像一台刚开箱的智能手机系统很流畅、算力很猛、什么都能干一点但出厂时并没有预装那些真正让你离不开它的App。你让它帮我做个晚饭它大概率会背出两百道菜谱但不会真的按照你家冰箱里还剩什么、你有什么忌口、今晚要控制在多少预算给你排出一份能直接执行的三菜一汤计划。Skills就是给这台手机安装的专精App。装上一个家庭晚餐规划技能AI在听到今天晚饭吃什么的时候会走一套固定流程先确认冰箱剩余食材、再询问忌口和用餐时间、接着按营养和预算约束生成菜谱、最后输出采购清单和烹饪顺序。它不再天马行空地聊而是按流程做。放到开发场景里也是一回事。前端工程师装上一个代码审查SkillAI就不只是简单地看看这段代码有什么问题。它会先读取项目技术栈、找到lint配置、执行一遍测试命令再按你团队规定的打分卡逐项输出审查结论。Skills的本质就是把一个具体岗位的最优工作流程变成AI随时能调用的肌肉记忆。1.2 它到底解决了什么问题第一类问题是专业知识的工程化复用。以前大家也靠Prompt让AI干活但Prompt是一次性的——每次都要重新写写长了容易漏写短了AI抓不住重点团队里也没法共享。Skills做成标准化的包之后结构固定、描述清晰、可以版本管理、可以分发给团队里的每一个人。同样一份审查标准不用每次复制粘贴几十行字装一次所有人随时能用。第二类问题是输出稳定性。用过AI的人都有体会同一个问题今天问和明天问结果经常不一样这种随机性在生产环境里是很头疼的。Skills把执行过程拆成明确的步骤序列和判定条件AI的自由发挥空间被压缩到合理范围内。就好比连锁店的汉堡为什么全球一个味道——不是因为厨子稳定而是因为操作手册写得足够细致。第三类问题是和外部系统的连接。Skills可以内置脚本和命令调用逻辑让AI不只会输出文字还能真正动手执行——跑测试、改文件、调接口、处理数据。它是把AI从顾问变成执行者的关键一环。1.3 和MCP、Prompt、Function Calling到底怎么区分这是我被问得最多的问题也是很多人装了Skills却不生效的根源——概念混淆。我直接用一张表说明。维度PromptFunction CallingMCPSkills本质一段输入文本模型输出的结构化调用指令工具互联协议可复用的能力包粒度一次对话一次调用系统级连接流程级封装典型例子帮我写一个正则模型决定调用search()连接数据库、浏览器等完整的SEO文章写作流程复用性低中高高维护成本低中较高中一句话版总结MCP解决的是AI的手和眼睛——它能操作什么外部工具Skills解决的是AI的工作方法和经验——它知道一个任务应该按什么步骤做才算专业。两者是互补关系不是替代关系。你的Skill里完全可以写着先通过MCP调用浏览器工具抓取页面再执行后续分析步骤。很多教程喜欢把它们混在一起讲实际用起来你会发现分工非常清楚。MCP更像管道负责连接Skills更像SOP手册负责流程。1.4 为什么这波Skills热潮发生在现在Skills这个东西的原理并不复杂但为什么2025年前后才集中爆发我理解有几个前提条件终于凑齐了。第一模型上下文窗口大幅扩容。Skill触发时要把SKILL.md和辅助材料注入上下文早期模型上下文只有几K token塞一份操作手册再加一份脚本输出就满了根本玩不转。现在大上下文成了标配注入一整个技能包压力小很多。第二Agent执行能力成熟了。让AI读完流程再执行这件事需要模型具备稳定的多步推理能力还要有可靠的工具调用基础。这两年在Claude和Codex上已经相对成熟Skills才从玩具变成生产力工具。第三行业需要可复现的专家经验。大家逐渐发现大模型博学但每个行业真正的竞争力恰恰是那些老师傅知道、文档里没有的工作流程。Skills提供了一种把这些经验编码下来、标准化分发的方式。2. 拆解Skills的运行原理从触发到执行的完整链路2.1 一次Skills调用是怎么发生的以Claude Agent Skills为例Codex的机制类似只是路径和格式略有差异一个技能就是一个目录目录里必须有SKILL.md文件。当用户和模型对话时客户端会把当前对话上下文和所有已安装技能的索引信息——主要是每个SKILL.md里声明的name和description——放到模型能读到的位置。模型拿到这个索引先判断当前任务是否匹配某个技能一旦匹配就把对应技能包里的完整SKILL.md内容注入上下文然后按里面的指令展开工作。我把这个过程比作一个公司模型是能力极强但缺少行业经验的实习生它的手机上装着一套目录Skills索引。你派给它一个任务它先翻目录找标题发现某本手册最合适就把那本手册抽出来加载SKILL.md然后一页页照着做。手册里如果说这一步要用专用工具它就打开工具箱scripts目录把对应的脚本拿出来运行。这个理解到位了后面所有排查工作都有方向技能不生效绝大多数问题出在索引环节——description没写好或者路径放得不对模型根本看不到索引。2.2 SKILL.md内部到底长什么样SKILL.md是整个技能包的大脑。一个标准文件分两大部分。第一部分是YAML frontmatter。关键字段有三个name技能名称一般是短横线分隔的英文小写比如frontend-perf-reviewdescription技能描述起招聘启事的作用决定模型什么时候会想到用这个技能有的实现还有version、license、dependencies等字段看具体工具的支持情况第二部分是Markdown正文。正文没有强制的模板但成熟技能一般都会包含这些小节技能的目标和适用范围、执行步骤清单通常是有顺序的编号列表、输出格式要求比如必须以JSON返回、必须包含摘要和结论、规则与禁忌也就是不要做什么的约束、一两个输入输出示例。我见过有的SKILL.md写成长达两千行的百科全书这其实是误区。模型在推理时读的是一份操作规程不是一本参考书。写得越聚焦执行越顺。参考类的大块内容应该单独放到data目录让SKILL.md保持主干清晰。2.3 description写作才是Skills的核心技术如果只让我给一个提升Skills命中率的忠告我会说把80%的精力花在写description上。description写得差主要有两种病。一种是兜底病。比如用于处理各种前端相关问题这种描述等于没说。模型一看什么都能往里套最后在所有技能里随机挑选一个去执行结果哪个都不贴切。另一种是说明书病。把执行步骤全部塞进description写了一大堆模型在索引阶段要快速扫描全部技能根本没法细看长description反而稀释了关键词密度。我现在写description用的模板是当用户[具体场景描述]或者提出[具体任务关键词]时使用此技能。 不适用于[明确不覆盖的场景]。正面说什么情况用反面说什么情况别用最后控制在3到5句话内。这句话是跟很多社区高下载量技能学的实测下来命中率比原来那种单句描述高出一大截。2.4 多文件组织SKILL.md是入口不是全部一个成熟技能包往往长这样my-skill/ ├── SKILL.md ├── scripts/ │ ├── analyze.py │ └── parse_data.js ├── data/ │ ├── template.json │ └── examples.md ├── assets/ │ └── reference/ └── requirements.txtscripts目录放可由AI执行或直接调用的辅助脚本。data目录放模板、词典、示例库。assets里是辅助素材。requirements.txt或package.json声明运行时依赖。为什么需要这些外围文件因为模型的计算和文件系统操作是两个维度。它可以直接生成代码但如果要分析一份几万行的日志靠模型一个个读上下文既慢又容易超限跑脚本去处理会稳得多。所以成熟的Skills一定是SKILL.md定规则、scripts做执行、data供参考的组合拳。2.5 为什么Skills是程序性知识的最佳载体认知科学把知识分成两类陈述性知识是知道是什么程序性知识是知道怎么做。大模型的训练语料决定了它更擅长前者——你问它什么是CDN它能讲三天三夜但按你们团队的发布流程把版本上线这种程序性知识基本不在语料里只存在于团队规范、行业经验和老师傅的脑子里。Skills这种设计最聪明的地方就是把程序性知识外置成明文文件让模型在需要的时候临时加载而不是试图把一切塞进模型参数。这带来两个直接好处一是内容可控你可以随时修改操作规程不用等模型重新训练二是可审计AI到底按什么步骤做的、每一步的依据是什么全在SKILL.md里出了问题查得到。3. 主流生态里Skills已经玩出花了3.1 Claude Agent Skills标准制定者和社区爆发的起点Anthropic在推进Agent Skills标准上动作比较早。官方发布过Skills格式说明也给了一些很不错的示例技能。Claude的客户端和Claude Code都支持把技能包放到~/.claude/skills目录应用启动时自动扫描索引。社区响应非常快GitHub上已经出现了大量awesome-claude-skills类的集合仓库收纳了几百个社区技能。从技能类型看大致可以分成四类工作流类周报生成、会议纪要整理、PR描述撰写、知识库问答编码类代码审查、重构建议、框架脚手架、测试生成内容创作类文章润色、分镜脚本、文案撰写、SEO写作数据处理类日志分析、CSV清洗、数据可视化、脚本生成其中最受欢迎的一批基本都满足一个共性把原本需要多轮对话人工协调才能完成的任务压缩成了一步。比如会议纪要技能收到会议录音转写稿之后会自动按决议事项、待办任务、风险项三个板块输出格式粒度都是行话。3.2 Codex Skills程序员群体的另一个重镇OpenAI的Codex也推出了自己的Skills机制整体思路和Claude的风格很像但实现细节和目录规范不一样。Codex Skills放在~/.codex/skills目录同样以SKILL.md为核心不同客户端版本对文件命名与格式要求有差异装之前先看官方文档语法上吸收了社区的经验。Codex技能生态里编码相关是绝对主力。我见过比较有代表性的包括技术栈迁移助手读取项目依赖给出逐步迁移方案并自动改代码测试用例补全工具根据源码和覆盖率报告补测试前端组件生成器按设计稿描述输出组件代码和样式有意思的是Codex的生态里还有一个不小的学术分支。codex写论文的skills能成为热词不是没道理的很多研究生用技能来自动整理文献、格式化参考文献、按期刊模板重排论文结构。这类技能把一个本来特别繁琐、重复性极高的体力活变成了拖进文件、等输出的自动化流程。3.3 现成的Skills去哪找目前找技能的渠道大概就三条。第一是官方市场。Claude官方有一些内建或市场化的技能目录Codex也在逐步完善自己的技能仓库。官方市场的优点是安全和兼容性好缺点是数量相对有限、质量分层明显。第二是GitHub。这里才是目前最大的集散地。搜索awesome claude skills、awesome codex skills这类主题仓库能按图索骥翻到一大堆社区里流传较广的superpower主题技能、各种storyboard分镜技能也多以这种方式分发。另外有些技能以单独repo形式存在star数高的通常验证过的人多踩坑信息也全。第三是npm等包管理工具。部分技能会以工具包形式发布装完顺便把技能文件也部署到系统目录对开发者比较友好。但这种方式的前提是你熟悉命令行和文件路径。前两条渠道覆盖了绝大多数需求。我的习惯是先在GitHub搜一下有没有现成可改的再去官方市场补缺最后才自己写。Skills这东西能站在别人肩膀上就不要从零开始。3.4 热词背后Skills正向非程序员人群扩散从最近的热度和搜索趋势看Skills早就不只是程序员的玩具了。前端开发skills、自动挖洞skills、分镜skills、写作skills、论文skills……这些需求都有一个共同点大家希望AI在自己的垂直领域按照行里的规矩办事。我接触过做短视频的朋友他们对分镜skills的需求是刚需——视频脚本不是随便写写就好分镜要按景别、运镜、时长、转场这些镜头语言去设计AI默认的输出风格跟你需要的完全不是一回事。封装成分镜Skills之后AI的输出就天然带着行业语感出来就能用改起来也快。自动挖洞skills这类安全方向的需求也在增多但我必须强调一句任何安全测试都只能在授权范围和合规前提下进行自动化工具不是用来绕过边界和规则的而是帮安全人员在授权的测试环境里提升效率。做安全技能包的思路同样是把侦察、验证、清理、复盘的标准流程固化下来而不是替人去做不该做的事。3.5 给刚入坑朋友的一个生态判断现在Skills生态还在快速演化中今天看到的某个最佳实践可能下个月就变了。我的建议是选定一个工具链为主线比如你日常工作主要在Claude Code就先吃透它的技能机制把另一个作为参考对比。不要两套生态一起追不然光目录规则和格式差异就够你折腾半天。先把一个平台用透你要的技能思维自然就建立起来了迁移到另一套只是换路径的事。4. 手把手开发一个自己的Skills4.1 开发前先做需求拆解别急着写文件很多人第一次开发Skills上来就写SKILL.md结果出来个四不像。我的建议是开发前先回答三个问题这个技能要解决的具体任务是什么要具体到输入什么、输出什么。这个任务有没有明确、可复用的流程如果任务本身就是发散性的帮我想想办法那不适合Skills适合普通对话。流程里的每一步AI能不能自己判断并执行如果某一步依赖人工决策或外部权限就要拆出去或写成需要用户确认的交互点。我开发一个前端性能审查技能时目标非常明确让AI按我们团队的性能规范对指定前端项目输出一份结构化报告。拆出来的流程是读取项目的package.json判断技术栈与框架版本找到入口文件和路由配置确认主要页面执行构建命令观察产物体积和警告检查关键指标页面首屏相关配置、资源请求数、chunk体积按团队评分卡逐项打分输出Markdown报告每一条都可执行、可判断、有明确结果这才是适合做成Skills的任务。4.2 创建技能目录与SKILL.md骨架在~/.claude/skills下创建目录我一般用短横线命名比如frontend-perf-review。然后创建SKILL.md。骨架示例--- name: frontend-perf-review description: 用于前端项目的性能审查。当用户提供一个前端项目目录路径或者要求评估页面加载性能、检查资源体积、分析构建产物时使用此技能。当用户只需要代码逻辑审查时不使用此技能。 --- # 前端性能审查 ## 目标 按团队性能规范对指定前端项目执行审查并输出结构化报告。 ## 执行步骤 1. 读取 package.json识别框架、构建工具与关键依赖版本。 2. 查找项目的路由配置列出主要页面。 3. 执行 npm run build记录产物路径与构建警告。 4. 运行 node scripts/collect_bundle_report.js读取输出结果。 5. 按性能打分卡逐项评分。 6. 输出 Markdown 报告。 ## 输出格式 报告包含项目概况、资源分析、性能得分、改进建议按优先级排序。 ## 注意事项 - 只读审查不修改项目源码。 - 构建失败时记录错误日志不要静默跳过。注意这里description里我特意写了当用户只需要代码逻辑审查时不使用此技能这就是前面说的负向约束实测能明显降低误触发率。4.3 用辅助脚本把能说变成能干如果只靠模型读代码性能审查难免偏主观。我加了一个scripts/collect_bundle_report.js干三件事解析构建产物中的stats信息按体积从大到小输出所有chunk计算每个资源的原始体积与gzip后体积SKILL.md执行步骤里写明构建完成后运行 node scripts/collect_bundle_report.js参数为构建产物目录路径。这样模型就有客观数据可用了不会出现我觉得这个页面加载应该很快吧这种拍脑袋结论。写辅助脚本有几个经验第一路径要写绝对或相对于SKILL.md的路径别依赖当前工作目录。模型执行任务时的工作目录往往是用户当时所在的目录不在你的技能目录里。第二脚本必须是纯命令行、非交互式的。不要写那种请按回车继续的脚本自动化执行环境处理不了交互。所有结果通过stdout用纯文本、JSON或Markdown输出。第三依赖要声明清楚。用Python就放requirements.txt用Node就放package.json并标注版本。SKILL.md里最好加一句执行前检查运行环境版本让AI先自查再干活。4.4 测试与迭代把Skills当代码来调试Skills写完一定要测而且要按三个层级测基础用例一个明显命中描述的任务比如请审查 /home/me/demo-project 的前端性能边界用例模糊任务比如帮我看看这个项目行不行观察它是否错误触发无关用例完全不相干的任务比如帮我写封请假邮件它不应该调用这个技能三个用例各跑一遍基本能定位大部分问题。我自己的调试习惯是开着调试模式跑观察模型是否在日志里输出loaded skill xxx。如果没加载先看目录路径加载了但执行不对看SKILL.md步骤描述执行报错看脚本和依赖。迭代改什么也很有讲究。命中率低——改description执行顺序不对——改正文章节顺序和编号输出格式不合要求——强化输出格式这节的措辞必要时给一个标准示例。4.5 完整实录一个分镜脚本生成器从0到1为了让过程更具体我把一个服务短视频创作者的分镜Skills开发全过程记下来。需求来源是朋友的一句话我每次要把文案变成分镜表然后用AI逐镜头生成画面提示词太乱了。这就是典型适合Skills的场景——输入是文案输出是标准分镜表中间有固定流程。目录结构storyboard-generator/ ├── SKILL.md ├── scripts/ │ └── format_storyboard.py └── data/ └── examples.mddescription最终定稿是当用户要求生成短视频分镜脚本、为一段文案设计镜头画面、或需要按景别/运镜/时长输出分镜表时使用。不适用于长片剧本、小说改编等完整叙事创作。执行步骤依次是向用户确认视频目标时长、画幅比例、内容主题如果用户没给主动提问将文案按语义切分为镜头单元为每个镜头标注景别远景/全景/中景/近景/特写、运镜推/拉/摇/移/跟、画面内容、台词或旁白、预估时长调用format_storyboard.py把结构化数据转成Markdown表格校验总时长是否与目标时长匹配如差距超过10%提示调整format_storyboard.py的作用是格式化和校验。它接收结构化镜头数据自动累加总时长检查每个镜头是否有运镜和景别字段缺失就打警告然后输出一个标准Markdown分镜表。测试中真踩了个坑AI自动切镜头时切得太碎15秒的视频给出16个镜头平均不到1秒一个外行人看了都觉得乱。我在SKILL.md里补了规则单镜头时长建议不低于1.5秒、不超过4秒总镜头数控制在视频秒数的0.3倍到0.5倍之间。若切分过碎自动合并连续动作。补上这条之后输出明显像业内人士做的了。这类规则哪里来就是从一次次实测反馈里捞出来写进去的。5. 安装和使用别人发布的Skills5.1 安装的两种路径界面操作和手动部署先说通过界面安装。Claude客户端里有技能或市场相关入口可以在可视化界面里搜索技能、点安装操作上跟装手机应用差不多。Codex也有类似机制直接在界面上搜技能名安装即可。这种方式的优势是路径、索引、版本都由客户端替你管理不用记一堆目录结构。第二种是手动部署也是社区里最常见的方式。从GitHub把仓库clone或下载解压放到对应目录Claude Code / Claude桌面端放到 ~/.claude/skills 下的子目录Codex放到 ~/.codex/skills 下的子目录包括你现在在用的其他类似工具原理大同小异目录路径和命名规范以对应官方文档为准社区教程经常混着写照搬可能就错了。装完之后要重启会话或重新加载让客户端重新扫描技能。这一步经常被忽略我见过有人复制完直接问技能呢其实只是没重载而已。不同客户端的目录规范可能存在差异最稳妥的做法是装之前先看一眼官方文档中关于Skills目录的规定。5.2 从GitHub等平台挑技能的标准GitHub上Skills鱼龙混杂我的挑选顺序是这样的看更新时间。超过半年没更新的基本淘汰模型能力和开发范式迭代太快旧写法很可能已经失效。看SKILL.md是否存在且规范。这是硬指标仓库里根本没有SKILL.md文件的多半只是把一堆Prompt文档包装成了Skills装上也不会被索引。看description和结构。description含糊的触发效果大概率差结构里有没有scripts、data能看出作者是不是真的做过完整技能。看scripts里的命令安不安全。出现不明来源的命令执行、可疑网络请求、无注释的清理命令我都不装。看issue区和讨论区。别人踩坑的信息都在这里比README里吹的功能信息实在得多。我见过很多收藏破千的技能合集仓库点进去发现就是个Markdown链接列表根本不是可安装的标准技能包。把注意力放在那些结构完整的单个技能仓库上收益高得多。5.3 装完怎么验证它真的生效了验证方法有三个直接在会话里问你当前可用的技能有哪些如果回复里列出了刚装的技能名说明索引到了用一个和技能描述高度匹配的任务去触发观察输出有没有走技能里的步骤而不是泛泛地回答开着调试模式看日志Claude Code和Codex在调试时都会输出技能加载信息如果没生效按优先级排查目录路径是不是错了技能文件是否多套了一层目录技能目录名和SKILL.md里的name是否一致部分客户端要求目录名匹配前端有缓存时是否确实重启了会话或刷新了技能列表SKILL.md文件编码或格式是否有问题比如frontmatter漏了结尾的---这些排查点覆盖了九成以上的装完不生效问题。5.4 修改别人的Skill三个地方最值得动下载的Skills很少完全贴合修改是常态。我不建议大改建议只动三个地方description改成自己工作场景的触发词和约束条件执行步骤里的模板和示例换成你团队的规范格式scripts里的参数比如输出路径、命名规则、依赖版本改的时候有两条纪律。第一不要在别人的SKILL.md里随意追加全局性约束比如所有输出必须用中文这会影响技能在非预期场景下的行为。第二不要为了兼容而随便升级脚本依赖版本可能引入不兼容行为。每次改动后在文件里留一行changelog注释方便日后复盘这是团队协作里很有价值的习惯。5.5 技能也要做版本管理当你开始维护自己的技能库之后版本管理就很重要。我的做法是每个技能仓库独立维护用Git做版本控制SKILL.md里的frontmatter里写version字段。每次改动提交一次commitcommit message写清楚改了哪个部分、为什么改。这样做的收益在团队协作时特别明显。我会把技能仓库当作普通代码库来review有精力的话让团队成员试用一批技能、集中提反馈然后统一更新版本。技能的演化其实和产品迭代没有本质区别。6. 常见问题与排查技巧实录6.1 装完了但技能从来不被调用这是出现频率最高的求助。症状很简单技能在目录对但AI输出就是素颜状态完全没走技能流程。先明确一点Skills的触发靠模型判断不是规则的精确匹配所以不存在100%的命中。减少漏触发的手段有两个方向。一是优化description。检查有没有写清什么场景用有没有负向约束长度是否控制在3到5句话。这是最常见的原因。二是明确指令。如果你的任务就必须用某个技能可以加一句请使用xxx技能执行或按xxx技能的要求来做。这就相当于手动指定绕过了模型自己的判断。还有一种容易被忽略的情况你同时装了太多技能索引太庞大模型扫描时注意力被稀释了。这时候把明显不用的技能先移出目录再测试命中率往往会回升。6.2 技能加载了但执行过程中报错技能被加载了说明索引没问题问题出在执行环境或步骤描述。常见报错类型脚本找不到因为当前工作目录不是技能目录脚本用了相对路径。解决办法是SKILL.md里写cd到技能目录或使用绝对路径。依赖缺失脚本要用的Python包或Node模块没装。解决办法是在requirements.txt或package.json里声明并在SKILL.md里写明执行前检查依赖。版本不兼容脚本在某版本能跑换环境就不行。所以SKILL.md里一定要写前置条件比如需要Node 18以上。我现在的写法是在每个SKILL.md开头放一个环境与依赖小节里面明确列出运行时要求和检查命令。AI执行前会自动读这段先自查环境再开始干活报错率大幅下降。6.3 多个技能互相抢活选错执行者技能一多description的触发词就会重叠。比如前端代码审查和前端性能报告两个技能都提到前端项目用户只说了一句看看这个前端项目AI就可能选错。解决思路是错位竞争把每个技能描述里的正向触发场景尽量区分开然后给每个技能加明确的不适用说明。这句话的作用是把AI的选择范围收窄。还可以在设计时做一层上位技能规划如果两个技能确实有很多重叠场景可以考虑合并成一个技能内部通过判断分支来分流任务而不是让两个技能抢。我有个内容创作技能内部按文章/脚本/分镜/文案做分支效果比三个独立小技能稳定得多。6.4 安全边界Skills的权限是把双刃剑这一点必须反复强调。一个技能包里的scripts脚本本质上拥有你运行它的账号的操作权限。社区下载的技能没法保证100%可信。我现在的安全习惯是新下载技能先通读SKILL.md和scripts里的所有代码再安装对脚本中出现的外部网络请求尤其是往未知地址上传数据的直接剔掉对应功能陌生技能先在隔离目录或低权限账号下跑一次冒烟测试验证行为定期清理不用的技能包减少API密钥、本地文件等敏感信息的暴露面这跟装手机App要审权限是一个道理。工具是拿来提升效率的不是拿来给自己埋雷的。别因为嫌麻烦跳过这一步。6.5 一个残酷但真实的观察最后想聊点技术之外的东西。Skills不是魔法它不能凭空让AI变得更强它的作用是把你已经验证过的工作流程以很高的保真度交给AI去执行。如果你的工作本身没有流程、没有规范、没有什么是对的的判断标准那Skills顶多让AI输出得更礼貌一点不会让结果本质变好。我见过一些朋友一口气部署了十几个Skills最后真正高频使用的只有两三个。这不算失败——开发过程帮他们想清楚了哪些事儿其实不该交给AI。Skills开发的价值一半在最终技能包一半是在梳理自己专业经验的过程中。抱着装个技能AI就会帮我搞定所有事期望来的人大概率会失望抱着把我知道的流程写下来让AI照着跑心态来的人大概率收获很大。最后分享一个特别实用的小技巧。如果你刚开始接触Skills别一上来就憋大招做一个通用性极强的大技能。挑一个你几乎每天都做的重复事——比如整理会议纪要、写周报、给PR写描述——先做个最小可用的版本用一两周你会对AI怎么理解我的工作产生特别直观的感受。等这段经验内化之后再去开发那些复杂的跨工具技能你写description、定步骤、设计脚本的能力会完全不一样因为你已经知道AI在哪类任务上听话、在哪类任务上跑偏了。我自己现在每开一个新项目第一件事就是翻一遍技能库——能直接用的就装上能改造的就改造实在没有的先不急着写观察真实需求出现两次以上再动手。Skills这个玩法真的只有自己装一个、跑一遍、改一轮才算真正入坑。