Agent Skills: Continuous Learning

Continuous Learning

Contents

• Scope — auto-memory or learned skill?
• When to run
• Pattern types
• Workflow
  • Step 1 — Find candidates
  • Step 2 — Apply the bar
  • Step 3 — Check existing learned skills
  • Step 4 — Confirm and write
  • Step 5 — Report
• Writing a good learned skill
• References (loaded on demand)

Reference files (open one when a step points to it):

• references/examples.md: Example learned skills
• references/pattern-types.md: Pattern types — criteria and body sections
• references/storage-format.md: Storage format

Promote a reusable problem-solving procedure from this session into a standalone skill that Claude Code discovers by itself. Each learned skill lives at ~/.claude/skills/learned-<slug>/SKILL.md; its description appears in every future session's skill listing, so the model loads the body when the trigger shows up again.

Scope — auto-memory or learned skill?

Claude Code's auto-memory (~/.claude/projects/<project>/memory/) already records preferences, corrections, project facts and pointers, one line each, and loads them into later sessions. This skill does not duplicate it.

| The learning... | Goes to | |---|---| | Fits in one memory line — a preference, a fact, a correction ("don't mock the database in integration tests", "this repo uses named exports") | Auto-memory. No skill. | | Is a multi-step procedure with a recognisable trigger — an exact error message, a named tool limitation, a symptom pattern, a named project task | A learned skill (this workflow) |

When a candidate turns out to be a one-liner, say it belongs in memory and move on.

When to run

Only when invoked; nothing triggers this skill automatically.

• The user asks: "save what we learned", "make this a pattern", "remember how we fixed this", "extract learnings from this session", or /continuous-learning.
• Another skill calls it at a natural boundary (implement-phase and tt-implement-phase do at phase completion).
• At the natural end of a long session in which a hard problem was solved, offer it in one line ("Want me to save the Prisma-in-CI fix as a learned skill?") and run it only if the user agrees.

There is no hook for this skill. A Stop hook fires after every response rather than once at session end, and a hook cannot run a skill, so a hook-driven version would fire on every turn or not at all.

Pattern types

Four types qualify. Per-type criteria and body sections → references/pattern-types.md. Complete examples → references/examples.md.

1. Error resolution — a non-obvious fix for a specific error. Trigger: the exact error text.
2. Workaround — a way around a tool, framework or environment limitation. Includes when it becomes unnecessary.
3. Debugging technique — a repeatable investigation sequence for a recognisable problem class.
4. Project procedure — a multi-step task specific to one codebase (release, migration, client regeneration). The description names the project.

User corrections and single-rule conventions are not a type here; they go to auto-memory.

Workflow

Step 1 — Find candidates

Scan the session for:

• Errors that took more than one attempt to fix, and the root cause that was found.
• "Can't do X, so we did Y" moments.
• Investigation sequences that located a non-obvious cause.
• Multi-step project tasks the user had to explain or that were worked out by trial.

Step 2 — Apply the bar

Promote a candidate only if all of these hold:

• It is a procedure (two or more steps), not a single rule.
• The trigger is concrete enough to recognise later — an error string, a tool and version, a symptom, a project and task name.
• The fix was not the first result in the official docs.
• The root cause or limitation is understood, not just the symptom silenced.
• It is likely to come up again, in this project or others.

Never save credentials, tokens, keys, passwords or personal data; use placeholders in any example.

Create or update at most 3 learned skills per run — pick the strongest candidates.

Step 3 — Check existing learned skills

Glob ~/.claude/skills/learned-*/SKILL.md and read each description.

• Same trigger or same root cause as an existing learned skill → update that skill (extend the fix, add an Evidence line, sharpen the description) instead of creating a near-duplicate.
• Related but with a different trigger → a new skill is fine; if the two would load in the same situations, merge them instead.

Cap: 20 learned skills. Every learned skill's description sits in the always-loaded skill listing, so the set has to stay small. If a new skill would take the count past 20, first propose merging two related skills or retiring one (its "Retire when" condition is met, the tool or version is gone, it never applied again), and add the new one only after a slot is free.

Step 4 — Confirm and write

Show the user the planned changes: for each, learned-<slug>, whether it is new / updated / merged / retired, and its description. Write after they confirm — these files load into every future session.

If no one can confirm — you were called by another skill running as a forked or background subagent, so AskUserQuestion is not in your tool list — write nothing. Return the planned changes as PROPOSED LEARNED SKILLS (one line each, as above) so the caller can show them to the user and re-run this skill to write the approved ones.

Each learned skill is a SKILL.md with frontmatter name: learned-<slug> and a trigger-specific description of at most 300 characters, then a short body: trigger, pattern, fix, evidence, dates. Exact layout and frontmatter rules → references/storage-format.md. Retiring a skill means deleting its learned-<slug>/ directory. New or changed skills are available from the next session on.

Step 5 — Report

Report only what happened in this run:

Continuous learning
  Created:  learned-prisma-client-not-generated — PrismaClientInitializationError after a schema change in Docker/CI
  Updated:  learned-jest-esm-json-imports — added evidence line 2026-10-06
  Retired:  none
  Left to auto-memory: "acme-frontend colocates tests next to source files"
  Skipped:  generic TypeScript null-check error — first result in the docs
  Learned skills: 7 / 20

If nothing qualified, say so in one line.

Writing a good learned skill

• Description: start with "Use when", name the trigger concretely (exact error text in quotes, tool and version, project name), then the fix in a few words. Leave out generic words ("debugging", "errors", "best practices") that would make it load for unrelated work.
• Body: fits on one screen; steps a future session can follow without this conversation.
• Evidence: dated, observable facts only — where it happened (repo), what was seen, what confirmed the fix (tests passed, command succeeded). No estimates of time saved or success rates.
• Retire when: the condition that makes the skill obsolete (upstream fix, version bump, migration finished).

When a run touches the set, also check for learned skills whose "Retire when" condition is now met and for pairs with overlapping triggers; include those retirements and merges in the Step 4 proposal.

References (loaded on demand)

• references/pattern-types.md — per-type criteria and body sections
• references/storage-format.md — location, naming, frontmatter rules, body layout, updating, merging, retiring
• references/examples.md — one complete learned skill per type, plus examples that belong in auto-memory instead