Agents don't learn. Sessions do, and sessions die the moment you close the terminal. Every "self-improving agent" setup I've seen that actually works comes down to one unglamorous mechanic: at the end of a session that went well, the lessons get written into a file that the next session loads. That's the entire trick. No fine-tuning, no vector database, no memory architecture diagram. A markdown file, written at the right moment, with the right things in it.
I've run this loop enough times to have receipts. My local skills folder currently holds 31 skills. The agent skills marketplace on this site publishes 53 more that I maintain. Almost none of them were designed up front. They were distilled, after the fact, from sessions where an agent and I figured something out the hard way. That distillation step is what people mean when they talk about training agents to learn autonomously, whether they realize it or not.
What "Training" Actually Means Here
The word "training" suggests gradient descent. Forget that. You are not changing the model. You are changing what the model reads before it starts working.
Claude Code loads skill files on demand: a markdown document with a name, a description that controls when it triggers, and a body of instructions. When a task matches the description, the agent pulls the skill in and follows it instead of rediscovering the approach from zero. The model stays frozen. The system around it learns.
This distinction matters because it tells you where to spend effort. People burn weeks on elaborate memory systems trying to make agents "remember." I run one of those too, and it has its place — I wrote about the layers in Claude Code's six levels of memory. But memory files hold facts. Skills hold procedures. "The staging database is called srv579" is memory. "Here is how to audit hreflang tags without breaking the six-locale setup" is a skill. Confusing the two is the most common reason these systems rot: procedures dumped into memory files never trigger at the right time, and facts stuffed into skills bloat every session that loads them.
My Skills Folder Is the Receipt
Thirteen of the 31 skills in my folder start with seo-. There's seo-audit, seo-hreflang, seo-sitemap, seo-schema, seo-programmatic, seo-technical, and seven more. Every single one exists because this website lost most of its indexed pages in the spring of 2026 — Google dropped it from roughly 7,000 indexed URLs to about 1,700 in a matter of weeks.
Digging out of that hole meant months of repetitive diagnostic work: checking canonical tags across six locales, validating structured data, hunting duplicate content, auditing sitemap coverage. The first time I did each of those tasks with Claude Code, it took a long session full of wrong turns. The agent would grep the wrong directory, misunderstand how my Laravel routes map locales, or suggest schema fixes that had already caused the problem. By the end of each session we had a working procedure, and the procedure went into a skill file before I closed the terminal.
The second time I ran each audit, the agent skipped every wrong turn. Not because it got smarter — because it read the file where the wrong turns were already documented as things not to do.
That's the insight I'd put on a poster: the best moment to write a skill is the last ten minutes of the session where you struggled. All the context is loaded. The agent knows exactly which approaches failed and why. Ask it to write the skill itself: "Turn what we just did into a skill file. Include the dead ends." The output is better than anything you'd write from memory a week later, because the dead ends are the valuable part and they're the first thing you forget.
The Anatomy of a Skill That Actually Triggers
A skill file has two jobs, and people obsess over the wrong one. The body — the instructions — is job two. Job one is the description in the frontmatter, because a skill that never triggers might as well not exist, and a skill that triggers on everything poisons unrelated sessions.
After enough iterations I've settled on descriptions that name concrete situations, not capabilities. Compare:
description: Helps with SEO tasks.
against:
description: Audit hreflang and canonical tags across locales.
Use when pages are dropping from the index, when hreflang
errors appear in Search Console, or when adding a locale.
The first version triggers never, or always. The second triggers exactly when it should, because it mirrors how the request will actually be phrased. I learned this from watching my own skills fail to fire in sessions where I obviously needed them — and from the skill-creator tooling I now run, which includes a description optimizer for precisely this problem.
The body follows a structure I keep consistent: prerequisites, the workflow steps, known issues, and success criteria. Known issues is where the compounding happens. When a skill fails in the field — a selector changed, an API renamed a field, my own codebase moved — the fix goes into that section, and the skill gets stronger. I covered the deeper craft lessons in what building Claude Code skills taught me, so I won't repeat them all here.
Closing the Loop: Evals Are What Make It Autonomous
Here's where most skill libraries stall. You write a skill, it seems fine, you move on. Three weeks later it silently gives worse instructions than no skill at all, and you don't notice because you never measured it.
The loop I run now, using a skill-creator workflow that manages this end to end:
- Draft the skill from a real session, as above.
- Write three to five test prompts that should trigger it — phrased the way I'd actually type them, not idealized.
- Run Claude with the skill against those prompts in the background.
- Review the transcripts qualitatively and score them against simple assertions: did it follow the documented steps, did it avoid the documented dead ends, did it produce the expected artifact.
- Rewrite the skill where it drifted. Rerun.
- Once it's stable, run the description optimizer so it triggers accurately.
Step 2 is the one nobody does and everybody should. Test prompts force you to confront the gap between what you think the skill covers and what you'll actually ask for. Half my skill revisions come from realizing my own test prompt didn't trigger the skill I wrote an hour earlier. I go deeper on this workflow in testing and optimizing skills with skill-creator.
Is this "autonomous"? More than you'd think. The agent writes the first draft of the skill, generates the test prompts, runs itself against them, and proposes revisions. My job has shrunk to judgment calls: is this procedure actually correct, is this dead end worth documenting, should this be one skill or two. That last question comes up constantly — my rule is that if two workflows share a description but diverge in the first three steps, they're two skills.
Skills Decay, and That's Fine
Anything that touches the outside world rots. My SEO skills needed edits when I restructured this site's sitemap into an index file. My Higgsfield generation skills hardcode model names that will need updating every time that lineup shifts. A skill written against one model's behavior sometimes reads as over-explained to its successor.
I treat this the way I treat dependencies in a Laravel project: version control and periodic exercise. The skills folder is in git, so I can see exactly when a workaround was added and safely delete it when the underlying quirk disappears. And because I use most skills weekly, decay surfaces fast. A skill you haven't run in two months is a skill you should assume is broken — run it before you need it.
This is also my honest caveat about the whole approach: it front-loads work and repays it only on repetition. If a task happens once, a skill file is pure overhead. My threshold is three occurrences. The first time, just do the work. The second time, notice the déjà vu. The third time, you're writing the skill anyway, so write it at the end of that session while the context is hot. If you're deciding which existing skills are worth adopting rather than writing your own, I keep a running list of the skills actually worth installing.
Where This Is Heading
I don't think the endgame is agents that mystically self-improve. I think it's this exact loop with the human turns getting shorter: agent does work, agent proposes the distillation, agent tests the distillation, human approves. The approval step stays, because a skill file is trusted input — a bad procedure codified is a bad procedure executed at speed, forever. I'd rather have a smaller library I trust than a large one I have to audit.
After 8+ years of shipping software and 1,500+ projects, the pattern feels familiar from an older discipline: this is just documentation culture, except the reader is an agent and the payoff arrives in the same week instead of when a new hire joins. Teams that wrote good runbooks always outran teams with heroic memories. Same law, faster clock.
Reading a working skill file teaches the format faster than any spec does. All 53 of mine are published in the Agent Skills Marketplace, each one born from a session where something didn't work until it did.
