/learn

name: learn
description: Update project CLAUDE.md with strategic knowledge discovered during this session — or CLAUDE.local.md when the discovery is per-developer/per-checkout and that file already exists. Defers to any project- or user-defined memory-placement guidance instead of overriding it. Use when user says "learn", "save knowledge", "update claude.md", "capture learnings", or at end of significant work sessions. Also used by commit skill for pre-commit knowledge capture.
allowed-tools: Read, Edit, Glob, AskUserQuestion

Learn

Review the current conversation history and identify strategic, reusable project knowledge that should be captured in the project CLAUDE.md file. When the project has opted into Claude Code's three-tier memory convention by creating `CLAUDE.local.md`, route genuinely personal or environment-specific discoveries there instead.

Analysis Process

1. **Review Session History**

• Examine all files read and modified during this session
• Identify patterns discovered while working on tasks
• Note architectural insights gained from exploring the codebase

2. **Extract Strategic Knowledge**

• Filter out tactical details (bug fixes, specific implementations)
• Focus on reusable patterns and project structure
• Identify conventions and architectural decisions

3. **Categorize Findings**

• Project architecture and structure
• Data flow patterns
• External service integrations
• Project-specific conventions
• Key dependencies and their purposes
• Configuration patterns
• Testing strategies
• Build and deployment processes
• Operational knowledge (debugging, DevOps)

Destinations

This skill writes to one of two files in the project root:

• **`CLAUDE.md`** (project memory, committed, team-shared) — the default destination. Use for architecture, conventions, integration patterns, and any other knowledge useful to the whole team.
• **`CLAUDE.local.md`** (local memory, gitignored personal overrides) — used only when **both** conditions hold:

1. `CLAUDE.local.md` already exists in the project (the project has opted into the three-tier memory convention). 2. The discovery describes per-developer / per-checkout state — not just *mentions* something personal, but the knowledge itself is meaningful only to the current developer on this machine. Examples: a tool-loading workaround that depends on this developer's interpreter / runtime setup, a personal alias, a per-checkout env override.

**Counter-example:** *"We keep credentials in `~/.aws/credentials`"* mentions a user-home path but describes a team-wide convention — the path is illustrative, not per-developer state. Such notes belong in project CLAUDE.md. When in doubt about whether a discovery is genuinely personal, default to project CLAUDE.md.

This skill never writes to the user's global `~/.claude/CLAUDE.md` (user memory) — only reads it to avoid duplicating cross-project knowledge.

**Default for ambiguous cases: project CLAUDE.md.** Leaking personal config into a committed file is a loud error that reviewers catch quickly; hiding project-wide knowledge in a gitignored personal file is a silent error that rots over time.

What Qualifies

**INCLUDE** - Strategic discoveries from this session:

• Architectural patterns uncovered while working
• Project structure insights gained from navigation
• Conventions noticed across multiple files
• Integration patterns discovered
• Configuration approaches identified
• Testing strategies observed
• Build/deployment processes encountered
• Performance optimizations found
• Security implementations discovered
• Operational knowledge:
• Database locations and connection details per environment
• Useful queries discovered during debugging
• Testing procedures and verification steps
• Deployment workflows and commands
• Log locations and monitoring endpoints
• Environment-specific quirks and gotchas

**EXCLUDE** - Session-specific tactical work:

• The specific bug we fixed
• The particular feature we implemented
• Temporary workarounds we used
• One-off code changes
• TODO items we encountered
• Historical context about changes

Decision Criteria

Ask yourself for each discovery:

• "Will this help understand the project in 6 months?"
• "Is this a pattern that appears multiple times?"
• "Does this represent a project-wide convention?"
• "Would knowing this speed up future development?"
• "Would this save debugging time in the future?" (for operational knowledge)

Workflow

1. Check for Existing Memory-Placement Guidance

Before applying the routing rules below, scan the project's root `CLAUDE.md`, any `.claude/rules/*.md` files, the user's global `~/.claude/CLAUDE.md`, and any `~/.claude/rules/*.md` files for documented memory-placement guidance — for example, a placement decision tree, an instruction to use a project-specific triage command, or specific destinations beyond `CLAUDE.md` / `CLAUDE.local.md`. If such guidance exists, defer to it: follow the documented workflow or place each discovery according to its rules instead of using this skill's defaults. The remaining steps apply only when no such guidance is found.

2. Check Existing Memory Content

Read the current content of project `CLAUDE.md`, `CLAUDE.local.md` (if present), and the user's global `~/.claude/CLAUDE.md` to avoid duplication — including cross-project entries already captured in user memory.

3. Early Exit if Nothing Found

If no new strategic knowledge was discovered during this session:

• Report "no new strategic knowledge to capture"
• Do NOT use AskUserQuestion tool
• End the skill execution

4. Classify Each Discovery

For each discovery, determine its destination per the [Destinations](#destinations) rules: default to project CLAUDE.md, and route to `CLAUDE.local.md` only when both file-exists and personal-content criteria are met (and the counter-example caveat doesn't apply).

5. New Knowledge to Add

Pre