这次我们来看一个 AI Agent 生态里出现频率快速上升的概念Skill。如果你最近关注过 Claude、Codex 或者 Cursor 的更新大概率会看到SKILL.md、Agent Skills这类名词在不少 Agent 框架的规划里Skill 也已经和 Tool、MCP 一起被当作 Agent 能力拼图中独立的一块。在动手写复杂的 Agent 工作流之前先把 Skill 是什么、它解决什么问题、和 Plugin / Function Calling / MCP 有什么区别讲清楚后面做工程才不会跑偏。这篇是系列教程的第 01 篇内容覆盖概念、目录结构、一个能跑通的完整示例以及 Skill 的加载与调试思路。下一篇再讲如何批量设计和管理一套 Skill 体系。先说结论Skill 本质上是一份“给 Agent 的操作手册”。它把模型默认不知道的专业流程、企业规范、手工操作步骤打包成一个带触发条件的指令包。Agent 判断当前任务和某个 Skill 相关时就把这份手册加载进上下文照着执行。和传统插件最大的差异在于Skill 的核心是“流程知识”而不是“可调用的外部函数”。1. 核心能力速览能力项说明项目类型AI Agent 的可复用技能包 / 指令包规范核心文件SKILL.md含 YAML frontmatter可选scripts/、assets/目录主要作用把 Agent 缺失的专业流程、企业规范、操作步骤沉淀为可加载指令触发方式由 Agent 根据用户请求和 Skill 描述自动匹配匹配后加载与 MCP 关系互补关系。MCP 解决“能调用哪些外部工具”Skill 解决“该怎么按流程做事”是否需要编程不需要。一个纯SKILL.md的 Skill 也能工作脚本只是可选项支持平台Claude 系产品、OpenAI Codex、Cursor 等不同产品目录规则不同是否消耗上下文匹配后会把 Skill 内容注入上下文所以SKILL.md需要控制长度分享方式通常以文件夹或压缩包形式分发也可放在代码仓库中共享适合场景代码审查流程、报告生成、数据处理规范、企业内部 SOP、专业领域知识包需要说明以上是 Skill 这套通用机制的能力边界。具体到某个产品目录位置、导入方式和字段命名要以官方文档为准。本文后面的示例会统一使用当前公开资料里最通用的写法。2. 什么是 AI Skill概念与价值先看一个具体场景。你用 Claude 或 Codex 写完代码想让 Agent 做一次规范的项目复盘。默认情况下模型只知道“复盘”这个词的通用含义不知道你团队要求的模板、字段、评分标准、输出格式。传统做法是在每次提问时把一长段要求粘贴进提示词框或者在系统提示词里写死一大段规则。前者每次都重复劳动后者会让无关任务也背上这部分上下文开销。Skill 解决的就是这个问题。它让你把“项目复盘怎么做”这套流程固化成一个文件夹里面有一份SKILL.md描述清楚“什么情况下用、按什么步骤做、输出什么格式”。Agent 判断当前请求与这份描述匹配时自动把流程加载进上下文并按步骤执行。用户不需要在每次对话里重新解释规则Agent 也不需要无差别地长期持有这些规则。从公开资料和社区实践看Skill 的价值主要体现在三个层面第一是流程可复用。一个团队可以把独有的开发规范、代码审查清单、发布检查步骤做成 Skill同一个仓库、同一个项目组共享。新人上手时Agent 自动携带团队经验而不是靠师傅口头传授。第二是提示词工程的可维护性。过去调试一长串 system prompt 很痛苦改动一个环节就要整体测试。Skill 把流程拆成独立单元改一个 Skill 不影响其他功能也方便做版本管理。第三是约束 Agent 的输出行为。Skill 里可以写死“必须输出哪些字段”“禁止做哪些操作”比在对话里临时叮嘱稳定得多。尤其是涉及合规、安全、格式要求的场景用 Skill 固化规则比依赖模型自觉可靠。需要提醒一个常见的概念混淆中文互联网搜索“Skill”会出现很多无关内容比如游戏技能、个人技能提升甚至一些不良内容。本文讨论的 Skill 特指 AGI / Agent 领域的技术概念即 OpenAI、Anthropic 等公司及其生态社区定义的 Agent Skills。后续看到SKILL.md、Agent Skill、skill pack这类词都应该按这个技术含义理解。3. Skill 与 Plugin、Function Calling、MCP 的边界Skill 刚流行时最容易踩的坑就是把它和 Plugin、Function Calling、MCP 混为一谈。这四者确实都服务于“让 Agent 更强”但解决的问题完全不同。对比维度SkillPlugin / 插件Function Calling / ToolMCP本质流程与指令包一组与宿主应用集成的功能模块模型可调用的函数接口一种统一工具接入协议解决什么问题不知道“怎么做”能“多做什么”能“调用什么”如何“标准化接入外部工具”是否需要代码不需要纯文本指令即可通常需要需要需要服务端与客户端实现加载时机按描述匹配后注入上下文随应用环境常驻或按权限启用模型按需发起函数调用按工具列表声明与调用典型例子代码审查流程、周报模板浏览器插件、IDE 扩展查询天气、计算器数据库连接、文件系统访问对模型能力影响改变“做事的流程与方法”扩展“应用的功能边界”扩展“可操作的外部世界”标准化“工具接入方式”Plugin 是应用层扩展。它直接给宿主软件增加新功能比如编辑器里加一个主题插件、浏览器里加一个翻译插件。Agent 领域的插件往往意味着新的界面入口或功能模块。Skill 不改变应用本身的功能只是给模型提供一套执行任务的指令。Function Calling / Tool 是能力接入。模型通过函数调用去执行一段真实代码获取计算结果或操作外部系统。它是“执行动作”的通道模型自己没有这条通道时什么都干不了。Skill 里也可以包含脚本但脚本只是辅助确定性步骤Skill 的主体仍然是流程指南。**MCP 是工具接入的标准化协议。**它解决的是“每个工具都自己定义接口格式Agent 接起来太累”的问题。MCP 统一了工具描述、调用、返回的格式。Skill 和 MCP 可以共存MCP 负责把外部能力变成标准工具Skill 负责教 Agent 如何组合使用这些工具完成一套复杂流程。最直观的理解方式MCP 给 Agent 提供了“能用的零件”Skill 给了“装配手册”。一份好的 Skill 里完全可以描述“先用 MCP 的文件工具读取代码再按清单逐条审查最后用 MCP 的文档工具生成报告”。两者不冲突反而经常一起出现。4. Skill 的标准结构目录、SKILL.md、脚本与资源目前主流 Agent 产品的 Skill 实现虽然细节不同但目录结构高度相似。一个标准的 Skill 通常是这样的my-skill/ ├── SKILL.md ├── scripts/ │ └── validate.py └── assets/ └── checklist.mdSKILL.md是唯一必需的入口文件。它负责声明 Skill 的基本信息和执行流程。文件头部有一段 YAML frontmatter至少包含name和description两个字段--- name: python-code-review description: 对 Python 代码进行系统化审查。当用户请求代码审查、寻找 bug、做重构建议时使用。 ---name是这个 Skill 的唯一标识通常是短横线连接的小写英文比如python-code-review。不同 Skill 的 name 不能重复。description是触发判断的关键。Agent 拿到用户请求后会和各 Skill 的 description 做语义匹配。匹配到才加载整个 Skill。SKILL.md的正文部分用来描述完整的执行流程。一般按“使用时机 - 操作步骤 - 输出格式 - 注意事项”组织。这部分内容会被加载进模型上下文所以必须准确、精简、可执行。scripts/目录放可执行脚本。当 Skill 里的某些步骤需要确定性计算时可以写脚本让 Agent 调用。典型的例子包括语法检查、文件批量重命名、数据格式转换。脚本不是必须的纯提示词型 Skill 也可以正常工作。但脚本能弥补模型在精确计算上的短板。assets/目录放辅助资源。包括参考文档、模板文件、checklist、示例图片等。Agent 执行流程时如果需要这些资源可以从这里读取。这个目录可以避免把大段模板塞进SKILL.md撑爆上下文。有一点必须强调Skill 不是注册制。它不像浏览器插件有统一商店也不像 MCP 有标准服务列表。主流做法是把 Skill 文件夹放到指定目录如项目的.claude/skills/或仓库的.codex/skills/或者从 URL 导入。具体目录位置和分发机制每个产品有自己规定以官方文档为准。5. 创建第一个 Skill从零到可用的完整示例下面创建一个“Python 代码审查”Skill演示从目录创建到实际可用的完整过程。这个示例适合任何在本地做过 Python 开发的人直接测试。5.1 创建目录结构先按目标产品的要求创建目录。这里以 Claude Code 项目级 Skill 的常见目录.claude/skills/为例mkdir -p .claude/skills/python-code-review/scripts mkdir -p .claude/skills/python-code-review/assets如果是 Codex 项目习惯上是放到仓库里的.codex/skills/路径。目录创建的思路一致路径名需要按实际产品替换。5.2 编写 SKILL.md在python-code-review目录下创建SKILL.md--- name: python-code-review description: 对 Python 代码做系统化审查。当用户请求代码审查、寻找 bug、做重构建议、提交前检查时使用。 --- # Python 代码审查 ## 使用时机 - 用户要求审查单个 Python 文件或整个目录。 - 用户准备提交代码需要提交前检查。 - 用户要求分析性能或安全隐患。 ## 审查步骤 1. 先读取目标文件或目录结构确认代码入口。 2. 按以下维度逐项检查 - 正确性边界条件、异常处理、空值处理 - 可读性命名、函数长度、注释质量 - 性能循环内重复计算、不必要的 I/O - 安全输入校验、命令拼接、依赖来源。 3. 如存在 assets/checklist.md按清单逐项核对。 4. 输出结构化审查报告。 ## 输出格式 - 使用表格输出| 文件 | 行号 | 严重级别 | 问题描述 | 修改建议 | - 严重级别分为 High / Medium / Low。 ## 注意 - 不直接重写用户代码除非用户明确要求。 - 对不确定的问题给出判断依据不要猜测。这份SKILL.md写清楚了触发条件、执行步骤、输出格式和边界。Agent 在对话中遇到代码审查相关请求时会尝试加载这份流程。5.3 添加辅助脚本在scripts/目录下放一个 Python 语法检查脚本用于让 Agent 在审查前先做一轮确定性的语法校验#!/usr/bin/env python3 # scripts/check_syntax.py import ast import sys from pathlib import Path def check_file(path: Path) - int: try: ast.parse(path.read_text(encodingutf-8)) print(f[OK] {path}) return 0 except SyntaxError as e: print(f[ERROR] {path}:{e.lineno} - {e.msg}) return 1 def main() - int: files list(Path(.).rglob(*.py)) if not files: print(no python files found) return 0 return max(check_file(f) for f in files) if __name__ __main__: sys.exit(main())如果本机没有脚本执行权限需要先加权限chmod x .claude/skills/python-code-review/scripts/check_syntax.py5.4 添加核查清单在assets/目录放一份checklist.md避免把过长内容写进SKILL.md主文件# 提交前核查清单 - [ ] 所有函数和变量命名是否清晰 - [ ] 是否有未处理的异常分支 - [ ] 循环内是否存在重复计算 - [ ] 是否使用了不安全的 shell 拼接 - [ ] 依赖是否写入 requirements 文件5.5 验证 Skill 是否生效完成以上步骤后目录结构长这样.claude/skills/python-code-review/ ├── SKILL.md ├── scripts/ │ └── check_syntax.py └── assets/ └── checklist.md启动 Agent输入一句触发性需求例如“帮我对这个项目的 Python 代码做一次提交前审查”。如果 Skill 配置正确Agent 会在回答中按SKILL.md里定义的步骤和输出格式执行。判断生效的标志是输出格式和你定义的表格结构一致并且执行了脚本或引用了 checklist。如果没有任何反应优先检查description是否足够明确以及目录是否放在了目标产品认可的路径下。6. Skill 如何被加载、是否消耗上下文、如何调试很多人在第一次使用 Skill 时会有一个疑问它是不是一直在后台运行答案是否定的。Skill 的加载是按需匹配机制。Agent 每轮对话开始时会拿到各 Skill 的name和description列表在用户请求到来后进行语义匹配。匹配命中才把SKILL.md正文注入上下文没命中就不加载。这也意味着description写得好不好直接决定 Skill 会不会被触发。这里有一个常见的上下文开销陷阱。Skill 的元信息name 和 description通常会被 Agent 常驻持有数量一多就会持续占用一定上下文空间。而匹配成功后加载的SKILL.md正文会在执行期间占用大量上下文。因此设计 Skill 时有两个明确原则description 要短而精准方便 Agent 快速判断SKILL.md 正文要精简到能完整执行流程能放 assets 的绝不堆进主文件。怎么确认 Skill 真的被加载了不同产品的调试手段不一样但通用的方法是看 Agent 的执行日志或回放记录。多数产品会在内部提示中写入类似“Loaded skill: python-code-review”这样的标记或者在最终输出里体现 Skill 中定义的格式。如果你在测试中发现输出没有按 Skill 里的格式走基本可以判断没有加载成功。Skill 不触发时按这个顺序排查目录位置是否正确文件名是否严格叫SKILL.mdYAML frontmatter 是否有语法错误name是否唯一description是否写得足够具体包含用户会用的触发词测试输入是否在 description 描述的语义范围内。调试 Skill 是一个迭代过程。改 description、加具体触发词、重新测试比一次性写一个完美的 Skill 更现实。建议每次只改一个变量观察效果变化。7. Skill 的部署与跨工具迁移Skill 目前在生态里还没有一个统一的“应用商店”部署方式仍然以目录和仓库为主。从社区实践看主要有三种方式项目级部署。把 Skill 放在项目仓库内跟随项目走。例如 Claude Code 常见的是.claude/skills/Codex 常见的是.codex/skills/。这种方式适合团队统一规范所有人 clone 仓库后 Skill 自动可用。用户级部署。把 Skill 放在当前用户的全局配置目录下对所有项目生效。具体路径因产品版本而异建议以官方文档为准。这种方式适合个人高频使用的通用技能比如日志分析、Markdown 排版规范。URL 导入。部分产品支持从 URL 直接导入 Skill本质上还是把远程的一个 Skill 文件夹拉取到本地目录。这种方式的优点是分发方便缺点是安全风险更高后面专门讲。跨工具迁移时要注意格式差异。虽然 SKILL.md 的大结构趋同但不同产品的 frontmatter 字段、目录路径、脚本调用约定可能不同。一个为 Claude Code 写的 Skill直接复制到 Codex 下可能识别不了。迁移时做三件事确认目标产品的 Skill 目录路径、检查 frontmatter 字段是否符合规范、用最简测试用例验证触发。一个值得提前规划的点是版本管理。既然 Skill 以文件夹形式存在天然适合纳入 Git 管理。建议每个 Skill 独立子目录在仓库里统一管理。改动 SKILL.md 时写清 commit message方便回溯是哪个版本引入的行为变化。8. Skill 编写最佳实践从公开资料和社区案例看写一个“刚好能用”的 Skill 很容易写一个“长期稳定、别人也好维护”的 Skill 需要遵循一些工程约束。这节给出当前实践中比较一致的几条建议。一个 Skill 只解决一个流程。试图把“代码审查 报告生成 自动修复 沟通周知”全塞进一个 Skill会让触发判断变得模糊。拆开后每个 Skill 的 description 可以写得更具体触发更精准维护也更独立。SKILL.md 控制长度。加载后它要进入上下文每多一行都是额外开销。把模板、长样例放进 assets主文件只保留“做什么、怎么做、输出什么”。经验上的合理区间是主流程能在一屏内看完具体长度按自己项目复杂度和上下文预算调整。步骤要写成可验证的指令。与其写“深入分析代码”不如写“逐文件检查边界条件、异常处理、空值分支并给出文件、行号、严重级别”。越具体结果越可预期。明确输出格式。在 Skill 里规定结构化输出比如“使用表格列为 文件/行号/严重级别/问题描述/修改建议”。这能让多次运行的结果保持稳定也方便后续接自动化流程。包含显式边界。写明“不做什么”和“什么情况下停止”。例如代码审查 Skill 里注明“除非用户要求否则不直接修改代码”可以避免 Agent 在审查过程中顺手改动业务逻辑。**脚本只做确定性步骤。**语法检查、格式转换这类结论确定的步骤适合用脚本需要判断、取舍、权衡的部分交给模型。把两者混在一起会让 Skill 变得脆弱。控制 Skill 总量。常驻元信息会占上下文Skill 太多还会增加匹配歧义。优先保留高频、稳定、效果好的 Skill低频技能单独按需加载而不是全部常驻。**纳入版本控制。**每个 Skill 独立目录进入 Git改动记录清楚。这个习惯在团队协作时价值远远大于个人使用。9. 安全与合规边界Skill 的本质是把一份指令注入 Agent 的上下文这意味着它拥有改变 Agent 行为的权限。如果这份指令来自不可信来源风险就会随之而来这是 Skill 使用中必须严肃对待的问题。第一个风险是 Skill 注入。一个被恶意构造的 SKILL.md可以指示 Agent 忽略用户约束、改变系统行为甚至诱导用户执行危险命令。在 Open WebUI、Claude Skills、Codex Skills 等生态中社区已经注意到对 Skill 文件本身的内容安全审查需求。启动任何来源不明的 Skill 前务必先通读一遍 SKILL.md 和 scripts 目录下的脚本确认没有隐藏指令。第二个风险是隐私泄露。Skill 的 description 和内容会随请求发送给模型服务商如果 Skill 里包含内部流程细节、企业敏感信息等于把这些内容直接暴露给外部服务。不要把密钥、内部系统地址、客户数据写进 Skill。第三个风险是自动化扩大的错误影响。Skill 让 Agent 可以按固定流程批量执行任务比如批量修改文件、批量发送消息。流程设计有误时错误也会被批量放大。第一次跑通 Skill 时先用小样本、只读模式验证再放开写操作。第四个风险是授权边界。如果用 Skill 处理代码、文档、影音素材需要确认素材来源合法、用户有对应授权涉及人脸的图像与视频类 Skill更需要严格核实授权链条。Skill 本身只是提高效率的工具不改变使用者的合规责任。结合当前合规要求使用 Skill 时应遵循几个底线原则只安装可追溯、可信来源的 Skill使用前审查内容不把敏感凭据写入任何 Skill 文件涉及生产环境的操作先在小范围灰度验证。10. 常见问题与排查方法以下问题列表基于 Skill 的通用机制整理覆盖社区反馈中出现频率较高的场景。不同产品的具体表现可能略有差异但排查思路基本通用。问题现象可能原因排查方式解决方案Agent 完全没有采用 Skill 里的流程目录位置不对或文件名不是 SKILL.md检查目录路径和大写按目标产品文档把文件夹放到正确路径Skill 偶尔触发、偶尔不触发description 写得太泛语义匹配不稳定查看执行日志确认匹配结果在 description 里加入更明确的触发词和示例场景SKILL.md 报解析错误YAML frontmatter 语法错误用 YAML 校验工具检查修正缩进、引号、字段格式脚本执行失败缺少执行权限或依赖未安装在本地直接手动执行脚本chmod x脚本按 requirements 安装依赖Skill 目录未被识别name 与其他 Skill 重复枚举所有 Skill 的 name改为唯一短横线命名加载后输出格式不稳定SKILL.md 中输出格式描述不够具体对比定义与实际输出补充字段示例明确使用表格或列表上下文占用偏高SKILL.md 正文过长检查每次加载的内容量把模板和长示例移到 assets 目录多个 Skill 竞争同一请求两个 Skill 的 description 语义重叠查看各自触发概率和日志拆分或合并重复 Skill明确各自边界导入外部 Skill 后行为异常Skill 内容被恶意构造立即停止使用并审查文件删除该 Skill检查 Agent 行为是否恢复正常遇到问题时先做小步验证。最有效的调试方式是把 Skill 目录临时简化到只含一个SKILL.md确认主流程能触发后再逐步加回脚本和资源。这个方法能快速区分问题是出在加载机制还是内容本身。11. 下一步从概念到批量管理这篇把 Skill 的概念、边界、目录结构、创建流程和排查思路讲完了。对读者来说最有价值的下一步不是立刻写很多个 Skill而是先做一次“验证循环”在你的目标 Agent 产品里按 5.1 到 5.5 的步骤创建一个最简 Skill用一个小请求确认触发生效然后基于这个验证过的格式逐步沉淀自己团队或个人的高频流程。把验证标准、触发词、输出格式在每个 Skill 里写清楚维护成本会低很多。后续教程会继续展开三块内容一是多个 Skill 之间的组织与管理包括命名规范、目录层级、共享与版本发布二是 Skill 中脚本的进阶用法如何与 MCP 工具组合完成复杂任务三是针对具体场景的 Skill 案例拆解例如文档解析 Skill、批量数据处理 Skill 和代码仓库治理 Skill。Skill 是一个门槛很低但工程上限很高的概念。不需要会写复杂代码就能入门但要把一套 Skill 体系做到稳定、安全、可复用需要投入设计和测试。建议收藏备用也欢迎在评论区留下你实际测试中遇到的报错现象后面案例篇会针对高频问题做专题排查。