最近我一直在折腾一件事把脑子里那些我会、但懒得每次重复交代的经验写成一个个 Skills 丢给 AI Agent 用。起因很简单每次让 Claude 帮忙写代码、让 Codex 整理报告都要临时贴上一大段背景说明、约束条件、输出格式烦了。后来试了一下 Agent Skills 的思路把这些重复性要求固化成独立的技能包Agent 一遇到对应场景就会自动调用实测下来整个工作流的稳定性和效率都上了一个台阶。今天这篇不聊概念空话直接把 Skills 是什么、主流生态有哪些、怎么写一个能用的 Skill、踩过哪些坑一次讲清楚。适合三类人看正在用 Claude Code / Codex 这类工具但觉得不够懂我的人想给 AI 编程助手定制专属工作流的人以及准备在团队里推广 Agent 协作方式的技术负责人。1. Skills 到底是什么AI 能力扩展的一次范式转变1.1 从提示词到技能Agent 是怎么变专业的先说一个所有 AI 重度用户都会遇到的痛点。大模型本身博学但它的博学是泛化的。你让它写一段 Python它写得像样你让它按照你们团队特定的代码规范、特定的文件组织方式、特定的测试框架来写它就抓瞎了因为它不知道这些隐性规则。早期解决方案是把这些规则写进一个超级长的 system prompt 里几百行既占上下文窗口又容易让模型在各种指令之间迷失。Skills 解决问题的思路完全不同它把一套特定场景下的完整工作方法封装成一个独立单元里面可以有指令、有模板、有参考示例、有可执行脚本。平时它安静地躺在技能目录里不占上下文当 Agent 根据任务描述判断这个场景匹配某个技能时才把它加载进来按照技能里的方法一步步执行。我习惯用一个类比这就像给一个全科医生配了一柜子专科诊疗手册平时不需要翻开遇到对应病例时按手册流程操作效率和准确率都会高很多。1.2 为什么是 Skills 而不是传统插件传统插件系统存在多年浏览器插件、IDE 插件、编辑器插件都是成熟形态。那 Agent Skills 又有什么不同核心差异在于插件的边界是人技能的边界是模型。传统插件需要开发者编写大量代码定义 UI、事件、接口用户还要处理安装、权限、版本兼容。而一个 Skill 核心通常就是一个结构化 Markdown 文件加一些附件资源它描述的是当遇到什么情况时按什么步骤做参考什么模板产出什么格式。模型负责理解和执行技能只负责提供知识和方法。这种设计带来的直接好处是轻量一个技能常常只有几个文件不需要编译打包可读技能内容本质是给人看的 Markdown既能被模型执行也能被人类 review可组合一个任务可以按顺序调用多个技能互相不污染可分发复制一个文件夹就能分享天然适合 Git 管理也是因为这种设计Skills 在 2024 年之后几乎成了各家 Agent 产品的标配能力从 Claude 到 Codex再到各种开源 Agent 框架核心思路都趋同让模型在正确的时候启用正确的技能。2. 主流 Skills 生态与选型对照2.1 三种主流实现方式现在市面上你能接触到的 Skills大体分三类。第一类是 Claude Agent Skills形态最规整。它规定了标准的技能目录结构核心是一个SKILL.md文件里面通过 YAML frontmatter 写技能名称和触发描述正文写具体执行步骤。技能可以挂在用户级目录、项目级目录或者通过官方市场安装。因为生态起步早社区里分享的现成技能数量最多。第二类是 Codex 的 Skills 体系。Codex 本身定位是执行编码任务的 AI Agent所以它的技能更偏向工程场景代码生成、仓库理解、测试编写、文档产出。加载方式与 Claude 类似也是目录结构加配置文件但具体路径和命令有差异。要注意的是Codex 的 skills 版本迭代很快不同版本的加载方式可能不一样最稳妥的方式是看当前版本的 CLI 帮助或官方文档。第三类是 GitHub Skills这个要单独说。GitHub Skills 更多是平台侧的交互式培养机制它把学习资源做成了仓库模板你在一个仓库里跟着 step-by-step 的 issue 流程完成任务从而掌握某个技能。这和 Agent Skills 不是一回事但很多人搜 skills 时会混淆所以选型前先搞清楚你要的是给 AI 装的技能还是给自己学的技能。为了让你看得更直白我整理了一张对照表类型核心载体运行方式典型适用场景主要受众Claude Agent SkillsSKILL.md 资源目录Agent 根据任务描述自动加载通用业务、文档、分析、编码Claude 用户、Agent 开发者Codex Skills技能目录 配置CLI 调用时按需加载编码辅助、仓库操作、研究开发者、DevOpsGitHub Skills仓库模板 issue 流程人机交互式引导学习者培养技能编程学习者、团队 onboarding2.2 判断一个 Skills 值不值得用的四个维度社区里现成 Skills 越来越多GitHub 上随手一搜就是一大批但质量参差不齐。我用四个维度筛选分享给你当参考。可维护性技能文件是不是纯文本、目录结构是否清晰、是否标注了适用边界和依赖项。一个文件套文件、结构混乱的技能加载成功率低后续想改也难。可调试性技能执行过程是否可观察。好的技能会让 Agent 阶段性地输出中间结果比如先读取配置文件再生成报告草稿这样出了问题你能准确定位是哪个环节。高效性技能加载后是不是真的减少了模型的无效思考。有些技能写了一大堆步骤结果每个步骤都在让模型自由发挥那还不如直接写个 prompt。安全性这一点我放在最高优先级的检查项。技能本质是一段会被 Agent 执行的指令文本存在提示词注入和恶意操作的风险来历不明的技能包坚决不碰。2.3 值得重点关注的技能方向从搜索热度和实际效果看以下几类 Skills 是当前社区里最被认可的。编程辅助类代码生成、Code Review、单测生成、依赖升级、命令行工具封装。这类技能把团队的工程规范固化下来Agent 生成代码时自动带上。写作研究类论文结构设计、文献综述框架、报告格式整理。比如你想让 Codex 帮你写论文一个好的技能会让它先建立大纲再逐节填充而不是一次性吐出一篇结构随意的文字。数据分析类数据清洗流程、图表生成、统计口径统一。技能里可以内置模板和检查清单保证每次输出的图表风格一致。移动安全与合规分析类这类技能通常封装壳检测、权限清单分析、反编译辅助等流程帮助安全人员在授权范围内做合规评估。我必须强调任何涉及逆向分析的技能只能用于自己拥有或已获得明确授权的应用绝不能服务于破解、灰产等非法目的。技术研究有边界这个边界别去踩。3. 从零开发一个自定义 Skill完整实操流程3.1 设计原则一个技能只干一件事这是我想强调的第一条原则。很多人第一次写 Skills 时会不自觉地写一个大而全的技能把帮用户处理日常事务当作描述结果 Agent 几乎在所有任务里都想加载它反而成了干扰。正确的做法是聚焦。我有一个专门的项目 README 生成技能职责非常单一当用户要求为项目生成说明文档时读取项目元信息按固定模板产出 README。不碰代码生成不碰依赖安装不碰部署流程。技能边界越清晰Agent 的触发判断就越准执行效果也越好。在设计阶段你先回答四个问题这个技能在什么场景下被触发输入是什么比如项目路径、数据文件、一段需求描述。输出是什么比如一份文档、一个表格、一段代码。它需要哪些外部资源比如模板文件、参考示例、可执行脚本。回答清楚再动手写。3.2 编写 SKILL.md核心是让 Agent 在正确时机加载你一个 Skill 的核心是SKILL.md文件它通常分成两大部分文件头部的元信息和正文的操作指引。看一下我的 README 生成技能的简化版--- name: readme-generator description: 当用户要求为项目生成 README、使用说明或项目介绍文档时使用。尤其当项目包含 package.json、pyproject.toml 等元信息文件时优先考虑加载。 --- # README 生成技能 ## 你的任务 为给定项目生成一份结构清晰的 README 文档包含项目简介、快速开始、目录说明、常见问题四个部分。 ## 执行步骤 1. 查看项目根目录元信息文件确认项目类型、依赖、启动命令。 2. 扫描源码目录归纳核心模块和主要入口。 3. 按模板填充内容保留具体的命令示例。 ## 输出要求 - 文档使用中文命令保持原样。 - 未知信息不要编造标注为待补充由用户确认。这里最关键的其实是description字段。Agent 判断是否加载技能主要靠它。如果 description 写得太抽象比如帮助用户写文档Agent 很可能在用户没有明确说生成 README时就跳过如果写得太宽泛又容易误触发。我的经验是description 里至少要包含触发场景、判断条件和偏好使用场景措辞要具体最好带上当……时使用优先考虑这类句式。正文部分要写清楚任务目标、执行步骤和输出要求。步骤不必写得太细给模型留出合理的推理空间但也不能空泛到按一般流程执行。最好的状态是一个熟悉该领域的人看完你的步骤能照做一个模型看完你的步骤能知道先做什么后做什么、产出物长什么样。3.3 绑定资源与脚本技能不只是提示词很多人误以为写个 SKILL.md 就算完事。实际上一个成熟的技能往往还要绑定资源。我的 README 技能目录是这样组织的readme-generator/ ├── SKILL.md ├── templates/ │ └── readme_template.md ├── scripts/ │ └── scan_project.py └── reference/ └── examples/ ├── example_1.md └── example_2.mdtemplates目录放输出模板scripts目录放辅助脚本reference目录放示例参考。这样设计的好处是模型在生成内容时有三层依据指令定义了流程模板定义了格式示例定义了风格。尤其是示例参考这个目录对提升输出质量帮助极大。大模型其实很擅长模仿你只要给它两三个高质量的示例它产出的内容风格立刻就会朝示例靠拢。辅助脚本可以很轻量比如scan_project.py只需要做一件事遍历项目目录提取关键文件结构并输出成简短的 JSON 摘要。#!/usr/bin/env python3 import os import json import sys def scan_project(root): result {files: [], dirs: []} for current, dirs, files in os.walk(root): rel_dir os.path.relpath(current, root) if rel_dir.startswith((., __pycache__, node_modules)): continue level rel_dir.count(os.sep) if level 1: result[dirs].append(rel_dir) for file in files: if file.endswith((.py, .js, .ts, .json, .toml, .md)): rel_file os.path.relpath(os.path.join(current, file), root) result[files].append(rel_file) return result if __name__ __main__: root sys.argv[1] if len(sys.argv) 1 else . print(json.dumps(scan_project(root), ensure_asciiFalse, indent2))SKILL.md 里可以这样引用脚本先让 Agent 运行python scripts/scan_project.py 项目路径把结果作为后续步骤的输入。这样一来技能从一个纯提示词变成了提示词 工具的组合能力边界一下就拓宽了。3.4 安装与加载官方市场、本地目录、团队共享技能写好后怎么装进去让它真正生效结合我自己的实践常见方式有这么几种。最省事的方式是从官方市场或社区源安装。下载一个技能压缩包或通过命令拉取然后解压到对应的技能目录。通常 Agent 产品会提供一个命令行入口比如skills install或skills add之类的子命令具体以你当前工具的--help输出为准。第二种是本地手动安装。这也是我用的最多的方式因为我对自己的技能目录有强控制欲。你只需要把技能文件夹放到约定的目录里即可。常见的全局技能目录包括用户主目录下的.claude/skills、.codex/skills等如果想做成项目级共享也可以放到项目目录下的.claude/skills或.codex/skills里。放在项目目录的好处是整个项目成员都能用配合 Git 管理非常舒服。第三种是作为文件直接导入。有些工具支持在对话中手动指定技能路径比如使用 /path/to/readme-generator 这个技能来生成 README。这种方式适合测试场景你还没决定要不要长期安装时可以先手动挂载试用。安装完成后建议你做的第一件事不是直接上线而是检查技能加载日志。大部分支持 Skills 的 Agent 工具都会在日志里输出已加载技能 xxx或根据描述匹配到技能 xxx之类的信息。这个日志是验证技能是否被正确识别的最快途径。4. 实战演练让 Agent 在正确时机调用你的技能4.1 在 Claude Code 中挂载并触发技能我以 Claude Code 为例说一遍完整流程。先确认你的技能目录位置把写好的readme-generator文件夹放进去。用claude命令启动交互对话然后说一句帮我给当前项目生成一份 README。如果技能加载正常它会在对话中明显表现出按步骤执行的痕迹先让我确认项目类型然后查看目录结构再按模板输出。如果没有这些表现说明技能没有被命中回到description字段去优化措辞。有一个值得留意的细节技能目录的路径不要有中文和空格。模型解析路径时中文和空格偶尔会引发意外尽量用英文短横线命名比如readme-generator而不是README_生成器。4.2 在 Codex 中启用同一套技能如果你像我一样同时使用多个 Agent 工具会希望同一套技能在 Codex 里也能用。好消息是 Codex 也支持类似的技能目录机制做法基本一致只是目录位置和命令前缀不同。以常见的 Codex CLI 为例你可以先执行codex skills list看看当前识别的技能路径然后把自己的技能文件夹放到对应目录重启会话后再执行codex skills list确认加载成功。Codex 对技能的执行逻辑通常更偏向命令行 编辑文件所以在技能的操作指引里你可以多写一些运行命令读取文件修改指定位置这类描述它会更容易领会。4.3 快速测试技能效果的三个方法技能装完只是第一步真正重要的是验证效果。我每次写新技能都会做三轮测试。第一轮是正面触发测试。用自然语言发出与技能描述高度匹配的指令看看技能能否被正确加载。比如对 README 技能直接说生成 README写一个项目说明文档。第二轮是边界测试。发一些模棱两可的指令比如帮我整理一下这个目录观察它是否会误触发。如果误触发了说明 description 里的条件判断写得太宽需要收紧。第三轮是对比测试。加载技能和不加载技能用相同的指令各跑一次对比输出质量。这个测试能直观告诉你技能到底有没有带来增量价值。如果两者输出差别不大说明技能的步骤设计得不够扎实哪怕触发了也是空转。5. 常见问题与排查技巧实录5.1 技能从来没被触发这个现象出现得最多。排查思路先看日志确定技能有没有被加载如果日志显示加载了再看是不是 description 写得太宽或太窄。太宽会导致 Agent 在无关任务里反复尝试太窄会导致它根本没有辨识出触发场景。调整方向是把描述里的关键词与实际用户语言对齐。比如用户常说生成说明文档你的 description 里就应该包含说明文档这个说法而不是只写README。5.2 加载报错或技能队列异常多数情况是目录结构问题。SKILL.md文件名必须是全大写很多工具靠这个文件名识别技能根目录大小写写错技能会被当普通目录忽略。另一种常见问题是 YAML frontmatter 格式错误比如name或description冒号后面少了空格、引号没闭合。这类错误通常在日志里会有明确提示按提示修正即可。5.3 多个技能的说明互相冲突当你的技能库大了以后会发现两个技能的 description 都覆盖了某个场景Agent 就会随机选一个或者来回跳。解决办法是给每个技能设一个明显的边界词。比如README 生成和文档整理两个技能前者在 description 里强调生成新的说明文档后者强调对已有文档做结构重组和分类。用词错开触发判断就稳定很多。5.4 安全风险来历不明的技能不要乱装这一点我必须单独拎出来讲。Skills 本质上是一种可被模型执行的指令载体恶意技能完全可以通过精心构造的 description 和步骤诱导模型执行危险操作比如读取敏感文件、执行带风险的系统命令、把数据外发到指定地址。你在网上看到效果炸裂一键搞定一切的技能包时多留个心眼。我的安全实践是只安装明确开源、能看完全部文件内容的技能技能里出现的每一条命令我都确认过它的作用绝不在技能里写绕过破解获取未授权数据这类指令也不要传播包含这些内容的技能很多人觉得AI 技能罢了能有什么风险实际上提示词注入的攻击面确实存在于这个环节。别让一个所谓的高效技能变成你环境里的后门。5.5 同一套技能在不同版本间失效Agent 工具迭代非常快经常出现某个版本还支持的技能目录路径下一个版本就废弃了。我的应对思路是把技能当作项目内共享资产来管理而不是绑定某个人的本机路径。在团队项目里把技能目录打进项目仓库每次升级工具时跑一遍技能兼容性检查发现问题就及时调整目录结构或配置项。多花十分钟做兼容适配比同事在群里说技能失效了强得多。6. 写技能这段时间的一些实话写得多、用得多了以后我最大的体会是Skill 不是把提示词换了个名字而是一种新的思考方式。以前我写 prompt 想的是怎么让模型听懂这句话现在写技能想的是怎么让一个陌生同事按照我的方法独立完成任务。两者的差别在于前者是对话后者是制度。还有一点很实用就是用 Git 管理你的技能库。每一次修改都保留版本记录每一次上线新技能都 commit 一次每个技能都写清楚它解决什么问题、不解决什么问题。时间拉长以后你的技能库就成了一笔有复利效应的资产而不是一堆散落的 Markdown 文件。如果你刚开始接触 Skills我的建议是别一上来就攒几十个技能。先挑一个你每天都在做的重复性任务比如生成周报、整理代码变更记录、写项目复盘做一个最小可用的技能跑通一遍编写—安装—触发—验证的闭环。等你真正体会过一次Agent 自动按照你的套路干活的顺畅感再慢慢扩充技能库也不迟。最后分享一个小经验技能里的示例文件比你在说明文档里写十句要专业一点都管用。模型是模仿大师你给它什么质量的样例它就回你什么质量的输出。所以把团队里最好的那份文档、最规范的代码片段、最成熟的报告模板挑出来放进去效果立刻不一样。
