前阵子技术圈聊得最多的一个词除了“agent”就是“skills”。Andrej Karpathy 在多个场合反复表达过一个观点与其让模型在 prompt 里翻来覆去地猜你的意图不如直接给它一组可验证、可复用的技能代码。网上关于“andrej-karpathy-skills”的讨论其实就是在聊大模型应用开发正在发生的这次转向——从“提示词工程”到“技能包工程”。这篇文章就把这件事拆开聊透skills 到底是什么、为什么 Karpathy 会把它推到台前、和 prompt 的边界在哪里、怎么亲手做一个能用的 skill以及社区里那些被反复推荐的热门技能包到底值不值得装。我尽量用从实践出发的口吻写不堆概念。你如果是正在做 agent 应用、研究大模型工作流的开发者或者单纯好奇“为什么现在大家都在说 skills 而不是 prompt”这篇应该能给你一个清晰的路径。1. 为什么 Karpathy 要提“skills”先看看 agent 项目的真实痛点1.1 prompt 越来越长模型却越来越“笨”我最早做 agent 项目的时候和大多数人一样遇到模型输出不稳定就疯狂往 system prompt 里加规则。今天加一条“你必须先分析需求”明天加一条“输出格式严格使用 JSON”后天再补一段“遇到边界情况请自查”。结果呢prompt 从 2K 涨到 8K模型not only没有变聪明反而经常把新规则和旧规则搞混。到了长上下文场景规则之间互相打架模型开始“自我否定”同一个任务跑三次能出三个完全不同的结果。这个问题的本质是文本形式的 prompt 对模型来说只是一种“建议”模型每次都在重新理解你的意图而不是直接调用一个已经被验证过的能力。就像你请一个实习生干活反复叮嘱他八条注意事项结果他还是按自己的想法来。你要的其实不是更多叮嘱而是一份可以直接照着执行的标准操作手册。Karpathy 聊 skills 时最核心的一句话大意是“把技能写进代码里而不是写进 prompt 里”。这句话点醒了我。代码是确定的、可验证的、可以被测试的而文本是模糊的、可被忽略的、不可控的。他想表达的是真正的 agent 能力不应该依赖模型“临场发挥”而应该把能力固化成一个个可调用的模块。1.2 从“教模型做事”到“给模型工具箱”传统 prompt 的思路是“教模型做事”把步骤、技巧、禁忌全部用文字描述。skills 的思路完全反过来把做事的能力封装成一个带入口、带参数、带输出规范的代码包模型只需要学会“什么时候调用哪个技能包”至于技能包内部怎么实现不需要模型关心。举个很直白的例子。你想让 agent 帮你统计代码仓库里的函数数量。用 prompt 的方式你得在提示词里写明“读取根目录、遍历所有 .py 文件、用正则匹配 def 开头、注意排除注释和字符串……”这一大堆逻辑。模型如果哪一步理解偏了结果就废了。用 skill 的方式你只需要提供一个count_functions技能包skill 描述里写清楚“统计 Python 仓库中的函数数量返回 JSON 数组”模型要做的事情就变成了一次“工具选择”而不是“逻辑推理”。这就是 Karpathy 反复强调的可靠性来源固定逻辑交给代码模型只做决策。这也是为什么现在很多 agent 框架比如 Claude Code、Codex、OpenCode都在大力支持 skills 机制。它们本质上都在做同一件事把模型从“执行者”变成“调度者”。2. Skills 到底是什么从目录结构到运行机制拆开看2.1 一个 skill 的标准骨架SKILL.md 才是灵魂社区里流传的 skills比如 Claude Code skills、Superpower Skills虽然形式各有差异但核心结构高度一致。一个 skill 本质上就是一个文件夹里面通常包含 SKILL.md、脚本、资源文件和测试用例。SKILL.md 是 skill 被模型感知的入口也是最重要的文件。它的格式类似 Markdown 带 YAML front matter里面会声明技能的名称name、触发条件description、依赖工具allowed-tools等元信息。模型读取这个文件来判断“当前任务是否应该调用这个技能”。所以 SKILL.md 里的 description 怎么写直接决定了模型会不会在你需要的时候想起这个技能。举个例子。我本地~/.claude/skills/analyze-repo/这个技能的 SKILL.md 长这样--- name: analyze-repo description: 分析当前代码仓库结构生成模块依赖关系图和关键代码定位说明。适用于代码审查、新人接手项目、技术方案编写等场景。 allowed-tools: bash, read, write, grep --- # analyze-repo 对仓库执行结构分析输出三部分内容 1. 顶层模块清单 2. 关键入口文件与依赖关系 3. 潜在维护风险点为什么 description 写得这么具体因为模型在决定是否调用技能时靠的就是把当前任务描述和 description 做语义匹配。“代码审查”这个词如果没出现在 description 里模型很可能就不会触发这个技能。这也是大部分自建技能失败率高的原因——不是技能本身写得烂而是触发条件写得模糊。2.2 Skills 和 Prompt、Plugin、Function Calling 到底有什么不一样很多朋友问过我skills 和 prompt 不是一回事吗和 function calling 有什么区别这确实是理解的关键。我做个不太严谨但很好懂的类比Prompt 是给模型读的一本“工作手册”模型读完之后自由发挥。Plugin 是一个“外挂设备”模型知道有这个东西但不知道具体用法需要你额外告诉它。Function calling 是“一个操作按钮”模型按固定格式填参数调用一次就返回一次结果是原子级的。Skills 是“一条完整的工作流”它内部可能包含多个函数、多步操作、多个文件是一个可以独立完成某项任务的技能单元。更准确地说skill 是介于 prompt 和 function calling 之间的存在。它比 prompt 更可执行因为它把能力落在了代码和脚本上它又比 function calling 更复杂因为它不是一个单次调用而是一整套流程。比如一个“生成月度数据报表”的 skill内部可能包含查询数据、清洗异常值、生成图表、导出 PPT 四步每步都是一段脚本或命令。模型要做的事情只是“决定调用这个技能”然后 skill 内部自动开始干活。这是 Karpathy 说的“superpower”的真正含义当模型拥有几十个这样的技能包它就不再是一个“什么都会一点但什么都不精”的通才而是一个“知道该找哪个专家”的调度者。技能之间还可以互相组合一个技能的输出成为另一个技能的输入agent 的复杂度就这样积累起来。3. 从零打造一个自己的 Skills 包5 步上手3.1 第一步选载体确定你的 agent 环境技术圈热词里出现频率最高的几个载体是 Claude Code、Codex、OpenCode 和 Superpower。不同载体对 skill 的加载路径有差异但思路是共通的都是扫描某个固定目录下的技能包然后注入到模型可见的上下文中。以 Claude Code 为例个人技能的默认目录是~/.claude/skills/每个子文件夹对应一个 skill。以 Codex 举例社区里常见的做法是把 skill 放在~/.codex/skills/OpenCode 则是通过npx skills add这种方式把 GitHub 上的某个仓库直接安装为本地技能。比如热词里提到的那条命令npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y参数含义拆开看npx skills是社区开发的一个技能管理工具add表示从远程仓库安装--agent claude-code指定安装目标为 Claude Code 环境-g表示全局安装-y跳过交互确认。这种方式的好处是安装的 skill 自带完整目录结构和说明你不用手工去建。3.2 第二步写清 SKILL.md尤其重视 description动手写技能之前先把 SKILL.md 写好。我强烈建议先写描述再写实现。因为描述决定了这个技能“在模型眼里长什么样”描述写清楚了后面的实现只是按图索骥。description 写作有三个要点。第一明确适用场景把“什么时候该用”说清楚。比如“适用于分析前端项目依赖时”“适用于数据预处理时”。第二写清楚输入和输出模型需要知道该给技能传什么、技能会返回什么。第三尽量使用命令式和结果导向的措辞避免模糊形容词。一个反例是这么写的description: 分析项目的代码结构这个太笼统。模型在分析前端项目时可能不会触发它在分析后端项目时反而触发了。改成这样会好很多description: 分析前端项目的代码结构识别页面组件、路由配置和状态管理模块的依赖关系输出 Markdown 格式的结构说明。适用于前端代码审查、组件重构评估等场景。3.3 第三步用脚本固化核心逻辑尽量做成黑盒skill 的核心逻辑应该用脚本来实现不建议写在 SKILL.md 里让模型自己发挥。为什么因为脚本是确定性的同样输入永远返回同样输出而模型的自然语言推理做不到这点。我自己做过一个“代码质量评分”技能最开始把评分逻辑写在 SKILL.md 里让模型自己判断结果同一个文件让我跑了五遍得到五个不同分数。后来我把评分逻辑写成一个 Python 脚本用 AST 分析代码复杂度、圈复杂度、注释比例输出一个固定的分数。模型只负责调用脚本和解释结果准确率立刻稳定了。这里的关键是能脚本化的逻辑一定要脚本化只把“要不要调用”“怎么解释结果”这类判断留给了模型。脚本尽量做成黑盒输入明确、输出明确内部实现不暴露给模型这样既降低模型混淆的可能也方便你单独测试。你可以用任意语言写脚本但要确保当前环境有对应运行时。比如我给 Claude Code 写的技能大部分用 Python 或 Node因为这两个运行时在开发机上几乎默认存在。脚本里要加好错误处理因为模型调用脚本时可能传了错误参数脚本要能给出友好报错而不是直接崩掉。3.4 第四步加测试用例确保技能可复现很多人做技能容易漏掉测试这一步但测试恰恰是 skill 和 prompt 最大的区别所在。Prompt 没法自动化测试skill 可以。一套完整的 skill 里应该有一个 test 目录放上几个典型的输入输出对每次修改技能后跑一遍确认没有回归。拿 analyze-repo 这个技能举例我会在它的 test 目录里放两个用例一个用例是空仓库期望输出是“未检测到代码文件”另一个用例是标准的 React TypeScript 项目期望输出包含“routes”“components”“hooks”三个关键模块名。跑测试时用脚本调用一下核心函数比较输出是否符合预期。测试不用做得很重能覆盖正常路径和异常路径就行。重要的是养成习惯技能改了测试也跟着改保证每个点位的技能包都是可信的。这也是 Karpathy 强调 skills 优于 prompt 的一个核心原因——技能代码可以被纳入 CI/CD 流程成为工程资产的一部分而 prompt 只能靠人肉回验。3.5 第五步安装、触发、调试形成闭环技能包写好后把它放到对应的 skills 目录下。如果是 Claude Code就放到~/.claude/skills/下如果是通过 npx 安装的直接执行 install 命令。然后启动 agent用一个测试任务验证模型是否能正确触发。调试阶段最容易出现两个问题。一是模型不触发技能这种情况 90% 是 description 写得不够具体或者没有命中模型当前的任务语境需要反复调整触发词。二是模型触发了技能但执行失败这种情况要看脚本输出和报错信息确认脚本在当前环境能独立运行。我调试技能时习惯用“直接对话”方式先在 agent 里手动输入一句能命中技能描述的任务比如“帮我分析当前仓库的前端模块结构”看模型是否会调用对应技能。如果没调用就去看日志或系统提示确认技能是否被正确加载。如果调用了但结果不对就单独在终端执行脚本定位是脚本问题还是调用方式问题。4. 社区热门 Skills 盘点哪些值得装哪些是智商税4.1 Coding 向技能包在 GitHub 上到底该搜什么热词列表里有一组高频搜索项coding skills github、codex skills、opencode skills、agent skills。这些搜索背后透露的信号是应用开发类的技能是目前社区最活跃的板块。GitHub 上有几个被反复推荐的仓库比如 anthropics/skills 下就有官方维护的文档和示例技能。社区里一些个人开发者把自己的技能仓库打上了awesome-skills之类的标签里面收集了几十个常用技能。这些仓库质量参差不齐安装前建议先看三点SKILL.md 写的是不是清楚、脚本有没有测试用例、最近一次 commit 是什么时候。那种只放了一个 README 没有实质脚本的“技能仓库”本质就是一篇 prompt 集合换了个皮安装了价值也不大。真正值得装的 coding 技能通常具备这样的特征解决了一个明确场景问题而且这个场景问题用 prompt 很难稳定解决。比如“自动生成代码提交信息”“按约定生成 API 文档”“分析代码圈复杂度并给出重构建议”这些技能因为结果边界清晰所以技能化效果非常明显。4.2 场景技能包前端、渗透、数模、公众号内容包热词里还有一批很有意思的场景化关键词前端开发 skills、渗透测试 skills、数学建模 skills、微信公众号文章相关的技有包 skills、结构图 skills、发明专利写作的 skills。这些词说明 skills 正在被应用到各行各业的具体工作流中。以“前端开发 skills”为例做的比较好的技能包通常组合了几个动作先分析 package.json和目录结构判断项目技术栈再识别路由配置和组件层级最后生成一个可读性极高的架构说明。这比直接丢给模型一个压缩包让它“自己看”要稳得多因为技能包内部知道该读哪些文件、该按什么顺序读、该总结哪些信息。“渗透测试 skills”这类技能包的思路也类似它不是要替代人工渗透测试而是把常见的预检步骤固定下来端口扫描、目录枚举、常见漏洞特征匹配。模型不需要记住 nmap 的参数技能脚本里全封装好了模型只需要判断“当前场景是否适合做端口扫描”。这类技能包的争议在于安全边界问题使用时注意遵守授权规则别乱扫。“数学建模 skills”则是我看到比较惊艳的一类。它把数据处理、模型选择、论文排版几个阶段拆成了单独的子技能数据预处理技能负责格式清洗和缺失值处理模型求解技能封装了几种常见算法的 Python 实现论文排版技能生成 LaTeX 模板。这种场景化拆解思路和 Karpathy 说的“几十个小专家的组合”完全吻合。这里说明一下这是我基于社区里常见做法整理的描述具体仓库建议自己去测评筛选。4.3 Superpower Skills 这类“全家桶”值不值得装热词里出现“superpower skills 安装”“前任skills官方下载”——没看错社区确实有人把某个技能包叫“前任”大概是玩梗。Superpower Skills 是目前社区里知名度较高的技能包集合作者把几十个技能打包发布覆盖了写作、编程、数据分析、项目管理等场景。我的实际体感是全家桶类技能包适合刚上手、想感受 skills 机制的开发者但对老手来说很多时候会感觉“哪个技能都用不上或者哪个技能都不够精确”。因为通用型技能包为了提高覆盖面技能的描述写得很宽泛触发机制就没那么精准了。比如“write-better-code”这种技能描述写的是“优化代码质量”但什么叫“质量好”在不同项目里标准完全不一致。所以我的建议是可以装全家桶感受一下但真正的生产环境技能还是要结合自己的项目场景去定制。你把常用的三五个流程固化成自己的 skill比安装 50 个泛化技能包要实用得多。技能包不在多在于准。5. Agent Skills 与 Harness 的关系为什么说这是“能力的操作系统”5.1 从单个技能到技能编排模型只是调度器Karpathy 反复提到 agent harness 这个词。Harness 可以理解成包裹在模型外面的一整套执行框架上下文管理系统、工具调用接口、权限控制、错误处理机制以及 skills 的加载和运行环境。模型是大脑harness 是身体skills 就是身体里一个个“肌肉记忆”。为什么说这个视角很重要因为当 skills 数量多起来之后真正的技术难点已经不再是“写一个技能”而是“让模型知道在什么场景调用什么技能以及技能之间如何编排”。比如你需要做一个数据周报仅仅有“数据查询”技能和“图表生成”技能还不够模型得知道先调数据查询再调图表生成最后再调周报排版。技能的编排顺序直接影响最终产出质量。目前常见的编排方式有两种一种是完全靠模型自发决策适合技能数量少、边界清晰的场景另一种是在 harness 层用 workflow 定义好技能调用顺序适合复杂任务。Karpathy 说的“rethinking skills and prompts for GPT-6 Astra”这类讨论其实就是在探索人机协作中哪些决策应该留给模型哪些决策应该由开发者在 harness 里提前锁死。5.2 Skills 落地的工程化版本控制、测试和共享技能包一旦进入生产环境就不能当个人脚本用了得按工程标准来管理。我现在的做法是把所有技能放到一个独立的 Git 仓库里每次修改技能都要走代码评审流程。仓库里每个技能有独立的目录、独立的 README、独立的测试用例。新成员入职拉到技能仓库就能获得和团队其他成员一样的 agent 能力。还有一个很重要的实践是技能的语义化版本管理。技能描述变了、脚本逻辑变了、甚至依赖的 Python 包版本变了都应该更新 version 字段。这样当 agent 返回结果质量突然变化时可以快速定位是不是最近的技能修改引起的。共享方面GitHub 是主流渠道。把技能仓库公开后别人可以直接用npx skills add来安装你的技能。但注意一个问题技能脚本会在使用者的机器上执行所以开源技能时一定要审视脚本内容别把内置了特殊路径、内网地址等不适合公开的内容放进去。5.3 哪些能力适合技能化哪些不适合不是所有任务都适合做成 skill。我总结了一个简单的判断标准重复度高的、确定性强的、结果有明确边界的任务适合技能化开放式的、需要创意灵感和大量主观判断的任务还是留给模型加 prompt 更合适。适合技能化的例子批量文件重命名、代码格式统一、接口自动化测试、日报生成、数据清洗。这些任务一旦固化效率提升非常明显。不适合技能化的例子写营销文案的“标题头脑风暴”、开放性的“产品方案策划”、需要大量审美判断的视觉设计。这些任务即使做成技能技能内部也无法做到全自动化最后还是要靠模型生成内容技能只起到提示词模板的作用。区分这两类任务的价值在于避免把时间浪费在那些根本无法收敛“正确结果”的技能上。Karpathy 在他的分享里也强调过类似的观点skills 的精髓是“确定性代替不确定性”。如果一个任务无法唯一定义“做完”的标准那技能化就得谨慎。6. 常见问题与排查技巧实录6.1 技能没有被加载或触发排查路径是什么这是自建技能后遇到最多的问题表现形式有几种模型根本不知道有技能存在、模型知道但从不主动调用、模型偶尔调用但触发时机不对。先说第一种。如果模型完全感知不到技能优先确认技能目录是否放对了。Claude Code 默认扫描~/.claude/skills/Codex 扫描~/.codex/skills/你如果放错目录加载日志里会有 warning。第二种“知道但不调用”基本是 description 的问题。可以试着把 description 改得更贴进模型的实际任务表达。因为模型做任务分类时会把你当前对话内容里的关键词和 skill 的 description 做匹配匹配度太低它就不会触发。第三种“触发时机不对”通常是 description 边界写得太宽。比如描述里写了“适用于代码分析”但模型在一个“代码生成”任务里也调用了这个技能那就是边界没写清楚需要把不适用场景也显式排除。6.2 脚本报错、权限不足、环境不一致怎么办技能脚本被模型调用时执行环境和手动执行时常常不同尤其是 PATH 环境变量和当前工作目录。比如你手动在终端跑一条命令能通但 agent 调技能时找不到命令这多半是 PATH 没继承。解决方法是脚本里显式使用绝对路径或者在脚本开头 source 当前 shell 的配置文件。权限问题也很常见。有些技能需要写文件、改 git 配置、下载依赖harness 默认的权限策略可能会拦截。这种情况不要盲目放开所有权限最好在技能里声明最小权限需求并在 SKILL.md 的 allowed-tools 字段里列清楚。系统提示词没给足权限时模型也会在调用环节犹豫所以确认 allowed-tools 和描述一致也很重要。Windows 和 Linux 之间的跨平台性问题是脚本技能的另一个重灾区。shell 命令不同、路径分隔符不同、Python 包管理器的差异都可能导致技能在另一台机器上直接失效。建议在脚本开头做一次平台判断必要时为不同平台写不同的分支逻辑。别偷懒技能包一旦给别人用跨平台问题早晚会找上门。6.3 描述写好了但模型就是不按预期用技能怎么办遇到这种情况先别急着怀疑模型能力先回头检查你的描述是否带有“歧义”。描述里如果用了一堆同义词比如“分析”“解析”“检查”“审查”混着写模型可能在你期望的“分析”场景里选择了“检查”这时候看起来就像是“不按预期用”其实模型只是按自己的理解做了选择。另一个容易被忽略的点是 SKILL.md 的前置条件没写清楚。技能需要什么输入、在什么状态下可以调用、调用前是否需要先执行别的步骤这些都要在描述里写清楚。模型如果觉得当前状态不满足技能前置条件它就不调用这不是模型懒而是你的描述让它觉得“时机未到”。如果做了这些调整还是不行那就建议不要在纯自然语言里硬抠触发逻辑了。直接把技能的调用约束写进 harness 层的 workflow 里用代码逻辑强制模型在某个步骤必须调用某个技能。说白了prompt 做不到的事交给代码来做——这本来就是 skills 的核心思路。6.4 技能包本身应该怎么维护和演进技能包的维护和业务代码一样要定期评审、更新、淘汰。我见过很多团队的技能仓库半年不更新等 Agent 效果变差了才发现原来某个技能依赖的 API 已经变了或者模型版本升级后描述里的触发词汇已经被新模型“换了一种说法”理解。我的实操建议是每个月做一次技能巡检重点看三项内容——每个技能近一个月的调用次数、失败率、输出质量是否达标。调用次数为 0 的技能要考虑是不是已经失配失败率高的技能要看脚本是不是需要升级输出质量不达标的技能要么改描述要么改实现要么直接移除。技能不是越多越好五十个失效技能带着运行反而会污染模型的选择空间让它更频繁地做出错误调用。维护技能这件事本质上就像维护一个内部工具库。工具库讲究的是“有人负责、有人用、有人改”技能包也一样。把技能当成代码资产来管理它就能持续提供价值。7. 实践中的一点体会和一些尚未解决的问题自己动手做了一批技能包之后我有个很深的感受真正拉开 agent 能力差距的不是模型的选型而是技能包的质量和编排水平。同一个模型配上合适的技能包输出质量可以产生质的提升反过来模型再好没有可靠的技能支撑还是会出现各种“有想法但落不了地”的问题。目前还有几个问题我没有找到特别满意的解决方案。一个是技能的通用性和定制性的平衡技能写得太具体换一个项目就没法用写得太通用又容易触发不准。另一个是技能之间的冲突有时候多个技能号称都能处理同类任务模型不知道该选哪个输出的结果时好时坏。这些问题可能还要等社区出现更好的编排模式才解得开。但就当前阶段来说把“能写 prompt”升级成“能写技能包”是每个做 agent 应用的开发者都值得花时间投入的方向。先从一个最小的技能开始把自己日常最常做、最花时间和人工的任务挑出来试着固化成技能跑通一次完整流程你就知道这条路的价值了。