Wiring Feedback Loops Into Agent Skills

Skills Are Static. Until They’re Not.

AI coding agents — Claude Code, Codex, and others — use “skills” to learn new workflows. A skill is typically a markdown file with instructions plus helper scripts that teach the agent how to do something specific: review PRs, generate docs, scaffold components.

The problem: skills are written once by the author. They don’t learn from actual usage.

When the agent makes a mistake — wrong severity on a comment, a false positive, a tone that doesn’t match the team — the same mistake repeats in the next session. The skill has no memory. Every session starts from zero.

The fix is simpler than you’d expect. Not fine-tuning. Not a vector database. Just files, structured carefully, with rules for how they evolve.

The Living Document Architecture

A self-evolving skill has three layers:

SKILL.md                  ← permanent guidance (the "constitution")
references/               ← operational guides (the "playbooks")
references/memory.md      ← memory file (the "learning")

SKILL.md is the stable foundation. It defines the workflow, script routing table, rules, and compatibility contracts. It changes rarely — only when a pattern has proven itself broadly reliable.

References are operational guides loaded on demand. The skill tells the agent when to load each one. These change more often as the team discovers better practices.

The memory file is where self-evolution happens. It’s a structured notebook of lessons learned from real sessions, organized into three zones:

• Candidate Patterns — newly captured lessons. Not yet proven.
• Current Patterns — proven patterns loaded at the start of every session.
• Archived Patterns — superseded entries with notes on where they were codified.

Wiring the Loop with Agent Hooks

The memory file is passive — just markdown on disk. What makes it alive are agent hooks: framework-level lifecycle events that trigger memory operations programmatically.

Most agent frameworks expose hooks for session start, tool execution, and session end. Use them:

• Session start hook — load Current Patterns into context automatically
• Tool result hook — capture corrections without agent intervention
• Session end hook — run cleanup when thresholds are hit

Without hooks, the loop relies on the agent following markdown instructions:

“Load the memory file at the start of every session.”

The agent might. It might also forget, or skip it when context is tight.

With hooks, the loop is deterministic — memory operations run every time, triggered by the framework, not by the agent’s interpretation of instructions.

The skill instructions still exist for human readers and as fallback. But the actual loop runs through hooks.

The Memory Loop

With hooks in place, the memory lifecycle runs automatically: capture → graduate → codify → archive.

Capture

When the agent makes a mistake and the user corrects it, record the correction. This typically happens at the end of an agent turn, during session wrapup, or via hooks that detect corrections automatically.

Each entry follows a structured format:

### 2026-05-26 | False positive on error handling
- Context: Agent suggested "add error handling" on a line that already had try/catch
- Lesson: Verify error handling doesn't already exist before suggesting it
- Next pass: Check surrounding lines for existing handling before commenting
- State: CANDIDATE
- Tags: false-positive, error-handling

The structured fields make the entries machine-parseable while staying human-readable.

Graduate

If the same lesson recurs — same type of mistake, same correction — it moves from Candidate Patterns to Current Patterns. The rule: two occurrences minimum. One-off corrections stay as candidates. Recurring ones get promoted.

Current Patterns are loaded at the start of every session. This is how the skill “remembers.”

Codify

When a pattern proves broadly reliable across many sessions, it gets folded into the permanent guidance — either SKILL.md or one of the reference guides. The pattern is no longer a “lesson learned” — it’s now part of the standard operating procedure.

Archive

When a pattern becomes stale, too narrow, or has been codified elsewhere, it moves to Archived Patterns with a note explaining why:

### 2026-04-15 | Check for existing error handling
- State: ARCHIVED
- Archive note: Codified in commenting-guide.md under "Verify before suggesting"

Cleanup Triggers

Memory files grow. Without maintenance, the Candidate section fills with stale entries that never graduate and never get archived.

Two triggers activate a cleanup pass:

1. 5 or more candidate entries — the backlog is growing
2. Oldest candidate entry is older than 14 days — stale entries aren’t graduating

During cleanup: merge duplicates, promote repeated lessons, codify reliable patterns, archive stale ones. A helper script can flag when cleanup is needed — the agent (or human) does the actual work.

The Compatibility Contract

The feedback loop is fragile. Future edits can break it — removing the load instruction, renaming sections, or changing field names.

The fix: include explicit rules in the skill:

• Do not remove the instruction to load the pattern file unless replacing the memory mechanism.
• Do not rename sections or fields without updating dependent logic.
• Migrate existing entries in the same update rather than resetting the file.

Why This Generalizes

The PR review skill is one application. The pattern works for any skill that involves human judgment and iterative refinement:

Code generation skills — capture when the user always renames variables, restructures generated functions, or removes boilerplate. Graduate naming preferences, structural patterns, and style rules.

Documentation skills — capture when the user reorders sections, changes formatting, or removes verbose explanations. Graduate formatting preferences and verbosity rules.

Testing skills — capture when the user rejects over-mocked tests, prefers integration-style tests, or removes redundant assertions. Graduate testing philosophy.

The pattern is always the same: hook into the agent’s lifecycle, capture corrections as structured entries, graduate proven ones, codify into permanent guidance, archive the rest.

The Key Insight

Self-evolution doesn’t require fine-tuning. It doesn’t require a vector database. It doesn’t require external infrastructure.

It requires three things:

1. Agent hooks that wire memory operations into framework lifecycle events
2. Graduation rules that promote proven lessons and prevent noise
3. A compatibility contract that protects the feedback loop from future breakage

The skill carries forward lessons in repo files. It’s version-controlled, human-readable, and machine-parseable. Every change is a commit. Every evolution is visible.

I used this pattern in the adaptive-pr-review skill — a PR review agent that improves from actual review sessions. The memory loop has been running for weeks, and the difference between the first review and the latest is visible in the pattern file’s commit history.