先说我自己的结论：这段时间我把 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 绕不开 MCP（Model Context Protocol）。很多人问我：skills 是不是就是 MCP 的替代品？

不是。这俩是不同维度的东西。打个比方：MCP 是给 AI 装“手”，让它能去操作外部世界——访问数据库、调外部 API、读写文件；Skills 是给 AI 装“脑子里的操作手册”，让它知道“这件事该怎么做得专业”。一个偏连接层，一个偏知识层，它们完全可以结合起来用。

举个例子：你可以用 MCP 给 AI 接上浏览器的能力，让它可以打开网页；但“如何从电商网页里提取商品信息并整理成结构化表格”，这个方法论是写在 skill 里的。MCP 解决“够得着”，Skills 解决“做得好”。

更准确地说，Skills 更接近于给 AI 提供一套“专家行为模板”。传统编程里我们封装函数、封装类，Skills 其实就是“封装行为”——但它封装的是 AI 的行为模式，不是代码逻辑。这个区分特别重要，因为很多人把 skill 写成了脚本合集——里面全是代码，几乎没有指导性文本。那是错误的用法，相当于你把函数体写好了但没写函数名和注释，调用者根本不知道怎么用。

1.3 谁最需要 Skills：三类典型用户

抛开概念，到底哪些人应该立刻开始用 skills？我在实践中筛出三类画像。

第一类是项目维护者。如果你维护一个开源项目或公司内部项目，代码风格统一是刚需。把项目的编码规范、目录结构约定、提交信息格式写进 skill，AI 在你仓库里的每一次代码生成、修改都会严格执行这些默认值，再也不用在 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.md

SKILL.md 的头部有一段 YAML frontmatter，也就是用---包裹的元信息区，里面定义了这个技能的名称、描述、额外目录等关键属性。这段 frontmatter 非常重要，因为AI 就是通过 description 字段来判断“什么时候该加载这个 skill”。

举个例子，我写了一个“代码审查”skill，frontmatter 大概长这样：

--- 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 类问题：未处理的异常、硬编码的敏感信息、N+1 查询、缺失的输入校验、不合理的错误吞没”才是步骤。

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.md

SKILL.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/ └──>