/compound-learnings

name: compound-learnings
description: Transform session learnings into permanent capabilities (skills, rules, agents). Use when asked to "improve setup", "learn from sessions", "compound learnings", or "what patterns should become skills".
allowed-tools: [Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion]

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

1. **Is it general enough?** Would it apply in other projects? 2. **Is it specific enough?** Does it give concrete guidance? 3. **Does it already exist?** Check `.claude/rules/` and `.claude/skills/` first 4. **Is it the right ty