compound-learnings

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

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

---

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/.md << 'EOF'

# Rule Name

[Context: why this rule exists, based on N sessions]

[The reusable principle]

• [Concrete action]

• [Anti-pattern]

• [session-id-1]: [what happened]
• [session-id-2]: [what happened]

EOF

```

#### For Skills:

Create .claude/skills//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/.sh << 'EOF'

#!/bin/bash

set -e

cd "$CLAUDE_PROJECT_DIR/.claude/hooks"

cat | node dist/.mjs

EOF

chmod +x $CLAUDE_PROJECT_DIR/.claude/hooks/.sh

```

Then create src/.ts, build with esbuild, and register in settings.json:

```json

{

"hooks": {

"EventName": [{

"hooks": [{

"type": "command",

"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/.sh"

}]

}]

}

}

```

#### For Agent Updates:

Edit existing agent in .claude/agents/.md to add the learned capability.

Step 8: Summary Report

```markdown

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.

```

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 type? Sequences → skills, heuristics → rules

• Learnings: .claude/cache/learnings/*.md
• Skills: .claude/skills//SKILL.md
• Rules: .claude/rules/.md
• Hooks: .claude/hooks/.sh + src/.ts + dist/.mjs
• Agents: .claude/agents/.md
• Skill triggers: .claude/skills/skill-rules.json
• Hook registration: .claude/settings.json → hooks section