最近 SkillOpt 很火。
微软的这个开源项目已经拿下 9000+ Star。

它把写Agent技能文档这件事也变成了一种真正的训练过程。
前向传播、反向传播、参数更新、门控验证等等全都用了上。
简单来说,SkillOpt 就是专门帮 Agent 打磨 skill.md 的,把原本靠经验写的技能文档,变成像训练模型一样不断迭代优化。

平时写技能文档就是这样的:
写了份技能文档之后就把它丢给了 Agent 去执行任务,结果不理想就又改了文档再运行一次,还是不行……
错误率高,并且没有系统的办法。
整个过程就是补课,但是没有考试、没有分数、不知道是对是错。
SkillOpt 把整个过程变成了一种真正的训练过程。

假如你要写一本《做菜指南》来教会一个初学者学会做饭。
01 先让他做一次,并且把整个过程都记录下来。
新手拿着你的指南走进厨房,你得让他把整个过程都记录下来:用了哪些食材、加了多少调料、温度是多少度、最后的味道如何。
SkillOpt 也是这样:让 Agent 用现有的技能文档来运行一些任务,并且把整个执行的过程、工具调用、验证反馈和最终得分全部记录下来。
这就如同深度学习中的“前向传播”,运行一次,观察一下结果。
02 查看记录,找到问题。
你看他做的记录,好的菜都有放盐,不好的就没有放盐。
找到问题了,在指南中没有提到“要放盐”。
SkillOpt 也是一样的:用一个单独的模型来分析这些轨迹,并找到哪里是错的、哪里是对的。
也就是说,它把失败与成功的过程分开来处理——失败的过程用来找出“哪些规则要修改”,而成功的过程则用来确定“哪些规则是有效的,不能随便改动”。
这就相当于在计算“梯度方向”,知道要朝哪个方向去修改。

03 改指南但是不要改太多。
你要修改指南,但是每次只改一两个地方。
为什么不能一次性全部修改呢?因为改动太多,你就不知道是哪一个改动起了作用,如果改错了也无从得知哪里错了。
SkillOpt 也一样:提出具体的操作——增加新的规则、去掉无用的规则、修改要改正的规则。
有一个很重要的概念叫做“文本学习率”,默认值为4,表示每次最多修改4处。
这就如同在深度学习中使用的learning rate一样,避免一次改变过大而把之前学到的东西给覆盖掉了。
04 试过了才知道,改对了才会留下。
新手拿着新的指南再试一次,如果菜变好吃的话,就说明改对了;如果没有变好吃,那么这个改动就被否决了,你要把这一个方向错误记录下来。
SkillOpt 也一样:新技能文档要在验证集上严格提高性能之后才被接受。

如果验证失败的话,那么这个编辑就会被拒绝并且记录在“拒绝编辑缓冲区”中,以防止下一次再出现相同的失败方向。
这就如同在深度学习中进行验证一样,保证修改的方向是正确的。
还有一个亮点:迁移能力。
GPT-5.5 训练出的技能文档可以被直接应用到 GPT-5.4-mini 上;在 Codex 上训练出来的也可以用在 Claude Code 上。

这就意味着你可以不用为每一个模型都重新编写技能文档了,只需要训练一次就可以重复使用。
测试结果怎么样?
52 个测试场景中,全部都是最好或者并列最好的。GPT-5.5 平均提高了 23.5 个百分点,在 ALFWorld 上 GPT-5.4-mini 由原来的 70.9% 提升到了现在的 85.8%。

只用了 4 个被接受的编辑。
训练中分数逐渐提高,被拒的编辑也可以看到。

如果你也想试一下,可以参考下面的步骤。
01 安装。
git clone https://github.com/microsoft/SkillOpt.git
cd SkillOpt
pip install -e .
02 配置 API。
把.env.example 复制一份到.env里,并把里面的API密钥填上:
# OpenAI
export OPENAI_API_KEY="sk-..."
# 或 Azure OpenAI
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
export AZURE_OPENAI_API_KEY="your-key"
# 或 Anthropic Claude
export ANTHROPIC_API_KEY="sk-ant-..."
03 准备数据。
两种方式:
-
自动划分:准备好原始数据,让 SkillOpt 自动划分训练集、验证集、测试集 -
手动划分:自己准备好三个文件夹
04 开始训练。
python scripts/train.py --config configs/searchqa/default.yaml
可以指定teacher和student模型:
python scripts/train.py \
--config configs/searchqa/default.yaml \
--teacher_model gpt-5.5 \
--student_model gpt-5.5
05 查看结果。
训练完成后,输出目录结构:
outputs//
├── best_skill.md #最后训练出的技能文档
├── skills/ #每个步骤都对应一个技能快照
├── steps/ #每个步骤都做了详细的记录
└── history.json #训练历史
06 部署使用。
把 best_skill.md 文件的内容直接放入到Agent的system prompt中就可以使用了。
整个训练过程中没有增加额外的推理开销,在部署的时候也不需要调用优化器模型,只是多了一个Markdown文件。
写到最后
SkillOpt 让我重新思考了一个问题:
Agent 的能力上限,到底是受限于模型本身,还是技能文档的质量?
过去人们只重视模型的能力,而现在发现技能文档的质量也很重要。
即使模型很强,但是文档写得不好,那么Agent也无法很好地发挥作用。
SkillOpt 提供了一个系统化的方案,让技能文档可以像模型一样不断训练和优化。
这可能会成为 Agent 工具链发展的重要方向。
项目基于 MIT 协议开放,感兴趣的同学可以去 GitHub 仓库看看源码和文档。
开源地址:https://github.com/microsoft/SkillOpt
SkillOpt is gaining traction.
Microsoft's open-source project has garnered over 9,000 stars.
It transforms the creation of Agent skill documentation into a genuine training process.
Leveraging forward propagation, backpropagation, parameter updates, and gated validation.
In essence, SkillOpt specializes in refining `skill.md` files for Agents, evolving the once experience-based process into an iterative optimization routine akin to model training.
The traditional workflow for writing skill documents is inefficient.
You write a document, the Agent performs the task, fails, you revise the document, and the cycle repeats with poor results and no systematic feedback.
The error rate is high, and there is no structured method to improve.
The entire process lacks clear metrics and a reliable feedback loop.
SkillOpt revolutionizes this by introducing a structured training regime.
Imagine writing a "Cooking Guide" to teach someone to cook.
First, you instruct them to cook and record the entire process — ingredients, quantities, temperatures, outcomes.
Similarly, SkillOpt runs Agents on tasks using current skill documents, logging execution details, tool calls, feedback, and scores.
This is the "forward propagation" phase — running the experiment to observe the outcome.
Next, you review the logs to identify what went wrong.
Perhaps the guide failed to mention adding salt.
SkillOpt uses a separate model to analyze these trajectories, distinguishing between successful and failed executions to pinpoint where rules are missing or incorrect.
This analysis determines the "gradient direction" — what needs to be changed.
When updating the guide, you must proceed cautiously.
Making too many changes simultaneously obscures which modification fixed the issue.
SkillOpt operates with a "text learning rate" (default 4), suggesting specific edits — adding, removing, or modifying rules — one step at a time.
This prevents "catastrophic forgetting" by limiting the scope of each update just like in deep learning.
The final step is verification.
The updated guide is tested again. If the dish tastes better (or the Agent performs better), the change is validated; otherwise, it is rejected and noted for future avoidance.
SkillOpt ensures that only edits proven to improve performance on the validation set are accepted.
A notable feature is transferability.
Skill documents trained on GPT-5.5 can be applied to GPT-5.4-mini, and Codex-trained skills can be used with Claude Code.
This allows for the reuse of high-quality skill documents across different models.
The test results are impressive.
In 52 scenarios, SkillOpt achieved the highest or tied-highest scores. GPT-5.5 saw an average improvement of 23.5 points, lifting GPT-5.4-mini from 70.9% to 85.8% on ALFWorld tasks.
This significant boost required only four accepted edits.
The plots show the training scores increasing and the rejection of unsuccessful edits.
Another highlight: transferability.
Install SkillOpt via pip.
Configure your API keys in the `.env` file.
Prepare your data — either let SkillOpt split it automatically or manually define training, validation, and test sets.
Run the training using the provided command, specifying your models.
Inspect the output directory for the finalized `best_skill.md` and analysis plots.
Finally, deploy the best skill document to your Agent's prompt to leverage the improved performance.
The training incurs no additional runtime overhead once deployed. The final artifact is simply a refined Markdown file used at inference time.
SkillOpt represents a paradigm shift in Agent development.
It suggests that the upper limit of an Agent's capability is not solely defined by the underlying model, but also by the quality of its skill documentation.
By treating the tuning of these documents as a trainable task, SkillOpt opens a new avenue for optimizing AI systems.
The project is open-source under MIT, with repositories available for both the framework and pre-refined skills.
两种方式:
Automatic splitting: Prepare the raw data and let SkillOpt automatically split it into training, validation, and test sets.
Manual splitting: Prepare the three folders yourself.
04 开始训练。
可以指定teacher和student模型:
05 查看结果。
After training, the output directory structure is:
06 部署使用。
The content of the best_skill.md file can be directly inserted into the Agent's system prompt for use.
No additional inference overhead was added during the training process, and there is no need to call the optimizer model during deployment — only a Markdown file is added.
写到最后
SkillOpt made me rethink a key question:
Is an Agent’s upper limit determined by the model itself, or by the quality of the skill documentation?
In the past, people only focused on the model's capability, but now we see that the quality of the documentation is also crucial.
Even if the model is strong, poor documentation prevents the Agent from performing well.
SkillOpt offers a systematic approach to training and optimizing skill documentation alongside the model.
This could become a major trend in Agent toolchain development.
The project is open under the MIT license — check out the GitHub repo for source code and documentation if interested.
开源地址:https://github.com/microsoft/SkillOpt