I Stopped Hand-Writing My Agents

Claude Code writes them from the runtime's own live manual. The agents write back.

One of my agents has a rule in its memory file that has fired seven times: when a post's urgency depends on a bug being unresolved, check whether the fix already shipped before drafting the warning. I never wrote that rule. I rejected one stale draft at the approval gate, the agent turned my comment into the rule, and now every future run starts already knowing.

That rule is the small visible end of the workflow I want to walk through. Most people make the same corrections to their AI over and over, because the chat forgets and the effort evaporates. This setup is built so a fix I make once keeps working while I'm not there: I don't hand-write agents anymore. A code agent writes them, and the agents improve themselves between edits.

The Setup

Every agent I run is a markdown file. YAML frontmatter for the contract (model, schedule, tool allowlists, approval gate), plain English for the job. The content repo alone holds 46 of these files: SEO rank tracking, newsletter measurement, support drafting, publishing pipelines.

The fleet is not a demo. It's the middle of a real transformation: LifeHack, the company I've run for twenty years, once with a full editorial and marketing team, is becoming an AI-first operation that one person carries. Most of these agents do work that used to be someone's job.

I don't open those files in an editor and type. I open Claude Code, or Codex when I want a different set of instincts on a gnarly one, and describe the agent I need. The code agent writes the file, runs it once, reads the session log, and fixes what broke.

That part is not novel. Everyone uses code agents to write code now. The part worth stealing is how the code agent knows what a good agent file looks like.

The Manual Lives in the Tool

My first instinct was the obvious one: write a long skill for Claude Code explaining AgentUse, the frontmatter fields, the gotchas. A frozen copy of the docs, pasted into the prompt.

That copy starts rotting the day you write it. Field names change. New gotchas surface. The skill says one thing, the installed version does another, and the code agent confidently writes agents for a runtime that no longer exists.

So the skill I actually use is a stub. Its core instruction is one command: agentuse skills get creator. The AgentUse CLI serves its own authoring manual, matched to the installed version. Before Claude Code writes or edits any agent, it pulls the current instructions from the binary that will run the file. When I upgrade the runtime, the manual upgrades with it. Nothing to sync, nothing to rot.

The stub itself installs with one command:

npx skills add agentuse/agentuse

The same file works in Claude Code, Codex, Cursor, and anything else that speaks Agent Skills. That's why switching code agents costs me nothing: the knowledge was never in the assistant. It's in the CLI they all ask.

This matters even if you never ship a framework yourself. When your code agent builds on any tool, don't let it work from its training-data memory of the docs, and don't paste frozen docs into a prompt either. Have it pull the current manual from the installed tool. And when you're choosing what to build on, prefer tools that can serve their own.

What the Code Agent Writes

The manual pushes one discipline hard: hard-code the invariants, delegate the judgment. The agent file is re-read on every step, so every line costs attention. Pin down only what must never drift: the approval gate, the exact commands it may run, the file paths it may touch, the output shape. Leave the rest to the model.

A real file from the fleet, for an agent that drafts posts for my review, pins exactly that: an Opus model with reasoning set high, approval: true, a bash allowlist a few commands long, and a guardrails section that opens "hard - never relax." One guardrail cites its own postmortem inline: a runtime race once let sibling tool calls fire while the approval gate was still pending, so the rule now says the gate must stand alone, with the incident date attached.

A human wrote almost none of that. Claude Code wrote it, then rewrote it after real runs. The incident citation is the point: the file carries its own case law.

The Agents Write Back

Creation is half the loop. The other half runs while I'm not looking.

Each agent has learning: true in its frontmatter, which does two things: capture lessons after a run, and inject stored lessons into the prompt before the next one. Lessons arrive from three sources. The agent's own self-evaluation. My comments at the approval gate, promoted into rules. And rules I save by hand.

Across the content fleet that's 281 entries in 19 learnings files, each tagged with a confidence score and a count of how often it has applied. The stale-warning rule from the opening has applied seven times. Another taught an agent to check whether the store lock it's waiting on belongs to a crashed process fifteen hours dead, instead of queuing behind a ghost. My favorite one is a guardrail an agent earned under revision pressure: it had turned a source author's practice into "the habit I trust now," a fabricated personal claim, and the lesson it kept says sounding more personal is never worth inventing a personal fact.

The runtime resolves conflicts with a strict precedence: agent instructions first, then learned guidelines, then skills, then reference files. Learnings override skill defaults. That ordering is what makes correction stick. I can fix a behavior once, at the gate, in one sentence, and the fix outranks the shared craft files every run after.

Closing the Loop Between the Two

None of this needs me. A lesson captured on Tuesday's run applies itself on Wednesday's, injected automatically before the agent starts. For most lessons, local, situational, cheap, that is the right home and the loop ends there. But when a lesson proves permanent, when it keeps applying run after run, or reveals the agent's structure is wrong, auto-injection stops being the answer.

That's when the two halves meet. I open Claude Code, point it at the agent and its learnings file, and have it merge the permanent lessons into the agent's own instructions, then prune the entries it absorbed. My git log is full of commits like "bake in this run's lessons for a clean next demo." That particular commit exists because a 119KB Amazon page stalled a cheap model mid-run: the agent file now tells its builds to bound large pages, and I learned to validate any network agent with one real run, because health checks and mock runs miss page size, latency, and blocked sources every time. There's even a commit correcting a learning that was itself wrong: the agent had blamed a port conflict for a failure that was actually Chrome auto-updating underneath it. Memory gets edited, not just appended.

So the full loop: a code agent writes the agent from the runtime's own live manual. The agent runs, and writes down what it learns from failures and from my gate comments. Learnings override defaults immediately. And when a lesson proves structural, the code agent folds it into the file and the queue empties. Each pass, the file gets shorter and harder to fool.

I'm building AgentUse, open-source infrastructure for autonomous agents, and the learning capture, the approval gates, and the self-serving manual above are all part of it. But the loop doesn't depend on my stack. It depends on the three pieces existing at all: a live manual, a memory the runtime actually injects, and a scheduled appointment between your code agent and that memory.

This week, take one agent, or one prompt you keep re-fixing, and give it a memory file the next run actually reads. Then put thirty minutes on the calendar to fold what accumulates back into the prompt. The first version of an agent is a guess. The file that's been through this loop a dozen times is the only spec I trust.