1. 从每次都要重新交代一遍说起我为什么会研究 Skills如果你也试过每次让 AI 助手干活前都要把同一套流程说明、输出格式、注意事项从头到尾复制粘贴一遍那你一定懂我的烦躁。连续帮同一个项目做代码审查到第三天我决定认真把 Agent Skills 这套思路捡起来研究结果不仅省掉了反复粘贴的体力活还顺带把整个团队的 AI 协作方式重新梳理了一遍。1.1 一个让我崩溃的日常场景我的日常有一大块工作是给项目做代码审查。最初我用 AI 助手的方式很原始每次打开新会话先贴一段你是资深工程师请按 XX 规范审查重点关注安全性和可维护性输出格式为问题列表再贴上 diff等结果。一天最多的时候我要复制这段前置指令五六次而且每次措辞还有细微出入——今天多写了一句别忘了检查 SQL 注入明天忘了写按严重程度排序。更麻烦的是这类长 prompt根本没法维护。今天加一条规则明天删一个步骤分散在十几个聊天记录里谁也说不清当前版本是什么。等团队里其他人想复用我这套审查方式时只能靠我把文字一段段发过去复制错了也没人发现。后来我开始认真研究 Agent Skills。说白了它就是把给 AI 的指令 配套的脚本 参考资料打包成一个标准目录放进约定的文件夹AI 助手就能在需要的时候自动发现并使用。这个思路解决的不是能不能生成代码的问题而是如何稳定地让 AI 按我的流程办事的问题。1.2 Skills 到底解决了什么问题一个 Skill技能包在我看来就是一个自包含的文件夹里面至少有一个SKILL.md文件这个文件用 YAML frontmatter 写元信息用 Markdown 正文写具体执行步骤旁边可以放脚本、模板、代码片段、参考文档等附属资源。以我日常使用的 Claude Code 生态为例官方把这套机制叫做 Agent Skills典型的目录结构长这样~/.claude/skills/ └── code-review/ ├── SKILL.md ├── checklist.md └── scripts/ └── run_review.pyAI 助手在启动时会先看到所有技能的目录清单知道每个技能叫什么、是干什么的这部分只有 name 和 description体积很小等到某个任务和某个技能描述匹配上了才会去读取那个技能的完整SKILL.md正文里提到需要某个脚本或模板时再按需加载那些附属文件。这个机制有点像家里的工具箱。你不需要把电钻、水平仪、螺丝刀全部握在手上才能干活你只需要知道柜子里有什么工具、每把工具标签上写了什么用途等真需要拧螺丝的时候再打开抽屉取出那把螺丝刀。整套文件都在柜子里但你手里始终只拿着当前需要的那件。值得一提的是这套抽象在多个厂商的生态里正在快速收敛。除了 Anthropic 的 Agent SkillsOpenAI 的 AgentKit 里也有名为 Skills 的能力封装社区里还出现了各种开源的多 Agent 技能格式。各家在命名、目录约定、字段细节上还有差异但骨架是一致的可发现、按需加载、自带方法论的可复用指令包。这也是我敢投入精力去研究它的原因——就算底层模型换成别家这套思维方式也大概率能平移过去。1.3 适合谁读这篇文章我想把这篇写成一份实战手记而不是官方文档的转述。如果你属于下面任何一类应该会有收获重度使用 AI 编程助手但一直在靠复制粘贴长指令干活团队里希望大家用同一套标准和流程调用 AI而不是每人一套 prompt遇到AI 每次给的答案风格差别很大、换个人问结果完全不一样这类问题希望把不确定性压下来。接下来我会按这样的顺序讲先拆解 Skill 包的文件结构和工作原理再对比它和 MCP、Subagent 的分工边界然后手把手带你把一个代码审查技能包从零写出来最后分享我迭代过程中踩过的坑和几条个人体会。2. 拆开一个 Skill 看看SKILL.md 与目录结构2.1 目录结构长什么样技能包本质上就是一个文件夹里面必须有一个SKILL.md。以 Claude Code 生态的约定为例技能通常放在三个层级放置位置作用范围典型用途~/.claude/skills/个人所有项目放自己最常用的通用技能比如会议纪要、提交信息生成项目/.claude/skills/当前项目团队放项目特有的规范比如该项目的数据库迁移审查流程插件plugin里可以随项目分发把整套技能打包进团队脚手架新成员 clone 即用放在这三处本质上都只是目录约定不用安装什么依赖。你把一个带SKILL.md的文件夹放进去AI 助手重启会话后就能发现它。举个例子你可以直接这样创建一个个人级技能mkdir -p ~/.claude/skills/code-review/{scripts,templates}就这么简单剩下的工作是把SKILL.md写出来。哪怕你现在用的是其他 AI 编码工具只要它支持技能或自定义指令这类机制思路都可以按同一套来一个文件夹、一份带元信息的说明文档、若干配套资源。2.2 SKILL.md 的 frontmatter 字段SKILL.md的头部是一段 YAML frontmatter常见字段长这样--- name: code-review description: 对代码变更进行系统化审查适用于 PR/MR 评审、提交前自查以及帮我看看这段代码有什么问题之类的请求。当用户提到 review、code review、代码审查、CR 时优先使用本技能。 allowed-tools: - Read - Grep - Bash - Write version: 1.2.0 license: MIT ---每个字段的作用不一样我的经验是name技能的内部标识一般用小写字母、数字、短横线。它主要用来被skill-name这种方式显式引用也方便你在日志里看到底是哪个技能被触发了。description这是整个技能包里最重要的字段。AI 助手判断当前任务要不要用这个技能时主要就是靠它。写得好模型在合适的时机自然想起它写得敷衍技能根本不会被触发。allowed-tools可选字段限定这个技能执行时可以使用哪些工具白名单。如果你不想让技能通过 Bash 随意改文件就把Edit、Write排除掉。version / license / metadata可选字段主要用于版本管理和团队分发。数量多了之后你一定会感谢自己当初顺手写了 version。2.3 渐进式披露Progressive Disclosure理解渐进式披露是掌握 Skills 的关键。在 Claude Code 这类实现里AI 助手的上下文窗口里平时只保留一份技能清单每一条包括技能名和 description可能还有版本号。这部分信息很轻几十个技能也不会占用太多 token。只有判断当前任务与某个技能匹配时它才会去读取该技能的SKILL.md全文而SKILL.md里引用的附属脚本、模板则要等真正派上用场时才加载。这个设计非常聪明因为我早年写过那种把所有规则一口气塞进 system prompt的做法很快就撞到几个问题指令太长后模型会选择性遗忘中间内容无关任务的场景也要白白承担这些 token 的开销想改一条规则还得在那段几千字的 prompt 里找半天。渐进式披露等于把常驻内存和磁盘中的文档做了分层。清单常驻全文按需加载。就像图书馆里你只需要随身带着检索卡片真要读某本书时才去书库取而不是把所有书都扛在背上。提示这也反过来提醒你SKILL.md的开篇和 description 一定要把什么时候用、怎么用说清楚因为模型做触发判断时只看这几行字。具体操作步骤写得再完美触发条件写得模糊技能也只会躺在文件夹里吃灰。3. Skills、MCP、Subagent这三兄弟到底怎么分工3.1 各自解决的问题第一次接触 Skills 的人最容易混淆的是它和 MCPModel Context Protocol工具、Subagent子代理到底什么关系我的理解是它们解决的是三个不同维度的问题。Skill解决的是怎么干它给模型提供了一套做事的流程、规范和领域知识。比如代码审查应该先看什么再看什么、输出格式是什么、哪些红线必须检查。MCP Tool / Function Call解决的是能干什么它给模型提供了操作外部世界的能力比如读文件、查数据库、调外部 API、在某个系统里创建工单。Subagent解决的是让谁去干它把一整块任务交给一个独立上下文的子代理区处理主代理不掺和中间的每一步只接收最终结果。可以用一张表把它们的差异列开对比维度SkillMCP ToolSubagent抽象层次方法论/流程操作能力独立执行者主要开销按需加载指令文本工具定义与调用独立上下文窗口是否可复用跨项目、跨会话直接复用配置好后通用通常按任务现场创建典型场景代码审查、会议纪要、发布检查读仓库、跑测试、调接口深度专项分析、长链路调研打个比方Skill 是操作手册MCP 是工具柜里的电钻Subagent 是你临时请来的老师傅。老师傅需要看操作手册Skill来了解你们团队的标准也需要用电钻MCP来施工但你不必每一步都盯着他。3.2 什么时候应该写成一个 Skill我在实战里总结了一个很简单的判断标准只要某个任务满足固定方法论 多步流程 需要领域规则而且你希望换个项目、换个会话之后还能用同样的方式完成就应该封装成 Skill。反之如果只是一次性让模型帮你改个正则表达式写成技能反而是过度设计。举个例子下面这几种都适合做成 Skill代码审查、依赖升级检查、安全扫描生成符合规范的 Git 提交信息、变更日志整理会议纪要并将行动项导出到指定格式按公司模板写技术方案、写复盘文档。一旦你开始把高频使用的 prompt 模板逐个技能化就会发现它们的共性有明确的输入、有稳定的步骤、有统一的输出格式。这正是适合固化下来的东西。3.3 一个典型的协作场景三者不是互斥关系实际项目里经常配合使用。我说一个自己最近在用的场景每次要审查一个 PR 时AI 助手会通过 MCP 提供的仓库读取能力拿到 diff 文件接着它发现任务和code-review这个技能描述匹配于是加载SKILL.md按照里面定义的流程开始逐层分析先跑一个 Python 脚本来做静态扫描脚本是技能包自带的再对照checklist.md逐项检查最后按模板输出审查报告。如果某个文件特别复杂主代理还可以派一个 Subagent 去专门深挖那段逻辑拿到结论后再汇总进报告。整个过程里技能负责按什么节奏做MCP 负责每一步怎么拿数据Subagent 负责把难啃的骨头丢给独立上下文去啃。4. 手把手把代码审查这个技能包从零写好4.1 先定义边界别贪多我第一次写技能就犯了个典型错误想一个技能包解决所有问题把风格审查、性能审查、安全审查、架构审查全塞进一个SKILL.md里。结果文档写了快两千行模型根本记不住触发之后表现还不如不触发。后来的经验是一个技能只做一件事把边界划清楚。所以我这里拿代码审查举例但刻意把它限定为一个具体场景——针对一个 PR/MR 的改动做正确性和安全性审查不做大架构评审。先想清楚三件事输入一个 PR 的 diff、相关文件路径、可参考的近期改动背景输出问题列表含严重程度、文件位置、代码引用、修改建议外加一个总结段落红线安全类问题注入、硬编码密钥、危险的默认参数必须强制标记为 High。边界一旦明确写SKILL.md就不会东拉西扯。4.2 写一份合格的 SKILL.md下面是一个可以直接抄的示例你完全可以把名字和细节换成自己的场景--- name: code-review description: 对代码变更进行系统化审查适用于 PR/MR 评审、提交前自查以及帮我看看这段代码有什么问题之类的请求。当用户提到 review、code review、代码审查、CR 时优先使用本技能。 allowed-tools: - Read - Grep - Bash - Write --- # Code Review 对一次代码变更进行系统性审查重点关注正确性和安全性兼顾可维护性。 ## 什么时候使用 - 用户请求审查一个 PR/MR 的 diff - 用户说帮我 review 一下这段代码、看看这次改动有什么问题 - 提交前自查。 ## 执行步骤 1. 获取变更范围和 diff。优先使用 scripts/run_review.py 做初筛该脚本会输出一个候选问题清单。 2. 阅读 checklist.md 中的逐项检查清单结合 diff 逐条核对不要遗漏安全类检查项。 3. 对每一个发现定位到具体文件和代码行给出严重程度评级 - HIGH会导致数据泄露、崩溃、明显错误行为 - MEDIUM潜在问题或不符合项目规范 - LOW风格、注释、可读性建议。 4. 按 templates/review_report.md 的格式输出报告。报告必须包含问题列表和总结两个部分。 ## 注意事项 - 不要把工具脚本发现的全部问题都直接丢进报告先人工判断是否为误报。 - 涉及安全红线注入、硬编码密钥、命令拼接时至少标 HIGH。 - 没有发现任何问题时也要明确写未发现高风险问题避免留白。这份文档的妙处在于它把触发条件写在了 description 里把执行步骤写成可核对的序列把红线写成显式规则把细化的对象checklist、模板、脚本都指向附属文件而不是全都堆在主文档里。4.3 配套资源文件怎么放技能包的威力很大一部分来自配套资源。还是以代码审查为例我建议至少准备三个附属文件。第一个是checklist.md它是审查的逐项清单比SKILL.md正文更细适合经常更新# 代码审查检查清单 ## 安全 - [ ] 是否存在 SQL 拼接、命令拼接、不安全的反序列化 - [ ] 是否有硬编码密钥、Token、连接串 - [ ] 是否有默认密码或可预测的鉴权逻辑 ## 正确性 - [ ] 边界条件是否处理空列表、None、超长输入 - [ ] 异常路径是否兜底失败后是否可能静默吞掉错误 - [ ] 并发场景下是否有竞态问题 ## 可维护性 - [ ] 命名是否清晰是否有大段重复代码 - [ ] 是否引入了不必要的复杂度第二个是scripts/run_review.py它做初筛用处是让模型不必每次从头读一遍整个仓库。脚本不用很高级能抓出常见的危险模式就够#!/usr/bin/env python3 import re, sys patterns { sql_concat: r(SELECT|INSERT|UPDATE|DELETE).*[\].*[%], hardcoded_secret: r(password|api_key|token)\s*\s*[\][^\]{6,}[\], eval_usage: r\b(eval|exec)\s*\(, } def scan_file(path): findings [] try: with open(path, r, encodingutf-8, errorsignore) as f: for lineno, line in enumerate(f, 1): for kind, pat in patterns.items(): if re.search(pat, line, re.IGNORECASE): findings.append((path, lineno, kind, line.strip()[:80])) except Exception as e: findings.append((path, 0, read_error, str(e))) return findings if __name__ __main__: for path in sys.argv[1:]: for f in scan_file(path): print(f{f[0]}:{f[1]} [{f[2]}] {f[3]})第三个是templates/review_report.md限定输出格式# 变更审查报告 - 审查范围: ... - 审查时间: ... ## 问题列表 | 严重程度 | 文件 | 行号 | 问题描述 | 建议 | | --- | --- | --- | --- | --- | ## 总结 ...这些资源文件用相对路径在SKILL.md里引用比如上面示例里的scripts/run_review.py、checklist.md整个技能包就能作为一个整体被拷贝、共享不会因为路径散落而失效。4.4 验证和迭代闭环写完先别急着到处用我的验证流程是这样的把技能包放进.claude/skills/或~/.claude/skills/开一个全新会话直接对 AI 说帮我 review 一下最近这次提交不要自己补充任何额外规则观察它是否加载了技能。如果它没按SKILL.md的步骤走第一条要怀疑的就是 description 写得不够明确让它跑一次真实 diff检查报告是否包含 HIGH/MEDIUM/LOW 分级、是否有误报把发现的问题带回checklist.md和SKILL.md修改重复第 2 步。提示测试时一定要开全新会话不要在同一个会话里既写技能又让它执行。同一个会话里模型已经知道你的意图即使没加载技能也可能表现正确这会严重干扰判断。5. 我踩过的几个坑写出来给你避雷5.1 description 写得太佛系模型根本想不起来用它我最早给代码审查技能写的 description 是用于代码审查。结果开了新会话后模型依然按照自己的习惯去回答技能完全没被触发。原因很简单模型需要在对话里做触发判断而代码审查这个信号太弱了。后来我改成写清楚触发条件 同义词 示例意图效果立刻不一样description: 对代码变更进行系统化审查适用于 PR/MR 评审、提交前自查以及帮我看看这段代码有什么问题之类的请求。当用户提到 review、code review、代码审查、CR 时优先使用本技能。要记住这个字段不是给人看的是给模型做检索用的。把你平时会说的每一种说法都写进去模型才更容易在正确时机把它捞出来。5.2 把 SKILL.md 写成了百科全书我见过有人把项目背景、API 文档、历史决策、团队组织架构全写进SKILL.md正文几百行起步。这样做有两个问题一是按需加载时全文会占用大量上下文挤压真正执行任务的空间二是内容太长后模型对文档中部的规则记忆会明显衰减。正确做法是让SKILL.md保持精炼只写步骤 规则 引用指向把细节拆到附属文件里。我现在的经验是主文档尽量控制在 300 行以内超过的部分问一句这个细节属于哪类资源然后拆出去。前端代码审查的规则放在checklist-frontend.md后端安全规则放在checklist-backend.md按任务类型分别引用而不是一股脑塞进主文档。5.3 资源文件引用与路径问题技能包被复制到不同项目后附属文件的相对路径一定会变。如果你的SKILL.md里写了scripts/run_review.py但某个项目里技能放在更深层目录触发后模型可能找不到文件。我的做法是在SKILL.md正文里明确写上脚本位于本技能目录下的scripts/run_review.py请先定位技能所在目录再执行。很多实现里模型可以用类似pwd或读取文件列表的方式来确认位置你只需要在指令里提示它先确认目录再运行命令就能避免大部分路径问题。5.4 忘了限制工具边界技能一旦被触发AI 助手在执行过程中是有工具调用权限的。如果你写了一个数据脱敏审查技能本来只想让它读文件、找敏感信息结果它顺手用Edit帮你改了文件那就危险了。allowed-tools字段就是干这个的。比如代码审查技能我通常只放Read、Grep、Bash、Write并且刻意不开放Edit——因为它要输出报告写报告是允许的但我不希望它直接改我的源代码。如果你的实现不支持这类白名单字段就在SKILL.md的注意事项里用禁止修改任何源代码文件只允许输出报告这样的强指令兜底。5.5 版本管理与团队共享技能一多版本混乱就来了。团队里有个人改了checklist.md另一个人还在用老版本审查结果自然对不上。我的经验是把技能包直接放进 Git 仓库管理团队共用一份改动走 MR 流程。推荐在仓库里按这样的结构组织skills-repo/ ├── code-review/ │ ├── SKILL.md │ ├── checklist.md │ └── scripts/ ├── meeting-notes/ │ ├── SKILL.md │ └── templates/ └── README.md # 写明每个技能的适用范围和维护人每个技能目录里放一个版本号改动时更新version和变更说明。刚开始不用搞复杂的治理机制两三个人协作时一条简单的约定就够了改技能必须连版本号一起改且要在 README 里留一行变更记录。6. 写给也想入坑的人几条个人体会最后分享几个我自己摸索出来的实操习惯不一定适合所有人但至少能帮你少走弯路。第一从你最长最常用的那条 prompt 模板开始改造成技能。我最先技能化的就是代码审查和会议纪要因为它们是我每周都要用十几次的流程投入产出比最高。不要一开始就想着建设一套庞大体系先做两个真正高频的跑通了再扩展。第二坚持一个技能只负责一件事。我拆过最夸张的一个技能原本涵盖审查、修 bug、写测试、生成提交信息四个功能后来拆成四个独立技能包每个都更稳定触发也更准确。技能之间的组合可以靠模型自然调度不需要硬塞进一个包里。第三每迭代一版都要在全新会话里验证一次。我很多次觉得改好了结果开新会话一测description 还是没触发或者某个路径写错导致脚本跑不起来。真正的验证标准只有一个在一个完全不知道你意图的新会话里它能不能靠 description 主动找到这个技能然后严格按流程执行。第四注意观察上下文开销。技能包越大、被触发的次数越多token 消耗越明显。我一般会对频率最高的技能定期瘦身把正文里的示例代码挪到附属文件把冗长的解释压缩成指令。毕竟技能是为了省事不是为了给模型加负担。第五团队共享之前先把个人版本跑稳。自己都没用顺手的技能别急着同步给同事。我在团队里推广的经验是先在个人环境里用一周确认输出稳定、误报率低再提交到共享仓库并在 README 里写明适用场景避免有人误用。这套东西不需要等谁发布新版本你今天就可以打开终端创建一个目录把你最常用那条 prompt 改写成第一份SKILL.md。我打包完第一批技能之后最直接的感受是和 AI 协作这件事终于从每次碰运气变成了按标准作业。希望你也能早点体会到这种感觉。