SkillOpt: Training a Markdown Skill File Like a Model Weight
Microsoft’s framework treats agent instructions as editable state, then optimizes them through rollouts, reflection, bounded patches, and validation gates instead of fine-tuning.
- SkillOpt turns a Markdown skill file into the unit of optimization, which makes agent improvement persistent, inspectable, and cheap to deploy.
- Its ReflACT loop borrows the discipline of training runs, but applies it to text through rollouts, reflection, bounded edits, and validation.
- The validation gate is the real guardrail, because it stops the system from accepting edits that make the skill worse on held-out tasks.
- The learning-rate metaphor is more than branding, because it controls how many text edits the optimizer is allowed to make at each step.
The prompt is the parameter. That is the whole trick. SkillOpt stops treating instruction files like fragile prose and starts treating them like trainable state. The result is a system that looks much closer to model training than to prompt tinkering, even though it never touches model weights.
SkillOpt treats a compact natural-language skill document as the trainable state of a frozen language agent, then learns that document through rollouts, reflection, bounded edits, and held-out validation gates.
What SkillOpt actually trains
The mental model matters. There are two models in play. The target model executes the task with the current skill file, while the optimizer model studies the resulting trajectories and proposes edits. The skill file sits in the middle as the mutable artifact.
That is why the repo feels like a training stack. It has epochs, batches, a scheduler, candidate updates, and a gate that decides whether the new version survives. The novelty is not that LLMs can critique text. The novelty is that criticism gets turned into bounded state updates.
The six-step loop: rollout, reflect, aggregate, select, update, evaluate
SkillOpt’s ReflACT loop is the core mechanism. A batch of tasks runs through the current skill. The rollout produces trajectories, including failure traces. Those traces become input to reflection, which proposes patches instead of a brand-new document.
The patches are then aggregated. That matters because the system is not merely accepting the loudest suggestion from one episode. It is collecting evidence across a batch, then selecting a candidate update that fits the edit budget and the current training stage.
This is where SkillOpt stops being a clever metaphor and starts behaving like an optimizer. It transforms a messy stream of agent behavior into discrete candidate patches, then selects one version as the best current skill. The text document is not just edited. It is iterated.
Why the validation gate matters
Without a held-out gate, text optimization would be easy to fool. A skill could get better at the training trajectories while quietly getting worse at the real task. SkillOpt’s validation step is what keeps the loop honest.
| Stage | Without a gate | With SkillOpt |
|---|---|---|
| Update acceptance | A patch can look good on the episode that produced it. | A patch must improve held-out validation before replacing the best skill. |
| Failure mode | The skill can overfit to one batch of trajectories. | The skill has a chance to be rejected before it becomes the new default. |
| Operational confidence | Teams have to trust the optimizer’s judgment blindly. | Teams can inspect the candidate skill and the validation result. |
| Deployment cost | Often still requires extra runtime machinery to keep adapting. | The accepted skill is just Markdown at deployment time. |
That gate is also why the project feels operational rather than experimental. The learned skill is compact, human-readable, and portable. If validation fails, the old skill stays in place. That makes the whole system much harder to trust breakage into existence.
Edits, not rewrites: how Markdown becomes mutable state
SkillOpt does not let the optimizer scribble anywhere. It exposes a narrow set of edit operations: append, insert_after, replace, and delete. It also protects regions marked with SLOW_UPDATE_START and SLOW_UPDATE_END so the most important parts of the skill do not get casually overwritten.
# Conceptual edit model
patch = [
{"op": "replace", "target": "step 3", "value": "use validation before final answer"},
{"op": "insert_after", "target": "# Constraints", "value": "- keep answers concise"},
{"op": "delete", "target": "redundant note"},
]
report = apply_patch_with_report(skill_md, patch)
# report can show applied_replace, skipped_protected_slow_update_region, and similar outcomesThat structure is the point. SkillOpt treats the skill as structured state, not freeform text. The optimizer can be powerful, but it is fenced in. The result is a document that can evolve without becoming unreadable sludge.
The learning-rate trick
The nicest idea in the repo is that learning rate becomes an edit budget. Early in training, the system can make broader changes. Later, the scheduler decays the budget so updates become more surgical. Big swings first. Fine-grained refinement later.
That is a remarkably clean translation of a deep learning concept into text space. Instead of changing step size in weight space, SkillOpt changes how many edits the optimizer is allowed to make. The metaphor is not decorative. It is operational.
| Setting | High edit budget | Low edit budget |
|---|---|---|
| Behavior | Broad rewrites and larger structural changes. | Small, targeted patches and local refinements. |
| Risk | More chance of overshooting or destabilizing the skill. | Less chance of dramatic improvement, but safer updates. |
| Use case | Early exploration. | Late-stage polishing and consolidation. |
That is also why the project feels different from a one-shot prompt rewrite. It has a schedule. It has a curriculum. It does not ask the optimizer to be clever once. It asks it to improve under a budget, then improve again under a tighter budget.
How it compares to prompt optimization and agent frameworks
SkillOpt is part of a crowded neighborhood. Prompt optimizers like TextGrad and GEPA improve instructions, but they do not emphasize a persistent skill artifact in the same way. Reflexion learns from self-critique, but it is episode-local. DSPy gives you structured optimization, but SkillOpt pushes harder on the training metaphor and the validation discipline.
| Project | Optimized artifact | Update style | Validation gate | Persistent skill artifact | Inference-time cost | Main limitation |
|---|---|---|---|---|---|---|
| SkillOpt | Markdown skill file | Bounded add, delete, replace | Yes | Yes | Zero extra deployment cost | New and still specialized |
| TextGrad | Prompt text | Textual optimization | Varies | Usually no | Low | Less emphasis on a reusable skill file |
| Reflexion | Agent behavior over episodes | Self-reflection loop | Not central | No | Depends on runtime loop | Can stay episode-specific |
| DSPy | Programs and prompts | Programmatic optimization | Yes in some workflows | Sometimes | Low | Less direct focus on skill documents |
| EvoSkill | Skills from trajectories | Evolutionary updates | Limited or different | Yes, but less bounded | Low | Stability and control are weaker |
The important distinction is not performance theater. It is artifact design. SkillOpt leaves you with a file you can inspect, version, ship, and reuse. That makes it more than a clever loop. It becomes an operating model for how agent instructions can improve over time.
Why this matters beyond one repo
SkillOpt suggests a future where agents get better through text-native training, not just through bigger models or heavier fine-tuning. That matters because instruction state is easier to inspect than weights, cheaper to deploy than runtime adaptation, and easier to transfer across environments than a custom workflow.
The deeper implication is cultural as much as technical. A lot of prompt engineering is artisanal. SkillOpt replaces that habit with something stricter: controlled edits, observable feedback, and an acceptance test. It makes improvement legible.
