agentleFS
ulpi-ioulpi-io/browse/.agents/skills/update-claude-learnings/SKILL.md

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.

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
  1. Distinctive:

    Before adding ANY learning to CLAUDE.md, you ABSOLUTELY MUST:

    line 8
  2. Distinctive:

    Verify the learning is about Claude Code behavior (not application code or skill structure)

    line 10
  3. Distinctive:

    Verify it applies to the main agent (not subagents or skill creation)

    line 11
  4. Distinctive:

    Check for duplicates in existing CLAUDE.md sections

    line 12
  5. Distinctive:

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

    line 24
  6. Distinctive:

    After discovering Claude Code should use a skill instead of manual commands

    line 56
  7. Distinctive:

    After session management issues (lost context, premature endings)

    line 57
  8. Distinctive:

    After scope control problems (over-engineering, tangential work)

    line 58
  9. Distinctive:

    After discovering project-specific behavioral needs

    line 59
  10. Distinctive:

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

    line 62
  11. Distinctive:

    Should Claude Code have used a skill instead of manual commands?

    line 96
  12. Distinctive:

    Read current CLAUDE.md from project root

    line 151
  13. Distinctive:

    Add new learning in imperative mood

    line 153
  14. Distinctive:

    Update "Last updated" timestamp

    line 155
  15. Very specific:

    Fix: Use /update-agent-learnings instead

    line 309
  16. Distinctive:

    Why Wrong: Not actionable - what specific behavior?

    line 320
  17. Distinctive:

    Fix: Search CLAUDE.md before adding, merge if similar exists

    line 326
  18. Distinctive:

    When update is complete, announce:

    line 369

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<EXTREMELY-IMPORTANT> Before adding ANY learning to CLAUDE.md, you **ABSOLUTELY MUST**:
  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. </EXTREMELY-IMPORTANT>

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)
Learning TypeExampleCorrect 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:

  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

CategoryWhat It CoversSection in CLAUDE.md
Workflow RulesSkill usage, command patterns, tool preferences## Workflow Rules
Session ManagementCheckpoints, timeouts, progress tracking## Workflow Rules > ### Session Management
Scope ControlExpansion rules, confirmation patterns## Workflow Rules > ### Scope Control
Behavioral PatternsProject-specific behaviors, conventions## Behavioral Patterns

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

SituationAction
Learning is about application codeRedirect to /update-agent-learnings
Learning is about skill structureRedirect to /update-skill-learnings
CLAUDE.md doesn't existCreate with standard structure
Category unclearAsk user to clarify
Duplicate existsMerge or skip, inform user
File structure brokenFix structure before adding

Safety Rules

RuleReason
Always get user confirmationEnsures learnings are accurate and desired
Never delete existing contentPreserve project configuration
Keep learnings actionableVague rules don't help
Use imperative moodClearer directives
Preserve file structureMaintains organization
Verify scope before addingWrong 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 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:

SkillTargetAudience
update-agent-learningsagent-learnings.md → agent filesSubagents writing code
update-skill-learningsskill-learnings.mdSkill creators
update-claude-learningsCLAUDE.mdMain 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 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.