Compound Learnings

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 87cf3db0e633 · 14 Oct 2026Report an issue or request a re-scan

• Publishervibeeval GitHub userOwner of the repository this skill is read from
• Source foldervibeeval/vibecosystem/skills/compound-learningsThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict87cf3db0e633A new audit runs when the source changes
• Repository statusNot archivedLast push 66 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

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

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

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/vibeeval/vibecosystem
git -C vibecosystem checkout 87cf3db0e633

Works in

1. 2026-10-14
   ✓SAFE B 89 / 100

   first audit · source 87cf3db0e633

Questions about Compound Learnings

• github.com/vibeeval/vibecosystem/tree/main/skills/compound-learn — the audited source at commit 87cf3db0e633 and every finding aboveObserved · 14 Oct 2026

Spotted something wrong? Report a correction · Methodology