先说我自己的结论这段时间我把 Claude Agent Skills、Codex 的 skills 机制、GitHub 上几个热门的 skills 仓库都翻了一遍自己也动手写了好几个。这东西不是什么新编程语言也不是什么框架它本质上是一套“给 AI 智能体用的能力扩展包”——把过去散落在 prompt 里的专业知识、操作流程、注意事项打包成一个结构化目录让 AI 在需要的时候按需加载、直接执行。听起来不复杂但实际用下来它对 AI 输出质量的上限提升远比想象中大。这篇东西我会从第一性原理的角度拆开讲skills 到底解决什么问题、内部结构长什么样、怎么自己开发一个、生态里有哪些好东西、以及我踩过的坑。适合的人群很明确正在用 Claude 或 Codex 做编码、写文档、做数据分析的人尤其是那些觉得“AI 总差一点意思”的开发者——大概率不是模型不行而是你还没给它一套像样的技能包。1. 从 Prompt 到 Skills一场必要的“能力封装”革命1.1 Skills 的核心思路渐进式披露先聊一个根本问题为什么需要 Skills在 skills 出现之前我们驯服 AI 主要靠两条路一条是写超长系统提示词把自己的行业知识、代码规范、输出格式全塞进去另一条是 RAG把文档库挂给模型让它去检索。但这两条路都有明显天花板。系统提示词的问题是“一次性加载”。你写了一个 3000 字的编码规范放在 system prompt 里模型每次对话都要处理这 3000 字。真正干活的时候它需要的是“写 Python 代码时注意 PEP8”而不是整段规范文本。这就好比你把整本《烹饪大全》塞给一个厨师告诉他“你要做红烧肉”他当然能做但阅读负担巨大而且书里那些法餐、日料的内容会干扰他对红烧肉火候的判断。RAG 的问题是“检索颗粒度太粗”。RAG 擅长回答“某某函数的签名是什么”“某某概念的定义是什么”但面对“按照公司规范给这个 React 组件写单元测试”这种复合型任务它就抓瞎了——因为这是一个多步骤流程不是一个知识点。Skills 的核心思路叫渐进式披露Progressive Disclosure。简单说每个 skill 是独立的知识包平时 AI 不知道它存在也不加载它的内容只有当任务相关时AI 才会按需加载 SKILL.md 这份“说明书”然后按说明书里的指引去调用辅助脚本、阅读参考文档、逐步完成工作。这带来一个非常关键的特性AI 的工作记忆不会被无关信息占用。它干活的时候只带当前任务需要的说明书而不是一整个知识库。我实测下来同样一个代码生成任务挂上对应 skill 之后生成的代码规范性和可维护性明显提升“瞎编 API”的情况也少了很多。1.2 Skills 与 MCP、子代理、插件的区别聊 skills 绕不开 MCPModel Context Protocol。很多人问我skills 是不是就是 MCP 的替代品不是。这俩是不同维度的东西。打个比方MCP 是给 AI 装“手”让它能去操作外部世界——访问数据库、调外部 API、读写文件Skills 是给 AI 装“脑子里的操作手册”让它知道“这件事该怎么做得专业”。一个偏连接层一个偏知识层它们完全可以结合起来用。举个例子你可以用 MCP 给 AI 接上浏览器的能力让它可以打开网页但“如何从电商网页里提取商品信息并整理成结构化表格”这个方法论是写在 skill 里的。MCP 解决“够得着”Skills 解决“做得好”。更准确地说Skills 更接近于给 AI 提供一套“专家行为模板”。传统编程里我们封装函数、封装类Skills 其实就是“封装行为”——但它封装的是 AI 的行为模式不是代码逻辑。这个区分特别重要因为很多人把 skill 写成了脚本合集——里面全是代码几乎没有指导性文本。那是错误的用法相当于你把函数体写好了但没写函数名和注释调用者根本不知道怎么用。1.3 谁最需要 Skills三类典型用户抛开概念到底哪些人应该立刻开始用 skills我在实践中筛出三类画像。第一类是项目维护者。如果你维护一个开源项目或公司内部项目代码风格统一是刚需。把项目的编码规范、目录结构约定、提交信息格式写进 skillAI 在你仓库里的每一次代码生成、修改都会严格执行这些默认值再也不用在 prompt 里反复叮嘱“记得遵守项目的 eslint 配置”。这个太爽了属于一劳永逸型收益。第二类是文档写作者。写技术文档、API 文档、教程的人会惊喜发现skills 能彻底解决“AI 写的东西没有上下文”的毛病。你可以写一个“项目文档生成器”skill里面记录项目的架构演进、技术选型理由、常见坑位AI 写出来的文档就不是泛泛而谈而是真的像在这个项目里干了两年的人写出来的。第三类是数据分析师。我见过有人做了个“数据清洗”skill里面定义了一整套数据质量检查流程先看缺失值分布再看异常值、看类型不一致、输出数据质量报告最后才动手清洗。AI 拿到这个 skill 之后数据分析流程规范化程度瞬间提升比我过去在 prompt 里反复强调“先检查再动手”有效得多。如果你是这三类之一往下看我会把从设计到落地的全套细节展开。2. 拆解 Skills 的“内脏”目录结构、元信息与运行机制2.1 一个标准 Skills 项目的完整结构一个标准 skill 在磁盘上就是一个文件夹通常放在项目的.claude/skills/或~/.claude/skills/目录下。Claude 和 Codex 都沿用了类似结构社区基本达成了一致。核心文件是SKILL.md它是这个 skill 的“门面”和“骨架”。一些复杂 skill 还会带上脚本、参考文档、模板文件。典型的目录长这样my-skill/ ├── SKILL.md # 技能说明书必需 ├── scripts/ # 辅助脚本可选 │ └── analyze.py ├── references/ # 参考资料可选 │ └── style-guide.md └── assets/ # 模板、示例文件可选 └── report-template.mdSKILL.md 的头部有一段 YAML frontmatter也就是用---包裹的元信息区里面定义了这个技能的名称、描述、额外目录等关键属性。这段 frontmatter 非常重要因为AI 就是通过 description 字段来判断“什么时候该加载这个 skill”。举个例子我写了一个“代码审查”skillfrontmatter 大概长这样--- name: code-review description: 用于执行全面的代码审查任务包括安全检查、性能分析、最佳实践检查。当用户要求审查代码或查找代码问题时使用此技能。 ---注意 description 的写法它不能只写“用于代码审查”而要写清楚“什么场景下触发”。我建议在描述里明确列出触发条件比如“当用户要求检查代码质量”“当用户提交 Pull Request 请求审查”。这样 AI 的触发判断准确率会高很多。2.2 SKILL.md 内部该写什么很多人写 SKILL.md 会犯一个致命错误——把它当成普通 Markdown 文档写想到哪写到哪。但 SKILL.md 本质上是一份“可执行的说明书”它的受众是 AI不是人。我们得按照 AI 理解信息的方式组织内容。我的经验是一份好的 SKILL.md 应该包含四个层次第一层是元信息frontmatter解决“什么时候用”的问题。第二层是任务说明body解决“这个技能是干嘛的、最终产出是什么”的问题。第三层是执行步骤解决“具体怎么做”的问题。第四层是补充资源指引解决“需要更多信息时去哪儿找”的问题。我把这套经验抽象成了一个模板你们可以直接抄作业--- name: skill-name description: 在 [具体场景] 下使用此技能用于 [完成任务目标]。 --- # 技能名称 ## 技能用途 说明这个技能解决什么问题最终产出什么格式的结果。 ## 使用前提 列出触发这个技能的前置条件以及不适用的场景。 ## 执行步骤 1. 第一步…… 2. 第二步…… 3. 第三步…… ## 注意事项 - 处理边界情况时的具体要求 - 常见的坑或禁忌 - 必须遵守的规范 ## 参考资源 - 详细文档路径[references/xxx.md] - 辅助脚本路径[scripts/xxx.py]这套结构写出来之后AI 加载 skill 的第一眼就知道“这个技能什么时候用、怎么用、有什么坑”。再配合 references 文件夹里的详细文档做深度参考就能形成“说明书 手册”的分级结构。这个设计不是拍脑袋它跟人学习新技能的方式一致先看一页纸的速查卡需要细节时再翻全书。2.3 运行机制AI 如何“学会”一个 skill要理解 skills 为什么有效还得搞懂它在运行时是怎么被 AI 消费的。这里有个工程细节值得展开。当用户给 AI 的任务明确指向某个 skill 时AI 会先读取该 skill 文件夹下的SKILL.md文件把它加入上下文。然后 AI 根据 SKILL.md 里的指令——而不是用户的原始 prompt——来决定调用哪些辅助脚本、参考哪些文档、按什么顺序执行。这个机制跟“把技能内容写进 system prompt”有个本质区别职责分离。用户的 prompt 只负责传达“我要什么”skill 负责定义“怎么做到专业”。过去这两者混在一起AI 要在理解用户意图和检索领域知识之间来回切换上下文管理压力大输出质量不稳定。现在拆开了AI 可以用全部“精力”去执行而不是被动接收知识。我在实际测试中发现一个很有意思的现象同一个任务比如“用 Python 写一个 ETL 脚本”在没有 skill 的情况下 AI 会按通用套路写——requests 拉数据、pandas 处理、入库完成是能完成但细节粗糙。挂上一个“公司数据管道规范”skill 后AI 会主动考虑错误重试、幂等性设计、日志记录这些生产级细节因为它读到的说明书里明确写了“所有 ETL 脚本必须实现幂等写入”这样的约束条款。这就是“说明书”和“裸模型”的差距。3. 从零开发第一个 Skill完整实操流程3.1 明确目标与边界开发 skill 的第一步不是写代码而是想清楚我要封装什么能力边界在哪里我建议从自己工作里最常重复、且最容易出错的场景入手。比如你经常让 AI 帮你写前端组件那最适合做一个“React 组件开发规范”skill如果你经常让 AI 整理会议纪要那做一个“会议纪要结构化”skill 就很实用。“高频 有规范 有坑”是挑选技能主题的三个黄金标准。边界也要想清楚。一个 skill 不要试图覆盖太多功能。你写一个“全能数据分析”skill里面既有数据清洗、又有可视化、又有建模AI 加载之后反而会混乱——因为它不知道当前任务该用哪一部分。更好的做法是拆分成“数据质量检查”“探索性数据分析”“图表生成”三个独立 skill各自小而专。我自己的一个教训早期我写了个“Python 项目开发”skill想把项目初始化、依赖管理、测试、打包全包进去结果 SKILL.md 写了两千多行。用的时候 AI 反而不知道用户要求“写个单元测试”时该不该加载它。后来拆成python-project-init、python-unit-test、python-packaging三个触发准确率和执行效果都大幅提升。记住一个 skill 只解决一个问题。3.2 填充 SKILL.md从模仿到创新如果你是第一回写最稳妥的方式是找一个成熟的 skill 参考它的结构。GitHub 上有不少 skill 仓库比如 anthropics 官方发布的 skills 集合、社区的 awesome-claude-skills 列表都是很好的范本。我自己的写法习惯是“先写流程再补细节”。先按经验把任务拆成 3-5 个大步骤然后在每个步骤下补充具体操作要求、输入输出、检查清单。最后再整体过一遍把那些“我默认知道但 AI 不知道”的隐含知识挖出来写进去。实操里有一个特别重要的心态写 skill 不是写文档是给 AI 写剧本。你得像给一个聪明但没经验的新员工写 SOP 一样把每个环节的“关键判断标准”写清楚。比如你让 AI 做代码审查“检查代码”不是步骤“检查代码并重点关注以下 5 类问题未处理的异常、硬编码的敏感信息、N1 查询、缺失的输入校验、不合理的错误吞没”才是步骤。3.3 元信息优化让 AI 准确地“按需加载”前面说过 description 决定了 AI 什么时候加载 skill。这里再展开讲讲怎么把 description 写好因为 90% 的人都会忽略它的重要性。先说不好的写法description: 代码审查工具再说好的写法description: 执行全面的代码审查包括安全检查、性能分析和最佳实践检查。当用户要求代码审查、检查代码质量问题、或审查 GitHub Pull Request 时使用此技能。区别很明显好的 description 包含了触发场景用户要求审查代码、检查质量、审查 PR、处理内容安全、性能、最佳实践、以及技能的定位全面的代码审查。这样 AI 在判断是否加载时不只能靠语义匹配还能靠任务意图匹配。实测下来优化过 description 的 skill 触发准确率从大概 60% 提升到了 90% 以上。还有一个小技巧在 description 里加否定条件。比如你写“当用户要求编写新代码时不要使用此技能”这能避免 AI 在写代码的场合误加载审查类 skill。这个细节看起来不起眼但对触发准确率的提升非常明显。4. 实战案例开发一个“技术文档生成器” Skill纯粹讲理论容易飘我拿一个我实际开发和使用的tech-doc-writerskill 来完整走一遍流程。这个 skill 是干嘛的当用户要求“为项目写技术文档”时AI 会加载它按规范生成一份包含背景、架构、核心模块、部署方式的技术文档。4.1 目录设计与元信息tech-doc-writer/ ├── SKILL.md └── references/ └── doc-format.mdSKILL.md 是这样写的--- name: tech-doc-writer description: 为项目生成规范的技术文档。当用户要求编写技术文档、设计文档或架构文档时使用此技能。不适合生成用户手册或营销文案。 --- # 技术文档生成器 ## 技能用途 根据当前项目的代码结构和上下文生成结构完整、内容准确的技术文档。 ## 使用前提 - 项目目录已经被 AI 读取或探索过 - 用户明确表达了写文档的需求 ## 执行步骤 1. 探索项目读取 README、找模块入口、查看 package.json 或 pyproject.toml 识别技术栈 2. 整理结构列出项目的核心模块、核心数据流 3. 分节撰写按 references/doc-format.md 中的模板分节撰写 4. 严格校验保证所有提到的文件名、函数名真实存在 ## 注意事项 - 严禁编造不存在的模块和函数 - 文档中的代码示例必须与代码库保持一致 - 不确定的信息用 [待补充] 标记不要臆造 ## 参考资源 - 文档格式模板[references/doc-format.md]references 里的 doc-format.md 长这样# 技术文档模板 ## 1. 项目概述 - 项目背景与定位 - 技术栈列表 ## 2. 系统架构 - 架构图ASCII 描述 - 模块职责划分 ## 3. 核心流程 - 关键业务流程的时序描述 - 数据流说明 ## 4. 部署与运行 - 环境要求 - 启动方式 - 调试命令这套搞完之后实际效果如何我拿一个内部项目做了测试。没有挂 skill 之前AI 生成的文档是“流水账”风格把每个文件介绍一遍缺少整体架构视角。挂上 skill 之后AI 会先梳理模块关系画完整架构图再按模板填内容。文档质量从“能看”变成了“能直接用”。4.2 测试与调优反复迭代的闭环写完 skill 不能直接用得测。测试方法是准备几个真实的典型任务跑一遍看输出再针对问题调整 SKILL.md。我测试tech-doc-writer时遇到过一个典型问题AI 生成的架构图经常和实际代码结构不符。排查后发现问题是 SKILL.md 里的“探索项目”步骤写得不够细——AI 不知道从哪里开始探索。后来我在步骤 1 里加了一句明确指引“优先读取项目的入口文件如 main.py、app.js和核心模块的init.py 或 index.js”这个问题的出现频率立刻下降。这是开发 skill 的标准流程写一版 → 跑测试 → 发现问题 → 精化指令 → 再跑测试。一轮典型的调优需要 3-4 次迭代才能达到稳定。不要指望一稿到位。4.3 进阶在 Skill 中调用脚本再进阶一层skill 里可以带辅助脚本让 AI 不只是“照着说明书做事”还能“用工具干活”。比如我在另一个log-analyzerskill 里放了一个analyze.py它负责统计日志文件中的错误频率和分布。SKILL.md 里写了“处理日志文件时使用 scripts/analyze.py 进行统计并基于统计结果生成分析结论”。这样做的好处是把确定性工作交给代码把判断性工作留给 AI。日志统计这种活儿让 AI 现写代码容易出错但如果 skill 里已经预置了经过验证的脚本这就变成了“读脚本输出 → 写结论”的稳定流程。这里要提醒一句脚本体积不要太大因为脚本本身会占用上下文。如果脚本超过 300 行最好做精简或者把说明文档留在 SKILL.md、把完整代码放 GitHub 让 AI 按需拉取。上下文是稀缺资源能省则省。5. 生态盘点Claude、Codex 与社区资源5.1 Claude 官方 Skills 生态Anthropic 官方对 Agent Skills 的定义是“结构化封装好的技能包让 AI 在合适的时机调用”。官方明确推荐的典型用例包括解析文件如 PDF、Docx、执行数据处理 pipeline、交易系统回测等。每个案例都是“描述任务目标 提供操作方式 让模型自主决策”的模式。Claude 目前支持在项目Project级配置 skills 文件夹也可以放在用户级目录作为全局技能。使用上只要把 skill 文件夹放到项目下的.claude/skills/路径即可。Claude Desktop 的官方文档中建议对于简单的指令不需要显式触发词因为这可能“过度限制模型”但对于复杂任务明确的触发模式往往提升准确率。我更偏向后者——明确触发在多数场景下是可靠性优先的选择。5.2 Codex 的 Skills 实验OpenAI 的 Codex 在 skills 上也做了大量工作。Codex 的 skills 目录结构和 Claude 类似但差异在于 Codex 更强调“可验证的规格”和“优化策略”。Codex 仓库里用spec.md来记录项目的规格说明和优化策略研究人员认为“人类指导的最高杠杆点”在于提供规范、设计模式、性能约束和反模式等。从我的体验看Codex 的 skills 更偏“代码生成代理”场景大量 skill 都是为了提升 AI 在代码生成任务中的规划与模式遵循能力。比如superpower skills这个仓库里就有很多“让 AI 从超长上下文中提取关键信息”的技巧对处理大型代码库特别有用。安装方式通常是将 skill 文件夹放入~/.codex/skills/或项目级.codex/skills/目录部分版本支持 CLI 命令直接安装。5.3 社区资源去哪找现成的 skills如果你不想从零开始GitHub 上已经有相当丰富的 skills 资源。anthropics/skills是官方仓库包含文档处理、PPT 生成、CSV 分析、Haiku 生成等常用技能。obra/superpowers是一个 Claude Code 技能合集包含多种提升开发效率的技能。还有hesreallyhim/awesome-claude-code这类非官方合集整理了大量社区技能。国内也有像 “reasonix” 之类的工具在做 skills 的管理和分享提供仓库式安装新 skills 的体验。找现成 skills 的判断标准看它是不是持续更新的、看 README 是否完整、看 SKILL.md 里是否有具体的执行流程而非空泛描述。社区里很多 skill 只是把一段 prompt 包装了一下那种没有实操价值不如自己写。5.4 自建私有 Skills 仓库用多了你会发现最适配你工作流的一定是自己写的 skill。所以维护一个私有 skills 仓库非常值得。我的做法是建一个 Git 仓库按目录组织skills-repo/ ├── coding/ │ ├── python-best-practices/ │ └── react-component-dev/ ├── writing/ │ ├── tech-doc-writer/ │ └── api-doc/ └── data/ ├── csv-analyzer/ └──>