Update Claude Learnings

1. Verify the learning is about Claude Code behavior (not application code or skill structure)
2. Verify it applies to the main agent (not subagents or skill creation)
3. Check for duplicates in existing CLAUDE.md sections
4. Get user confirmation before writing

Adding learnings without verification = cluttered CLAUDE.md, conflicting rules

This is not optional. Every learning requires disciplined validation.

Update Claude Learnings

MANDATORY FIRST RESPONSE PROTOCOL

Before adding ANY learning to CLAUDE.md, you MUST complete this checklist:

1. ☐ Identify the specific behavioral pattern from the session
2. ☐ Verify this is about Claude Code behavior (not application code or skills)
3. ☐ Verify it applies to main agent (not subagents)
4. ☐ Categorize: Workflow Rules, Session Management, Scope Control, or Behavioral Patterns
5. ☐ Check CLAUDE.md for existing related rules
6. ☐ Formulate as actionable directive (imperative mood)
7. ☐ Present learning to user for confirmation
8. ☐ Announce: "Adding to CLAUDE.md: [category] - [brief description]"

Adding learnings WITHOUT completing this checklist = noise in project config.

Purpose

This skill captures learnings about Claude Code's own behavior in this project.

What it captures:

• Workflow rules (use skills, command patterns)
• Session management (checkpoints, timeouts, focus)
• Scope control (expansion rules, confirmation patterns)
• Behavioral patterns (project-specific behaviors)

Output: Updates to project's CLAUDE.md file

Does NOT:

• Capture application code patterns (use /update-agent-learnings)
• Capture skill creation patterns (use /update-skill-learnings)
• Apply to subagents (they don't read CLAUDE.md during task execution)

When to Use

• After discovering Claude Code should use a skill instead of manual commands
• After session management issues (lost context, premature endings)
• After scope control problems (over-engineering, tangential work)
• After discovering project-specific behavioral needs
• Invoke via /update-claude-learnings

Never add learnings proactively. Only when session revealed concrete patterns.

Decision Guide: Which Skill to Use?

Is the learning about...

Application code patterns?
├── Applies to subagents writing code
└── Use: /update-agent-learnings

Skill creation/improvement?
├── Structural patterns, quality signals
└── Use: /update-skill-learnings

Claude Code's own behavior?
├── Workflow rules, session management, scope control
└── Use: /update-claude-learnings (this skill)

Step 1: Session Analysis

Gate: Identify at least one concrete behavioral pattern before proceeding to Step 2.

Review the current conversation/session for Claude Code behavioral patterns:

1. Workflow discoveries:

   • Should Claude Code have used a skill instead of manual commands?
   • Are there command patterns that should be standardized?
   • Are there tools that should always/never be used?

2. Session management discoveries:

   • Did context get lost?
   • Did the session end prematurely?
   • Were checkpoints needed but missing?

3. Scope control discoveries:

   • Did Claude Code over-engineer?
   • Was confirmation needed before expanding scope?
   • Did tangential work distract from the main task?

4. Project-specific discoveries:

   • Are there project conventions Claude Code should follow?
   • Are there paths/files that need special handling?
   • Are there commands specific to this project?

Step 2: Learning Extraction

Gate: User confirms extracted learning before proceeding to Step 3.

Present findings to user and ask for confirmation:

I identified the following Claude Code behavioral learning from this session:

**Category:** [Workflow Rules / Session Management / Scope Control / Behavioral Patterns]

**Learning:** [Description in imperative mood]

**Why:** [Brief explanation of what happened]

Should I add this to CLAUDE.md?

Use AskUserQuestion to:

• Confirm the extracted learning is accurate
• Allow user to refine the wording
• Get approval before making changes

Learning Classification

Step 3: Update CLAUDE.md

Gate: CLAUDE.md updated successfully before proceeding to Step 4.

1. Read current CLAUDE.md from project root
2. Locate the appropriate section based on category
3. Add new learning in imperative mood
4. Preserve existing structure and content
5. Update "Last updated" timestamp
6. Write updated file

CLAUDE.md Structure

# Claude Code Project Configuration

---

## Workflow Rules

### Use Available Skills
- [skill usage rules...]

### Session Management
- [checkpoint rules, timeout handling...]

### Scope Control
- [expansion rules, confirmation patterns...]

---

## Project Context

### Repository Purpose
[project description]

### Key Directories
[important paths]

---

## Behavioral Patterns

[project-specific behaviors derived from sessions]

---

*Last updated: [date]*

Step 4: Verification

Gate: All checks pass before marking complete.

Check 1: Learning Added

• New learning appears in correct section
• No duplicate entries created
• Timestamp updated

Check 2: Learning Quality

• Learning is actionable (imperative mood)
• Learning is specific (not vague)
• Learning applies to main Claude Code agent

Check 3: File Integrity

• File structure preserved
• No sections accidentally removed
• Markdown formatting valid

Check 4: Correct Scope

• Learning is NOT about application code (would go to agent-learnings)
• Learning is NOT about skill structure (would go to skill-learnings)
• Learning IS about Claude Code behavior in this project

Pre-Update Checklist

Before updating, verify:

• Learning is about Claude Code behavior
• Learning applies to main agent, not subagents
• Category assignment is correct
• No duplicates exist in CLAUDE.md
• User confirmed the learning

Error Handling

Safety Rules

Quality Checklist (Must Score 8/10)

Score yourself honestly before marking update complete:

Learning Identification (0-2 points)

• 0 points: Vague observation, not actionable
• 1 point: Somewhat specific but could be clearer
• 2 points: Concrete, actionable behavioral rule

Scope Verification (0-2 points)

• 0 points: Wrong scope (should be agent or skill learning)
• 1 point: Correct scope but borderline
• 2 points: Clearly Claude Code behavior, correct scope

User Confirmation (0-2 points)

• 0 points: Added without showing to user
• 1 point: Showed but didn't wait for confirmation
• 2 points: Full confirmation before writing

File Integrity (0-2 points)

• 0 points: Broke file structure
• 1 point: Minor formatting issues
• 2 points: Clean update, structure preserved

Category Placement (0-2 points)

• 0 points: Wrong section
• 1 point: Correct section but awkward placement
• 2 points: Perfect section and placement

Minimum passing score: 8/10

Common Rationalizations (All Wrong)

These are excuses. Don't fall for them:

• "This is obvious behavior" → STILL document it explicitly
• "It's in the other learnings files" → Check scope - CLAUDE.md is for main agent
• "The user knows the workflow" → Future sessions need this documented
• "It's a small thing" → Small rules compound into consistent behavior
• "CLAUDE.md is already long" → Organization matters more than brevity

Failure Modes

Failure Mode 1: Wrong Scope

Symptom: Added "Run tsc --noEmit after edits" to CLAUDE.md Why Wrong: This is for subagents writing TypeScript, not main Claude Code Fix: Use /update-agent-learnings instead

Failure Mode 2: Skill Pattern in CLAUDE.md

Symptom: Added "Include EXTREMELY-IMPORTANT block in skills" Why Wrong: This is about skill structure, not Claude Code behavior Fix: Use /update-skill-learnings instead

Failure Mode 3: Vague Rule

Symptom: Added "Be more careful with commits" Why Wrong: Not actionable - what specific behavior? Fix: Make specific: "Use /commit skill instead of manual git commit"

Failure Mode 4: Duplicate Added

Symptom: Same rule exists in multiple sections Fix: Search CLAUDE.md before adding, merge if similar exists

Quick Workflow Summary

STEP 1: SESSION ANALYSIS
├── Review session for behavioral patterns
├── Identify workflow issues
├── Identify session management issues
├── Identify scope control issues
└── Gate: Concrete pattern identified

STEP 2: LEARNING EXTRACTION
├── Categorize the learning
├── Verify correct scope (not agent/skill learning)
├── Formulate as actionable directive
├── Check for duplicates
├── Present to user
├── Get confirmation
└── Gate: User approved

STEP 3: UPDATE CLAUDE.MD
├── Read current CLAUDE.md
├── Locate correct section
├── Add new learning
├── Update timestamp
├── Write file
└── Gate: File updated

STEP 4: VERIFICATION
├── Verify learning added correctly
├── Verify learning quality
├── Verify file integrity
├── Verify correct scope
└── Gate: All checks pass

Completion Announcement

When update is complete, announce:

CLAUDE.md updated.

**Quality Score: X/10**
- Learning Identification: X/2
- Scope Verification: X/2
- User Confirmation: X/2
- File Integrity: X/2
- Category Placement: X/2

**Learning Added:**
- Category: [category]
- Section: [section path]
- Learning: [brief description]

**File Updated:** CLAUDE.md

**Next steps:**
The learning will be active in future sessions.

Integration with Other Skills

The update-claude-learnings skill completes the learning system:

Complete Learning System:

Session reveals pattern
         │
    ┌────┼────────────────┐
    ▼    ▼                ▼
Subagent  Skill        Claude Code
pattern?  pattern?     behavior?
    │        │             │
    ▼        ▼             ▼
/update-  /update-     /update-
agent-    skill-       claude-
learnings learnings    learnings
    │        │             │
    ▼        ▼             ▼
agent-    skill-       CLAUDE.md
learnings learnings
.md       .md
    │
    ▼
Synced to
agent files

Workflow Chain:

Session reveals behavioral pattern
              │
              ▼
update-claude-learnings skill (this skill)
              │
              ▼
CLAUDE.md updated
              │
              ▼
Future sessions benefit from the rule

Examples

Example 1: Workflow Rule - Use Skills

Session Issue: Used git add && git commit instead of /commit skill.

Learning Extraction:

• Category: Workflow Rules
• Section: Use Available Skills
• Learning: "Use /commit instead of manual git add && git commit"

Result: Added to CLAUDE.md under ## Workflow Rules > ### Use Available Skills

Example 2: Session Management

Session Issue: Complex task completed but no checkpoints provided.

Learning Extraction:

• Category: Session Management
• Section: Session Management
• Learning: "Provide checkpoint summaries every 3-5 edits on complex tasks"

Result: Added to CLAUDE.md under ## Workflow Rules > ### Session Management

Example 3: Project-Specific Behavior

Session Issue: Edited files in .claude/agents/ without running learnings sync.

Learning Extraction:

• Category: Behavioral Patterns
• Section: Behavioral Patterns
• Learning: "After editing agent files, run /update-agent-learnings to sync global learnings"

Result: Added to CLAUDE.md under ## Behavioral Patterns

Example 4: Scope Redirect

Session Issue: User suggests adding "Run tests after code changes"

Analysis: This applies to subagents writing code, not main Claude Code behavior.

Action: Redirect to /update-agent-learnings instead of adding to CLAUDE.md.

Source: ulpi-io/browse — distributed by TomeVault.