The Lessons Learned skill is a specialized knowledge management framework designed for software engineers to capture, review, and operationalize insights gained during coding sessions. It transforms fleeting technical discoveries into a structured, searchable repository, helping developers avoid recurring bugs, master complex patterns, and automate best practices through AI-assisted synthesis and workflow integration.

When should I use lessons?

lessons is useful in the following scenarios: • Bug Prevention & Post-Mortems: Documenting the root cause and resolution of complex technical issues to create a 'prevention' guide that reduces future debugging time. • Architectural Pattern Cataloging: Recording reusable code structures, such as TypeScript generic constraints or design patterns, to maintain high code quality across multiple projects. • Workflow Automation: Converting recurring lessons into actionable developer assets like custom Git hooks, IDE snippets, and standardized PR checklists. • Continuous Learning & AI Synthesis: Utilizing AI to extract key takeaways from long coding sessions, identify knowledge gaps, and generate quizzes to reinforce technical mastery.

name	lessons
description	Capture and review lessons learned from coding sessions. Use to record insights, read past lessons, and improve over time.

Lessons Learned

Capture insights and learn from past experiences.

Capture Patterns

Quick Lesson Capture

When you learn something valuable during a session:

# Write to lessons file
cat >> ~/.claude/lessons.md << 'EOF'

## [Date] - [Topic]

**Context:** What were you doing?
**Lesson:** What did you learn?
**Application:** When to apply this?

EOF

Structured Lesson

## 2024-01-15 - TypeScript Generic Constraints

**Context:**
Building a type-safe form library, struggled with generic types.

**Problem:**
Generic function wasn't narrowing types correctly.

**Solution:**
Use `extends` constraints to narrow:
```typescript
function getValue<T extends { value: unknown }>(obj: T): T['value'] {
  return obj.value;
}

Lesson: TypeScript generics need explicit constraints for type narrowing.

Tags: #typescript #generics #types


## Lesson Categories

### Bug Lessons

```markdown
## Bug: [Brief description]

**Symptom:** What happened
**Root Cause:** Why it happened
**Fix:** How to fix
**Prevention:** How to avoid in future
**Time Cost:** How long to debug (motivation to remember!)

Pattern Lessons

## Pattern: [Name]

**When to use:** Situations where this applies
**How to implement:** Basic structure
**Gotchas:** Common mistakes
**Example:** Working code

Tool Lessons

## Tool: [Name]

**What it does:** Brief description
**Key commands:** Most useful commands
**Gotchas:** Things that trip people up
**Alternatives:** Other options

Review Practices

Daily Review

# Review recent lessons
tail -100 ~/.claude/lessons.md

# Search for topic
grep -A 10 "typescript" ~/.claude/lessons.md

Weekly Audit

gemini -m pro -o text -e "" "Review these lessons from the past week:

$(tail -500 ~/.claude/lessons.md)

1. What patterns emerge?
2. What mistakes keep recurring?
3. What should be turned into automation?
4. What needs deeper study?"

Before Starting Work

# Get relevant lessons
TOPIC="authentication"
grep -B 2 -A 10 -i "$TOPIC" ~/.claude/lessons.md

Automation from Lessons

When a lesson appears multiple times, automate it:

Create Git Hook

# Lesson: Always run tests before commit
# → Create pre-commit hook

cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
npm test || exit 1
EOF
chmod +x .git/hooks/pre-commit

Create Snippet

# Lesson: This pattern is useful
# → Save as snippet

cat > ~/.claude/snippets/async-error-handling.ts << 'EOF'
async function safeAsync<T>(promise: Promise<T>): Promise<[T, null] | [null, Error]> {
  try {
    const result = await promise;
    return [result, null];
  } catch (error) {
    return [null, error as Error];
  }
}
EOF

Create Checklist

# Lesson: Keep forgetting these steps
# → Create checklist

cat > ~/.claude/checklists/pr-review.md << 'EOF'
# PR Review Checklist
- [ ] Tests pass
- [ ] No console.logs
- [ ] Types are explicit
- [ ] Error handling present
- [ ] Documentation updated
EOF

AI-Assisted Learning

Extract Lessons from Session

gemini -m pro -o text -e "" "Extract lessons learned from this coding session:

[Paste conversation or summary]

For each lesson:
1. What was learned
2. When it applies
3. How to remember it"

Connect Lessons

gemini -m pro -o text -e "" "Find connections between these lessons:

$(cat ~/.claude/lessons.md)

1. What themes emerge?
2. What knowledge gaps exist?
3. What should be studied next?"

Generate Quiz

gemini -m pro -o text -e "" "Create a quiz from these lessons:

$(tail -1000 ~/.claude/lessons.md)

Generate 5 questions that test understanding of key concepts."

Storage Options

File-based

# Single file
~/.claude/lessons.md

# By date
~/.claude/lessons/2024-01.md

# By topic
~/.claude/lessons/typescript.md
~/.claude/lessons/git.md

Memory Integration

# Save to basic-memory
basic-memory tool write-note \
  --title "Lesson: TypeScript Generics" \
  --folder "lessons" \
  --content "$(cat lesson.md)" \
  --tags "lesson,typescript"

Best Practices

Capture immediately - Don't wait, you'll forget
Be specific - Include code examples
Note the cost - Time spent motivates remembering
Review regularly - Lessons fade without review
Automate repeated - Turn lessons into tools
Tag consistently - Makes searching easier
Connect to context - When does this apply?

lessons

When & Why to Use This Skill

Use Cases