- Improve the workflow, not the base model.
- Write down failures before adding memory or tools.
- Keep risky actions behind approval until the loop is boringly reliable.
Why this matters
“Self-improving agent” sounds like a lab problem. Many people hear the phrase and imagine a model that trains itself, rewrites its own weights, and gets smarter every day.
That version exists as a research direction. It is not the version most people can use.
The practical version is less cinematic and much more useful:
For an ordinary user, small team, or independent developer, the agent gets better when its work environment gets better: clearer rules, better logs, reusable skills, stronger checklists, more reliable validation, and human approval for changes that could cause damage.
What practical self-improvement means
Reflexion is a useful starting point because it separates improvement from model training. The Reflexion paper describes agents that learn from task feedback by writing verbal reflections into memory rather than updating model weights. Self-Refine makes a related point: a model can generate an output, critique it, and refine it iteratively without extra training data or reinforcement learning. RReflexion paper↗SSelf-Refine paper↗
The ordinary-user version is similar in spirit but grounded in files and workflows:
| Layer | What improves | Practical artifact |
|---|---|---|
| Trace | You can see what the agent did. | Logs, traces, task history, tool-call records |
| Eval | You know whether the result passed. | Tests, validators, checklists, review rubrics |
| Reflection | The agent explains what worked and failed. | Post-task notes, root-cause analysis |
| Memory | Lessons survive the next chat. | SOPs, AGENTS.md, project docs, memory files |
| Skill | A repeated workflow becomes reusable. | SKILL.md folders, scripts, templates, references |
| Approval | Bad lessons do not become permanent. | Human review before high-risk rule changes |
This is not weaker than the sci-fi version. It is the version that can be built today.
Do not start with model optimization
Most users should not begin with fine-tuning, reinforcement learning, or automatic prompt mutation. Those approaches can be useful, but they require data, compute, deployment discipline, and reliable evaluation.
The first question should be smaller:
| Tempting idea | Why it is risky for normal users | Better first step |
|---|---|---|
| Fine-tune the model | You need clean data, evals, deployment, and rollback. | Write better task-specific instructions and checklists. |
| Let the agent rewrite its own rules | It may turn a one-off mistake into permanent policy. | Generate a proposal and require human approval. |
| Auto-run every tool | File writes, deploys, emails, and payments can cause real damage. | Use allowlists and approval gates. |
| Trust self-evaluation alone | The model may praise its own bad output. | Use external checks: tests, validators, links, diffs, reviewers. |
The minimum architecture
A normal person can build a self-improving workflow with a folder, a few documents, and one consistent habit after each task.
/my-agent-system
/tasks
2026-06-12-example-task.md
/sop
writing-sop.md
publishing-sop.md
document-patch-sop.md
/logs
self-improvement-log.md
/skills
research-note-skill/
SKILL.md
safe-document-patch-skill/
SKILL.md
/evals
checklist.mdAfter each meaningful task, ask six questions:
- Was the task completed?
- How was it validated?
- What failed or required user correction?
- Is the lesson a rule, preference, pattern, bug, or one-off observation?
- Should it become a log entry, SOP update, template, script, or skill?
- Does the change require human approval?
This is the smallest usable self-improvement loop.
Open-source building blocks worth knowing
There is no single open-source product that gives every user a perfect self-improving agent. The useful tools solve different layers of the loop.
| Tool | Best for | Self-improvement lesson |
|---|---|---|
| LangGraph | Stateful agent workflows | Use durable execution and human-in-the-loop interrupts when actions need review. |
| Langfuse | LLM traces, evals, prompt management, observability | You cannot improve what you cannot inspect. |
| OpenHands | Software engineering agents that work in real environments | Agents need workspaces, tool boundaries, and sandboxed execution. |
| SWE-agent | Research-grade software engineering agents | The agent-computer interface matters as much as the model. |
| AutoGen | Multi-agent systems and event-driven agent workflows | Split work into worker, reviewer, logger, and approver roles when complexity justifies it. |
| CrewAI | Role-based multi-agent orchestration | Use crews only when the task genuinely benefits from separate roles. |
LangGraph is especially relevant when you need a workflow that can pause and wait for a human decision. Its documentation describes durable execution, streaming, human-in-the-loop patterns, and interrupts that pause execution while preserving state. Langfuse covers another layer: traces, evals, prompt management, cost, latency, and debugging for LLM applications. LGLangGraph overview↗LGLangGraph interrupts↗LFLangfuse docs↗
OpenHands and SWE-agent are useful references for coding-agent design. OpenHands describes itself as an open-source, model-agnostic platform for cloud coding agents that execute real engineering work, while SWE-agent focuses on giving models tools to fix real GitHub repository issues. OHOpenHands platform↗SWESWE-agent docs↗
AutoGen and CrewAI are better references when the problem naturally splits into roles. AutoGen describes itself as an event-driven framework for scalable multi-agent AI systems, and CrewAI describes itself as a framework for building agents, crews, and flows with guardrails, memory, knowledge, and observability. MSAutoGen docs↗CRCrewAI docs↗
How common agents can implement it
The same self-improvement loop should not be forced into every product. Claude Code, OpenClaw, Cursor, and Codex each have a different natural memory layer.
Claude Code users: turn repeated work into skills and hooks
Claude Code users should think in terms of project instructions, skills, hooks, subagents, permissions, and checkpoints. Anthropic’s public skills repository describes skills as folders of instructions, scripts, and resources that Claude loads dynamically to improve performance on specialized tasks. The Claude Agent SDK documentation says it includes built-in tools, hooks, subagents, MCP, permissions, and sessions. AIAnthropic Skills repository↗AIClaude Agent SDK overview↗
| Claude Code layer | Use it for |
|---|---|
| Project instructions / CLAUDE.md-style guidance | Stable project rules and constraints |
| Skills | Repeated procedures such as PR review, release checks, docs updates |
| Hooks | Deterministic post-task checks or reminders |
| Subagents | Separate reviewer, tester, researcher, or logger roles |
| Checkpoints | Rollback after risky edits |
The best Claude Code pattern is simple: repeated good work becomes a skill; repeated mistakes become hooks or checklists; broad permission changes require human approval.
OpenClaw users: improve the workspace, not the chat
OpenClaw users should build self-improvement at the workspace level. OpenClaw’s workspace documentation says the workspace is the agent’s home, the only working directory used for file tools and workspace context, and should be treated as memory. Its skills documentation says Skill Workshop is a proposal queue: when the agent spots reusable work, it drafts a proposal instead of directly writing to active skill files; the user reviews and approves before changes apply. OCOpenClaw workspace docs↗OCOpenClaw Skill Workshop↗
| OpenClaw layer | Use it for |
|---|---|
| AGENTS.md | Long-term workspace rules and project constraints |
| TOOLS.md | Tool inventory and safe usage notes |
| BOOT / HEARTBEAT-style files | Startup checks and periodic maintenance |
| Workspace skills | Reusable procedures scoped to the workspace |
| Skill Workshop | Human-approved skill proposals |
The best OpenClaw pattern is: let the workspace accumulate memory, but do not let the agent silently rewrite its own operating rules.
Cursor users: turn rules and review feedback into loops
Cursor users live inside the IDE, so the self-improvement layer should be repo rules and review feedback. Cursor’s rules documentation covers Project Rules, Team Rules, User Rules, and AGENTS.md. Cursor’s skills documentation describes Agent Skills as a way to package reusable knowledge and scripts for agents. CUCursor Rules docs↗CUCursor Skills docs↗
| Cursor layer | Use it for |
|---|---|
| User Rules | Personal preferences |
| Project Rules / AGENTS.md | Repo-specific build, test, style, and safety rules |
| Team Rules | Organization-wide coding norms |
| Agent Skills | Repeatable procedures that need instructions or scripts |
| PR review / Bugbot-style feedback | Repeated defects that should become rules |
The best Cursor pattern is: turn repeated review comments into rules, and turn repeated multi-step coding workflows into skills. Do not put every preference into one giant rule file.
Codex users: start with AGENTS.md, then upgrade to skills
Codex users should treat AGENTS.md as the first memory layer and skills as the upgrade path for repeated workflows. OpenAI’s Codex documentation says Codex discovers AGENTS.md guidance from global and repo-level locations, and its skills documentation says a skill is a directory with a required SKILL.md plus optional scripts, references, and assets. Codex can invoke skills explicitly or select them implicitly from the skill description. OCodex AGENTS.md guide↗OCodex Skills docs↗
| Codex layer | Use it for |
|---|---|
| Global AGENTS.md | Personal default behavior and safety boundaries |
| Repo AGENTS.md | Setup, test, lint, build, and repo-specific conventions |
| Nested AGENTS.md | Directory-specific rules |
| Skills | Repeatable tasks that need packaged instructions, references, or scripts |
| Subagents / automations | Parallel exploration or recurring checks, when appropriate |
OpenAI’s Codex best-practices page gives a plain rule that fits this whole article: once a workflow becomes repeatable, stop relying on long prompts and turn it into a skill. OCodex best practices↗
Implementation map
| Agent type | Best memory layer | Best reusable workflow layer | Best validation layer | Approval point |
|---|---|---|---|---|
| Claude Code | Project instructions / CLAUDE.md-style guidance | Skills, hooks, subagents | Tests, hooks, checkpoints | Before permission, hook, or global skill changes |
| OpenClaw | Workspace files, AGENTS.md, TOOLS.md | Workspace skills, Skill Workshop | Build scripts, health checks, workspace logs | Skill Workshop approval and high-risk workspace rules |
| Cursor | Project / Team / User Rules, AGENTS.md | Agent Skills, review workflows | Tests, PR review, Bugbot-style checks | Before team rules, broad autofix, or repo-wide rules |
| Codex | Global and repo AGENTS.md | Codex Skills | Tests, lint, task-specific evals | Before global AGENTS, skill scripts, or repo-wide defaults |
Checklist before you call something self-improving
- Does it record what the agent actually did?
- Does it validate results with something outside the model?
- Does it separate rules, preferences, patterns, bugs, and observations?
- Does it store lessons somewhere future sessions can read?
- Does it convert repeated workflows into skills or templates?
- Does it require human approval for high-risk changes?
- Can a bad rule be found, edited, or rolled back?
- Does it avoid granting new permissions just because a task succeeded once?
If the answer is no, the agent is not really self-improving. It is just running again.
The bottom line
The useful version of a self-improving agent is not an agent that secretly changes itself.
It is an agent whose working environment improves after each task.
Rules tell it how to behave. Skills tell it how to repeat a workflow. Logs tell it what happened. Evals tell it whether the result was good. Human approval prevents bad lessons from becoming permanent.
That is the self-improving agent normal people can actually build.
Further reading
Three sources worth reading next. Each card links to the original source; the thumbnails are AI Picker editorial covers, not publisher images.
