How to use the Learn agent skill: save session lessons

What the learn skill makes the agent do

When you type /learn or ask the agent to save, remember, or distill lessons, the skill tells it to review the conversation so far and pick out class-level, reusable lessons. These include corrected approaches, non-trivial techniques, and durable user preferences.

The skill deliberately skips one-off narratives and environment-specific failures, since those are not reusable. Before proposing anything, the agent checks the injected skill index. If an existing skill already covers the topic, it prefers a patch or update over creating a near-duplicate.

Changes are never written directly to files. Each lesson is submitted through the stage_skill tool with a reason and a verbatim evidence quote from the session. A deterministic promoter validates the proposal and lands it. Rejections are reported at the next session start.

Install the learn skill from the ZIP

Download the ZIP for the learn skill from this page. The package contains a single file, SKILL.md. Unzip it so the skill folder sits in one of the locations below.

For a personal skill, place it in ~/.claude/skills/. For a project-specific skill, place it in the project's .claude/skills/ folder. If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.

• Personal: ~/.claude/skills/learn/
• Project: .claude/skills/learn/ inside your project
• Claude apps: Settings → Capabilities → Skills → upload

Check the requirements before you rely on it

The skill itself assumes a skill library that provides a stage_skill tool and a deterministic promoter. The SKILL.md file does not describe that infrastructure, so the skill will not produce useful results on its own. Without that backend, there is nothing to receive the proposals.

The skill runs no scripts and makes no network calls, according to its listing.

Trigger the skill with natural requests

You can invoke the skill with /learn or with plain requests that match its description, such as asking the agent to remember something, save a lesson, or distill what it learned. Be specific about what should be kept so the agent does not have to guess.

Examples of requests that fit the skill include corrections you gave during the session, a preferred way of doing something you want kept for future sessions, or a technique that took effort to find.

• /learn
• Remember that I want commit messages in the imperative mood.
• Save the lesson from this session about how we fixed the build cache.
• Distill what we learned about the review process into the skill library.

Review proposals and handle rejections

Because proposals go through a promoter, the agent does not confirm each change in the moment. If the promoter rejects a proposal, the rejection is reported at the start of your next session.

The skill also tells the agent to search managed skill trees for statements that contradict a new lesson and stage updates so the new version wins. This rewrites statements across those trees, so review the results carefully on any shared library.

• Check the next session's start message for rejected proposals.
• Re-read updated skills after a /learn run that superseded an older rule.

Know when not to use it

The skill is not a good fit for one-off tasks or for failures caused by a specific environment, because the skill itself tells the agent to skip those. It is also a poor match for shared or production skill libraries where automatic edits should be reviewed by a person first, since it can rewrite statements across managed skill trees.