Claude Code starts every session fresh, so a correction you made on Monday can be needed again on Friday. This repo
gives it a simple learning loop. When you correct it, it writes the lesson down as one short line in the right file, and
the next session reads that file when the task calls for it. Once a week a tidy-up pass keeps the files small. It is
built only from parts Claude Code already has: skills, hooks, memory and scheduled tasks.
Install: one command Undo: one command
Explainer page: kat-titter.github.io/claude-code-learns
For agents: AGENTS.md
What it looks like
A correction becomes a habit.
You: no, the legend covers the data. legends go outside the plot.
Claude: Moved the legend below the chart. Skill updated: figure-design, legend outside the plot.
Two weeks later, in a new session, you ask for a different chart. The legend is outside the plot, and nobody had to say
so. The lesson went in as one line: what to do, an example, the date.
Taste goes to your own file, not everyone's.
You: please no dots between words in the footer, I find them fussy.
That's a preference, not a rule of good design, so it goes to your personal style skill (yourname-style). Your general
skills stay usable by anyone, and your taste lives in one place.
A project fact goes to that project's memory.
You: the staging server is on port 8080, not 3000.
That's true for one project only, so it becomes a memory note for that project and never clutters a skill.
It catches what slipped by.
You mention "why is this taking so long?" halfway through a busy task, and Claude, busy, says nothing about it. After
the reply, a hook jots the line into a notebook (lessons-inbox.md). On its own it stays there. If it comes up again
next week, the weekly pass suggests a lesson for it.
It points at the right skill.
You: two of the references in this report look made up, and the numbering has drifted
Skills often go unused even when they fit: in one person's real sessions, a skill that clearly matched the request
loaded on its own only about 1 time in 5. So a hook notices that the request shares rare words (references, numbering,
drifted) with one skill's description, here the example skill citations, and adds
a single line naming it. Claude loads it before starting, so every source is checked and every marker matched to its
entry.
Monday morning, a short report.
The weekly pass leaves a page like this, and changes nothing until you say yes. It also reads new posts on X (links
you pasted into Claude Code that week, and accounts listed in ~/.claude/practice-accounts.txt) and proposes a
practice only when a measurement on your own sessions shows you don't follow it yet:
Stalled 1 of last week's 4 proposals landed; the other 3 get one more week, then drop
Upstream 1 new skill (pdf-forms): overlaps nothing you have
Practice a post you pasted: "gate on the exit code"; 0 of 103 workflows do, so proposed
Gaps 2 notes in the inbox that no skill covers, e.g. "the numbers don't match the sources"
Misses github-practice loaded for 3 of 9 requests that matched it: add "pages, publish" to its description?
Health one skill is 540 lines: split by task
Proposed at most five changes, grouped by what a mistake would cost to undo
Five words you'll need
| word | in plain terms |
|---|
| Claude Code | an AI assistant that works in your terminal or desktop app, reading and editing files with you |
| skill | a short how-to file. Each session sees only its one-paragraph description, like a label on a shelf; the full text is read only when a task matches |
| hook | a tiny script Claude Code runs at a set moment, such as when you send a message or after each reply. Here hooks only add a line of context or write a log; they never block you |
.md (Markdown) | a plain-text file with light formatting (# for a heading, - for a list). Every skill, memory note and CLAUDE.md is one, so the memory itself is files you can open, read and edit |
memory and CLAUDE.md | notes Claude Code keeps about you and each project (a short index is read every session), and a short file of standing instructions read at the start of every session |
How it works
You appear twice: once with a correction, once with a yes. Every arrow names what it carries; the colours are the
same in every figure here and on the explainer page. A text version of this map is in AGENTS.md.
- Notice. Hooks spot feedback ("no", "from now on", "too much text") and add a one-line reminder to route it.
- Generalize. Claude asks what family of problems the correction belongs to, and writes for the whole family.
- Route. How anyone should do the work goes to a general skill; your taste to your style skill; a fact about one
project to that project's memory.
- Write the gist. One line: what to do, an example, the date. A second case folds into the same line.
- Check it loads. A lesson that never loads might as well not exist, so the setup tests that skills load when
they should, both in tests and in real sessions.
- Tidy weekly. A scheduled pass reads the notebook, the miss report and the library's health, and proposes at
most five changes.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
