compound-learnings

SKILL.md

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:

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

---

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