Compound Learnings
Transform ephemeral session learnings into permanent, compounding capabilities.
When to Use "What should I learn from recent sessions?" "Improve my setup based on recent work" "Turn learnings into skills/rules" "What patterns should become permanent?" "Compound my learnings" Process Step 1: Gather Learnings
List learnings (most recent first)
ls -t $CLAUDE_PROJECT_DIR/.claude/cache/learnings/*.md | head -20
Count total
ls $CLAUDE_PROJECT_DIR/.claude/cache/learnings/*.md | wc -l
Read the most recent 5-10 files (or specify a date range).
Step 2: Extract Patterns (Structured)
For each learnings file, extract entries from these specific sections:
Section Header What to Extract
Patterns or Reusable techniques Direct candidates for rules
Takeaway: or Actionable takeaway: Decision heuristics
What Worked Success patterns
What Failed Anti-patterns (invert to rules)
Key Decisions Design principles
Build a frequency table as you go:
| Pattern | Sessions | Category |
|---------|----------|----------|
| "Check artifacts before editing" | abc, def, ghi | debugging |
| "Pass IDs explicitly" | abc, def, ghi, jkl | reliability |
Step 2b: Consolidate Similar Patterns
Before counting, merge patterns that express the same principle:
Example consolidation:
"Artifact-first debugging" "Verify hook output by inspecting files" "Filesystem-first debugging" → All express: "Observe outputs before editing code"
Use the most general formulation. Update the frequency table.
Step 3: Detect Meta-Patterns
Critical step: Look at what the learnings cluster around.
If >50% of patterns relate to one topic (e.g., "hooks", "tracing", "async"): → That topic may need a dedicated skill rather than multiple rules → One skill compounds better than five rules
Ask yourself: "Is there a skill that would make all these rules unnecessary?"
Step 4: Categorize (Decision Tree)
For each pattern, determine artifact type:
Is it a sequence of commands/steps? → YES → SKILL (executable > declarative) → NO ↓
Should it run automatically on an event (SessionEnd, PostToolUse, etc.)? → YES → HOOK (automatic > manual) → NO ↓
Is it "when X, do Y" or "never do X"? → YES → RULE → NO ↓
Does it enhance an existing agent workflow? → YES → AGENT UPDATE → NO → Skip (not worth capturing)
Artifact Type Examples:
Pattern Type Why "Run linting before commit" Hook (PreToolUse) Automatic gate "Extract learnings on session end" Hook (SessionEnd) Automatic trigger "Debug hooks step by step" Skill Manual sequence "Always pass IDs explicitly" Rule Heuristic Step 5: Apply Signal Thresholds Occurrences Action 1 Note but skip (unless critical failure) 2 Consider - present to user 3+ Strong signal - recommend creation 4+ Definitely create Step 6: Propose Artifacts
Present each proposal in this format:
Pattern: [Generalized Name]
Signal: [N] sessions ([list session IDs])
Category: [debugging / reliability / workflow / etc.]
Artifact Type: Rule / Skill / Agent Update
Rationale: [Why this artifact type, why worth creating]
Draft Content: ```markdown [Actual content that would be written to file] ```
File: .claude/rules/[name].md or .claude/skills/[name]/SKILL.md
Use AskUserQuestion to get approval for each artifact (or batch approval).
Step 7: Create Approved Artifacts For Rules:
Write to rules directory
cat > $CLAUDE_PROJECT_DIR/.claude/rules/
Rule Name
[Context: why this rule exists, based on N sessions]
Pattern
[The reusable principle]
DO
- [Concrete action]
DON'T
- [Anti-pattern]
Source Sessions
- [session-id-1]: [what happened]
- [session-id-2]: [what happened] EOF
For Skills:
Create .claude/skills/
Frontmatter (name, description, allowed-tools) When to Use Step-by-step instructions (executable) Examples from the learnings
Add triggers to skill-rules.json if appropriate.
For Hooks:
Create shell wrapper + TypeScript handler:
Shell wrapper
cat > $CLAUDE_PROJECT_DIR/.claude/hooks/
!/bin/bash
set -e
cd "$CLAUDE_PROJECT_DIR/.claude/hooks"
cat | node dist/
Then create src/
{
"hooks": {
"EventName": [{
"hooks": [{
"type": "command",
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/
For Agent Updates:
Edit existing agent in .claude/agents/
Step 8: Summary Report
Compounding Complete
Learnings Analyzed: [N] sessions Patterns Found: [M] Artifacts Created: [K]
Created:
- Rule:
explicit-identity.md- Pass IDs explicitly across boundaries - Skill:
debug-hooks- Hook debugging workflow
Skipped (insufficient signal):
- "Pattern X" (1 occurrence)
Your setup is now permanently improved.
Quality Checks
Before creating any artifact:
Is it general enough? Would it apply in other projects?
Is it specific enough? Does it give concrete guidance?
Does it already exist? Check .claude/rules/ and .claude/skills/ first
Is it the right type? Sequences → skills, heuristics → rules
Files Reference
Learnings: .claude/cache/learnings/*.md
Skills: .claude/skills/