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