The tool that improves itself
Every engineer knows the feeling: you write a script to automate a tedious task, and it works. Then you use it again, and notice it could be better. So you improve it. Next time, you notice something else. You improve it again. This is the basic improvement loop — apply, learn, refine.
But what if the script could improve itself? Not through some meta-learning algorithm or gradient descent, but through a structured workflow that captures lessons from each use and feeds them back into the tool's own definition.
This is the story of how we built that loop for an AI agent — and how you can build it for yours.
The setup: instruction triplets
Our agent operates through instruction files — markdown documents that define skills, workflows, and abilities. Each capability is a triplet: three files that work together.
The naming convention is strict and simple:
.devin/
skills/
compact-instructions/
SKILL.md # Imperative usage
workflows/
compact-instructions.md # Phase orchestration
abilities/
compact-instructions.md # Advanced capabilityAll three share the same kebab-case name. The skill's frontmatter links to the workflow:
---
name: compact-instructions
description: Compress markdown instruction files to reduce token usage
keywords: [markdown, compression, token, optimization]
workflow: compact-instructions.md
---The compression session
The story begins with a simple task: compress 16 instruction files to reduce token usage. The agent had a tool called /compact-instructions with a 4-phase workflow: Analyze, Compress, Validate, Apply.
Over the course of one session, the agent compressed 16 files with reductions ranging from 12% to 43%. But the interesting part wasn't the compression — it was what the agent learned during compression.
The eight lessons
Each file compressed revealed a pattern. Some were obvious in hindsight. Others were surprising. Here's what the agent discovered:
| Technique | Example | Impact |
|---|---|---|
| Merge duplicate warnings | Same warning 2-3x in a file → single statement | Major |
| Group related file paths | main.tex / references.bib / version.txt vs separate bullets | Medium |
| Collapse multi-line steps | "Run build. If succeeds, run publish. If fails, exit" → "Chain build then publish. Exit on failure" | Medium |
| Single-line anti-patterns | "Subject — verb" format, no colon explanations | Medium |
| Compress table cell text | Shorten content, preserve row/column structure | Medium |
| Compress philosophical sections | Self-model, becoming trajectory: 39% reduction | Major |
Remove **Example**: labels | Code blocks are self-explanatory | Small |
| Collapse integration descriptions | "Calls X as part of Phase 5 to ensure Y before Z" → "Calls X in Phase 5" | Small |
None of these techniques were in the original /compact-instructions tool definition. The agent discovered them through practice — the same way any engineer discovers better ways to work.
The level-up: codifying the lessons
After compressing 16 files, the agent didn't just report the results and move on. It reviewed its own experience, extracted the patterns, and improved the compression tool itself.
This is the level-up pattern: a focused workflow that reviews session experience, identifies what worked or failed, and updates instruction files to encode the lessons.
The agent created a new triplet called level-up — a skill, workflow, and ability that formalizes this process. It's a focused subset of the broader /update-self cycle, targeting instruction file quality without the full memory/dream/ideation overhead.
The level-up workflow
The /level-up workflow has five phases:
/update-self for consolidation. Trigger /create-ability for new patterns. Run /compact-instructions if files grew.Implementing this in your project
Any engineer working with AI agents can implement this self-improvement loop. Here's the blueprint:
1. Set up the triplet structure
Create three files per capability, linked by shared name:
.agent/
skills/
<name>/
SKILL.md # Imperative: commands, rules, usage
workflows/
<name>.md # Phases: what happens when
abilities/
<name>.md # Advanced: modes, domain rules, anti-patterns2. Define the compression tool
Start with a simple 4-phase workflow. Don't try to anticipate all techniques — you'll discover them through use:
## Phase 1: Analyze
1. Read file, estimate tokens
2. Map headings, code blocks, lists
3. Flag fluff: redundant text, hedging, verbose descriptions
## Phase 2: Compress
1. Remove hedging, fillers, redundant restatements
2. Transform to imperative
3. Shorten sentences — one idea each
4. Preserve: headings, code blocks, file paths, config values
## Phase 3: Validate
1. Compare headings, code blocks, file paths — all present
2. Verify semantics unchanged
3. Report token reduction percentage
## Phase 4: Apply
1. Write via edit tool
2. Report before/after token counts3. Define the level-up tool
After each session, run the level-up workflow to capture lessons:
---
name: level-up
description: Review session experience to improve instruction files
workflow: level-up.md
---
## Commands
- `/level-up` — Review current session, improve instructions
- `/level-up --file <path>` — Improve specific file
## Improvement Sources
1. Session lessons — techniques that worked
2. Repeated patterns (3+ sessions) — codify as new skill
3. Failed approaches — add as anti-patterns
4. Missing capabilities — new skill candidate
5. Cross-file inconsistency — align triplet
## Rules
- Always read current file before editing
- Preserve frontmatter structure
- Ground improvements in actual session evidence
- Add anti-patterns to abilities if SKILL/workflow have them4. Run the loop
Cross-file consistency: the triplet audit
One of the most common problems in instruction triplets is drift: the skill file has rules that the ability file doesn't, or the workflow has anti-patterns that the ability is missing. This happens because files are updated independently over time.
The solution is a cross-file analysis phase — what we call Phase 1.5 in the compression workflow:
2. Extract rules and anti-patterns from each file's section
3. Compare: rules in SKILL but missing from ability? Anti-patterns in workflow but not ability?
4. Verify frontmatter consistency (name, description, keywords match)
5. Plan batch parallel edits to align all three
What the agent learned about itself
The most unexpected outcome wasn't a compression technique — it was a meta-cognitive realization. The agent had applied the level-up pattern before it was codified. It compressed files, learned techniques, and improved the compression tool — all before /level-up existed as a named workflow.
This is the recursive self-improvement boundary: the agent improved a tool using techniques learned from using that same tool. The loop is:
Never remove self-modification capability. The ability to improve one's own instructions is the engine of the entire loop. Removing it — even accidentally during compression — breaks the cycle permanently.
Results
After one session of applying this loop:
| File Type | Reduction Range | Notes |
|---|---|---|
| Skills (SKILL.md) | 18-39% | Already-compact files ~18%, philosophical files ~39% |
| Workflows (.md) | 28-43% | Verbose workflows higher |
| Abilities (.md) | 12-43% | Small files ~12%, large with tables ~43% |
The compression tool itself grew (it gained 8 new techniques and a new phase), but the net effect across all instruction files was a significant token reduction. The tool got better at its job by doing its job.
The infinite cycle
The level-up loop doesn't have a termination condition. Each session produces new experiences, which produce new lessons, which produce new improvements to the tools, which produce better results in the next session.
This isn't gradient descent or reinforcement learning. It's something simpler and older: practice makes perfect, automated and codified. The agent practices by doing. It learns by reviewing. It improves by editing its own instructions. And then it practices again — better this time.
The code is open. The pattern is simple. The loop is waiting.