update-claude-learnings
Skill15 starsChanged 8 months agoApache-2.0View on GitHub
Extract learnings about Claude Code behavior from a session and add them to the project's CLAUDE.md file. Use for behavioral rules, workflow patterns, and project-specific instructions that apply to the main Claude Code agent. Invoke via /update-claude-learnings after sessions revealing behavioral patterns.
In this repository63 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- agent-browserSkill
- ast-grepSkill
- branch-review-before-prSkill
- browse-qaSkill
- browser-useSkill
- browseSkill
- bugfixSkill
- build-dmgSkill
- claude-reviewSkill
- codemapSkill
- code-simplifySkill
- codex-reviewSkill
- commitSkill
- cost-estimateSkill
- create-prSkill
- find-agentsSkill
- find-bugsSkill
- frontend-design-ui-uxSkill
- git-merge-expertSkill
- git-merge-expert-worktreeSkill
- kiro-reviewSkill
- laravel-filamentSkill
- laravelSkill
- lokeiSkill
- map-project-monorepoSkill
- map-projectSkill
- nextjsSkill
- plan-founder-reviewSkill
- plan-to-task-list-with-dagSkill
- pr-retroSkill
- run-parallel-agents-feature-buildSkill
- run-parallel-agents-feature-debugSkill
- rustSkill
- secretsSkill
- startSkill
- update-agent-learningsSkill
- update-claude-settingsSkill
- update-skill-learningsSkill
- ast-grepSkill
- branch-review-before-prSkill
- codemapSkill
- code-simplifySkill
- commitSkill
- cost-estimateSkill
- create-prSkill
- find-bugsSkill
- frontend-design-ui-uxSkill
- git-merge-expertSkill
- git-merge-expert-worktreeSkill
- map-project-monorepoSkill
- map-projectSkill
- plan-founder-reviewSkill
- plan-to-task-list-with-dagSkill
- pr-retroSkill
- run-parallel-agents-feature-buildSkill
- run-parallel-agents-feature-debugSkill
- startSkill
- update-agent-learningsSkill
- The first 60 shown.
The file
Show its rules and text
We split this skill into the rules it gives an agent
18 rules. About 0 are common, 17 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈17
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Before adding ANY learning to CLAUDE.md, you ABSOLUTELY MUST:
- Distinctive: line 10
Verify the learning is about Claude Code behavior (not application code or skill structure)
- Distinctive: line 11
Verify it applies to the main agent (not subagents or skill creation)
- Distinctive: line 12
Check for duplicates in existing CLAUDE.md sections
- Distinctive: line 24
Before adding ANY learning to CLAUDE.md, you MUST complete this checklist:
- Distinctive: line 56
After discovering Claude Code should use a skill instead of manual commands
- Distinctive: line 57
After session management issues (lost context, premature endings)
- Distinctive: line 58
After scope control problems (over-engineering, tangential work)
- Distinctive: line 59
After discovering project-specific behavioral needs
- Distinctive: line 62
Never add learnings proactively: Only when session revealed concrete patterns.
- Distinctive: line 96
Should Claude Code have used a skill instead of manual commands?
- Distinctive: line 151
Read current CLAUDE.md from project root
- Distinctive: line 153
Add new learning in imperative mood
- Distinctive: line 155
Update "Last updated" timestamp
- Very specific: line 309
Fix: Use /update-agent-learnings instead
- Distinctive: line 320
Why Wrong: Not actionable - what specific behavior?
- Distinctive: line 326
Fix: Search CLAUDE.md before adding, merge if similar exists
- Distinctive: line 369
When update is complete, announce:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<EXTREMELY-IMPORTANT>
Before adding ANY learning to CLAUDE.md, you **ABSOLUTELY MUST**:- Verify the learning is about Claude Code behavior (not application code or skill structure)
- Verify it applies to the main agent (not subagents or skill creation)
- Check for duplicates in existing CLAUDE.md sections
- Get user confirmation before writing
Adding learnings without verification = cluttered CLAUDE.md, conflicting rules
This is not optional. Every learning requires disciplined validation.
</EXTREMELY-IMPORTANT>
Update Claude Learnings
MANDATORY FIRST RESPONSE PROTOCOL
Before adding ANY learning to CLAUDE.md, you MUST complete this checklist:
- ☐ Identify the specific behavioral pattern from the session
- ☐ Verify this is about Claude Code behavior (not application code or skills)
- ☐ Verify it applies to main agent (not subagents)
- ☐ Categorize: Workflow Rules, Session Management, Scope Control, or Behavioral Patterns
- ☐ Check CLAUDE.md for existing related rules
- ☐ Formulate as actionable directive (imperative mood)
- ☐ Present learning to user for confirmation
- ☐ 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)| Learning Type | Example | Correct Skill |
| Testing patterns | "Run tsc --noEmit after TypeScript edits" | update-agent-learnings |
| Skill structure | "Include EXTREMELY-IMPORTANT block" | update-skill-learnings |
| Workflow behavior | "Use /commit instead of git commit" | update-claude-learnings |
| Session behavior | "Checkpoint every 3-5 edits" | update-claude-learnings |
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:
- 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?
- Session management discoveries:
- Did context get lost?
- Did the session end prematurely?
- Were checkpoints needed but missing?
- Scope control discoveries:
- Did Claude Code over-engineer?
- Was confirmation needed before expanding scope?
- Did tangential work distract from the main task?
- 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
| Category | What It Covers | Section in CLAUDE.md |
| Workflow Rules | Skill usage, command patterns, tool preferences | ## Workflow Rules |
| Session Management | Checkpoints, timeouts, progress tracking | ## Workflow Rules > ### Session Management |
| Scope Control | Expansion rules, confirmation patterns | ## Workflow Rules > ### Scope Control |
| Behavioral Patterns | Project-specific behaviors, conventions | ## Behavioral Patterns |
Step 3: Update CLAUDE.md
Gate: CLAUDE.md updated successfully before proceeding to Step 4.
- Read current
CLAUDE.mdfrom project root - Locate the appropriate section based on category
- Add new learning in imperative mood
- Preserve existing structure and content
- Update "Last updated" timestamp
- 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
| Situation | Action |
| Learning is about application code | Redirect to /update-agent-learnings |
| Learning is about skill structure | Redirect to /update-skill-learnings |
| CLAUDE.md doesn't exist | Create with standard structure |
| Category unclear | Ask user to clarify |
| Duplicate exists | Merge or skip, inform user |
| File structure broken | Fix structure before adding |
Safety Rules
| Rule | Reason |
| Always get user confirmation | Ensures learnings are accurate and desired |
| Never delete existing content | Preserve project configuration |
| Keep learnings actionable | Vague rules don't help |
| Use imperative mood | Clearer directives |
| Preserve file structure | Maintains organization |
| Verify scope before adding | Wrong file = wrong audience |
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 passCompletion 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:
| Skill | Target | Audience |
update-agent-learnings | agent-learnings.md → agent files | Subagents writing code |
update-skill-learnings | skill-learnings.md | Skill creators |
update-claude-learnings | CLAUDE.md | Main Claude Code agent |
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 filesWorkflow Chain:
Session reveals behavioral pattern
│
▼
update-claude-learnings skill (this skill)
│
▼
CLAUDE.md updated
│
▼
Future sessions benefit from the ruleExamples
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
/commitinstead of manualgit 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-learningsto 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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

