Session Learn

Session Learn

Analyzes past session transcripts and extracts actionable improvements: recurring workflows that should become skills, corrections that should become CLAUDE.md rules, persistent facts for MEMORY.md, and gaps in existing skills.

Phase 1: Gather Data

Run these in parallel:

# List recent sessions
session-recall --list 20

# Cross-session error/correction/retry analysis
session-recall --all 10 --report

# Correction and constraint patterns
session-recall --all 10 "correction|wrong|mistake|don't|never|always|stop"

# Repeated workflow patterns
session-recall --all 10 "deploy|send|check|create|build|update|push"

Also invoke MCP tools if available (they give richer structured output):

• recall_report - error/retry/correction analysis with stats
• recall_decisions - key decisions across sessions
• recall_search with keywords for targeted pattern search

Phase 2: Classify Each Finding

For each finding, assign exactly one category:

| Category | Threshold | Target | |----------|-----------|--------| | Skill candidate | 3+ occurrences across sessions | New ~/.claude/skills//SKILL.md | | CLAUDE.md rule | 2+ occurrences, global constraint or correction | Append to ~/.claude/CLAUDE.md | | MEMORY.md entry | Any count, persistent fact or preference | Append to ~/.claude/projects/-root/memory/MEMORY.md or topic file | | Existing skill update | Any count, gap in current coverage | Edit existing ~/.claude/skills//SKILL.md |

Cross-reference against existing skills before proposing new ones:

ls ~/.claude/skills/

Read the description field of potentially overlapping skills to check for duplication before proposing a new skill.

Phase 3: Present Findings

Format the report as a table per category. Do NOT apply anything yet.

## Session Learning Report

### New Skill Candidates
| Workflow | Sessions seen | Current coverage gap | Proposed skill name |
|----------|--------------|----------------------|---------------------|
| ...      | ...          | ...                  | ...                 |

### New CLAUDE.md Rules
| Pattern observed | Evidence (sessions/count) | Proposed rule text |
|-----------------|--------------------------|-------------------|
| ...             | ...                       | ...               |

### MEMORY.md Updates
| Topic | Current state | Proposed addition |
|-------|--------------|-------------------|
| ...   | ...          | ...               |

### Existing Skill Improvements
| Skill | Gap found | Proposed change |
|-------|-----------|----------------|
| ...   | ...       | ...            |

Always state the evidence count. "Seen in 4 sessions" is valid. "Seen once" is not sufficient for a CLAUDE.md rule (need 2+).

Phase 4: Apply (after explicit approval)

Wait for explicit user approval. Apply only the approved items.

Creating a new skill

mkdir -p ~/.claude/skills/
# Write SKILL.md with YAML frontmatter (name + description) and body

Use imperative form in the body. Description must include trigger phrases. Keep body under 500 lines. Move reference material to references/ files.

Appending to CLAUDE.md

Read the file first, then append at the bottom of the most relevant section. NEVER cut or condense existing content. Only append or reorder.

# Read first, then edit with Edit tool - never overwrite

Updating MEMORY.md

Check if a topic file already exists before adding to MEMORY.md directly. Topic files live at ~/.claude/projects/-root/memory/.md. If MEMORY.md exceeds 200 lines, add to a topic file and reference it.

Sync to moto repo (if applicable)

# Check if the skill directory is tracked by a setup repo
ls ~/moto/ 2>/dev/null || ls ~/claude-setup/ 2>/dev/null || ls ~/.claude-setup/ 2>/dev/null
# If it exists, copy new skill files there and commit

Rules

• Present findings before applying. Never auto-apply.
• Require 3+ occurrences for new skill, 2+ for CLAUDE.md rule.
• Never cut existing CLAUDE.md content.
• Prioritize by severity: safety/correctness errors > workflow inefficiency > convenience.
• Cross-reference against all existing skills before proposing duplicates.
• Keep proposed rule text concise and imperative (mirrors CLAUDE.md style).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: floomhq
• Source: floomhq/moto
• License: MIT
• Homepage: https://github.com/floomhq/moto#readme

Install and usage instructions live in the source repository linked above.