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:

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

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 :

{ "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

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