How I Built a Claude Skill That Makes Claude Code Never Forget What It Learns

Let’s say you’re debugging.

Again.

That same gnarly issue that made you question your entire career choice last Tuesday. And the Tuesday before that. Your brain does that thing where it whispers: “Wait… didn’t I fix this already?”

You definitely fixed this already.

The solution exists somewhere—buried in a three-week-old Slack thread, or maybe that commit message you wrote at 2 AM when you were feeling particularly verbose. (Spoiler: You weren’t. The message says “fixed bug.”)

Here’s the thing: We’re hemorrhaging wisdom every single day.

Not because we’re not learning. We learn constantly. We discover edge cases, make architectural decisions, stumble upon performance tricks that would make your CS professor weep with joy.

But then? We move on. Next feature. Next sprint. Next fire.

And all that hard-won knowledge?

Poof.

Gone like your willpower at 3 PM when someone mentions there’s leftover birthday cake in the break room.

.

.

.

The Problem: Claude Code Has The Memory of a Goldfish

Picture this: You’re vibe coding with Claude Code. (Yes, that’s a technical term now. Roll with it.)

Together, you and Claude are making dozens of micro-decisions every session:

• “Oh right, this package completely changed its API in v2”
• “We need to store files in org-scoped directories for multi-tenancy”
• “This approach is 10x faster than the obvious solution”
• “Never—and I mean NEVER—use pattern X here because of edge case Y”

These aren’t just code comments, friend. This is architectural wisdom. The kind that separates the “I can center a div” developers from the “I’ve seen things you wouldn’t believe” architects.

But here’s what happens next. (You already know where this is going, don’t you?)

1. Claude Code discovers something important
2. You fix the issue together
3. You high-five virtually and move on
4. Next week, Claude Code makes the exact. Same. Mistake.
5. You debug the exact. Same. Issue.
6. Rinse, repeat, cry a little

Sure, we’ve got CLAUDE.md for project rules.

But let me ask you something: When was the last time you updated that file after a coding session?

Cricket sounds.

Exactly.

Nobody has time to document discoveries when you’re in the zone. Nobody.

So I built a Claude Skill that remembers everything for us.

(Stay with me. This gets good.)

.

.

.

The Complete Workflow: Capture, Review, Integrate

The Build Insights Logger skill creates what I like to call a “knowledge management system.” (Fancy, right? It’s actually pretty simple.)

• Step 1: Automatic Capture – Logs insights while you’re coding
• Step 2: Smart Review – Shows you insights organized by category
• Step 3: Selective Integration – Adds the good stuff to CLAUDE.md
• Step 4: Compound Learning – Every future session gets smarter

Let me show you how this saved my bacon. (Actually, it was more like saving me from a dependency nightmare, but “saved my bacon” sounds more dramatic.)

.

.

.

Step 1: Automatic Knowledge Capture (While You Code!)

Here’s what the Build Insights Logger does brilliantly: it automatically logs meaningful insights as Claude Code works.

No manual documentation.
No “I’ll add this to the docs later.” (You won’t.)
No lost learnings.

Just automatic capture of:

• Non-trivial edge cases you stumble upon
• Design decisions and their rationale (the WHY behind the WHAT)
• Performance optimizations that made you go “whoa”
• Security implications that could bite you later
• Architecture patterns you actually adopt
• API gotchas and their fixes
• Implementation trade-offs

Everything gets logged to .claude/insights/ during your session. Ready for review when YOU’RE ready.

Real-World Example: Building a Document Management System

On Monday, I was building a document management system. The complex kind—file uploads, multi-tenant storage, previews, the whole enchilada.

I started with my standard instruction to Claude Code

Notice the magic phrase: “Please use the build-insights-logger skill.”

That’s it. That’s all it takes.

Claude Code immediately gets it:

With the skill activated, Claude Code starts building. But—and here’s where it gets interesting—it’s not just coding. It’s documenting its discoveries:

As Claude works through the implementation, it automatically creates an insights log:

What Gets Captured: Real Architectural Decisions

These insights aren’t fluff. They’re the real deal—architectural decisions that matter:

Look at that first insight—a pluggable storage abstraction. Claude Code discovered you needed to support multiple storage backends (local disk, S3, Azure Blob) and documented the pattern.

Key insight captured: “By storing files in org-scoped directories with year/month structure (storage/documents/{orgId}/{yyyy}/{mm}/{filename}), we maintain tenant isolation at the filesystem level and enable efficient cleanup/archiving strategies.”

That’s not a code comment, friend.

That’s institutional knowledge.

As development continues, more insights accumulate:

Notice the categories:

• Architecture: System design decisions
• UI Patterns: Implementation approaches that actually work
• Navigation: Integration strategies
• Implementation Strategy: Why we’re building it this way

Each insight includes:

• The files involved
• Relevant tags (for finding it later)
• Clear explanation of the decision
• Why it matters (the part everyone forgets to document)

The Moment That Made Me a Believer: The cuid2 Bug

Here’s where the skill earned its keep.

After implementing the core functionality, I hit an error:

The build was failing. The error message? Cryptic as a fortune cookie: “Export cuid doesn’t exist in target module.”

Now, normally this triggers The Debugging Dance. You know the one—check imports, read docs, sacrifice a rubber duck to the Stack Overflow gods.

But watch what happened when I asked Claude Code to fix it and log the insight:

Claude Code didn’t just fix the bug.

It:

1. Researched the root cause
2. Created a comprehensive fix plan
3. Documented the gotcha for future reference

The fix was simple—the package had changed its API between v1 and v2:

But here’s the crucial part—this knowledge was captured permanently:

Look at that bug fix documentation:

• Clear problem statement
• Root cause analysis
• Wrong pattern marked (with a big ❌)
• Correct pattern provided (with a reassuring ✅)
• Package version context

This bug will never bite us again.

Never.

(Well, unless we forget to use the skill. But we won’t. Right?)

.

.

.

Step 2: Transforming Raw Insights Into Permanent Knowledge

So you’ve been capturing insights automatically. Your .claude/insights/ folder is filling up with valuable learnings like a wisdom piñata.

But insights in session files are like vegetables in your crisper drawer—valuable, but not helping anyone if they’re just sitting there.

Time for the review workflow. This is where the magic happens.

Triggering the Review: On YOUR Schedule

The Build Insights Logger respects your flow. It never interrupts with “Hey! Want to review your insights? How about now? Now? What about now?”

Never.

You review when YOU want. After the feature ships. After the bug is squashed. After your coffee. (Definitely after coffee.)

Here’s how simple it is:

One command: “Please use the build-insights-logger skill to review the insights from existing sessions.”

Claude Code immediately understands:

Watch what happens next. Claude doesn’t just dump a wall of text like your cousin’s Facebook posts. It systematically explores your insights directory:

Two session files found. 160 lines of insights total.

Raw knowledge waiting to be refined. Like coffee beans waiting to become that sweet, sweet nectar of productivity.

The Presentation: Organized, Categorized, Actually Useful

This is where the skill really shines.

Instead of showing you raw session logs (boring), Claude Code presents your insights like a senior architect presenting findings to the team:

Look at that organization!

Architecture & Design Patterns

• Document storage abstraction with migration paths
• Backend-first implementation strategy

Prisma & Database Patterns

• Complex filtering with OR/AND combinations
• Many-to-many relations with soft deletes

Each insight is:

• Numbered for easy selection (1/, 2/, 3/…)
• Categorized for context (because context is everything)
• Summarized with key details
• Explained with why it matters

The presentation continues:

Security & Permissions

• Tiered permission levels for different operations
• Defensive soft-delete checking

Data Integrity & Business Logic

• Transaction links removed on soft delete
• Per-file error handling in batch operations

And more:

UI Implementation Patterns

• File upload with hidden input ref pattern
• Document preview with MIME-type detection
• Two-level navigation integration

Bug Fixes & Dependencies

• That @paralleldrive/cuid2 import issue (remember that little rascal?)

13 insights total. Each one a potential bug prevented, a pattern established, a decision documented.

It’s like having a time machine that lets you send wisdom to your future self.

.

.

.

Step 3: Curating Your Knowledge Base (Be Picky!)

Claude asks: “Which insights would you like to add to CLAUDE.md?”

This is where you become the curator of your own knowledge museum. (Fancy!)

My selections:

• 2 – Backend-first implementation strategy (methodology worth preserving)
• 3 & 4 – Prisma patterns (made generic for any schema)
• 5 – Tiered permissions (security pattern)
• 13 – The cuid2 import bug (never. again.)

Notice what I did with insight 3? “Make this rule generic so that it can be applicable for any Prisma schema.”

The skill doesn’t just copy-paste like a lazy intern. It adapts insights to be broadly useful.

I didn’t select everything. Some insights were too specific. Others were already covered.

Quality beats quantity.

Every. Single. Time.

The Integration: Surgical Precision (No Mess)

Watch what happens when Claude Code integrates my selected insights:

Claude reads my existing CLAUDE.md (278 lines) and begins surgical integration.

It doesn’t just slap new stuff at the end like a P.S. on a love letter. It finds the RIGHT sections:

The Permission Layers section gets enhanced with the tiered strategy:

• GET endpoints for regular members
• PATCH/POST/DELETE for destructive operations require admin
• Clear examples with specific routes

A new Prisma Query Patterns section appears with that complex OR/AND filtering pattern:

// When combining multiple OR conditions in a single query, wrap them in AND:
if (where.OR) {
  where.AND = [{ OR: where.OR }, { OR: searchConditions }];
  delete where.OR;
}

This pattern will save you hours of debugging Prisma query conflicts.

Hours.

The Common Pitfalls section gets the cuid2 import pattern:

// ❌ WRONG - v1 pattern, will fail with "Export cuid doesn't exist"
import { cuid } from '@paralleldrive/cuid2';

// ✅ CORRECT - v2 exports createId
import { createId } from '@paralleldrive/cuid2';

Complete with root cause explanation. This bug will never happen again in any project.

(I’m not crying. You’re crying.)

The Confirmation: Knowledge Preserved

The summary tells the complete story:

Added to CLAUDE.md:

1. Backend-first implementation strategy → Coding Standards section
2. Complex Prisma filtering → New Prisma Query Patterns section
3. Filtering many-to-many relations → Same section, generalized
4. Tiered permission strategy → Enhanced Permission Layers section
5. @paralleldrive/cuid2 import → Common Pitfalls section

Session files archived:

• session-2025-11-18-003404.md → .claude/insights/archive/
• session-2025-11-18-121019.md → .claude/insights/archive/

The insights aren’t lost. They’re archived. But the valuable patterns? They’re now in CLAUDE.md where they’ll guide every future coding session.

It’s like upgrading from sticky notes to a proper filing system. (But one that actually works.)

.

.

.

The Selection Philosophy: What Makes the Cut?

Not every insight belongs in CLAUDE.md.

Here’s my selection criteria. (Yes, I have criteria. I’m fancy like that.)

Always Include:

• Universal patterns that apply across features
• Security decisions that affect the whole app
• Performance optimizations that should be standard
• Bug fixes for external dependencies
• Architectural principles that guide development

Usually Skip:

• Feature-specific implementation details
• One-off workarounds
• Obvious patterns Claude already knows
• Project-specific business logic
• Temporary fixes waiting for upstream patches

Transform When Adding:

• Make patterns generic (not tied to specific models)
• Extract the principle, not just the implementation
• Add context about when to apply (and when NOT to)
• Include examples that clarify usage

The goal isn’t to document everything. The goal is to capture patterns that make your next project better.

Less encyclopedia, more greatest hits album.

.

.

.

The Compound Effect:

Here’s what happens over time. (Spoiler: It’s beautiful.)

• Week 1: You capture 10 insights about authentication patterns
• Week 2: You capture 8 insights about performance optimizations
• Week 3: You capture 12 insights about error handling
• Month 2: You have 100+ insights spanning every aspect of your codebase

Now imagine Claude Code with access to all of that institutional knowledge.

It’s not just avoiding bugs. It’s:

• Consistent architectural decisions
• Proven patterns applied automatically
• Edge cases handled proactively
• Performance optimizations baked in
• Security considerations from day one

Your codebase doesn’t just grow. It evolves.

(Like Pokémon, but for code.)

Picture this:

Before this review:

• 2 session files with 13 insights
• Knowledge trapped in temporary logs
• Claude Code blissfully unaware

After 2 minutes of review:

• 5 critical patterns added to permanent knowledge
• CLAUDE.md enhanced with battle-tested wisdom
• Every future session benefits

Now multiply this across every coding session:

• Week 1: 5 insights added → Next development avoids 5 issues
• Week 2: 8 more insights → Next development avoids 13 issues
• Month 2: 50+ insights → Your codebase is basically bulletproof

Each review session doesn’t just improve documentation. It improves every future line of code Claude writes.

It’s compound interest for your codebase.

.

.

.

Your Complete Workflow: From Chaos to Compound Knowledge

Here’s your complete workflow. (Print this out. Stick it on your monitor. Tattoo it on your forearm. Whatever works.)

During Development (Automatic):

1. Activate build-insights-logger at session start
2. Code normally—insights log automatically
3. Discoveries, decisions, and fixes are captured
4. Session file grows with valuable learnings

After Development (5 minutes):

1. Request review: “Review insights from existing sessions”
2. Read through categorized insights
3. Select the valuable patterns (usually 30-50%)
4. Let Claude integrate into CLAUDE.md
5. Session files archive automatically

Next Development (Automatic Benefits):

1. Claude reads enhanced CLAUDE.md
2. Applies all captured patterns
3. Avoids all documented pitfalls
4. Implements proven architectures
5. Your code is better without trying

It’s not just documentation.

It’s evolutionary development.

Each development builds on the learnings of the last. Like standing on the shoulders of giants, except the giant is your past self. (Your past self is very tall in this metaphor. Roll with it.)

.

.

.

Your Action Items (Yes, You. Right Now.)

1. Implement the Build Insights Logger skill in your current project
2. Activate it at the start of your next coding session
3. Code normally—let insights capture automatically
4. Review weekly—spend 5 minutes curating insights
5. Watch your CLAUDE.md grow from basic rules to battle-tested wisdom
6. Measure the difference—track how many repeated bugs you avoid

What insights are waiting in your .claude/insights/ folder right now?

Go review them.

Your future self will thank you. (Your future self might even buy you coffee. Your future self is thoughtful like that.)

Resources:

• How to add “Build Insights Logger” skill into your Claude Code