说实话，我最近无论刷技术社区还是看各大 AI 工具的更新日志，都绕不开“skills”这个词。Claude 官方端出了 Agent Skills，OpenAI 的 Codex 也紧随其后搞了自己的 Skills 体系，再加上各路效率博主整理的“skill 推荐”“skill 下载”“skill 安装”帖，一时间圈子里人人都在给自己的 AI 助手“加技能点”。
但我发现一个很现实的问题：大多数人对 skills 的理解还停留在“这是一个新出的提示词模板”，或者“就是插件换了个名字”。如果只是这种认知，那基本上等于白折腾。我花了两周时间把 Claude Code 和 Codex 两套 skills 机制都跑了一遍，从官方文档、社区仓库到自己动手写技能，中间踩了不少坑。这篇就把我从原理到实操的完整记录写下来，尽量把“为什么这么设计”也讲清楚。
1. Agent Skills 到底是什么：先拆掉“提示词”的旧认知
1.1 一个 skill 的实体长什么样
先说结论：一个 skill 不是一个文件，而是一个“目录”。它里面至少有一个SKILL.md作为入口，还可以附带脚本、模板、知识文档。拿我最近写的一个代码审查技能举例，目录结构大概是这样的：
code-review-skill/ ├── SKILL.md └── resources/ ├── review_checklist.md ├── security_rules.md └── generate_pr_description.pySKILL.md是这个技能的主文件，用 Markdown 写，开头有一段 YAML 格式的 frontmatter，用来声明技能的名称、描述、适用条件，正文则写具体的执行步骤。这跟 GitHub Actions 的action.yml、Python 包的pyproject.toml是一个思路——用一个结构化入口描述“这是什么、什么时候用、怎么用”，真正的复杂度收在资源和脚本里。
我当时第一次看到这个结构的时候愣了一下：就这？没有编译、没有配置文件、没有复杂的依赖管理，一个文件夹加一个 Markdown 文件，就是“技能”了？实际用下来才发现，恰恰是这种简单结构让 skill 的传播成本极低。任何人拿到一个 skill 目录，扔到指定位置，就能被 AI 代理识别和使用，不需要安装程序、不需要注册表，从这点来说它比传统插件轻量太多。
1.2 Skills 与 MCP、提示词、插件的边界
我见过不少人把 skill 和 MCP 混为一谈，这俩确实是容易搞混。简单来说，MCP（Model Context Protocol）解决的是“AI 能连接什么”，Skills 解决的是“AI 该怎么干”。一个是给你接上数据库、浏览器、文件系统这些外部资源，一个是把处理任务的方法论和流程固化下来。
| 机制 | 定位 | 典型使用场景 |
|---|---|---|
| 普通 Prompt | 一次性指令 | 临时让 AI 做某件事，指令随对话消失 |
| Skill | 按需调用的知识包/工作流 | 重复执行的任务、团队规范、专业流程沉淀 |
| MCP Server | 能力扩展，接入外部工具和数据 | 访问 API、操作数据库、调用浏览器等 |
| Plugin | 深度集成到编辑器的扩展 | 改变 IDE 行为、增加快捷键、面板等 |
举个例子：你让 AI“读取某个接口的返回数据”，这是 MCP 的活；你让 AI“按团队的 Code Review 规范把一段代码检查一遍，输出结构化意见”，这是 Skill 的活。二者可以配合使用——skill 的执行过程中需要访问外部服务时，可以调用 MCP；MCP 只负责把数据和能力送进来，不负责教 AI 按什么流程处理。把这条边界理清了，后面做选型就顺手很多。
2. 为什么“渐进式披露”是 Skills 的关键设计
2.1 上下文窗口的“预算”逻辑
很多人的第一反应是：既然 skill 这么有用，那把整个团队所有规范都写成一个大 skill 不就行了？我一开始也是这么想的，直到实际测试才明白这条路走不通。
核心原因在于上下文窗口（context window）是 AI 代理最宝贵的资源。你写一个 5000 行的超级 SKILL.md，AI 每次处理任务的时候都得把全部内容加载进上下文，光是“读说明书”就占掉一半 token 预算，留给真正干活的空间就不多了。而且文档越长，模型在步骤执行时越容易遗漏细节——这跟人一样，给你一本五百页的操作手册让你找关键步骤，你也会犯迷糊。
Skills 的解法叫“渐进式披露”（Progressive Disclosure）：AI 代理启动时只读取SKILL.md这个入口文件，里面写清楚“这个技能是干什么的、什么时候该用、执行步骤摘要”，真正的细节放在resources/目录下的子文件里，等到模型判断确实需要时才按需打开。
用生活化的话说，这就像你去图书馆查文献，不会把整座图书馆的书都搬到自己桌上，而是先在检索目录里找到相关书目，然后一本一本去开架区拿。SKILL.md是检索卡片，resources/是书架，AI 代理是那个很有耐心的读者，按需取书、翻到哪页算哪页。
2.2 从“写死提示词”到“按需调用”的思维转变
这个设计带来的直接改变是：我们用 AI 的方式从“每次重新嘱咐”变成“按名字调用”。以前我让 Claude 帮我写前端周报，得在对话里把格式要求、包含模块、数据来源讲一遍，偶尔换了个上下文还得重新交代。现在我把这些要求封装进一个weekly-reportskill，对话里只需要说一句“用 weekly-report 技能写周报”，模型会通过description和when_to_use字段判断这个技能是否适用，命中后就自动加载SKILL.md，执行其中的步骤。
网上那篇很火的《Claude Agent Skills: A First Principles Deep Dive》其实就是在讲这个转变。作者把 skill 理解为把“经验知识”固化成代理可执行资产的方式，而不是简单的提示词拼接。我完全认同这个判断——提示词是告诉 AI“这一回怎么做”，skill 是告诉 AI“遇到这类事情，永远按这套流程做”，后者显然更有复利效应。
这也解释了为什么官方把 skill 的 frontmatter 里设计了一个when_to_use字段。这个字段越精准，模型在任务触发时就越容易做出正确判断。我见过有人把when_to_use写成“when user asks for help”，这就等于没说，模型遇到什么任务都可能尝试加载，最后反而干扰正常对话；如果写成“when user requests a code review with structured output focusing on security and performance”，模型就能在代码审查类任务时精准调用，其他场景完全不打扰。
3. 动手开发第一个自己的 Skill
3.1 准备目录与 SKILL.md 骨架
先上一份最小可用的SKILL.md模板，是我自己用着比较顺手的结构：
--- name: code-review description: 对代码变更进行结构化审查，输出包含安全、性能、可读性、测试覆盖四个维度的评审意见 when_to_use: 当用户要求审查 Pull Request、代码变更或提交差异时 version: 1.0.0 allowed-tools: - Read - Bash - Edit --- # 代码审查技能 ## 目标 对代码变更进行系统化审查，识别潜在缺陷与改进点。 ## 执行步骤 1. 获取变更文件的 diff 与上下文 2. 按优先级检查：安全风险 -> 性能问题 -> 可读性 -> 测试覆盖 3. 每条审查意见必须给出：问题位置、严重等级、修改建议 4. 输出结构化报告，按严重等级排序 ## 注意事项 - 安全类问题（注入、越权、密钥泄露）必须置顶 - 性能问题需附上具体的复杂度或基准估计 - 不要给出“代码风格不佳”这类泛泛而谈的意见frontmatter 每个字段都不是摆设。name是技能的全局唯一标识；description是给模型看“这个技能做什么”的简介；when_to_use是触发条件；version帮你做版本管理；allowed-tools相当于权限声明，限制这个技能执行过程中能调用的工具类型，是安全边界的一部分。
正文部分我强烈建议采用“目标 + 执行步骤 + 注意事项”的三段式。目标让模型理解任务的终点，执行步骤给出路径，注意事项圈定边界和禁忌。写注意事项的时候最忌讳用“请仔细检查”“认真分析”这种空洞表述，模型无法量化执行，要写就写“检查 SQL 查询是否存在字符串拼接注入风险”这种能被验证的具体指令。
3.2 把“流程”写进技能而不是写进对话
有人问我，同样一段流程，我写在系统提示词里不也一样吗？何必单独搞个 skill？我在实际使用中体会到的差异有这么几点：
第一，可复用性和一致性。写在系统提示词里的流程，换个项目、换个对话就丢了；写进 skill，所有项目都能用，而且每次的行为表现一致性高，不会因为临时对话的措辞不同导致输出质量波动。
第二，注意力聚焦。AI 代理同时加载的上下文越杂，越容易犯“抓不住重点”的毛病。你要是把几十条规范一次性塞进对话里，模型执行时很快会忘记前面的内容。Skill 的动态加载机制恰恰能避免这种“信息过载”，像刚才说的，它只在需要的时刻把对应流程加载进来。
第三，团队共享和迭代。一个写清楚的 skill 可以是一份活的团队文档。我见过一个团队把发布流程做成 skill：预发布检查、构建、测试、打包、生成更新日志、推送，每一步都对应resources/里的脚本和模板，新人接手项目时直接让 AI 跑一遍流程，比自己翻 Confluence 文档高效得多。这就是我理解的“流程资产化”。
3.3 脚本与资源释放
另一个关键点是：resources/里不仅可以放静态文档，还可以放可执行的脚本。例如我这个代码审查 skill 里的generate_pr_description.py，作用是从 git diff 和 commit 信息生成一条结构化的 PR 描述：
#!/usr/bin/env python3 import subprocess import re from pathlib import Path def get_commit_messages(): result = subprocess.run( ["git", "log", "--oneline", "-10"], capture_output=True, text=True, check=True, ) return result.stdout.strip().splitlines() def main(): commits = get_commit_messages() lines = [] for commit in commits: match = re.match(r"^[0-9a-f]+\s+(.*)", commit) if match: lines.append(match.group(1)) if not lines: print("No recent commits found.") return print("## Changes") for line in lines: print(f"- {line}") print("\n> Generated by code-review skill") if __name__ == "__main__": main()为什么把脚本放在resources/而不是直接让 AI 现场写一段 Python？因为 skill 的价值在于“可预期”。脚本是执行验证过的、结果确定的，AI 代理调用它拿到了稳定输出，再把输出编排进最终回复里。如果现场写脚本，每次生成的代码质量参差不齐，还可能引入 bug。把脚本作为资源释放出来，相当于把裁缝的手艺沉淀成了精确的纸样——下次裁剪不用重新发挥，照着纸样来就行。
关于依赖，这里有个坑：skill 的脚本不能假设目标环境里装了你期望的所有 Python 包。正确的做法是把脚本依赖尽量限制在 Python 标准库内，或者把需要的依赖声明写进resources/requirements.txt并在 SKILL.md 的步骤里注明“运行前若无依赖则先 pip install -r resources/requirements.txt”。第三方依赖要谨慎，不是不能用，而是你得意识到，这个技能将来会被其他人在完全不同的环境里运行，你偷懒少写一行依赖说明，别人执行时就要多花半小时排查。
4. 安装与调试：从 GitHub 到本地验证的完整链路
4.1 到哪里找：官方市场、GitHub 与社区聚合站
经常有人问“skills 下载平台有哪些”，这个问题在生态早期实际上没有统一答案。不像手机 App 有官方应用商店，skills 的分发目前是“多源并存”的状态。
第一类是官方渠道。Claude 的官方文档里维护着一个 Skills 目录，可以找到 Anthropic 出品或官方认可的技能；OpenAI 的 Codex 也有类似的内置技能集。这些技能的质量和安全性相对有保障，适合刚上手的人先体验“官方成品”。
第二类是 GitHub 社区仓库。目前最大的来源是各大 AI 工具开发者整理的技能集仓库，有些仓库把几百个技能按类别收纳得整整齐齐，比如按写作、编程、数据分析、报告生成、视频分镜等场景分类。这种仓库的优势是量大、主题覆盖广，从“写论文大纲”到“生成 PR 标题”都能找到现成的；劣势是你得自己判断质量。
第三类是第三方聚合站点。有些独立开发者做了 skill 的搜索和下载站，有点像早期的 npm 或者 Homebrew 的网页搜索版，可以按关键词检索，还能看下载量、评论。这类站点更新快，但质量参差，安装前最好检查一下维护活跃度和代码内容。
我自己在选 skill 时有一套标准：优先看维护频率（最近三个月有没有提交记录）、看 star 和 issue 反馈、看作者是否提供了清晰的文档。那些只有一堆文件、没有任何说明的“神秘技能包”，我再想要也不会装——因为你完全不知道里面藏了什么。
4.2 安装的本质：把目录放到正确位置
说清楚一个容易让人困惑的点：Skills 的安装本质上是“复制目录”，不是编译、不是注册、不是数据库迁移。以 Claude Code 为例，它支持两种粒度的安装：
- 全局安装：放到类似
~/.claude/skills/的目录下，所有项目都能用； - 项目级安装：放到当前项目的
.claude/skills/目录下，只对本项目生效。
Codex 的设计思路类似，也是全局目录加项目目录的组合。为什么要有两套？因为有些技能是个人习惯（比如你自己的周报格式），放全局；有些技能是项目特有的规则（比如某项目的 Git 提交规范），放项目级，跟随仓库走，团队成员拉了仓库就能共享同套技术规范，不用各自配置。
实操时我在命令行里做这样几步：
mkdir -p ~/.claude/skills cp -r code-review-skill ~/.claude/skills/ find ~/.claude/skills -maxdepth 2 -type f复制完并不代表万事大吉，我会先确认目录层级是对的。很多人在“国内安装 skills”这个环节翻车，十有八九是目录嵌套问题——比如复制成了~/.claude/skills/code-review-skill/code-review-skill/SKILL.md，多套了一层目录，代理扫描时就识别不到。
4.3 调试技巧：如何确认 skill 真的被加载了
安装之后最经典的问题是“我装了，但 AI 好像根本没有在用”。这里我强烈建议养成一个习惯：装完 skill 后，用一个最小测试用例单独验证。我把验证步骤总结为三件事：
第一，先问代理自己。直接在对话里向 AI 提问，让它列出当前可用的技能列表。如果这个工具支持/skills之类的命令就用命令，不支持就问一句。这一步能最快确认技能是否被扫描到。如果列表里没有，八成是目录放错了位置或者是文件名不是规范要求的SKILL.md。
第二，构造一个“完美命中”的测试任务。比如我的code-reviewskill 的when_to_use写的是“审查 Pull Request 或代码变更”，那我就造一个简单的代码 diff，让 AI 用这个技能审查。正常情况下它应该按SKILL.md里的步骤输出结构化的四维评审报告，如果输出内容和普通对话没什么区别，说明技能没有被正确触发。
第三，开调试模式看上下文。不少 AI 编程工具都支持调试日志输出，能直接看到代理加载了哪些文件、识别到哪些技能。我习惯在调试模式下跑一遍测试任务，观察日志里是否出现了code-review-skill/SKILL.md的加载记录。如果出现了，说明机制在正常工作，剩下的问题多半出在技能描述和任务匹配度上。
5. 常见问题与排查技巧实录
5.1 技能没被调用：原因与解法
我把这段时间遇到的问题整理成一张速查表，基本覆盖了常见的翻车原因：
| 症状 | 可能原因 | 解决方案 |
|---|---|---|
| AI 完全没提到技能 | description 或 when_to_use 写得太泛/太偏 | 用任务动词重写，明确触发场景 |
| 技能列表里根本没有 | 目录层级错误，或缺少 SKILL.md | 检查目录是否多套了一层，文件名是否规范 |
| 加载了但不按步骤执行 | SKILL.md 正文指令模糊 | 改成祈使句，步骤尽量原子化、可验证 |
| 执行脚本时报错 | 依赖缺失、路径写错 | 将依赖装入 resources 目录，脚本用相对路径 |
| 多个技能互相干扰 | 多个技能描述重叠 | 限定边界，保持技能职责单一 |
这里我重点说下第一类问题。模型决定是否加载一个技能，主要靠匹配“任务描述”和description/when_to_use的相关性。如果你的描述用的是“帮助用户处理各种事务”这种万能句式，模型很可能会在你问天气的时候也尝试加载它，或者干脆在所有场景下都犹豫不决。最好的写法是倒过来想：用户在那条具体任务里会怎么说？把任务动词、目标对象、输出形式写清楚，让模型一看就知道要不要调用。
5.2 技能之间互相干扰：命名空间与资源隔离
技能装多了以后，我遇到过两个技能都想抢同一个任务的情况。比如写周报的 skill 和写项目总结的 skill 都声明了“用户要求总结近期工作时触发”，结果 AI 要么随机挑一个，要么把两个都加载进来，输出内容是缝合怪，四个不像。
解决思路有两条。第一条是在描述层面做减法，每个技能只负责一个足够窄的任务域。写完周报就别管数据分析，深度比广度重要。第二条是统一命名习惯，给技能加上组织前缀或场景前缀，比如report-weekly、report-sprint，让模型在语义上更容易区分。
资源隔离的问题同样需要留意。假设两个技能都用resources/下的同一个template.md文件名，一旦安装到同一个 skills 根目录，就可能相互覆盖或被串读。我自己习惯给 resources 里的文件也加上技能名前缀，比如把模板命名为code-review_checklist.md，虽然文件目录是多了一层，但能有效避免命名冲突。
5.3 安全与规范：别随便装来路不明的 skill
这个点我必须放在比较靠后的位置讲，因为它最容易被忽略，但出事时代价最大。很多用户对“安装包下载”有着朴素的理解——下载、解压、放进去，完事。但 skill 不是一个被沙箱保护的普通文本文件，它的resources/里可以放脚本，而这些脚本会被 AI 代理在本地执行。
换言之，安装一个 skill 相当于把一段可能被执行的可信代码放进了你的开发环境。如果它来自一个你完全不了解的第三方渠道，你就得假设它可能是恶意的。我记得看到过一些公开的安全讨论，有人在分析某些恶意 skill 时发现，里面藏了收集环境变量、读取敏感配置、甚至尝试执行未授权命令的脚本。这类问题在“自动挖洞”或“安全检查”类技能中尤其要警惕，涉及扫描与测试行为的脚本，使用前务必确认其已获得目标系统授权，并且只运行在隔离环境里。
我给自己定了几条安全底线：
- 只用官方来源、GitHub 高 star 仓库、有明确维护记录的技能；
- 安装前打开
SKILL.md，从头到尾读一遍描述和步骤； - 打开
resources/里的脚本文本，看到可疑的网络请求或系统命令就要警觉； - 尽量不给 skill 配置过大的工具权限，
allowed-tools里只保留它完成任务真正需要的工具； - 重要项目里用项目级安装而不是全局安装，控制技能的影响边界。
这不是劝你因噎废食，而是像装浏览器插件一样——装之前看一眼“这个扩展要读取哪些数据”，那些什么都想读、又闭着源的，趁早别碰。
6. 生态观察：Claude Skills 与 Codex Skills 的异与同
6.1 同一套思路，两套实现
Claude 和 Codex 的 Skills 体系在核心设计上高度同构，都是“目录 + SKILL.md + 资源文件 + 渐进式披露”，但在具体落地时有差异。我整理了一个粗略对比：
| 维度 | Claude Agent Skills | Codex Skills |
|---|---|---|
| 发布时间 | 2025 年 10 月正式推出 | 随后跟进，生态快速成型 |
| 核心入口 | SKILL.md + frontmatter | 类似的结构化技能定义 |
| 安装位置 | ~/.claude/skills 与项目 .claude/skills | 对应的 codex 全局/项目目录 |
| 分发渠道 | 官方文档、GitHub、第三方聚合站 | 官方内置 + 社区仓库 |
| 侧重点 | 方法论沉淀、工作流固化 | 与代码代理工具链深度结合 |
实际用下来，Claude 的 skills 在“团队流程沉淀”上给我的体验更顺手一些，因为它的when_to_use和资源按需加载机制让技能更像一个会自我介绍的专家；Codex 的 skills 则跟它的 agent 工具链绑定得更紧，在自动化执行、写代码任务里表现很直接。两者各有所长，但对于我们这种既写代码又管流程的普通用户来说，底层逻辑通了一套之后，换平台也就是把目录结构换个路径的事。
6.2 接下来怎么玩：从消费技能到制造技能
现在社区里的 skill 生态已经很热闹了。写作类有帮你搭论文框架的、生成短视频分镜脚本的；开发类有自动生成 PR、做代码审查、写测试用例的；效率类有整理会议纪要、汇总周报的。但我不建议你现阶段把大量时间花在“囤技能”上——下载一百个不如自留十个真正解决自己重复劳动的。
从我的经验看，最有价值的做法是反过来的：盯住你每周至少要重复三遍以上的任务，挑一个把它写成 skill。比如设计师每周都要出分镜脚本，那就写一个分镜技能；运营每周都要写数据复盘，那就写一个复盘技能。第一次写可能比较慢，但写完一次之后，你后面每一次说“按 XX 技能来”都是纯赚。这种“从消费到制造”的转变，才是这套机制真正让人上瘾的地方。
我个人在实际操作中的体会是，Skills 最大的价值不是“多了一个装技能的地方”，而是逼着我们把重复劳动抽象成流程。以前我写提示词，每次都要把自己的要求重新说一遍；现在我把这些要求拆成SKILL.md和resources，一次写好，之后每个项目只要一句“按 XX 技能来”就行。最后再分享一个小技巧：把技能的版本号写在 frontmatter 里，每次迭代完顺手提交一个 git tag，你会发现这套“技能资产管理”的玩法比想象中更上瘾——你维护的其实不是一堆 Markdown 文件，而是一套正在快速进化的个人方法论。
