Skip to content
Skills Library
AI & agents · Automation

compound-learnings

/compound-learnings

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

Licence
MIT
Last repository change
08.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 08.08.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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

Triggers from the description

improve setuplearn from sessionscompound learningswhat patterns should become skills
Original author 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".

How it works

  1. When to Use
  2. Process
  3. Quality Checks
  4. Files Reference
Original SKILL.md headings · 243 lines, 869 words
SKILL.md preview
---
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

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

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

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

Versions

The database has no other skills named compound-learnings.

Identical content appears in 3 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version c19f0af7528f (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100review-learnings
    Extract reusable learnings from completed octomux agent sessions and append to .claude/rules/learnings.md. Use when reviewing what agents learned, or to manually add a learning.
  • 81reconcile
    Use this skill when the user wants to reconcile learnings into rules, run /reconcile, propose rules from learnings, turn learnings into .claude/rules/ entries, or review what rules would be generated from current session learnings. On-demand version of session-end Phase 3.6.8.
  • 81reconcile
    Use this skill when the user wants to reconcile learnings into rules, run /reconcile, propose rules from learnings, turn learnings into .claude/rules/ entries, or review what rules would be generated from current session learnings. On-demand version of session-end Phase 3.6.8.
  • 86reflecting-to-root
    Use when the user asks to turn session learnings into durable rules.
  • 90reflect-yourself
    Self-learning system that captures corrections, discovers workflow patterns, and syncs learnings to skills and rules. Use when ending a session, after corrections, or when the user wants to formalize learnings (v1.1.3).
  • 100mine-history
    Extract and synthesize learnings from past Claude Code session transcripts into project documentation. Use when asked to "mine history", "extract learnings from past sessions", "what patterns keep recurring", or "improve docs from history".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.