我最近在整理自己的 AI 使用工作台时发现自己手里攒了一大堆 skills 文件。很多人第一次听到这个词以为又是某种新兴的提示词技巧实际上它比提示词工程往前迈了一大步。简单说Agent Skills代理技能就是把一个专家做事的整套方法——步骤、判断标准、经验、模板、小工具——全部打包成一个可复用的文件夹交给 AI 代理在合适的时机去自动调用。这篇文章不讲虚的我会用自己实际构建、测试、迭代多个技能的经验带你从零看懂 Skills 的内部结构动手做一个真正能用的技能并把它和 MCP、Subagents 的边界彻底理清楚。不管你是重度用 Claude 的开发者还是正在折腾各类 Agent 工具的产品运营这套方法论都通用。1. 先别急着写代码理解 Skills 到底是什么1.1 Skill 改变的是“会做”到“按方法做”我最早对技能的理解也是错的。当时我以为是某种更高级的提示词模板往里面塞一堆“你是一个专家”之类的角色设定就能解决问题。直到我负责给团队搭建一套自动化周报流程时才发现问题真正出在过程一致性上。折腾了大半周的方案每次跑出来的格式都不一样光是调整模板就花了两天这让我意识到提示词并不能稳定约束具体流程。举个例子。没有技能时你跟 AI 说“把今天的销售数据整理成日报”它确实会给你一份日报但它的处理路径完全是黑盒今天先写结论明天先列表格后天又改成纯文字。哪怕你在提示词里写得再细它也只能做到“听一次做一次”换个输入场景就立刻变形。而技能解决的恰恰是把“怎么做这件事”沉淀成一套可执行手册。我习惯用一个类比来解释提示词是你在派对一个新员工时说的那句“好好干”技能则是递过去的那本部门 SOP 手册。手册里不但写清楚了岗位目标还规定了第一步做什么、遇到什么情况走哪条分支、什么数据必须填、什么话术不能用。新员工甚至不用特别聪明只要照着手册走输出的下限就能保证。这个逻辑落到 Agent 身上完全成立——模型能力再强也需要一个外部约束来兜住结果的一致性。1.2 为什么这个时间点开始流行从技术演进看技能概念的流行不是偶然。前两年大家还在拼命研究“怎么把提示词写得更长更细”但很快就发现提示词的边际效益到头了它没有目录、没有依赖、没有版本一百行提示词堆进上下文模型反而抓不住重点。代码工具那边倒是成熟可又要求使用者具备编程能力而且把任何流程改动都变成重新开发。技能正好卡在中间这个断档上。它用结构化的文件夹组织能力既不需要你写多复杂的代码又能提供比提示词更稳定的工程化保障。再加上 Agent 工具本身的生态起来了各家都开始对齐“技能包”这种可分发、可插拔的格式做一次技能就能反复使用甚至可以跨团队共享于是这套东西一下子就火了。说实话现在讨论技能更像在讨论“Agent 时代的插件规范”。它把过去散落在个人对话框里的优质思路变成了能被发现、被复用、被迭代的工程资产。对我这种需要同时对付开发、运营、写作多重角色的人来说每一次沉淀都是实打实的省时间。现在回头看技能火起来几乎是必然因为模型能力已经冲到了前面工程化封装反而成了真正限制落地效率的瓶颈。1.3 Skills 和普通 Prompt 文件的分水岭很多人都会问我同一个问题我文件里已经积累了几十个 prompt 模板和 skills 到底有什么区别。我的回答通常很直接prompt 是交流产物skill 是工程产物。交流产物的使命是把意思表达清楚用完即走工程产物则必须考虑结构、版本、依赖、复用和可维护性它要在一套系统里长期运行。一旦想通这一层很多设计决策就不用再纠结了。你还可以从几个更具体的维度来观察。复用方式prompt 只能靠复制粘贴改一处全盘重来skill 有独立目录和参数入口可以像安装插件一样被 Agent 自动发现。内容结构prompt 是一段连续文本毫无分层skill 至少拆成主文件、参考资料、模板、脚本四部分分别承担不同的职责。触发机制prompt 要手动喂给模型模型才知道该做什么skill 自带 description 触发条件模型能根据你的当前任务自行决策是否调用。质量保障prompt 输出全看模型发挥skill 可以在流程里内置自查清单、校验脚本甚至 dry-run 模式从机制上逼近稳定输出。演进方式prompt 改完没有痕迹skill 可以打版本号、写 changelog、做灰度验证慢慢变成一条团队标准。所以我一直建议那些一周之内没用到第二次的 prompt没必要硬升级成 skill。真正值得沉淀的是你每天都在做、且步骤固定、有明确质量标准的重复性事务。这样的东西做成技能才有价值。2. 拆开一个 Skill 看内部结构2.1 目录放哪里决定它给谁用技能本质上就是一个包含元数据的文件夹但放在哪里直接决定它的生效范围。主流 Agent 工具普遍约定两类位置。第一类是个人级技能库一般放在用户主目录下的.claude/skills其他框架可能叫.agent/skills它对你启动的所有项目生效适合放那些与具体代码仓库无关的通用能力比如写周报、做会议纪要、整理 changelog。第二类是项目级技能库放在当前工程根目录下的.claude/skills只对这个项目生效适合放和项目强相关的流程比如“按本仓库规范提交代码”“按内部标准生成 API 文档”。更细一点说技能包还支持通过插件机制分发。第三方技能会带一个plugin.json里面声明了技能的名称、作者、描述和文件清单工具启动时会自动扫描并加载。我自己的习惯是个人技能负责“你这个人擅长的东西”项目技能负责“这个项目特有的规矩”插件技能负责“别人帮你打包好的能力”。三者的装载优先级一般以项目级为最高避免和通用技能冲突。如果你发现某个技能在 A 项目里行为正常、在 B 项目里完全不触发优先检查是不是目录放错了作用域。2.2 frontmatter技能的名称和触发逻辑每个技能的主目录下必须有一个SKILL.md它是技能的门面也是 Agent 首先要读的文件。文件开头用 YAML frontmatter 定义元信息至少包含name和description两个字段。name要短、要语义化我建议用“动词-对象”的形式比如weekly-report、code-review、meeting-minutes这样在日志里看调用来源时一目了然。description才是真正决定“什么时候触发”的字段它会在每次任务开始前被 Agent 扫描。写 description 的第一原则是写明适用条件而不是写功能宣传。比如不能说“用于生成周报”而要说“当用户提供本周工作记录、或者提到周报、本周总结、日报汇总时使用该技能生成结构化周报”。条件写得越具体触发准确率越高。还有一个容易忽略的细节frontmatter 里不要用特殊字符和复杂引号。YAML 解析器对这些很敏感凡是遇到冒号、列表符号宁可拆成两行纯文本也别硬挤在一行。我踩过一次很蠢的坑在 description 里写了一个带英文冒号的完整句子结果整个技能加载失败排查了半天才发现是格式问题。从那以后我写 frontmatter 都会刻意避开英文标点只用最基础的键值对结构。2.3 渐进披露主文件要薄细节要厚技能设计里最容易被新手搞反的是把SKILL.md写成一本百科全书。几十个大步骤外加各种判断分支全塞在主文件里。Agent 每次加载技能都会先把这些内容读进上下文第一步还没做完几千 token 已经烧掉了。而且信息密度太低模型根本分不清优先级等于给它发了厚厚一本说明书最后只记住了目录。正确做法是“渐进披露”。SKILL.md只保留最核心的目标、流程主线和硬性约束通常控制在 40 到 60 行以内。所有需要展开的细节按用途拆到references/、scripts/、templates/子目录里。主文件里只需要写“当遇到 XX 情况时阅读 references/xxx.md 再继续”模型只在真正走到那个分支时才按需加载对应文档。这个设计和本科教材的思路很像目录和导论给你一个整体框架真正推导细节的章节放在后面你不需要为了读第一页就把整本书背下来。放到技能上收益直接体现在 token 开销和响应速度上。技能越精细这种分层带来的收益越明显尤其当技能库里有二三十个技能的时候谁能在加载阶段保持轻量谁就能真正用好这套机制。3. 从零做一个“周报 Skill”3.1 先划边界这个技能到底管什么动手之前先把技能的功能边界画清楚这是我反复强调的一步。以周报技能为例我在公司内部定义它的职责是把零散的工作记录整理成一份结构化、可量化、可归档的周报。这里面的关键词是“整理”不是“代写”也不是“自动取数”。那“不做什么”同样重要。我不会让这个技能自动去访问外部系统拉取数据那属于 MCP 的活我也不会让它直接替用户决定哪些事项上头条决策权必须留给人。边界越窄技能的行为越可控后续测试和维护的成本也越低。你甚至可以在这个步骤里顺便列一份排除清单写进SKILL.md的“禁止事项”里从机制上防止模型跑偏。这个排除清单写得越具体模型就越不容易在输出里自由发挥。3.2 骨架搭建和主文件编写确定边界后开始搭建目录。一个最小可用的技能结构大概长这样。.claude/skills/weekly-report/ ├── SKILL.md ├── references/ │ ├── format-guidelines.md │ └── grading-rubric.md ├── scripts/ │ └── extract-metrics.py └── templates/ └── weekly-report.mdSKILL.md是入口。我的初版通常只写目标、主流程和红线要求尽量不出现分支细节。--- name: weekly-report description: 当用户提供本周工作记录、会议纪要或零散事项且提到“周报”“本周总结”“周会材料”时使用此技能将输入整理为结构化周报。 --- # 任务目标 将输入的工作记录整理成一份结构清晰、数据可查的周报方便团队周会使用和归档。 # 工作流程 1. 收集读取用户提供的所有工作记录、会议纪要、任务列表。 2. 归类按“重点项目推进”“日常运维”“团队协作”“风险与阻塞”四类整理。 3. 量化将模糊表达改写为有数据、有结果的表述数字必须来自输入。 4. 输出按 templates/weekly-report.md 渲染输出前先向用户确认归类是否合理。 # 硬性要求 - 不得编造数据任何数字必须能在原始记录中找到来源。 - 每条工作事项控制在 30 字以内突出产出而非过程。 - 输入信息不足时明确标注“待补充”禁止猜测。 # 进阶参考 - 涉及跨部门协作内容时阅读 references/grading-rubric.md。 - 涉及指标计算时使用 scripts/extract-metrics.py 并说明计算口径。这个模板的主流程只有四步模型一眼能看完红线要求直接钳住最常见的犯错场景编数据、写流水账、无中生有。templates/weekly-report.md是输出骨架规定了周报的章节顺序、标题层级和填写规则模型照着填空格式稳定度会大幅提升。references/里放更细的操作标准和示例比如“风险与阻塞这一类应该描述什么、应该附上什么证据”这些内容不需要每次装载只在模型判定自己遇到对应分支时才翻看。3.3 写好 description让 AI 在正确时机调用在我实际用过几十个技能之后可以下这个结论description写得好不好决定了技能一半的成败。它有几乎反直觉的规则宁可啰嗦一点也要把触发条件交代清楚。一个好 description 至少包含三个要素用户会怎么表达这个需求也就是触发词输入大概长什么样也就是输入形态什么时候不应该使用该技能也就是负向条件。比如“当用户提到周报、本周总结、周会材料”这是触发词“并提供工作记录、git commit、会议纪要等原始材料”这是输入形态“如果用户只是想修改某一条文字而没有整理诉求则不使用”这是负向条件。把这三个要素写进 description模型在任务起步阶段就能快速判断该不该调用误触发的概率会低很多。我见过很多人把 description 写成“这是一个爆款周报技能能够把一切杂乱信息变成高转化率高可读性的周报”这种营销式文案对模型没有任何作用。模型只能吸收语义信息不能被你夸大其词的形容词打动。所以描述要像给同事写交接说明而不是写广告文案。写完之后不妨自问一句如果我是模型这段描述能让我清楚知道“什么时候出手”吗3.4 用真实输入测试并迭代技能写完不是终点第一次测试会暴露一整套问题。最好的测试方式是回到真实对话里用你手头真实的零散记录去触发它。执行阶段观察两件事第一技能有没有在预期时机被自动调用第二调用之后是不是严格按主流程走完。第一次跑我的周报技能时模型确实被成功触发了但它在归类那一步出了岔子把两条“和客户对需求”的事项分别放进了“重点项目推进”和“团队协作”理由写着“因为一个是推进需求、一个是协作沟通”。其实输入里的信息不足正确做法是合并成一条而不是硬拆。我没有去改流程而是在references/grading-rubric.md里加了一条判定标准来源相同、时间相同的两件事原则上一律合并。这个细节调整之后类似问题再没出现过。整个迭代周期建议控制在两天内完成三轮测试初版、修正版、稳定版。每轮记录“触发是否准确”“流程是否稳定”“输出是否达标”三项指标。一轮测试下来你的技能距离可复用状态就不远了。这里真正的坑是“舍不得删”总觉得每个细节都有用结果主文件越来越重模型越来越乱。测试阶段要学会果断丢弃低信息量的描述只保留能直接指导行为的句子。4. Skills、MCP 与 Subagents 的正确配合4.1 一张表看清三者的分工在 Agent 生态里技能经常和 MCP、Subagents 放在一起聊但三者解决的问题完全不同。我用一张表把它们的分工固定下来。维度SkillsMCPSubagents本质做事的方法和流程连接外部工具和数据的能力任务分解与并行执行存储形态本地文件目录一个服务进程或远端接口程序化子任务配置依赖关系不依赖网络只依赖模型必须通过工具协议通信依赖主 Agent 调度典型场景周报、代码审查、会议纪要查数据库、调 API、发消息并行做需求拆分、测试用例改造成本低改文档即可中需要写工具定义中需要设计任务边界典型误用把 API 密钥和网络调用写进技能把多步流程判断都塞进工具把全部状态都丢给子代理这张表我看着特别有感觉。技能是最接近“人脑方法”的抽象MCP 是“人的手脚”的外延Subagents 则像是“一个团队里的临时成员”。你想让 Agent 真正像个老手一样干活三者其实是配合关系而不是竞争关系。很多人一上来就问“我该用 skills 还是 MCP”这本身就是伪命题关键看你需要解决的问题落在哪个层面。4.2 组合示例拉取数据到生成结果光看定义很难有体感我拿一个真实工作流来演示项目发版后需要自动整理 changelog 和更新风险清单。第一步用 MCP 连接 git 仓库和项目管理系统拉出本次发版涉及的所有 commit、PR 以及关联需求单。这一步解决了“数据从哪来”的问题MCP 负责把外部信息接入上下文。第二步调用changelog技能让模型按仓库规范把原始 commit 分类成功能、修复、重构三类生成人类可读的 changelog。这是典型的技能职责——把输入的原始数据按照既定标准加工成标准化产出。第三步把 changelog 中的新增功能内容输入给一个risk-review子代理让它并行评估每个新功能的技术风险并给出测试建议。在这个流程里MCP 负责取数技能负责加工子代理负责专项分析。三个环节各司其职就没有必要在技能里硬写一段网络请求代码也不必把整个风险评审塞进技能保持单层职责边界流程才经得起长时间复用。4.3 我踩过的边界坑边界问题我栽过几次说一个最有代表性的。有一段时间我需要让 Agent 生成带实时数据的销售日报。我嫌 MCP 配置麻烦直接在技能里写了一段调用外部接口的 shell 脚本密钥也顺手写进了技能目录。结果两周后这个技能被共享到项目仓库密钥也随之进入公共视野差点酿成事故。那次教训让我彻底定了规矩技能里永远不碰外部连接凡是需要实时数据的地方一律交给 MCP。技能里最多保留对 MCP 返回数据的加工规则这样职责划分干净也规避了敏感信息泄露风险。还有一个容易踩的坑是把太多决策逻辑塞进 subagent导致子代理脱离主流程。主 Agent 该做的流程控制一旦下沉到子代理整个任务的进度和结果质量就变得不可控。我现在的原则是“技能管方法、MCP 管连接、主代理管状态和调度”。这九个字挂在嘴边绝大多数架构问题都迎刃而解。5. 把 Skills 变成个人工作资产5.1 个人技能库的目录与命名规范技能一旦多起来命名和归类的混乱程度会指数级上升。我现在有三十多个常用技能靠的就是一套简单但严格的规范。首先是目录统一。个人技能全部放在~/.claude/skills/每个技能一个独立文件夹文件夹名就是技能名。其次是命名统一。一律使用动词-对象的形式比如generate-weekly-report、review-pull-request、summarize-meeting避免出现“周报123”“最终版skill”这类没法看的名字。最后是索引统一。在技能库根目录放一个README.md把每个技能的触发条件、适用场景和最近更新版本写成一页索引这样我每次想找技能都不需要逐个翻目录。这套规范带来的收益很直接。给技能写调用日志时日志里能看到清晰的技能名写插件配置时名称不会因为大小写、标点产生歧义更重要的是当我把技能库放进 git 仓库管理时commit 历史会非常清晰回滚和协作都变得容易。很多人的技能库写成一团乱麻不是工具不支持纯粹是命名和目录没规划好。5.2 团队分发与版本管理个人管理得再好团队协作才是技能真正发挥威力的场景。把技能库做成 git 仓库后我通常按两个维度组织根目录下skills/放公共技能projects/下按项目分目录放项目私有技能。分发方面可以直接让团队 clone 这个仓库并按约定把仓库路径配置成工具的技能目录也可以打成插件包依赖plugin.json描述元数据和依赖关系共享给没有代码权限的同事。无论哪种方式都要做两件事一是写清使用文档说明技能触发条件、输入要求、输出预期二是把技能的版本号写进元数据避免团队里有人还停留在旧版本。版本管理的核心不是复杂的分支策略而是简单的可见性。我习惯每个技能文件夹里放一行version记录并在文档里汇总每次改动的意图和日期。一旦某个技能在线上出了问题第一时间能知道是从哪个版本开始引入的这比重新翻整个目录高效得多。还有一点团队公共技能一定不要随便推送到 master先在自己分支上跑几轮真实用例确认没有破坏性变更再合入。5.3 迭代方法论小步快跑而不是大改很多人在给技能做升级时总想一次把它做成“完美版本”结果战线拉长、测试不到位技能反而退步。我的经验是每一轮迭代只改一个变量一次只调整一个流程分支或者一次只收紧一条硬性要求。改完立刻跑一次真实场景没有回归问题再进入下一个改动。还有一条实战心得不建议让技能“自己写自己”。听起来很高级但 Agent 一旦具备修改自身文件的能力很容易进入循环为了让输出更符合预期它会在主文件里不断叠加条件最后把一个简洁技能写成庞然大物。这个过程的不可控程度我亲测过毫无必要。把技能的演进权握在人类手里每次改动都经过审视长期看反而是最快的路径。6. 使用 Skills 的常见问题排查记录6.1 技能没有被自动调用这是新手上路碰到最多的状况。可能性按顺序排查如下。第一检查description是不是写得太宽泛导致模型无法在触发条件里精确匹配。比如只说“用于周报”它很难判断什么时候该用改成“当用户提供工作记录且提到周报时”命中率立刻上升。第二检查目录名称和大小写Linux 环境下路径大小写敏感weekly-report写成Weekly-Report就可能导致扫描失败。第三检查所在目录~/.claude/skills与项目根目录.claude/skills的作用域不同技能放错位置自然不会被加载。第四检查插件状态如果技能是从第三方插件加载的确认插件在配置里是启用状态。我自己的排查套路是先用一条包含明确触发词的指令去测试比如直接说“请把以下内容整理成周报”如果还不触发再逐个检查上述四项。这个方法在绝大多数场景下都能定位到原因。如果四项都没问题才去考虑是不是工具版本太旧不支持新格式的技能目录这种情况虽然少见但升级工具后经常自然解决。6.2 模型不按流程走触发了但模型自行发挥。这通常不是模型不听话而是主文件里的流程写得太模糊。技能主文件中描述的步骤如果只是“整理工作记录”“生成周报”模型能理解的空间就很大自然会按自己的习惯执行。解决起来有三个办法。第一用“必须”字眼强化流程中的不可变步骤且步骤编号清晰让模型明确这是一个顺序链路。第二把任何选择分支下沉到references/文件主文件只保留唯一主路径这样模型不需要在每一步做判断题。第三删掉优先级不高的说明某种意义上的断舍离主文件越短被忽略的风险越低。我在周报技能的实践里就做过类似调整把“归类时来源相同、时间相同的两条事项默认合并”写进参考资料后模型的行为明显稳定了。如果你发现自己已经在主文件里写了“可以”“通常”“一般建议”那就要警觉了这些含糊词会把模型引向自由发挥的方向。6.3 Token 开销与控制技能用久了token 浪费会成为隐痛。如果你发现对话上下文动不动就几十万 token先看是不是SKILL.md过于臃肿把所有参考内容都内联在主文件里了。渐进披露是解决 token 开销的最好工具主文件只留线索模型在走到对应分支时才去读references/。另外技能的加载是持续性的它只要出现在技能库里就会被模型自动识别为可调用对象。如果某些技能你已经一周都没用上不如暂时移出活跃目录放进skills-archive/归档。这既减少了模型的扫描负担也让活跃技能列表保持精简有度。实际效果比我预想的还要明显归档掉十来个低频技能后日常会话的响应速度和上下文清晰度都有了可感知的提升。再分享一个细节工具运行时可以开启 verbose 日志观察每次任务实际加载了哪些文件。很多你以为被读进去的内容压根不会进入上下文先看了日志再优化比盲猜高效得多。我见过一个团队把技能从几千 token 优化到几百 token方法就是把主文件里的每个段落逐一确认“是否有用”没用的全部下沉或删除。6.4 自查清单和进阶小技巧最后说一个我愿意分享给所有人的技巧给技能内置一份“输出自查清单”。在SKILL.md的最后加一段强制要求让模型在输出完成前逐项检查“是否所有数字都有来源”“是否遵守了模板格式”“是否存在冗余表述”“是否识别了待补充项”。这条要求很小但对输出质量的稳定作用非常明显因为模型在生成完之后再回看一眼能把最常见的低级错误从源头拦下来。很多技能之所以输出忽好忽坏不是模型能力波动而是缺了这个最后的校验环节。有了自查清单就相当于给流程加了一道质检工序。进阶玩法是给技能设计一个--dry-run参数模式。输出正式文本之前先让模型只输出一个结构预览比如周报标题和小节纲要用户确认后再渲染完整内容。这个设计对生成文档类内容尤其友好既能避免写到一半发现方向错误又能让用户对 AI 输出保持一定的控制感。我后来把这个模式复制到了好几个技能里凡是产出物超过两百字的内容都会先跑一遍预览实际协作体验提升得很明显。从我自己的体会来看技能不是越复杂越高级而是越贴合你真实现场、越能让模型稳定交付的东西才算真本事。你今天可以挑一个自己重复了一星期的事务性工作把它做成第一个技能跑上一周再回头看大概率不会再想回到没有技能的日子。