Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.automagik.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
/learn — Behavioral Correction

When a user corrects a mistake, /learn diagnoses which behavioral surface caused it and applies a minimal, targeted fix. This is an interactive skill — the user invokes /learn directly, and the agent runs in the foreground, conversing with the user throughout.

​
When to Use

  • User corrects agent behavior (“no, don’t do that”, “you should always…”, “stop doing X”)
  • Agent made a mistake that should never recur
  • A pattern of repeated errors suggests a missing behavioral rule

​
Flow

1

Analyze the mistake

What went wrong? Read the conversation context, recent changes, and relevant code to understand the error.
2

Determine root cause

Why did the agent behave this way? Missing rule? Stale convention? Wrong default?
3

Diagnose the surface

Which behavioral surface needs to change? See the Writable Surfaces table below.
4

Propose minimal fix

Enter native plan mode. Show exactly which file will change, what content will be added/modified, and why. One change per learning — never batch.
5

Apply with approval

User must approve before any write. Apply the change and confirm what was learned.
6

Save to memory

Write the learning as a feedback memory in .claude/memory/ so Claude native memory retains it across sessions.

​
Writable Surfaces

The learn skill diagnoses which surface needs the fix:
SurfacePathWhat It Controls
Project conventionsCLAUDE.mdCommands, gotchas, project rules, coding style
Agent identityAGENTS.mdAgent role, preferences, team behavior
Agent personalitySOUL.md / IDENTITY.mdTone, communication style
Global rules~/.claude/rules/*.mdCross-project behavioral rules
Claude native memory.claude/memory/Feedback, user prefs, project context
Project memorymemory/Project-scoped knowledge files
Hooks.claude/settings.jsonEvent-driven automation, permission gates
Any config filevariesAny file that shapes agent behavior

​
Never-Touch Surfaces

These files are maintained by framework developers and must never be modified by /learn:
  • plugins/genie/skills/ — framework skills
  • plugins/genie/agents/ — framework agents
  • Other projects’ files — scope is the current project only
  • Source code — /learn updates behavior configuration, not implementation

​
Claude Native Memory Connection

When a learning is applied, it is also saved as a feedback memory for cross-session persistence: 
# .claude/memory/feedback_example.md
---
name: use-uv-not-pip
description: System uses uv for Python package management, pip is not installed
type: feedback
---

Use uv instead of pip for all Python operations.
**Why:** pip is not installed on this system; uv is the only package manager.
**How to apply:** Any time a Python package needs installing, use uv tool install or uv pip install.
The .claude/memory/MEMORY.md index is updated with a pointer to the new file.

​
Example

User corrects the agent: “Stop using pip install — this system only has uv.” The agent runs /learn:
  1. Analyze: Agent used pip install python-dotenv which failed because pip isn’t installed.
  2. Root cause: No rule in ~/.claude/rules/ about Python tooling.
  3. Surface: Global rules (~/.claude/rules/python-tooling.md) — applies to all projects.
  4. Propose fix (plan mode): Create ~/.claude/rules/python-tooling.md with rules for using uv.
  5. User approves. File written.
  6. Save to memory: Write feedback memory to .claude/memory/feedback_python_tooling.md.

​
Rules

  • Plan mode is mandatory — never write without user approval via native plan mode
  • One learning at a time — diagnose one surface, propose one fix
  • Never assume — verify with the user before recording any learning
  • Never modify framework files — plugins/genie/skills/ and plugins/genie/agents/ are off limits
  • Never write source code — behavioral configuration only
  • Minimal changes — add the smallest rule that prevents the mistake from recurring
  • Always save to memory — every learning gets a feedback memory for cross-session persistence