Agent Skills是什么？一文搞懂技能机制与MCP区别及实战编写

最近在 AI 编程工具的讨论里出现频率最高的词除了 Agent就是 Skills。如果你留意 Google 生态里的开发社区会发现关于 Skills 的提问越来越多Skills 是什么和 MCP 有什么区别为什么要装 Skills 而不是直接写提示词我的判断是Skills 不是又一个插件系统的变体而是 Agent 从会对话走向会做事的关键机制。它把提示词、工作流、参考知识和工具调用规范打包成可复用、可分发、可版本管理的能力单元。换句话说以前你教 AI怎么做一件事只能写在对话上下文里关掉就没了现在你把怎么做做成一个技能文件任何一次对话、任何一个项目Agent 都能按需加载。这篇文章会帮你做三件事第一讲清楚 Agent Skills 的核心概念和原理以及它和 Function Calling、MCP、传统插件的边界第二结合 Google 在 AI 底座、搜索与智能体方向的布局分析 Skills 生态为什么是当前 Agent 开发的必争之地第三通过完整的示例带你从零编写一个可运行的 Skills并在 Claude Code、Codex、OpenCode 这些主流工具中加载验证最后给出常见问题排查和工程化建议。这里先说一句结论如果你已经在用 AI 编程助手但还停留在让它写代码、改 bug的层面Skills 就是你下一步应该投入时间的地方。1. 为什么Skills突然成为 Agent 开发的关键词很多人第一次听说 Skills是在 Claude Code 或 Codex 的更新日志里。随后OpenCode、Continue、Cline 等开源项目也陆续支持了类似的机制。社区里的讨论越来越多但概念反而越聊越乱有人管它叫技能有人叫技能包还有人把它和 MCP Server 混为一谈。先看一个最基础的问题为什么现有的大模型不够用关键在于上下文窗口和长期记忆的矛盾。LLM 的上下文窗口虽然在不断变大但真正稳定可控的上下文空间依然有限。你在一个会话里塞入大量背景文档、团队规范、编码风格说明一方面会挤压模型处理实际任务的空间另一方面这些内容是一次性的——下一个会话、下一个项目又得重新粘贴。更麻烦的是Agent 在执行复杂任务时往往需要一套稳定的流程先做什么、再做什么、遇到什么情况走哪条分支、每个环节输出什么格式。这些流程如果只存在于某次提示词里就无法沉淀成团队资产。Skills 的解决思路很直接把完成某类任务所需的知识、流程、示例、约束打包成一个独立目录目录里有核心指令文件通常是 SKILL.md和必要的资源文件。Agent 在遇到匹配的任务描述时按需加载这个目录而不是把内容无差别塞进上下文。这里真正容易踩坑的地方是很多人以为 Skills 只是高级提示词模板。如果只看表面确实像但它的价值不在于模板本身而在于三点第一按需加载。Agent 看到任务后先判断该用哪个技能再读取技能内容。它不会在无关任务上白白消耗上下文。第二可复用。一个写好的代码审查技能可以放在个人目录、项目目录、乃至团队共享仓库里不同项目都能引用。第三可组合。一个复杂任务可以由多个技能协作完成例如前端开发技能调用代码审查技能和运行测试技能形成一条流水线。从信息架构的角度看Skills 把模型知识和人的经验知识分开了。模型参数里装的是通用语言理解Skills 文件里装的是我们这个团队、这个项目、这个领域怎么做事情的经验知识。后者更新成本极低改一个 Markdown 文件就能让 Agent 学会新规范这个设计背后的原因恰恰是当前大模型微调成本太高、周期太长而知识又需要频繁更新。所以Skills 火起来不是偶然。它踩中了 Agent 工程化最核心的诉求让能力可沉淀、可分发、可治理。2. 什么是 Agent Skills从会对话到会做事要理解 Skills建议先放下插件的思维惯性。传统软件插件是在程序里挂载一段可执行代码定义好接口和生命周期Skills 更像是一份岗位说明书加操作手册Agent 根据这份手册用自己已有的能力去完成任务而不是被注入新的可执行代码。2.1 一个 Skills 的直观样子一个典型的 Skills 目录长这样my-skill/ ├── SKILL.md ├── references/ │ ├── coding-standards.md │ └── api-errors.md ├── examples/ │ ├── good-example.py │ └── bad-example.py ├── scripts/ │ └── format-check.py └── assets/ └── architecture.png其中 SKILL.md 是整个技能的核心。它通常包含两部分YAML 格式的 frontmatter声明技能名称、描述、触发条件Markdown 正文写清楚技能的目标、工作流程、输入输出规范、注意事项。当 Agent 收到用户请求后会先根据技能描述判断当前任务是否匹配。匹配后它读取 SKILL.md再按需读取 references、examples、scripts 等资源文件。这个过程称为渐进式披露也是 Skills 能控制上下文占用的关键设计。2.2 Skills 与 MCP、Function Calling、传统插件的区别很多读者会在这一步混淆概念我用一张表格来对比机制核心作用运行时典型场景Function Calling让模型输出结构化的函数调用参数单次请求需要调用一个具体 API 时MCP模型上下文协议标准化连接外部工具与数据源工具调用连接数据库、文件系统、第三方服务Skills向 Agent 注入流程知识与经验任务级加载完成代码审查性能优化文档生成等一类任务传统插件扩展宿主程序功能宿主进程在 IDE 中增加一个新面板或快捷键这里的关键差异在于Function Calling 是模型决定调用哪个函数MCP 是给 Agent 提供一批标准化的工具入口而 Skills 是告诉 Agent 如何组织思路来完成一类任务。举一个实际例子。你要让 AI 助手做一次代码审查用 Function Calling你需要提前定义获取代码执行静态检查提交评论这些函数模型在对话中按需调用。用 MCP你可以接入一个代码库服务让 Agent 通过工具读文件、查变更记录。用 Skills你写一份代码审查手册规定审查维度、输出格式、严重级别判断标准。Agent 加载这个技能后会结合 MCP 提供的数据访问能力像一位资深工程师那样完成审查而不是零散地调用几个工具。在实际项目中二者往往是配合使用的。Skills 负责方法论MCP 负责数据通路Function Calling 负责具体动作。只装 SkillsAgent 可能缺少访问数据的能力只装 MCPAgent 可能不知道该怎么组织执行流程。所以判断一个工具生态是否成熟不能只看它支持多少个 MCP Server还要看它是否提供了良好的 Skills 机制。这也是 Google 生态中与 AI、搜索、浏览器相关的工具链越来越重视技能化封装的原因之一。3. Google 与 Agent Skills搜索、模型与知识沉淀提到 Google 和 Skills 的关系很多人的第一反应是Google 又在做平台战略。但从技术演进的视角看Google 对 Agent 技能生态的影响是结构性的而不是单纯的市场动作。3.1 Google 的 AI 底座与 Agent 能力无论是 Transformer 架构的提出还是后续大规模语言模型的工程化Google 都在 AI 底座层面给整个行业提供了关键支撑。对开发者来说这层底座决定了 Agent 的通用能力——语言理解、代码生成、逻辑推理都是从基础模型层获得的。而 Skills 需要有一个足够强的模型来执行手册。同一份 SKILL.md在小模型上可能表现平平在大模型上就能发挥出完整效果。这就是为什么 Skills 机制真正普及要等到 Claude、Gemini、GPT 这些模型具备足够强的指令跟随能力之后。从公开信息看Google 在 AI 产品上的一个重要方向是把模型能力嵌入搜索结果、办公套件和云服务中。对这种趋势更稳妥的判断是Google 正在把通用知识检索和任务执行结合起来而技能化的思路天然适合描述一类任务应该怎么做。3.2 搜索与 Grounding让 Agent知道现实Agent 的一个老大难问题是幻觉。模型知道很多知识但不知道当前的事实——最新接口文档、你自己项目的报错信息、某个服务的实时状态。Google 的优势在于搜索和知识图谱这给 Agent 提供了 Grounding接地能力也就是让模型的回答基于真实、可检索的信息。Skills 在这里的价值就很清晰技能文件里可以写明查询资料时应优先使用哪些搜索入口如何判断信息来源是否可信如果搜索无结果应该怎么降级。当 Agent 执行任务时这些规范会约束它的行为降低幻觉风险。举例来说一个前端开发技能可以内置这样一条规则当不确定某个框架的最新 API 时不要直接凭记忆作答而是先搜索官方文档再根据文档内容编写代码。这条规则不用改模型不用重新训练只需要在 SKILL.md 里写清楚。Google 生态中的 Chrome、Workspace 等产品也在向更智能的方向演进如果围绕这些产品的 Agent 能力普及Skills 很可能成为连接用户工作流与AI 助手的标准书签。早期开发者现在掌握技能化思维等于提前占住这个位置。这一章的小结论是Google 在 Agent 技能生态中的角色更多是基础设施与知识通路的提供者而 Skills 是应用层把 AI 能力落到具体工作流的关键桥梁。对开发者而言与其争论谁是平台赢家不如先把技能化能力掌握起来等到生态切换时能快速迁移。4. 主流 Agent 工具中的 Skills 生态当前支持或正在支持 Skills 的 Agent 工具越来越多。这里不讨论哪个最好而是帮你建立一个横向认知这些工具的 Skills 概念虽然相似但加载方式、目录约定和生态成熟度有差异。4.1 Claude Code SkillsClaude Code 是把 Skills 概念推向大众的一个重要推手。它的基本思路是把技能目录放到约定路径下Claude Code 在启动时扫描这些目录Agent 在对话中按需加载。个人技能通常放在用户目录下的.claude/skills/项目技能放在项目根目录下的.claude/skills/。每一个技能对应一个子目录目录里至少有一个 SKILL.md。实际路径和命名规则以官方文档为准不同版本可能有调整。从社区反馈看Claude Code Skills 对描述文件的质量要求比较高。SKILL.md 中 description 写得好不好直接决定模型能否在正确时机触发技能。很多技能不生效不是因为代码有问题而是描述词与用户请求的表达不匹配。4.2 Codex SkillsOpenAI 的 Codex 在支持 Agent Skills 上也做了类似设计。官方把技能视为一组可复用的说明书Agent 可以在多步骤任务中加载它们。Codex 对技能文件的格式有相对明确的约定通常要求包含标准化的元信息。与 Claude Code 相比Codex 的 Skills 生态更强调自动化执行和多步骤编排。社区里已经出现不少技能合集比如用于自动化测试、代码迁移、CI 脚本生成的包。安装时要注意技能的来源和授权避免执行来历不明的脚本。关于网络热搜中提到的各种skills 下载skills 推荐这里给出一个统一的建议优先选择官方文档或知名仓库中的技能安装前通读 SKILL.md检查它是否会要求 Agent 执行敏感操作。4.3 OpenCode 与开源项目OpenCode 等开源项目也在吸收 Skills 概念。这类项目的好处是透明——你能看到技能加载和执行的完整代码路径也更容易定制自己的技能管理器。社区中出现了一些技能中心或技能 Hub项目尝试把分散的技能包集中管理类似于前端的 npm。但目前还没有形成统一标准跨工具复用时需要做一些格式适配。这也是一个值得关注的机会点如果你有开源经验可以考虑做一个跨工具的技能格式转换器。5. 动手编写第一个 Agent Skills有了前面的概念下面进入实操。我们会从零编写一个代码审查技能并把它加载到支持 Skills 的工具中。整个过程建议在本地完成不需要特殊网络环境也不需要修改任何系统级配置。5.1 Skills 的目录与文件规范技能的最小结构是code-review-skill/ └── SKILL.mdSKILL.md 决定了技能能不能被正确识别和触发。常见结构如下--- name: code-review description: 当用户要求审查代码、review 代码、检查代码质量时使用本技能。 --- # 代码审查技能 对目标代码进行系统化审查输出结构化审查报告。 ## 使用场景 - 用户要求审查代码或检查代码问题 - 代码提交前需要质量把关 - 需要排查潜在的性能与安全隐患 ## 执行流程 1. 读取需要审查的代码文件确认语言和项目结构。 2. 从以下四个维度逐一检查 - 逻辑正确性边界条件、空值、并发、异常处理 - 安全性输入校验、权限校验、敏感信息泄露 - 性能循环效率、SQL 查询、资源释放 - 可维护性命名规范、函数长度、重复代码 3. 输出审查结论 - 先列高风险问题给出严重级别 - 再列中低风险问题和改进建议 - 最后给一句总体评价 ## 注意事项 - 不确定的内容不要编造可以标注需要确认 - 如果代码量过大优先查关键逻辑和公共方法5.2 环境准备与加载方式这一步需要准备好支持 Skills 的 Agent 工具。以 Claude Code 为例常见做法是# 创建个人技能目录 mkdir -p ~/.claude/skills/code-review # 复制技能文件 cp code-review-skill/SKILL.md ~/.claude/skills/code-review/ # 验证目录结构 find ~/.claude/skills -name SKILL.md如果你在某个项目中使用更推荐放在项目目录下方便团队共享mkdir -p .claude/skills/code-review cp code-review-skill/SKILL.md .claude/skills/code-review/加载技能不需要额外启动服务。工具会在对话过程中根据用户请求自动匹配技能描述。如果你希望验证技能是否被识别可以重启 Agent 会话然后输入帮我审查一下这段代码观察它是否主动按照技能流程执行。5.3 示例让技能支持参考资源实际的代码审查技能还可以加入示例文件。例如在技能目录下放一个容易出错的示例代码模型可以对照示例给出更具体的问题描述。code-review-skill/ ├── SKILL.md └── examples/ └── dangerous-code.pydangerous-code.py 内容# 文件路径code-review-skill/examples/dangerous-code.py import os def delete_file(path): # 缺少路径校验可能删除任意文件 os.remove(path) def query_user(uid): # SQL 拼接存在注入风险 sql SELECT * FROM users WHERE id uid print(sql)在 SKILL.md 中补充一条说明审查时可以参考 examples 目录中的典型反例。这样 Agent 诊断真实代码时会更有针对性地指出类似的风险点。如果你的工具支持多语言技能目录建议把参考资源控制在较小的体积内。技能本身以方法论为主大体积的规则文件会拖慢加载速度。6. 完整示例把团队规范变成 Agent 技能这一节我们做一个更实战的案例把团队的前端开发规范封装成技能让 Agent 在写代码时自动遵守。6.1 技能目录设计frontend-dev-skill/ ├── SKILL.md ├── references/ │ ├── commit-convention.md │ └── style-guide.md └── templates/ ├── component-template.tsx └── api-service-template.ts其中 SKILL.md 指明技能的使用场景当用户要求实现前端组件、编写接口请求、提交代码时加载。references/commit-convention.md 的内容示例# 提交信息规范 - 使用 Conventional Commits 格式 - type 可选值feat, fix, docs, style, refactor, test, chore - scope 表示影响模块例如 feat(button): 添加加载状态 - 提交信息不超过 72 个字符references/style-guide.md 则集中记录团队的代码风格比如命名使用 camelCase、组件文件使用 PascalCase、禁止使用 any 类型等。6.2 在 Agent 中验证技能编写完成后在支持技能的 Agent 中发起一个任务请帮我实现一个用户登录表单组件并提交代码如果技能加载成功Agent 会输出符合团队规范的组件代码并使用约定的 commit 信息格式。你可以从这个验证中直观地看到没有技能时Agent 给出的代码风格是通用风格有技能后代码会主动贴近团队规范。6.3 技能的更新与版本管理技能文件本质上是文本天然适合放在 Git 仓库里管理。团队可以单独建一个 skills 仓库每个技能作为一个目录通过 PR 流程更新。更新技能时注意一个关键点SKILL.md 的 description 变更会影响触发准确性。不要频繁修改技能描述如果需要调整建议先在个人验证环境中测试触发效果再合并到共享仓库。7. 运行验证与常见问题排查技能不生效是最常见的问题。我整理了一个排查清单问题现象可能原因排查方式解决方案Agent 完全没有触发技能SKILL.md 中 description 与用户请求不匹配检查 description 关键词是否覆盖常见表达重写 description加入同义说法技能触发但输出不符合预期技能正文中的流程描述不够具体阅读 SKILL.md确认执行步骤是否明确补充分步骤说明和输入输出格式技能时好时坏上下文窗口被其他内容占用查看会话中是否有大量无关上下文新建会话或精简技能内容技能目录未被识别目录路径或命名不符合工具约定检查工具文档和目录结构修正路径确保 SKILL.md 位于根目录技能加载后 Agent 变慢技能内嵌了大量参考资源查看加载的辅助文件数量和体积把大文件拆分为按需加载的子目录跨工具不兼容不同工具对 SKILL.md 格式要求不同对比各工具的官方示例做格式转换或维护多版本安全风险技能要求 Agent 执行危险命令阅读技能的 scripts 目录和命令删除可疑命令遵循最小权限原则这里特别强调一下安全边界。Skills 文件会被 Agent 自动读取如果技能来自不可信渠道它可能诱导 Agent 执行恶意操作比如读取本地敏感文件、发送请求到非预期地址、修改关键配置。在生产环境中使用团队共享技能时务必在合并到共享仓库前完成代码审查并只在测试环境中验证后再推广。判断技能是否生效还有一个简单的观测方法在 Agent 对话中开启详细日志或调试模式查看它是否在任务开始时读取了技能文件。不同工具的日志展示方式不同具体可以参考工具官方说明。8. 最佳实践与工程建议Skills 的编写看起来简单但真正用起来有不少工程细节。以下是几条经过社区验证的实践建议。8.1 命名与描述规范技能命名尽量短小、语义明确例如 code-review、docker-deploy、vue-component。description 要覆盖用户可能使用的多种表达但也不宜过长。建议在 description 中写入至少一个正例表达比如当用户要求审查代码或 review 代码时使用。8.2 控制技能体积一个技能的目标是唤起方法论不是把整个知识库塞进上下文。references 目录最好只放高频使用的关键信息完整文档放在外部链接中让 Agent 按需阅读。如果某个技能加载后明显影响响应速度优先检查辅助文件体积。8.3 渐进式披露在 SKILL.md 正文中只写做什么和怎么做把详细代码模板、完整示例放到子目录。Agent 会根据需要读取子目录内容而不是一次性全部加载。这个设计能让技能保持轻量。8.4 版本管理与团队协作建议为技能仓库建立独立的发布节奏每个技能有独立的变更记录更新后标注版本号通过 CI 检查 SKILL.md 的格式是否符合规范在合并前让至少一位成员在实际任务中验证技能的触发效果。8.5 安全与权限最小化技能中的 scripts 目录不要放置难以审计的压缩脚本。如果技能需要执行 shell 命令必须在文档中说明命令用途并在沙箱或测试环境验证。Agent 工具的配置中尽量使用最小权限的 API Key 和账号避免技能传播导致凭据泄露。8.6 与 MCP 合理分工在团队引入 Agent 能力时先画出任务流程再决定哪些环节用 Skills哪些用 MCP。经验法则是方法论和流程用 Skills数据访问和外部动作用 MCP。把两者放在同一个技能目录中会导致职责混乱排错也会变难。9. 总结与后续深入学习方向Skills 的兴起标志着 Agent 开发从提示词工程向能力工程过渡。以前优化一个 Agent 的效果靠调整 prompt现在靠积累一张张技能卡片。这种变化对普通开发者非常友好你不需要训练大模型也不需要深入掌握强化学习只要能把一件事的流程和规范写清楚就能把它变成 Agent 的能力。读到这里你已经掌握了 Agent Skills 的核心概念、主流工具生态、技能文件规范、完整编写示例和排查方法。下一步建议这样做第一先挑一个自己日常重复率最高的任务写成第一个技能。不要贪多一个就够重点是跑通编写、加载、触发、验证这个闭环。第二把你正在用的 AI 编程工具切换为支持技能的版本把常用技能沉淀到项目目录。第三观察一段时间记录哪些技能经常被触发、哪些几乎用不上不用的技能要及时精简避免干扰 Agent 判断。如果想继续深入可以研究三个方向一是不同工具 Skills 格式的差异与转换工具二是如何用多个技能编排复杂的 Agent 工作流比如需求分析技能 架构设计技能 代码生成技能 测试技能组合起来完成一个模块的交付三是技能仓库的自动化评测也就是用一组标准测试任务量化评估安装技能前后Agent 输出质量的提升幅度。最后提醒一句技能是你与 AI 协作经验的固化它会随着你的团队和实践不断迭代。把它当作代码一样维护而不是一个写一次就再也不管的配置文件这样才能真正享受到它带来的长期价值。