---
title: Your agent can rewrite its own instructions. Here is why it converges.
canonical: "https://agenticup.dev/posts/skillopt-lite-agent-self-evolution/"
pubDate: "2026-07-08T00:00:00.000Z"
description: "Editing your agent's skill file is not a hack. SkillOpt-Lite formalizes it as Zeroth-Order optimization with three principles that guarantee convergence. Plus HarnessOpt — optimizing agent code as a trainable parameter."
tags: [ai-agents, skill-optimization, agent-evolution, llm-research, coding-agents]
---

**TL;DR:** The [SkillOpt-Lite paper](https://arxiv.org/abs/2607.03451) (Shen et al., arXiv 2607.03451, July 2026) formalizes agent skill optimization as Zeroth-Order optimization. The pipeline: run N rollouts, save every trace as a file, find what successful traces share, edit the skill document, validate on a held-out set before accepting. Three principles guarantee convergence. The same loop extends to the agent's Python harness code via HarnessOpt. GPT-5.4-nano with an optimized harness beats GPT-5.5 with a stock pipeline.

> **Key takeaways:**
> - Editing your agent's CLAUDE.md is not trial and error. It's Zeroth-Order optimization in text space. The theory proves it converges.
> - Three principles are sufficient: file-system trajectory exploration, consensus attribute mining, independent validation gating. That's the minimal viable pipeline.
> - HarnessOpt extends the same loop to edit agent Python code. Treat code as a trainable parameter. GPT-5.4-nano plus HarnessOpt beats GPT-5.5.
> - SkillOpt-Lite eliminates the separate optimizer model. The coding agent IS the optimizer. Faster and more accurate than full SkillOpt.
> - The catch: text-space optimization works for skill refinement, not for teaching the model capabilities it does not have.

I spent three weeks manually tuning an agent's CLAUDE.md.

Every morning, I would run 20 test cases, skim the failures, spot a pattern, edit two lines in the skill doc, and rerun. The score would go up. Then plateau. Then I would spot another pattern and repeat. The loop worked. I had no idea why.

I was doing manual Zeroth-Order optimization. I did not know the name at the time.

## Here's what makes agent skills optimizable

There are two ways to improve agent performance.

**Weight-space optimization** fine-tunes the model's parameters. You collect data, set up a training pipeline, run gradient descent, and ship new weights. It's expensive, needs GPUs or TPUs, and you cannot inspect what changed by reading a diff.

**Text-space optimization** edits the agent's natural-language skill document. A CLAUDE.md, a AGENTS.md, a skills.md. The model stays frozen. The skill file behaves like a trainable parameter. You can see every change in a diff.

Weight-space optimization is the standard approach. Text-space optimization is what every power user already does when they edit their CLAUDE.md after a failed test run. The difference is that one has a century of optimization theory behind it and the other felt like guesswork.

SkillOpt-Lite provides the theory. It proves that text-space optimization converges. And it defines the minimal pipeline that makes it work.

## Why it works: Zeroth-Order optimization

Here's the non-obvious insight.

In classical optimization, you compute a gradient that tells you which direction to move your parameters. That requires a differentiable function. An agent's skill document is not differentiable. You cannot backprop through a natural-language instruction.

Zeroth-Order optimization solves this. It only needs function evaluations. Run the agent with skill A, get score X. Run it with skill B, get score Y. If Y beats X, keep the change. No gradients needed.

The mapping works like this in SkillOpt-Lite:

- **State:** current skill.md
- **Perturbation:** an edit to the skill text
- **Function evaluation:** run the agent on rollout cases, measure accuracy
- **Accept or reject:** compare validation scores, gate on improvement

The catch: classical Zeroth-Order optimization uses random numerical perturbations. It perturbs every parameter by a small random value and evaluates. SkillOpt-Lite does not perturb randomly. It perturbs based on what actual trajectories revealed.

This is the key divergence from classical ZO. Skill trajectories are not blind noise. They are interpretable debugging feedback. When the agent runs 40 rollouts and saves every one as a .md file, the difference between a passing trace and a failing trace tells you exactly what to edit.

## Three principles for convergence

The paper establishes three principles. Every component in the pipeline is justified by theory or empirical necessity. Nothing extra.

**Principle 1: File-system-based trajectory exploration.**

Save every rollout as an inspectable file. Not a log. Not a database row. A markdown file on disk that the agent can read back. This is how the agent learns from its own behavior. It reads the traces like it reads any other file.

The paper uses this approach because it guarantees the agent can inspect any past attempt without needing a separate retrieval system. The file system is the memory.

**Principle 2: Consensus attribute mining.**

Run 40 rollouts. Some pass. Some fail. Now look at what the successful traces share. Did they all check an edge case first? Did they all use the same import pattern? Did they all avoid a specific code path?

Mine those shared attributes across successful trajectories. Those are the patterns you reinforce in the skill doc. Failures also share attributes. Missing steps, incorrect assumptions, skipped validations. Fix those in the same edit.

**Principle 3: Independent validation gating.**

This is the gate that prevents overfitting. You never accept an edit based on training scores alone. Every skill edit runs against a held-out validation set first. If the validation score does not improve, the edit is discarded.

The PAC learning analysis in the paper proves that this three-rule pipeline converges to a near-optimal skill within a bounded number of rounds. The bound depends on the number of rollouts per round and the complexity of the edit space.

## How the loop runs

You type one line:

```
/skillopt-loop rounds=10 batch=40 target=gpt-5.4-nano
```

The agent drives the rest. It runs 40 rollouts with the current skill doc. Saves every trace to disk. Analyzes what passed and what failed. Edits the skill doc based on consensus attributes. Validates on held-out cases. Either keeps or rolls back the edit. Repeats for 10 rounds.

At the end, workspace/skill.md is the best skill the loop found. You ship it.

The paper's results:

| Benchmark | Model | Gain over full SkillOpt |
|---|---|---|
| LiveMath | GPT-5.5 | +8.8 points |
| LiveMath | GPT-5.4-nano | +25.4 points |
| ALFWorld | GPT-5.4-nano | +9.5 points |
| Spreadsheet (avg) | - | +12.6 points |

The nano model with SkillOpt-Lite surpasses GPT-5.4 optimized by full SkillOpt. Lite is not cheaper because it's worse. It's cheaper because it's simpler, and simpler converges faster.

## HarnessOpt: optimizing the agent's Python code

Here's where the paper goes from useful to strange.

SkillOpt-Lite edits the skill document. A natural-language file. Intuitive. You tell the agent how to behave, the agent follows instructions.

HarnessOpt edits the agent's **Python code**. The rollout logic. The React loop. The executor. The adapter. All treated as editable parameters in the same optimization loop.

Here's why this works. The paper's insight: a coding agent's harness is also text. If skill.md is a trainable parameter in text space, so is rollout.py, react_agent.py, executor.py, and adapter.py. The same three principles apply. Run rollouts. Save traces. Mine what winners share. Edit the code. Validate before accepting.

The result that made me re-read the paper: GPT-5.4-nano with an optimized harness achieves 0.7758 accuracy on SpreadsheetBench. GPT-5.5 with a stock harness scores 0.7620. A smaller model with an optimized harness and optimized skill outperforms a larger model without either.

The nano model beats the frontier model because its code was trained. Not its weights. Its code.

## The catch

Text-space optimization cannot teach the agent something it does not know. If the model has never seen a programming language, no amount of skill editing will make it write correct code in that language. The knowledge has to exist in the weights first.

Weight-space optimization is still necessary when:
- The agent needs a new capability its base model lacks
- The task requires knowledge that was not in the training data
- The behavioral change is too large for a text document to express

Text-space optimization works for refinement. It takes an agent that usually gets it right and makes it get it right more consistently. It takes an agent that understands the domain and teaches it the specific playbook for your task.

The two approaches are complementary. Use weight-space optimization to teach the model what it needs to know. Use text-space optimization to teach the model how to apply that knowledge to your specific problem.

## What this means for agent development

The SkillOpt-Lite pipeline is already open source at [github.com/EvolvingLMMs-Lab/SkillOpt-Lite](https://github.com/EvolvingLMMs-Lab/SkillOpt-Lite) (MIT license, 41 stars, 19 commits). It works with VS Code Copilot, Claude Code, and Codex CLI. The Copilot example includes six benchmarks: LiveMath, SpreadsheetBench, ALFWorld, DocVQA, OfficeQA, and SearchQA.

The pipeline accepts any model accessible through your agent. The benchmarks use GPT-5.4-nano and GPT-5.5, but the loop is model-agnostic. The same /skillopt-loop command works with any coding agent that can read and edit files.

The roadmap includes an agent-agnostic loop runner that wraps the pipeline around any existing agent codebase, plus plugins for Codex CLI and Claude Code.

The direction is clear. Agent development is becoming an automated optimization problem. The skill doc is a training parameter. The harness code is a training parameter. The developer sets the objective, runs the loop, and ships the artifact. Manual CLAUDE.md editing is the first iteration. SkillOpt-Lite is the second.

## FAQ

> **Does SkillOpt-Lite require me to change my agent framework?**
> No. The loop works with any coding agent that can read and write files. VS Code Copilot, Claude Code, Codex CLI. The same /skillopt-loop command works everywhere. The paper specifically tested integration with VSCode Copilot.

> **How many GPUs does this need?**
> Zero. The model stays frozen. The optimization happens entirely in text space. You pay for API calls to run the rollouts, but there's no training compute. No gradients. No weight updates.

> **What is the difference between SkillOpt-Lite and writing a better prompt manually?**
> Manual prompt editing is unstructured. You guess what to change, edit, test, and repeat. SkillOpt-Lite structures this as an optimization loop with three principled steps. It does not edit blindly. It validates before accepting, mines consensus across multiple rollouts, and maintains a history of every attempt. The difference is systematic convergence versus trial and error.

> **Can I use SkillOpt-Lite with local models?**
> Yes. The pipeline is model-agnostic. If your coding agent can access a local model through Ollama, llama.cpp, or vLLM, the same loop works. The rollouts run against whatever model your agent connects to.

> **What skill optimization problems does the paper not address?**
> The paper focuses on single-task skills and harnesses. Multi-task skills, cross-domain transfer, and skills that interact with each other are open problems. The HarnessOpt result is limited to one benchmark and one model size. These are limitations the authors acknowledge in the future work section.

## Related Posts

- [Your agent passed the test. It still used skills wrong.](/posts/your-agent-passed-the-test-it-still-used-skills-wrong/). SkillCoach evaluates whether an agent used skills correctly. SkillOpt-Lite optimizes the skills themselves. The two papers solve complementary halves of the same problem.
- [Your context window is a workspace, not a filing cabinet](/posts/your-context-window-is-a-workspace-not-a-filing-cabinet/). Context engineering decides what goes in the agent's context. Skill optimization decides how the agent uses what it receives.
- [Your LLM judge flips a coin 13.6% of the time](/posts/llm-judge-flips-a-coin/). Evaluation signal quality determines whether a skill optimization loop learns the right thing. If your evaluation ties, your optimization stalls.

---

This article was published on Agentic Up (https://agenticup.dev): practical guides for developers and founders building with AI agents. Reach me at hello@agenticup.dev