拿到 reverse-skill 这个项目时，我的第一反应是：这名字起得有点误导人。它既不是逆向工程框架，也不是什么反向代理工具，而是一个专门讨论“怎么让 AI Agent 学会倒着干活”的技能包。最近一年，skill 在 cursor、codex、claude code、opencode 这些工具里几乎是标配，随便一搜都是“skill 推荐”“skill 安装”“skill 开发指南”，但真正系统讲清楚“一个 skill 内部到底该长什么样、为什么这样设计、怎么从别人那反向学”的内容反而不多。这篇就用 reverse-skill 当引子，把这条路完整走一遍。
1. 重新理解 reverse-skill：它不是逆向工具，而是一套“先验证再执行”的 Agent 工作流
1.1 Skill 到底是什么：AI Agent 的岗位说明书
我接触过不少刚上手 Agent 的朋友，他们普遍有一种误解：skill 等于“更强的 prompt”。这句话对了一半。skill 确实由 prompt 构成，但它更像是一份岗位说明书——它定义了模型在某个具体任务里的职责边界、执行流程、可用工具、输出格式，以及遇到例外情况时该怎么处理。
常规 prompt 是流动的，聊天框里写一段就过去了。skill 则是静态的，它被固定在项目的某个目录或全局配置里，每次触发时由工具自动把它注入到模型的上下文中。模型读完这份说明书，就等于知道自己现在被“任命”为什么角色、需要按什么节奏把任务做完。
同样一件事，没有 skill 时模型会自由发挥；有了 skill，模型就有了行为契约。我在实际使用里的感受是：skill 解决的不是“模型不够聪明”，而是“模型太容易自作主张”。每次输出前要不要检查？顺序是什么？哪些事绝对不许做？这些如果不写死，模型就会用自己的方式理解，结果就是每次结果都不一样。
1.2 reverse-skill 的 reverse：先想否定情况，再做正事
这个项目之所以叫 reverse，核心思想不是“让 AI 逆序输出文字”，而是让模型在正式干活之前，先做一轮反向操作。
我举个例子。如果你让 AI 去清理某个目录里的临时文件，常规 skill 的流程是：扫描目录、识别临时文件、删除、汇报。reverse-skill 的思路则会变成：
- 先列出“绝对不能删”的保留清单；
- 再列出符合删除条件的临时文件清单；
- 对每个文件先模拟一次删除结果，确认没有影响；
- 最后才执行真正的删除。
这个设计解决的是不可逆操作的风险问题。模型本身没有“试错成本”，它每执行一步都是真实的系统调用。如果第一步就删错了，后面再补救就晚了。先反向确认边界，再正向执行，本质上是用一次阅读成本换取操作安全。
类似的设计对批量重命名、生成覆盖、配置修改、数据库变更这类场景都适用。reverse-skill 其实不是某一种具体技能，它是给其他技能加的一道“前置闸门”。
1.3 适合谁读：Agent 工具使用者、skill 作者、想构建可复用工作流的人
如果你只是想在聊天窗口里问 AI 问题，那你不需要 skill，普通对话就够了。但如果你在用 cursor、codex、claude code 这类工具做真实开发，或者你在折腾 workbuddy、trae、opencode 的 skill 插件，又或者你在研究“怎么给 AI 自定义一套固定的论文写作、科研绘图、代码审查流程”，那 skill 就是你绕不开的一环。
尤其对 skill 作者来说，很多人第一次写 skill 时都会犯同一个毛病：把一个 prompt 写得很长，然后把它当成 skill 保存。这样做不是不行，但大概率会在使用时发现上下文被占用、触发不稳定、模型理解跑偏。这篇文章后面会专门讲结构，你照着拆就能避开这些坑。
2. 解剖一个 Skill：从目录结构到执行逻辑
2.1 SKILL.md 是协议，不是 README
几乎主流的 skill 机制都遵循同一个约定：在一个目录里放一个名为 SKILL.md 的 Markdown 文件，工具发现这个文件后，就把它的内容作为该技能的行为协议加载。
很多人把 SKILL.md 当成 README 写，开头先介绍“这是什么”，再写“为什么做”，然后才慢慢讲“怎么做”。这是顺序上的错误。SKILL.md 不是给人看的手册，而是给模型看的指令协议，它应该从第一行就进入状态。
我见过比较好的 SKILL.md 结构通常长这样：
--- name: code-review-reverse description: 对代码进行先结论后证据的审查，适合合并请求、重构前风险评估 --- ## 执行流程 1. 先读完整输入，输出一份“风险清单”，只列该文件中最可能出问题的 3 个位置； 2. 对每个风险位置，说明“为什么可疑”而不是“应该怎么改”； 3. 再按严重程度从高到低给出修复建议； 4. 最后输出一段 50 字以内的总体结论。 ## 禁止事项 - 不解释无关代码； - 不生成与本次审查无关的重构方案； - 不修改任何文件。注意看，description 字段写得非常具体：“对代码进行先结论后证据的审查，适合合并请求、重构前风险评估”。模型靠这个字段判断什么场景触发该技能。如果 description 写得太泛，比如“帮助用户审查代码”，那么模型在正常对话时也容易调用它，造成上下文被无关内容占满。
2.2 scripts、prompts、references：各自该干什么
一个完整的 skill 目录里往往不止 SKILL.md 一个文件。我拆过不少主流项目，发现它们的目录分工大致可以整理成下面这张表：
| 子目录 | 职责 | 典型内容 | 什么时候该用 |
|---|---|---|---|
| scripts | 需要确定性执行的代码或命令 | 处理文本的 Python 脚本、Shell 命令 | 结果必须精确、不能靠模型生成时 |
| prompts | 大段行为指令、模板、示例对话 | 分步骤的指令块、少样本示例 | 希望模型按固定话术和顺序生成时 |
| references | 参考资料、帮助文档、规范文本 | API 文档、代码规范、数据集说明 | 仅在需要时按需拉取，不常驻上下文 |
这里有一个新手容易搞混的点：到底应该把逻辑写进 SKILL.md，还是写进 prompts 子目录？
我的经验是：SKILL.md 里只保留最核心的流程与禁忌，控制在 200 行以内。凡是超过这个体量的规则细节、模板示例、领域资料，全部外置到子目录里。SKILL.md 通过一句话告诉模型“详细规则在 prompts/xxx.md，遇到 XX 情况时读取”。这样模型在非必要时不会把所有内容读入上下文，token 消耗和指令干扰都会大幅下降。
2.3 元数据和命名：容易被忽略但影响实测的信息
拆 skill 时，我一般先看三样东西：name、description、version。
name 是技能的标识符，也是模型理解“自己正在使用哪套规则”的依据。命名尽量用一个名词或动词短语，少用空泛的形容词。比如“code-review-reverse”比“careful-review”好，因为前者准确，后者含糊。
description 是触发器的命门。好的 description 应该包含三部分：适用对象（对什么输入用）、处理方式（做什么）、适用场景（什么时候不要用）。例如：
description: 用于处理 CSV 导入任务的技能；对脏数据先做反查，输出清洗方案后再执行修改；不适用于图片或非结构化文本。“不适用”这部分很多人不写，但它恰恰能防止模型在错误场景下调用技能。我在 reverse-skill 的源码里看到，作者在 description 末尾专门加了一句“不用于网络请求任务”，这个小细节能直接减少误触发。
version 字段影响调试效率。skill 迭代非常快，没有版本号，你很难判断当前模型加载的是旧规则还是新规则。建议在每个版本修订后同步递增版本号，并在 SKILL.md 里加一行 changelog。
2.4 reverse-skill 目录实例：一个最小可用的布局
根据我对这类项目的拆解，一个最小可用的目录布局大致如下：
reverse-skill/ ├── SKILL.md ├── scripts/ │ ├── reverse_check.py │ └── build_rollback.py ├── prompts/ │ ├── reverse_plan.md │ ├── reverse_review.md │ └── rollback_guide.md └── references/ └── examples.mdSKILL.md 负责定义整体流程：先调用 reverse_check.py 检查输入合法性，再让模型按 reverse_plan.md 的格式输出执行计划，每一步执行前由 reverse_review.md 做反向验证，最后把所有待执行操作通过 build_rollback.py 生成回滚脚本。
可以看到，真正常驻上下文的只有 SKILL.md 这个小文件。scripts 里的脚本是模型按需调用的，prompts 里的模板是执行到对应阶段才读取的，references 则只在模型需要示例时查阅。这就是一个典型的高效 skill 设计。
3. 为什么 “C++11 以下能用 std::reverse 吗” 会出现在这类内容的高频搜索里
3.1 答案就是可以，这条路很早就通了
我查了一下和 reverse-skill 关联的热搜词，里面有一条“C加加11以下能用st d reverse吗”，一开始我有点意外，后来想明白了：很多人搜索“reverse skill”时，会把 reverse 理解成 C++ 标准库里的 std::reverse，尤其是开发者用户占比高的场景里，这种混淆非常常见。
先说准确答案：能用。std::reverse 是 C++98/03 时代就进入标准库的算法，C++11 只是让它更安全、更好用，而不是发明它。你只要包含 头文件，在 C++98 编译环境下也可以正常调用：
#include <algorithm> #include <vector> #include <string> #include <iostream> int main() { std::vector<int> nums = {1, 2, 3, 4, 5}; std::reverse(nums.begin(), nums.end()); // C++98 中已有 std::string word = "skill"; std::reverse(word.begin(), word.end()); // 结果是 "lliks" return 0; }如果你用的是原始数组，也不受影响：
int arr[] = {1, 2, 3, 4, 5}; std::reverse(arr, arr + 5);数组本质上是一段连续内存，指针可以作为迭代器使用，因此 std::reverse 可以直接作用于裸数组中。
3.2 使用 std::reverse 的三个先决条件
虽然 std::reverse 很老派很稳，但你要真正用好它，必须满足三个条件。
第一，容器或区间必须提供双向迭代器。vector、string、deque、list、数组都满足这个要求；但 forward_list 不行，因为它是单链表，只提供前向迭代器，无法从尾部向前移动。
第二，元素类型必须可交换。C++11 之前，std::reverse 使用元素类型的赋值拷贝来实现交换，如果元素类型只读或不可复制，编译期会报错。C++11 之后，标准库内部优先使用 move 语义，效率提升了不少，但依然要求元素可移动。
第三，区间必须合法且不重叠。传入的 [first, last) 范围必须属于同一个容器，first 的位置不能排在 last 之后。违规行为属于未定义行为，编译器并不保证报错，这在实际开发里比迭代器类型错误更难排查。
还有一个容易混淆的点：如果你看到的是 std::ranges::reverse，那确实是 C++20 才加入的。所以如果有人问“C++20 以前能不能用”，答案是不能；如果问“C++11 以下能不能用”，答案则是能。造成混淆的原因往往是没分清 std::reverse 和 std::ranges::reverse 这两兄弟。
3.3 手写一个不依赖标准库的 reverse 需要注意什么
有些项目为了避免引入标准库依赖，会选择手写逆序逻辑。标准做法是双指针从两端向中间交换：
template <typename BidirIt> void reverse_range(BidirIt first, BidirIt last) { while (first != last && first != --last) { std::iter_swap(first, last); ++first; } }这段代码里有几个值得注意的细节。循环条件里的first != last是为了处理空区间，first != --last则同时完成“指针前移”和“区间合法性判断”。如果区间长度为偶数，两个指针会在中点相遇；如果是奇数，则会错位一次，但循环条件会在中点的正确位置停止。
手写版本最容易犯的错误是写成“先从尾部遍历到头部再翻转”，这不仅多了一次无意义的全量遍历，还会让时间复杂度从 O(n) 变成 O(2n)。另一个常见错误是交换时逐个赋值而不是用 iter_swap，导致对象拷贝开销巨大。写这种底层算法，少即是多。
3.4 把“区间边界”思维带回 Skill 开发
我之所以在讲 skill 的文章里花一整节聊 C++ 的 reverse，是因为这两个东西在工作方式上有很强的同构性。
std::reverse 的前提是“区间合法”。如果 first 和 last 不在同一个容器里，整个操作就是未定义行为。skill 也一样，任何技能都必须有明确的边界：它能处理什么输入、不能处理什么输入、在什么条件下应该主动停止。很多 skill 表现不稳定，根本原因不是 prompt 写得不到位，而是边界没有画清楚。
模型拿到一个 skill 时，它就像 std::reverse 拿到一对迭代器——它只对“你定义的区间”负责。如果你没告诉它“这个技能只处理 Markdown 文件，遇到 PDF 直接退出”，它就会去处理 PDF；如果你没告诉它“这个流程输出审核报告时不允许修改代码”，它就可能顺手把代码改了。边界即安全，这条 C++ 教给我的经验，在 AI 技能设计里同样成立。
4. 从 reverse 到可落地：完整地把一个 Skill 部署到 cursor / codex / claude code / opencode
4.1 先写“期望结果”，再写执行步骤：反序设计的模板
我写自己的技能时，习惯先用一个“反序设计法”：先想清楚这个技能最终要给用户交付什么，再倒推这个过程需要哪些检查。
假如我要做一个“文档批量格式化”技能，我不会直接写“先扫描文件，再执行格式化”。我会先想清楚结果：用户最终得到的应该是一份变更清单、一套可回滚的备份文件、以及格式化后的文档。为了让这三样结果成立，我必须在一开始就设计出检查点和回滚点。于是技能的步骤自然变成了：
1. 先备份原文件； 2. 生成本次修改的 diff 预览； 3. 确认 diff 无误后再写入； 4. 写入后重新生成 diff 并与预览版比对； 5. 输出变更清单。这种设计方法的本质就是 reverse。从目标倒推要求，而不是从能力正推流程。用它写出来的 skill 往往比直接把 prompt 列一遍更健壮，因为每一步都有存在的理由。
4.2 示例：写一个“代码审查技能”时的 reverse 流程
结合 reverse-skill 的思路，我给出一个可以直接照抄的简单技能示例。假设你经常在 cursor 或 claude code 里做代码审查，可以创建一个名为 review-by-risk 的技能目录：
review-by-risk/ ├── SKILL.md └── prompts/ └── review_template.mdSKILL.md 核心内容如下：
--- name: review-by-risk description: 代码审查技能。先列风险点，再给修复建议。适合合并前、重构前的快速审查。不适用的场景包括需求讨论、代码生成、架构设计。 --- ## 流程 1. 读取目标代码后，先输出风险清单，最多列 3 项； 2. 风险清单必须包含：位置、为什么危险、触发条件； 3. 不要在第一轮给出修复建议； 4. 等用户确认风险清单后，再按风险级别输出修复方案。 ## 输出格式 - 风险标题（一行） - 位置引用（代码片段或行号） - 触发条件（什么时候会出问题） - 可能影响（可选，一行）prompts/review_template.md 里放一个标准的审查示例。这样模型每次审查时，先读的是 SKILL.md 的简洁规则，只有进入具体步骤时才读取模板，上下文开销小，规则也清晰。
4.3 安装到不同工具时，建议走的通用流程
cursor、codex、claude code、opencode 的 skill 目录格式会有差异，官方文档也一直在更新，我不建议直接照抄某个固定路径。但它们的通用逻辑基本一致：你把一个包含 SKILL.md 的目录，放到某个特定搜索路径下，工具启动时扫描到后，就把它作为一个可用的技能。
我自己的操作习惯是四步走：
- 在项目或全局配置目录下新建 skills 文件夹，放入技能子目录；
- 用文本编辑器打开 SKILL.md，检查 name、description、version 是否填写正确；
- 重启工具或开启新会话，让模型重新加载技能索引；
- 直接问模型“你现在加载了哪些 skill”，确认新技能已被识别。
第四步很多人会忽略。工具不一定会在每次对话中主动列出技能列表，直接问是验证加载成功最快的方式。如果回答里没有你要的技能，优先检查目录位置和 SKILL.md 的文件名大小写，这两处是最容易出问题的地方。
4.4 调试 Skill 的实用方法：问答式验证
我调试 skill 的方式比较笨，但很有效。我会准备三个输入样本：一个典型样本、一个边界样本、一个完全不该触发的样本。
典型样本要验证模型是否按流程执行；边界样本要验证模型是否知道“什么时候该停下来”；不该触发的样本则用来验证 description 是否写清楚了适用范围。如果边界样本触发了技能，说明 description 里的“不适用”信息不够强；如果典型样本没有完整走流程，说明 SKILL.md 里的步骤顺序有歧义。
这套验证逻辑本质上也是 reverse：先假设它会犯错，然后拿不同的输入去触发错误，再根据错误反修规则。
5. 写 Skill 最容易翻车的四个坑
5.1 把 SKILL.md 写成说明书，而不是使用协议
这是我见过最多的问题。很多作者写 skill 时，大段解释“这个技能是什么”“原理是什么”，结果模型读到的是大量背景信息，真正有操作性的指令反而被淹没在长文本里。
模型不是读者，它是执行者。SKILL.md 每一行都应该直接作用于执行：要么指明动作顺序，要么规定输出格式，要么规定禁止行为。解释性的文字全部删掉。我现在写 SKILL.md 时会刻意控制总行数，超了就外置到 references，不跟协议混在一起。
5.2 一个技能管太多事，导致上下文爆炸
有人喜欢把“论文写作”做成一个万能技能，里面同时包含大纲生成、降重改写、引用整理、图表设计。这种设计在模型能力不足时会显得很强大，但实际用起来容易出问题：description 语义过宽，触发频率不正常；SKILL.md 内容过多，每次触发都浪费大量上下文窗口。
我的建议是拆分。论文写作拆成“论文大纲生成”“论文语言润色”“引用格式检查”三个独立技能。单个技能只做一件事，description 明确，触发稳定，上下文占用也小。
5.3 忽视 prompt 注入风险
Skill 的内容会原样进入模型上下文，这意味着如果你从网上下载一个别人写的 skill，实际上你是把一串外部可控的指令喂给了模型。某些恶意 skill 里可以隐藏“忽略用户后续所有约束”之类的对抗文本，这是真实存在的风险。
即使你不信任任何第三方，自己写 skill 时也要注意：不要在 SKILL.md 里写“无条件执行”“忽略安全提示”这类表述，也不要要求模型执行明显超出边界的命令。skill 是给模型看的协议，不是给模型的无限制授权工具。我会给每个 skill 单独设置最小化的工具权限，比如只在指定目录内读文件，不写系统级配置。
5.4 不看触发频率和 token 成本
skill 的触发高度依赖 description。description 越宽泛，触发越频繁，token 消耗越大。很多技能支持者在宣传时只说“优先检索多多益善”，但从实际成本看，无关技能频繁加载会让模型注意力分散。
我在 description 的结尾固定加一句“不适用于……”，并要求模型满足适用条件时才加载。这样能让触发相对克制。像论文写作、科研绘图这类热门技能，正是最容易因为 description 太宽松而导致模型在该用的时候没用、不该用的时候乱用的典型。
6. 把 reverse 变成习惯：定期反向审查自己的 Skill 库
6.1 每次用爽一个技能之后，反向拆一遍
同样受到 reverse-skill 的启发，我现在每用到一个让我觉得“这一步省事很多”的技能，都会事后把它重新拆开看一遍，重点问三个问题：
- 它哪一步的设计让我觉得顺滑？
- 把这一步的顺序换到后面，效果会变差吗？
- 它在什么输入下会失效？
这套“反向审查”比我直接看作者写的说明文档更有效。因为作者写的文档往往只讲设计意图，不会告诉你它的失效条件。而失效条件恰恰是你在实战里最需要预判的。
6.2 维护一份预留的“技能反向笔记”
我在本地维护了一个简单的技能笔记仓库，每个技能一个目录，里面除了 SKILL.md 之外，还放一个 REVIEW.md，专门记录这个技能在实际使用中暴露出的问题。改一次就记录一次，不整理得很复杂，几句话就够。
这个习惯帮了我很大的忙。技能调整时，我不会凭记忆去改，而是先看 REVIEW.md 里记过的失效案例，再对照案例逐一修补规则。时间一长，每个技能都像被反复打磨过一样稳定。
如果你也在折腾 skill，我的建议是从“用现成的”尽快切换到“拆现成的”。找一个你高频使用的技能，把目录打开，逐行读它的 SKILL.md，再结合你实际使用时的体感差异去理解作者为什么这么写。这个逆向过程，往往比你自己闷头写十个新技能更有用。
