AI skills 是当前 AI Agent 开发里被频繁讨论的一个概念它不只影响程序员。设计师、前端开发、测试人员、内容创作者只要在使用 Claude、Codex、OpenCode 这类带 Agent 能力的工具都会碰到同一个问题想让 AI 稳定地按自己的流程做事不应该每次重新打字教它一遍。AI skills 正是为了解决这个问题出现的。它把“告诉 AI 怎么做”这件事从临时对话变成可安装、可复用、可版本管理的技能包。这篇文章会围绕 AI skills 的原理、SKILL.md 的编写方式、安装加载流程和常见排错链路展开目标是让读者能自己创建一个可用的 skill并知道如何在项目里验证它真的被 Agent 读取和执行。1. 理解 AI Agent Skills 要解决的根本问题1.1 从“提问-回答”到“专业任务自动执行”普通 AI 对话可以回答“Python 依赖冲突怎么办”但不会主动按照你团队的规范去排查、记录、修复并输出一份固定格式的排查报告。要做到这一点以前只能通过长提示词、预设模板或外部脚本辅助。在 AI Agent 的语境下Agent 已经具备调用工具、拆分任务、读取文件的能力但它缺少一样东西针对特定专业任务的“操作手册”。AI skills 就是把操作手册做成标准化文件让 Agent 在遇到匹配任务时自动读取并执行。所谓 skill通常就是一个包含SKILL.md的目录。SKILL.md用 Markdown 编写包含 YAML 格式的元信息以及给模型看的操作步骤、规则、示例和检查清单。当用户问题命中 skill 的描述时Agent 会把这份文件的内容注入自己的上下文然后按照里面的流程工作。1.2 Skills 与普通 Prompt 的本质区别普通 Prompt 是一次性的。你把规则写在聊天框里这个会话有效下一个会话还要重新写。稍长一点的规则会占大量上下文空间而且不同用户、不同项目之间很难共享同一套规则。Skills 相当于把 Prompt 升级为“可安装的模块”。它具备三个普通 Prompt 没有的特点可发现Agent 通过 description 判断是否应该加载这个 skill。可复用同一个 skill 可以安装在个人目录也可以放在某个项目里被团队共享。可维护skill 是文件可以进 git、做版本管理、走代码评审、写测试用例。普通 Prompt 告诉模型“这一次怎么做”skill 告诉模型“遇到这类任务时始终按这套标准做法执行”。1.3 Skills 在 Agent 工作流中的位置一个带 skills 能力的 Agent通常工作流程是这样的接收用户任务例如“帮我看看为什么 requirements.txt 装不上”。Agent 解析任务意图并与已安装 skill 的 description 做匹配。匹配成功后Agent 读取对应SKILL.md必要时也读取 skill 目录下的 references、scripts 等附属文件。模型把 skill 内容当作执行规则结合工具能力完成步骤。最终输出结果。在这个链路里skill 不是被外部程序直接调用的函数而是“指导模型如何完成任务的上下文”。不理解这一点很容易把 skill 与插件、工具、MCP 混在一起。2. 先分清 Skills、MCP、Tools 和普通 Prompt2.1 核心概念的定位在 AI Agent 生态里常见的四个概念是普通 Prompt、Skill、ToolFunction Calling和 MCP Server。四者经常被混用但解决问题的层次完全不同。普通 Prompt 是给模型的一次性指令所有内容都在对话里传递。Skill 是打包好的过程性知识可以包含步骤、规范、示例、参考文档甚至能附带脚本。它强调“模型应该怎么想、怎么按流程做”。Tool 是一个可执行的函数通常有入参和出参Agent 根据任务决定是否调用。它强调“模型可以动用什么能力”。MCP Server 是一个标准化的服务通过 Model Context Protocol 暴露一组工具和数据源让多个 Agent 应用可以复用同样的后端能力。它解决的是“工具之间如何统一接入”的问题。2.2 四者对比维度普通 PromptSkillTool / FunctionMCP Server本质一次性指令可复用的过程性知识包可调用的函数通过标准协议暴露工具与数据源主要作用调整当前对话行为指导模型按固定流程完成任务执行具体操作并返回结果统一接入外部工具和数据是否自动加载否需要每次粘贴是根据 description 自动匹配模型按需调用模型从工具列表中调用是否涉及执行不执行本身不执行可引用脚本执行函数逻辑由服务端执行典型场景临时写作要求代码评审、依赖排查、设计走查查询天气、创建文件、调用 API连接数据库、业务系统、外部 API从这张表可以看出skill 和 MCP 并不是竞争关系。简单说MCP 或 Tool 解决“能力有没有”skill 解决“任务怎么做更规范”。2.3 什么时候该用 Skills以下场景适合把能力沉淀为 skill任务频率高团队反复让 AI 完成同类工作。任务有明确的步骤和质量要求不能只靠模型自由发挥。任务需要大量背景知识每次重复写提示词成本很高。任务输出格式需要统一方便后续自动化处理。反过来如果任务只需要一次临时问答或者需要实时查询外部系统或者需要真正修改生产数据那更适合用普通对话、Tool 或 MCP而不是 skill。3. 从零开发一个可复用的 AI Skill3.1 Skill 的最小目录结构一个 skill 本质上是一个目录目录里必须有一个SKILL.md。最小的结构是这样python-deps-check/ ├── SKILL.md └── references/ └── pip-error-dictionary.mdSKILL.md是入口文件模型只会自动读取这个文件。references目录用来放需要按需引用的长文档比如常见错误对照表、团队规范、示例片段。脚本可以放在scripts目录里但 skill 本身不能保证所有环境都能执行脚本因此脚本只作为辅助不应该是唯一逻辑。在很多 Agent 工具中skill 会被放到约定好的目录里。常见路径有~/.claude/skills、.claude/skills也有工具使用.codex/skills或.cursor/skills。具体用哪个目录以你使用的工具文档为准。开发时建议先在项目目录里建一个 skills 子目录调试通过后再决定是放到个人目录还是发布到团队仓库。3.2 Frontmatter 决定“何时被触发”SKILL.md的开头必须有 YAML frontmatter。最少包含两个字段name和description。--- name: python-deps-check description: 当用户遇到 pip install 报错、Python 依赖版本冲突、导入失败或 requirements.txt 无法安装时使用本技能排查依赖关系并给出修复步骤。 ---name是技能的唯一标识通常用短横线连接的英文命名例如python-deps-check。description不是简介而是“触发条件”。Agent 会根据用户问题与 description 的匹配程度决定要不要加载这个 skill。description 写得越具体越好。不要写“这是一个排查 Python 依赖问题的技能”而要写清楚“当用户遇到 XXX 类问题时使用本技能”。因为模型匹配的是语义不是搜索引擎里的关键词密度。触发场景里的动词、对象、报错现象都要写出来。3.3 正文是“工作说明书”不是“背景科普”SKILL.md正文会被模型当作工作指南。它应该包含目标、前置条件、执行步骤、检查点、输出格式。避免写大段背景介绍因为上下文空间宝贵而且模型不需要知道 skill 是怎么被发明的它需要知道下一步做什么。可以按这个顺序组织正文技能目标这个 skill 解决什么问题。前置条件什么情况下才能开始执行需要哪些输入。执行步骤按顺序列出必须完成的动作。检查点每一步完成后如何确认结果正常。输出格式最终回答需要包含哪些部分。禁用行为哪些操作不要做。3.4 示例开发一个 Python 依赖冲突排查 Skill下面给一个完整的SKILL.md示例。这个 skill 的作用是让 Agent 按固定流程排查 Python 依赖问题。--- name: python-deps-check description: 当用户遇到 pip install 报错、Python 依赖版本冲突、导入失败、requirements.txt 无法安装或 package 版本不兼容时使用本技能排查依赖关系并给出修复步骤。 --- # Python 依赖排查 ## 目标 定位 Python 项目中依赖冲突或安装失败的具体原因给出可执行修复方案。 ## 前置条件 1. 用户提供报错信息、项目目录或 requirements 文件。 2. 如果用户没有提供先请求用户贴出以下内容中的任意一种完整报错日志、requirements.txt、pyproject.toml、pip install 命令。 ## 执行步骤 1. 读取项目依赖文件。 - 检查 requirements.txt、pyproject.toml、Pipfile 是否存在。 - 如果文件不存在提示用户先创建虚拟环境并生成依赖文件。 2. 识别报错类型。 - 如果报错包含 No matching distribution说明包源或包名有问题。 - 如果报错包含 conflict 或 dependencies说明依赖约束冲突。 - 如果报错包含 ImportError 或 ModuleNotFoundError需要检查运行时环境是否与依赖声明一致。 3. 判断 Python 版本。 - 执行 python --version 或让用户提供版本。 - 许多包在新旧 Python 版本中的支持策略不同先确认版本再继续。 4. 选择排查策略。 - 小项目建议使用虚拟环境重新安装。 - 大项目使用 pip check 检查已安装包的依赖一致性。 - 存在平台差异时检查 Pillow、numpy、pydantic 等常见二进制包是否匹配当前平台。 5. 给修复建议。 - 如果只是临时环境问题建议重建虚拟环境。 - 如果是锁文件缺失建议先生成锁文件再安装。 - 如果某个包版本过旧明确建议升级到哪个版本并说明影响范围。 6. 输出最终报告。 ## 输出格式 最终回答必须包含 - 根因一句话说明问题出在哪。 - 证据命令行输出、报错关键字或依赖树片段。 - 修复步骤按顺序给出命令和预期结果。 - 验证方式如何确认问题已经解决。 - 预防建议如何避免下一次同类问题。 ## 禁用行为 1. 不要直接建议 pip uninstall 或 pip install --force-reinstall 而不说明后果。 2. 不要在没有安装日志的情况下猜测包名拼写错误。 3. 不要修改项目依赖文件而不先备份。这个示例包含了模型完成排查任务所需的全部信息。关键在于任何用户只要复现同一个问题Agent 都会按相同顺序处理不会再出现“这次问到的答案和上次完全不一样”的情况。3.5 示例Web UI 设计走查 Skill如果团队经常让 AI 评审前端页面可以把设计走查规则做成 skill。这里只给出 frontmatter 和正文骨架实际使用时要补上团队自己的设计规范。--- name: web-ui-design-review description: 当用户要求评审网页界面设计、检查布局一致性、色彩对比度、间距规范、可访问性或响应式问题时使用本技能逐项走查并输出评审报告。 --- # Web UI 设计走查 ## 目标 按照既定设计规范对页面进行系统走查输出问题清单和修改建议。 ## 前置条件 1. 用户提供页面截图、线上地址或设计稿描述。 2. 如果页面包含明确设计规范先读取规范文档。 ## 执行步骤 1. 检查布局层级。 - 确认页面是否遵循栅格系统。 - 确认主要模块之间的间距是否一致。 2. 检查色彩对比度。 - 前景色与背景色对比度应满足可访问性要求。 - 深色模式和浅色模式都要检查。 3. 检查字体与文字层级。 - 标题、正文、辅助文字的字号与字重是否分级。 - 长文本行宽是否适合阅读。 4. 检查交互状态。 - 按钮是否包含 hover、active、disabled 三类状态。 - 表单错误提示是否出现在输入框附近。 5. 检查响应式表现。 - 桌面端、平板、手机端的布局是否分别合理。 - 关键操作在窄屏下是否仍然可达。 6. 输出评审报告。 ## 输出格式 评审报告必须包含 - 页面截图或位置描述 - 严重程度阻断性问题、一般问题、建议优化 - 问题描述指出具体不符合的规范点 - 修改建议给出可落地的 CSS 或布局调整方向 ## 禁用行为 1. 不要只写“整体设计不错”必须逐项给出结论。 2. 不知道设计规范时先询问用户而不是默认使用某种风格。 3. 不要修改线上代码只做评审和建议。这个示例说明一个问题skill 并不局限在编程任务里。设计走查、文案审核、测试用例设计、论文写作辅助只要流程足够固定都可以写成 skill。3.6 容易误解的细节Skill 不是插件也不是 Prompt 模板Skill 和 Prompt 模板最大的区别是Prompt 模板通常只解决“怎么写提示词”而 skill 是完整的上下文包它可以附带参考文档、脚本和校验清单。Skill 也不是插件。插件通常会在 Agent 里注册新的命令或 UI而 skill 不一定会注册为一个独立按钮。它更接近“当上下文命中时被自动注入的操作指南”。有些工具会把 skill 显示出来让用户手动触发但触发后真正起作用的仍然是SKILL.md里的内容。4. 安装、加载与验证 Skill 是否生效4.1 个人级安装与项目级安装Skill 的安装方式不统一但常见的做法是复制目录到约定路径。以 Claude Code 这类工具为例可能有这些位置~/.claude/skills/ # 个人级所有项目可用 .claude/skills/ # 项目级仅当前项目可用如果你使用的是 Codex CLI、OpenCode 或其他 Agent 工具目录名可能是.codex/skills、.skills或.cursor/skills。开发前先花两分钟确认工具支持哪种 skills 约定否则文件放错了位置Agent 不会报错但也不会加载。个人级 skill 适合经常使用的通用技能比如“依赖排查”“代码评审”“Commit 信息生成”。项目级 skill 适合与项目强绑定的团队规范比如“本项目的 API 设计规范”“本项目的目录约定”“发布前检查清单”。# 示例把开发好的 skill 放到个人目录 mkdir -p ~/.claude/skills/python-deps-check cp -r python-deps-check/SKILL.md ~/.claude/skills/python-deps-check/# 示例项目级安装 mkdir -p .claude/skills cp -r python-deps-check .claude/skills/注意这里用的是示例目录具体路径以你使用的 Agent 工具说明为准。4.2 触发方式自动匹配与手动调用大多数 Agent 工具同时支持两种触发方式自动匹配用户问题命中 skill 的 description 时Agent 自动加载 skill。手动调用用户在会话里输入斜杠命令或从技能列表里选择技能。自动匹配适合“不打扰用户”的场景但前提是 description 写得准确。手动调用适合用户清楚知道要用哪个技能的场景比如“用设计走查 skill 检查这个页面”。开发阶段建议先手动调用确认 skill 内容正确后再依赖自动匹配。否则你无法判断技能没生效是路径问题还是 description 匹配问题。4.3 验证 Skill 是否真的被读取验证 skill 是否被读取可以使用三种方法查看技能列表。很多 Agent 工具提供列出所有可用技能的命令例如/skills。如果技能没有出现在列表里说明安装路径或文件格式有问题。直接在对话里要求 Agent 说明自己正在使用哪个技能。你可以问“你现在是否加载了 python-deps-check 技能”并观察模型是否回答出技能名称和内容概要。查看会话日志或扩展日志。不同日志路径不同但通常可以在日志里搜 SKILL.md 或技能名字。注意不要只验证技能列表里能看到它还要验证执行过程中确实读到了技能内容。技能列表只证明文件被扫描到了不等于模型按流程执行了。4.4 最小验证实验给技能加“水印”一个很实用的验证技巧是在SKILL.md里加入输出标记要求。例如在技能正文末尾写## 输出标记 当本技能的所有步骤执行完成后在最终回答的最后一行输出 SKILL_MARK[python-deps-check:executed]如果 Agent 确实加载了 skill最终回答会出现这行标记。如果没出现说明 skill 没有被读取或者读取的内容被模型忽略了。这个技巧在开发阶段很有用但正式发布时通常不需要这种水印除非你希望通过日志解析来统计技能使用情况。4.5 学习环境与生产环境的差异学习阶段可以直接在个人目录里建 skill改完马上测试低成本迭代。生产环境要考虑更多因素版本控制skills 目录应该纳入 git记录每次变更。测试为每个 skill 准备一组输入和预期输出跑回归。权限包含敏感信息的 skill 不要放到公共仓库项目目录权限要控制。审计在日志中记录技能命中情况方便分析“哪些技能有效哪些技能长期没被使用”。回滚如果新版 skill 导致 Agent 行为异常要能快速回退到上一个版本。5. 常见问题排查Skill 不生效时按这条链路查5.1 按链路排查的顺序当 skill 不生效时不要先怀疑模型能力按下面的顺序排查。确认文件路径是否正确。确认 skill 是否出现在技能列表里。确认SKILL.mdfrontmatter 格式是否正确。确认 description 是否覆盖用户问题里的表达。确认正文是否包含明确步骤和输出要求。确认工具版本是否支持 skills。查看日志确认 agent 是否读取了该 skill。5.2 问题现象与处理方案问题现象常见原因检查方式处理建议技能从未被调用description 没有覆盖用户问题的表达查看技能列表并阅读 description在 description 里补充用户常说的动词、对象、报错现象技能列表里看不到技能目录路径或文件命名错误对照工具文档确认目录名和文件名将目录移到约定路径保证文件名是 SKILL.md技能被读取但回答不完整正文缺少步骤和检查点检查正文是否按执行顺序组织把引言改成“目标、步骤、输出格式、禁用行为”更新 SKILL.md 后不生效Agent 缓存了旧的技能信息重启会话或重新加载技能列表修改后先重启会话再验证多个技能名称冲突name 字段重复查看技能列表是否出现同名项修改 name 为唯一值技能引用的脚本没有执行当前环境没有脚本执行权限或依赖检查脚本权限和依赖确保 skill 不依赖脚本也能给出主要方案5.3 三个最典型的坑第一个坑是 description 写得太像简介。比如写“这是一个前端设计评审技能”模型很难判断什么情况下该用它。正确写法是列出触发场景“当用户要求评审网页界面设计、检查布局一致性、色彩对比度、可访问性或响应式问题时使用本技能。”模型匹配的是语义不是标签。第二个坑是正文写成了科普文档。开发技能时容易把SKILL.md写成介绍文章堆了很多背景。但模型读取技能时需要的是行动指令。把“什么是布局一致性”改成“检查页面主要模块之间的间距是否一致”效果会好很多。背景可以放进 references 目录按需引用。第三个坑是让 skill 承担动态执行能力。比如在 skill 里写“查询数据库并返回结果”但 agent 根本没有数据库连接工具模型只能给出一段伪代码。正确做法是把动态能力交给 Tool 或 MCPskill 只负责告诉模型“查询后如何解读结果、如何组织输出、遇到异常如何处理”。5.4 排查清单检查项操作目录路径确认 skill 位于工具约定的 skills 目录下文件命名确认入口文件名是 SKILL.mdFrontmatter确认 name 和 description 存在格式是合法 YAML触发描述用用户真实问题测试是否能命中 description正文结构确认包含步骤、检查点、输出格式引用文件确认 references 或 scripts 路径相对 SKILL.md 正确会话状态修改后重启会话或重新加载技能列表日志搜索 SKILL.md、技能名或输出标记确认被读取6. 从“会用 Skill”到“写好 Skill”工程实践与扩展6.1 Skill 开发检查清单写一个可维护的 skill下面这些检查项值得遵守。name 使用 kebab-case比如web-ui-design-review。description 写清触发条件不写空泛介绍。正文从目标开始明确执行步骤、检查点、输出格式。高频长文档放到 references 目录避免每次加载全部内容。输出格式保持一致便于后续脚本解析。涉及脚本时确保 skill 在无脚本环境下也能给出核心方案。不把密钥、内网地址、敏感业务数据写进 skill 文件。每次修改都进 git并写清楚变更原因。为 skill 准备两个测试输入和一个预期输出。定期检查哪些 skill 被频繁使用清理长期未用的技能。这个清单可以直接复制到团队文档里作为 skill 编写规范。6.2 团队共享与版本管理skill 的目录结构和普通代码项目一样可以放进 git 仓库。建议按下面结构组织团队技能库team-skills/ ├── python-deps-check/ │ └── SKILL.md ├── web-ui-design-review/ │ └── SKILL.md └── README.mdREADME.md可以写明每个 skill 的用途、安装方法、维护人、测试方式。发布时可以采用 tag 标记版本例如v1.0.0避免团队里出现“新旧版本混用但说不清谁在哪个版本”的问题。社区里也有很多开发者整理的 skills 合集安装他人 skill 前要做三件事检查SKILL.md内容是否满足你的安全要求确认许可证允许使用注意维护频率。不要因为标题好看就一键安装到生产环境。6.3 如何测试 Skill测试 skill 不能只靠“我试了一次好像有效”。建议建立一个测试用例文件每个用例包含输入、期望步骤、期望输出标记。python-deps-check/ ├── SKILL.md ├── references/ └── tests/ ├── case-1-input.txt ├── case-1-expected.md └── case-2-input.txt每次修改 skill 后把测试输入重新发给 Agent对照期望输出检查是否一致。如果行为变化判断是改进还是回归缺陷。遇到模型自身输出不稳定的情况可以通过“输出格式”和“检查点”来约束尽量减少随机性。6.4 与 MCP、Hooks、Templates 一起用Skill 不是孤立概念。复杂 Agent 应用里Skill、MCP、Hooks、Templates 可以配合MCP 提供外部工具和数据源能力。Skill 提供完成专业任务时的流程指导。Hooks 在特定生命周期触发时执行脚本比如任务开始前做检查。Templates 提供项目骨架比如“新建一个 Python 服务时先生成标准目录”。选型时可以这样判断需要真实调接口或查数据用 MCP 或 Tool需要模型按规范完成多步任务用 Skill需要在事件节点自动执行脚本用 Hooks需要快速初始化工程结构用 Templates。6.5 下一步学习方向已经会写简单 skill 后可以继续往三个方向深入研究较长技能的内容组织当SKILL.md超过几十 KB 时如何拆分成 references、如何设计“先读哪份文档”的决策逻辑。编写跨工具兼容的技能尝试让自己的 skill 同时在 Claude Code、Codex、OpenCode 中可用注意不同工具对 frontmatter 字段和目录约定的差异。将 skill 与业务系统打通通过 MCP 获取业务数据再通过 skill 决定如何分析、判断和输出形成完整 Agent 工作流。AI skills 的价值不在于文件本身而在于它把专业经验沉淀成了模型能稳定消费的结构化知识。对于普通开发者先从一个 30-50 行的SKILL.md开始把它放到项目里跑通再逐步加入 references 和脚本是最稳妥的路径。真正需要理解的不是某个工具的命令而是让 Agent 稳定、可复现地完成任务的方法。
