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. When Claude Code discovers something non-obvious (a debugging technique, a workaround, some project-specific pattern), it saves that knowledge as a new skill. Next time a similar problem comes up, the skill gets loaded automatically.

This is a fork of blader/Claudeception refactored for Claude Marketplace installation.

1. Add the marketplace:

/plugin marketplace add SSS135/Claudeception

2. Install the plugin:

/plugin install claudeception@SSS135/Claudeception

Or use the interactive UI with /plugin.

1. Clone the repository:

git clone https://github.com/SSS135/Claudeception.git ~/.claude/plugins/claudeception

2. Register the plugin in ~/.claude/settings.json:

{
  "plugins": [
    "~/.claude/plugins/claudeception/plugins/claudeception"
  ]
}

The skill activates automatically when Claude Code:

• Just completed debugging and discovered a non-obvious solution
• Found a workaround through investigation or trial-and-error
• Resolved an error where the root cause wasn't immediately apparent
• Learned project-specific patterns or configurations through investigation
• Completed any task where the solution required meaningful discovery

Trigger a learning retrospective:

/claudeception:review

Or explicitly request skill extraction:

Save what we just learned as a skill

Not every task produces a skill. It only extracts knowledge that required actual discovery (not just reading docs), will help with future tasks, has clear trigger conditions, and has been verified to work.

The idea comes from academic work on skill libraries for AI agents.

Voyager (Wang et al., 2023) showed that game-playing agents can build up libraries of reusable skills over time, and that this helps them avoid re-learning things they already figured out. CASCADE (2024) introduced "meta-skills" (skills for acquiring skills), which is what this is. SEAgent (2025) showed agents can learn new software environments through trial and error, which inspired the retrospective feature. Reflexion (Shinn et al., 2023) showed that self-reflection helps.

Agents that persist what they learn do better than agents that start fresh.

Claude Code has a native skills system. At startup, it loads skill names and descriptions (about 100 tokens each). When you're working, it matches your current context against those descriptions and pulls in relevant skills.

But this retrieval system can be written to, not just read from. So when this skill notices extractable knowledge, it writes a new skill with a description optimized for future retrieval.

The description matters a lot. "Helps with database problems" won't match anything useful. "Fix for PrismaClientKnownRequestError in serverless" will match when someone hits that error.

More on the skills architecture here.

Extracted skills are markdown files with YAML frontmatter:

---
name: prisma-connection-pool-exhaustion
description: |
  Fix for PrismaClientKnownRequestError: Too many database connections
  in serverless environments (Vercel, AWS Lambda). Use when connection
  count errors appear after ~5 concurrent requests.
author: Claude Code
version: 1.0.0
date: 2024-01-15
---

# Prisma Connection Pool Exhaustion

## Problem
[What this skill solves]

## Context / Trigger Conditions
[Exact error messages, symptoms, scenarios]

## Solution
[Step-by-step fix]

## Verification
[How to confirm it worked]

See plugins/claudeception/resources/skill-template.md for the full template.

The skill is picky about what it extracts. If something is just a documentation lookup, or only useful for this one case, or hasn't actually been tested, it won't create a skill. Would this actually help someone who hits this problem in six months? If not, no skill.

See plugins/claudeception/examples/ for sample skills:

• nextjs-server-side-error-debugging/: errors that don't show in browser console
• prisma-connection-pool-exhaustion/: the "too many connections" serverless problem
• typescript-circular-dependency/: detecting and fixing import cycles

claudeception/
├── .claude-plugin/
│   └── marketplace.json      # Marketplace metadata
├── plugins/claudeception/
│   ├── plugin.json           # Plugin configuration
│   ├── skills/
│   │   └── SKILL.md          # The claudeception skill
│   ├── hooks/
│   │   └── hooks.json        # Hook configuration
│   ├── scripts/
│   │   └── activator.js      # Auto-activation script
│   ├── examples/             # Example extracted skills
│   └── resources/            # Templates and references
├── README.md
└── LICENSE

Contributions welcome. Fork, make changes, submit a PR.

MIT