Claudeception: The Claude Code skill that teaches an agent to remember what it just learned
A self-referential meta-skill for turning debugging wins, workarounds, and project-specific patterns into reusable long-term knowledge.
- Claudeception treats debugging as a source of long-term memory, not a one-off fix.
- Its real trick is not storage, but teaching Claude Code to notice when a session produced reusable knowledge.
- The shell activator matters because it forces reflection often enough for learning to become routine.
- The skill format is optimized for future retrieval by encoding symptoms, context, solution, and verification together.
The curse of the forgetting assistant
Claude Code can solve a problem quickly, then act like it never happened. That is fine for generic tasks, but brutal for project-specific bugs, odd framework behavior, and fixes that only make sense once you have already burned an hour finding them.
Claudeception is a direct answer to that failure mode. It turns a successful debugging session into a reusable skill, so the next time the same symptom shows up, Claude does not start from zero.
Every time you use an AI coding agent, it starts from zero. You spend an hour debugging some obscure error, the agent figures it out, session ends. Next time you hit the same issue? Another hour. This skill fixes that.
What Claudeception actually does
The core loop is simple. Claude notices that a fix was non-obvious, checks whether the lesson already exists, then writes a new skill with the problem, context, solution, and verification steps.
---
description: "Prisma connection pool exhaustion. Use when you see P2024 or repeated connection timeout symptoms."
context:
- "P2024"
- "PrismaClientInitializationError"
solution: "Reduce concurrent connections, reuse the client, and verify pool settings."
verification: "Run the failing query again and confirm the timeout no longer appears."
---The activator is the trick
The clever part is not just the skill file. It is the shell hook that injects a mandatory evaluation prompt into every interaction, so Claude keeps asking whether the current task produced extractable knowledge.
That matters because semantic matching alone is lazy. A reminder on every prompt increases the odds that Claude will stop and classify a lesson before it disappears into the next task.
The hook injects a reminder on every prompt that tells Claude to evaluate whether the current task produced extractable knowledge. This achieves higher activation rates than relying on semantic description matching alone.
Why the skill format matters
Claudeception stores lessons as markdown with YAML frontmatter because retrieval is the job. The file needs to be readable by humans and searchable by the agent, so it encodes the symptom, the trigger conditions, the fix, and the verification in a format that can be matched later.
| Project | Primary job | What it stores | What triggers retrieval | Why Claudeception is different |
|---|---|---|---|---|
| README notes | Human documentation | General advice and project lore | A person reads it | It is written for people, not for future agent recall. |
| MemGPT | Long-term memory management | Conversation state and retrieved context | Memory selection logic | It retrieves information, but does not focus on manufacturing new skills from lived debugging. |
| Claudeception | Skill extraction for Claude Code | Symptoms, context markers, solution, verification | Matching error patterns and prompt hooks | It turns successful experience into a future retrieval hook inside Claude Code. |
That is why the repo emphasizes exact errors and context markers. A future failure does not need a perfect semantic description if the trigger text already looks enough like the last one.
From debug fix to reusable skill
The examples make the pattern concrete. A Prisma connection pool issue, a Next.js server-side error, or a TypeScript circular dependency becomes a structured lesson instead of a buried memory in a chat transcript.
Each skill records the same basic arc. Here is the symptom. Here is the context where it matters. Here is the fix. Here is how to prove the fix worked.
Symptom: P2024, timeout, or repeated connection exhaustion
Context: high concurrency, stale client reuse, noisy local dev environment
Fix: reuse the client, reduce parallel connections, adjust pool settings
Verify: rerun the failing path and confirm the error no longer reproducesClaudeception’s real competition
The closest alternatives are not other Claude Code skills. They are generic notes, memory frameworks, and research agents that solve adjacent problems but miss the same target.
| Project | Primary job | What it stores | What triggers retrieval | Why Claudeception is different |
|---|---|---|---|---|
| Claudeception | Teach Claude Code to preserve lessons | Reusable skills built from debugging experience | Matching symptoms plus a prompt hook | It creates future knowledge artifacts from the work itself. |
| Voyager | Learn executable skills in an environment | Code skills for repeated action | Task and environment state | It is built for research learning, not developer workflow memory. |
| Reflexion | Improve performance through self-review | Textual reflections | Evaluation prompts | It reflects, but Claudeception also persists the result as a skill. |
That distinction is the whole story. Claudeception is not trying to be a universal memory layer. It is trying to make Claude Code institutionalize the weird stuff it learns along the way.
Why this matters beyond Claude Code
The bigger pattern is simple: agents do not just need access to knowledge. They need a way to manufacture it from experience. Claudeception shows how a tool can convert a solved edge case into a durable asset the next time the edge case returns.
That is a useful direction for developer tools in general. The best agent may not be the one that remembers everything. It may be the one that learns how to save the right thing, in the right form, at the right moment.
