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

bash

# 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:

markdown

| 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:

markdown

---

## 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:

bash

# Write to rules directory
cat > $CLAUDE_PROJECT_DIR/.claude/rules/<name>.md << 'EOF'
# 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/<name>/SKILL.md

with:

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:

bash

# Shell wrapper
cat > $CLAUDE_PROJECT_DIR/.claude/hooks/<name>.sh << 'EOF'
#!/bin/bash
set -e
cd "$CLAUDE_PROJECT_DIR/.claude/hooks"
cat | node dist/<name>.mjs
EOF
chmod +x $CLAUDE_PROJECT_DIR/.claude/hooks/<name>.sh

Then create

src/<name>.ts

, build with esbuild, and register in

settings.json

json

{
  "hooks": {
    "EventName": [{
      "hooks": [{
        "type": "command",
        "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/<name>.sh"
      }]
    }]
  }
}

For Agent Updates:

Edit existing agent in

.claude/agents/<name>.md

to add the learned capability.

Step 8: Summary Report

markdown

## 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/<name>/SKILL.md
```
Rules:
```
.claude/rules/<name>.md
```

Hooks:

.claude/hooks/<name>.sh

src/<name>.ts

dist/<name>.mjs

Agents:
```
.claude/agents/<name>.md
```
Skill triggers:
```
.claude/skills/skill-rules.json
```
Hook registration:
```
.claude/settings.json
```
→
```
hooks
```
section

compound-learnings

NPX Install

Tags

SKILL.md Content

Compound Learnings

When to Use

Process

Step 1: Gather Learnings

Step 2: Extract Patterns (Structured)

Step 2b: Consolidate Similar Patterns

Step 3: Detect Meta-Patterns

Step 4: Categorize (Decision Tree)

Step 5: Apply Signal Thresholds

Step 6: Propose Artifacts

Step 7: Create Approved Artifacts

For Rules:

For Skills:

For Hooks:

For Agent Updates:

Step 8: Summary Report

Quality Checks

Files Reference