1. 从skills这个模糊词说起它到底指什么第一次看到skills这个标题我脑子里冒出来的第一个念头是这词太泛了。技能、技巧、能力什么都能往里装。但结合热搜词里那一串Agent Skillsclaude agent skillscodex skillsskills开发skills安装包下载方向就清晰了——这里说的 skills指的是给 AI Agent 挂载的能力模块也就是让大模型从只会聊天变成能干活的那一层扩展机制。打个比方。大模型本身像一个刚毕业的高材生脑子好使但没进过具体岗位不知道你们公司的报销流程、代码规范、部署脚本长什么样。skills 就是给他配的一本本岗位操作手册每本手册对应一类任务写周报的、查数据库的、跑测试的、生成分镜的。Agent 接到任务后先翻手册再动手。这套机制为什么这两年突然火因为大家发现光靠提示词prompt堆砌能力上限很低。你写一千字的提示词教模型怎么调接口不如直接给它一个封装好的 skill里面写清楚输入输出、依赖、边界条件。提示词是口头交代skill 是写成文档的 SOP后者可复用、可版本管理、可测试。所以这篇内容我打算聊清楚几件事skills 的本质是什么、一个 skill 由哪些部分组成、怎么从零开发一个能用的 skill、安装和调试时最容易踩的坑、以及市面上那些skills 大全skills 推荐到底该怎么挑。适合两类人看一类是天天跟 Agent 打交道、想给自己工作流加能力的开发者另一类是听说过这个词、但还没搞明白它和普通插件有什么区别的观望者。提示本文讨论的 skills 是通用的 Agent 能力扩展概念不绑定任何特定厂商。不同平台的实现细节有差异但核心思路相通。2. 拆开一个 skill 看内部它和普通插件差在哪2.1 skill 的最小构成单元很多人把 skill 和插件plugin混为一谈其实两者定位不同。插件通常是往宿主程序里注入代码运行在宿主进程内skill 更像一份结构化的能力说明书 可执行逻辑Agent 在需要时加载它用完可以卸载。它的最小构成一般包含四块元信息metadata名称、描述、适用场景、触发条件。这部分决定了 Agent 什么时候会想起用它。描述写得烂skill 再强也没人调用。指令instructions自然语言写的操作步骤告诉模型遇到这类任务该怎么做。这是 skill 区别于传统函数库的关键——它是给模型看的不是给人看的。工具/脚本tools/scripts真正干活的代码可能是 shell 脚本、Python 函数、API 调用封装。资源resources模板文件、参考文档、示例数据供模型在执行过程中读取。我见过太多人只写了脚本元信息一句话带过结果 Agent 根本不知道这个 skill 存在。元信息的描述质量直接决定 skill 的调用率这一点后面会展开讲。2.2 为什么是渐进式披露而不是一次性全塞进去Agent 的上下文窗口是有限资源。如果一上来把几十个 skill 的完整内容全塞进系统提示token 直接爆炸模型还会因为信息过载而抓不住重点。所以主流做法是渐进式披露progressive disclosure第一层只加载所有 skill 的名称和一句话描述让模型知道我有哪些能力可用。第二层当模型判断某个 skill 相关时才加载它的完整指令。第三层执行过程中按需读取资源文件。这个设计很像公司里的知识库你不会把全公司的文档都背下来但你知道财务部有报销手册需要时去查。理解这一点你就明白为什么 skill 的描述要精准——它是模型做要不要深入决策的唯一依据。2.3 skill 与 MCP、function calling 的关系热搜里出现了claude mcpservers npx说明很多人把 skill 和 MCPModel Context Protocol搞混。简单区分概念定位类比function calling模型调用单个函数的机制打电话叫一个服务MCP标准化的工具/资源接入协议统一的插座标准skill面向任务的能力封装可含指令工具资源一本岗位操作手册三者不冲突。一个 skill 内部完全可以用 MCP 去连外部服务也可以用 function calling 调函数。skill 是更高层的组织单位关注的是完成一类任务而不是调用一个接口。3. 从零开发一个 skill我实际走通的流程3.1 先想清楚这个 skill 解决什么重复劳动开发 skill 最大的误区是为了做而做。我建议你先记录一周内自己重复操作超过三次的任务从中挑一个。比如每次写完代码要手动跑 lint、跑测试、生成 changelog这就是一个典型的可 skill 化场景。判断标准有三条步骤固定、输入输出明确、不需要复杂的人类判断。三条都满足才值得做成 skill。如果每次流程都不一样那还是老老实实手动做硬做成 skill 只会增加维护负担。3.2 目录结构怎么摆一个可维护的 skill 目录我习惯这样组织my-skill/ ├── SKILL.md # 元信息 指令核心文件 ├── scripts/ │ ├── main.py # 主逻辑 │ └── utils.py # 辅助函数 ├── resources/ │ ├── template.md # 模板 │ └── examples/ # 示例 └── tests/ └── test_main.py # 测试用例SKILL.md是整个 skill 的入口。它的头部用 YAML frontmatter 写元信息正文写指令。这个结构不是强制的但社区里大部分实现都遵循类似约定照着来兼容性最好。3.3 SKILL.md 里到底写什么这是最考验功力的部分。我踩过的坑是一开始把指令写成了给人类看的文档结果模型执行时各种跑偏。后来总结出几条经验用第二人称对模型说话你需要先检查 X然后执行 Y而不是该 skill 会检查 X。把判断条件写死如果文件不存在直接报错退出不要尝试创建比处理文件不存在的情况有效得多。给出具体命令不要描述意图。写python scripts/main.py --input {file}不要写运行主脚本处理输入文件。列出反例不要修改原始文件只输出到临时目录这类否定约束能挡掉大量意外行为。元信息里的description字段尤其关键。它要同时说清做什么和什么时候用。我常用的模板是当用户需要[完成某任务]时使用此 skill它会[具体动作]适用于[场景边界]。3.4 脚本部分能确定性完成的事别交给模型一个原则能用代码确定性完成的绝不交给模型判断。模型适合做模糊匹配、内容生成、意图理解精确计算、格式转换、文件操作交给脚本。比如从日志里提取所有 ERROR 行并统计数量这活儿用grep一行搞定让模型去数纯属浪费 token 还容易错。反过来根据错误日志判断可能的根因并给出修复建议这才是模型该干的。脚本的输入输出要设计得傻瓜化参数用命令行传入结果输出到 stdout 或指定文件退出码规范0 成功非 0 失败。这样模型调用时不用猜。3.5 测试别等上线才发现 skill 不触发skill 的测试分两层。第一层是脚本本身的单元测试跟普通代码一样。第二层是触发测试——给 Agent 几个应该触发和不应该触发的任务描述看它是否正确调用。我一般准备这样一组用例输入任务期望行为帮我跑一下测试并生成报告触发本 skill解释一下这段代码不触发跑测试触发测试报告模板长啥样不触发这是查询不是执行触发测试不过关说明你的 description 写得有问题回去改元信息而不是改脚本。4. 安装与调试那些让人抓狂的坑4.1 npx 相关命令失败的常见原因热搜里npx playwright install失败是个高频问题虽然它本身是浏览器自动化工具但暴露的坑具有普遍性。npx 类命令失败八成是这几个原因网络问题依赖包下载不下来。国内环境下配置好镜像源能解决大部分问题。Node 版本不匹配某些包要求 Node 18你还在用 16报错信息往往很隐晦。权限问题全局安装目录没有写权限尤其在 Linux 上。缓存损坏npx的缓存目录脏了清掉重来往往就好了。排查顺序建议先看完整报错别只看最后一行再确认 Node 版本再检查网络最后清缓存。我遇到过最坑的一次是磁盘满了报错却显示成网络超时查了半天。4.2 skill 装了但 Agent 不调用这是新手最常问的问题。原因通常有三个第一description 太笼统。写处理文件相关任务模型根本不知道什么时候该用。改成当用户要求批量重命名图片文件时使用触发率立刻上去。第二skill 数量太多。上下文里塞了几十个 skill模型选择困难。建议同时启用的 skill 控制在 10 个以内不用的及时关掉。第三指令里有冲突。两个 skill 都声称处理代码审查模型就懵了。定期清理功能重叠的 skill。4.3 调试 skill 的实用手法我习惯在 skill 的脚本里加一个--debug参数输出详细的中间过程。Agent 调用失败时先手动跑一遍脚本确认脚本本身没问题再怀疑是模型调用环节的问题。另外把 Agent 的完整调用日志打开看它到底传了什么参数进来。十次里有三次是参数格式不对——比如你期望 JSON模型传了个自然语言字符串。这时候要么在指令里强调格式要么在脚本里做容错解析。注意调试阶段不要怕日志多上线前再收敛。我见过有人为了日志干净把关键信息都删了出问题时两眼一抹黑。5. 挑选现成 skill市面上的skills 大全怎么用5.1 官方市场和第三方仓库的区别现在有官方 skill 市场也有 GitHub 上各种第三方合集。官方市场的优势是审核相对严格、版本可控、更新及时第三方仓库的优势是种类多、更新快、有些小众需求只有那里有。我的策略是核心工作流用官方的尝鲜和长尾需求用第三方的但第三方的一定要审代码。skill 本质上是能执行代码的东西来源不明的 skill 直接装等于把执行权限交给陌生人。审的时候重点看脚本里有没有网络请求、有没有读写敏感路径、有没有执行外部命令。5.2 判断一个 skill 值不值得用看四个维度描述是否清晰连描述都写不明白的指令质量大概率也不行。最近更新时间半年没更新的可能已经不适配当前版本。有没有测试带测试用例的 skill作者通常更靠谱。issue 区活跃度有人提问、有人回复说明还在维护。5.3 组合使用的心得单个 skill 能力有限真正提效的是skill 组合。比如代码审查 skill 测试生成 skill changelog skill串起来就能覆盖一次完整的提交前检查。组合时注意执行顺序和数据传递格式前一个 skill 的输出最好能直接作为后一个的输入。我一般会写一个编排 skill专门负责按顺序调用其他 skill把胶水逻辑集中在一处方便调整。6. 几个真实场景的落地记录6.1 用 skill 自动化日常报告我给自己配了一个日报生成 skill读取当天的 git commit、issue 变更、日历事件汇总成结构化日报。脚本负责拉数据模型负责把干巴巴的数据写成通顺的段落。这个 skill 每天省我大概二十分钟关键是它不会漏项。6.2 分镜生成类 skill 的思路热搜里有分镜 skills 下载说明内容创作领域也在用。这类 skill 的套路是输入一段文案输出分镜表镜号、画面描述、时长、转场。核心难点在于输出格式的稳定性——模型很容易自由发挥。解决办法是在指令里给出严格的表格模板并要求只输出表格不要任何额外说明。6.3 论文写作辅助 skill 的边界codex 写论文的 skills这类需求我的建议是只用来做辅助不做主体。文献格式整理、参考文献去重、图表编号检查这些确定性任务交给 skill 很合适。但核心论点和论证逻辑还是得自己来。把写作全交给模型出来的东西经不起推敲。7. 我踩过的坑和几条硬经验第一条别追求 skill 数量。我一开始兴致勃勃做了二十多个结果维护不过来一半都废弃了。现在稳定在用的就七八个每个都打磨得比较扎实。第二条版本管理要跟上。skill 改了指令或脚本行为可能就变了。用 git 管理每次改动写清楚原因。我吃过亏改了一句话结果触发条件变了某个自动化流程静默失效一周后才发现。第三条给 skill 设边界。明确写清楚这个 skill 不做什么比写做什么更能防止意外。比如文件处理 skill 里写明不删除任何文件只做复制和重命名能挡掉很多危险操作。第四条定期做触发回归测试。模型版本更新后原来的触发逻辑可能失效。我每个月跑一次触发测试集发现偏差及时修 description。第五条敏感操作加确认。涉及删除、覆盖、发送外部请求的 skill在指令里要求执行前先向用户确认。自动化不等于无脑执行留一道人工闸门。这套东西说到底核心就一句话skill 是把你的经验固化成可复用资产的手段。写得好的 skill是你工作方法的延伸写得烂的只是给模型添乱。从一个小场景开始跑通、打磨、再扩展比一上来铺大摊子靠谱得多。