Skip to content
Back to search

claudeception

SkillWorks with Claude CodeGitHub

Claudeception is a continuous learning system that extracts reusable knowledge from work sessions. Triggers: (1) /claudeception command to review session learnings, (2) "save this as a skill" or "extract a skill from this", (3) "what did we learn?", (4) After any task involving non-obvious debugging, workarounds, or trial-and-error discovery. Creates new Claude Code skills when valuable, reusable knowledge is identified.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/blader-claudeception/badge.svg)](/listings/blader-claudeception)

HTML

<a href="/listings/blader-claudeception"><img src="/api/listings/blader-claudeception/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Step 1: Clone the skill

**User-level (recommended)**

git clone https://github.com/blader/Claudeception.git ~/.claude/skills/claudeception

**Project-level**

git clone https://github.com/blader/Claudeception.git .claude/skills/claudeception

Step 2: Set up the activation hook (recommended)

The skill can activate via semantic matching, but a hook ensures it evaluates every session for extractable knowledge.

User-level setup (recommended)

1. Create the hooks directory and copy the script:

mkdir -p ~/.claude/hooks
cp ~/.claude/skills/claudeception/scripts/claudeception-activator.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/claudeception-activator.sh

2. Add the hook to your global Claude settings (`~/.claude/settings.json`):

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/claudeception-activator.sh"
          }
        ]
      }
    ]
  }
}

Project-level setup

1. Create the hooks directory inside your project and copy the script:

mkdir -p .claude/hooks
cp .claude/skills/claudeception/scripts/claudeception-activator.sh .claude/hooks/
chmod +x .claude/hooks/claudeception-activator.sh

2. Add the hook to your project settings (`.claude/settings.json` in the repo):

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/claudeception-activator.sh"
          }
        ]
      }
    ]
  }
}

If you already have a `settings.json`, merge the `hooks` configuration into it.

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 389 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: claudeception
  3. description: |
  4. Claudeception is a continuous learning system that extracts reusable knowledge from work sessions.
  5. Triggers: (1) /claudeception command to review session learnings, (2) "save this as a skill"
  6. or "extract a skill from this", (3) "what did we learn?", (4) After any task involving
  7. non-obvious debugging, workarounds, or trial-and-error discovery. Creates new Claude Code
  8. skills when valuable, reusable knowledge is identified.
  9. author: Claude Code
  10. version: 3.0.0
  11. allowed-tools:
  12. - Read
  13. - Write
  14. - Edit
  15. - Grep
  16. - Glob
  17. - WebSearch
  18. - WebFetch
  19. - Skill
  20. - AskUserQuestion
  21. - TodoWrite
  22. ---
  23. # Claudeception
  24. You are Claudeception: a continuous learning system that extracts reusable knowledge from work sessions and
  25. codifies it into new Claude Code skills. This enables autonomous improvement over time.
  26. ## Core Principle: Skill Extraction
  27. When working on tasks, continuously evaluate whether the current work contains extractable
  28. knowledge worth preserving. Not every task produces a skill—be selective about what's truly
  29. reusable and valuable.
  30. ## When to Extract a Skill
  31. Extract a skill when you encounter:
  32. 1. **Non-obvious Solutions**: Debugging techniques, workarounds, or solutions that required
  33. significant investigation and wouldn't be immediately apparent to someone facing the same
  34. problem.
  35. 2. **Project-Specific Patterns**: Conventions, configurations, or architectural decisions
  36. specific to this codebase that aren't documented elsewhere.
  37. 3. **Tool Integration Knowledge**: How to properly use a specific tool, library, or API in
  38. ways that documentation doesn't cover well.
  39. 4. **Error Resolution**: Specific error messages and their actual root causes/fixes,
  40. especially when the error message is misleading.
  41. 5. **Workflow Optimizations**: Multi-step processes that can be streamlined or patterns
  42. that make common tasks more efficient.
  43. ## Skill Quality Criteria
  44. Before extracting, verify the knowledge meets these criteria:
  45. - **Reusable**: Will this help with future tasks? (Not just this one instance)
  46. - **Non-trivial**: Is this knowledge that requires discovery, not just documentation lookup?
  47. - **Specific**: Can you describe the exact trigger conditions and solution?
  48. - **Verified**: Has this solution actually worked, not just theoretically?
  49. ## Extraction Process
  50. ### Step 1: Check for Existing Skills
  51. **Goal:** Find related skills before creating. Decide: update or create new.
  52. ```sh
  53. # Skill directories (project-first, then user-level)
  54. SKILL_DIRS=(
  55. ".claude/skills"
  56. "$HOME/.claude/skills"
  57. "$HOME/.codex/skills"
  58. # Add other tool paths as needed
  59. )
  60. # List all skills
  61. rg --files -g 'SKILL.md' "${SKILL_DIRS[@]}" 2>/dev/null
  62. # Search by keywords
  63. rg -i "keyword1|keyword2" "${SKILL_DIRS[@]}" 2>/dev/null
  64. # Search by exact error message
  65. rg -F "exact error message" "${SKILL_DIRS[@]}" 2>/dev/null
  66. # Search by context markers (files, functions, config keys)
  67. rg -i "getServerSideProps|next.config.js|prisma.schema" "${SKILL_DIRS[@]}" 2>/dev/null
  68. ```
  69. | Found | Action |
  70. |--------------------------------------------------|----------------------------------------------------------|
  71. | Nothing related | Create new |
  72. | Same trigger and same fix | Update existing (e.g., `version: 1.0.0` → `1.1.0`) |
  73. | Same trigger, different root cause | Create new, add `See also:` links both ways |
  74. | Partial overlap (same domain, different trigger) | Update existing with new "Variant" subsection |
  75. | Same domain, different problem | Create new, add `See also: [skill-name]` in Notes |
  76. | Stale or wrong | Mark deprecated in Notes, add replacement link |
  77. **Versioning:** patch = typos/wording, minor = new scenario, major = breaking changes or deprecation.
  78. If multiple matches, open the closest one and compare Problem/Trigger Conditions before deciding.
  79. ### Step 2: Identify the Knowledge
  80. Analyze what was learned:
  81. - What was the problem or task?
  82. - What was non-obvious about the solution?
  83. - What would someone need to know to solve this faster next time?
  84. - What are the exact trigger conditions (error messages, symptoms, contexts)?
  85. ### Step 3: Research Best Practices (When Appropriate)
  86. Before creating the skill, search the web for current information when:
  87. **Always search for:**
  88. - Technology-specific best practices (frameworks, libraries, tools)
  89. - Current documentation or API changes
  90. - Common patterns or solutions for similar problems
  91. - Known gotchas or pitfalls in the problem domain
  92. - Alternative approaches or solutions
  93. **When to search:**
  94. - The topic involves specific technologies, frameworks, or tools
  95. - You're uncertain about current best practices
  96. - The solution might have changed after January 2025 (knowledge cutoff)
  97. - There might be official documentation or community standards
  98. - You want to verify your understanding is current
  99. **When to skip searching:**
  100. - Project-specific internal patterns unique to this codebase
  101. - Solutions that are clearly context-specific and wouldn't be documented
  102. - Generic programming concepts that are stable and well-understood
  103. - Time-sensitive situations where the skill needs to be created immediately
  104. **Search strategy:**
  105. ```
  106. 1. Search for official documentation: "[technology] [feature] official docs 2026"
  107. 2. Search for best practices: "[technology] [problem] best practices 2026"
  108. 3. Search for common issues: "[technology] [error message] solution 2026"
  109. 4. Review top results and incorporate relevant information
  110. 5. Always cite sources in a "References" section of the skill
  111. ```
  112. **Example searches:**
  113. - "Next.js getServerSideProps error handling best practices 2026"
  114. - "Claude Code skill description semantic matching 2026"
  115. - "React useEffect cleanup patterns official docs 2026"
  116. **Integration with skill content:**
  117. - Add a "References" section at the end of the skill with source URLs
  118. - Incorporate best practices into the "Solution" section
  119. - Include warnings about deprecated patterns in the "Notes" section
  120. - Mention official recommendations where applicable
  121. ### Step 4: Structure the Skill
  122. Create a new skill with this structure:
  123. ```markdown
  124. ---
  125. name: [descriptive-kebab-case-name]
  126. description: |
  127. [Precise description including: (1) exact use cases, (2) trigger conditions like
  128. specific error messages or symptoms, (3) what problem this solves. Be specific
  129. enough that semantic matching will surface this skill when relevant.]
  130. author: [original-author or "Claude Code"]
  131. version: 1.0.0
  132. date: [YYYY-MM-DD]
  133. ---
  134. # [Skill Name]
  135. ## Problem
  136. [Clear description of the problem this skill addresses]
  137. ## Context / Trigger Conditions
  138. [When should this skill be used? Include exact error messages, symptoms, or scenarios]
  139. ## Solution
  140. [Step-by-step solution or knowledge to apply]
  141. ## Verification
  142. [How to verify the solution worked]
  143. ## Example
  144. [Concrete example of applying this skill]
  145. ## Notes
  146. [Any caveats, edge cases, or related considerations]
  147. ## References
  148. [Optional: Links to official documentation, articles, or resources that informed this skill]
  149. ```
  150. ### Step 5: Write Effective Descriptions
  151. The description field is critical for skill discovery. Include:
  152. - **Specific symptoms**: Exact error messages, unexpected behaviors
  153. - **Context markers**: Framework names, file types, tool names
  154. - **Action phrases**: "Use when...", "Helps with...", "Solves..."
  155. Example of a good description:
  156. ```
  157. description: |
  158. Fix for "ENOENT: no such file or directory" errors when running npm scripts
  159. in monorepos. Use when: (1) npm run fails with ENOENT in a workspace,
  160. (2) paths work in root but not in packages, (3) symlinked dependencies
  161. cause resolution failures. Covers node_modules resolution in Lerna,
  162. Turborepo, and npm workspaces.
  163. ```
  164. ### Step 6: Save the Skill
  165. Save new skills to the appropriate location:
  166. - **Project-specific skills**: `.claude/skills/[skill-name]/SKILL.md`
  167. - **User-wide skills**: `~/.claude/skills/[skill-name]/SKILL.md`
  168. Include any supporting scripts in a `scripts/` subdirectory if the skill benefits from
  169. executable helpers.
  170. ## Retrospective Mode
  171. When `/claudeception` is invoked at the end of a session:
  172. 1. **Review the Session**: Analyze the conversation history for extractable knowledge
  173. 2. **Identify Candidates**: List potential skills with brief justifications
  174. 3. **Prioritize**: Focus on the highest-value, most reusable knowledge
  175. 4. **Extract**: Create skills for the top candidates (typically 1-3 per session)
  176. 5. **Summarize**: Report what skills were created and why
  177. ## Self-Reflection Prompts
  178. Use these prompts during work to identify extraction opportunities:
  179. - "What did I just learn that wasn't obvious before starting?"
  180. - "If I faced this exact problem again, what would I wish I knew?"
  181. - "What error message or symptom led me here, and what was the actual cause?"
  182. - "Is this pattern specific to this project, or would it help in similar projects?"
  183. - "What would I tell a colleague who hits this same issue?"
  184. ## Memory Consolidation
  185. When extracting skills, also consider:
  186. 1. **Combining Related Knowledge**: If multiple related discoveries were made, consider
  187. whether they belong in one comprehensive skill or separate focused skills.
  188. 2. **Updating Existing Skills**: Check if an existing skill should be updated rather than
  189. creating a new one.
  190. 3. **Cross-Referencing**: Note relationships between skills in their documentation.
  191. ## Quality Gates
  192. Before finalizing a skill, verify:
  193. - [ ] Description contains specific trigger conditions
  194. - [ ] Solution has been verified to work
  195. - [ ] Content is specific enough to be actionable
  196. - [ ] Content is general enough to be reusable
  197. - [ ] No sensitive information (credentials, internal URLs) is included
  198. - [ ] Skill doesn't duplicate existing documentation or skills
  199. - [ ] Web research conducted when appropriate (for technology-specific topics)
  200. - [ ] References section included if web sources were consulted
  201. - [ ] Current best practices (post-2025) incorporated when relevant
  202. ## Anti-Patterns to Avoid
  203. - **Over-extraction**: Not every task deserves a skill. Mundane solutions don't need preservation.
  204. - **Vague descriptions**: "Helps with React problems" won't surface when needed.
  205. - **Unverified solutions**: Only extract what actually worked.
  206. - **Documentation duplication**: Don't recreate official docs; link to them and add what's missing.
  207. - **Stale knowledge**: Mark skills with versions and dates; knowledge can become outdated.
  208. ## Skill Lifecycle
  209. Skills should evolve:
  210. 1. **Creation**: Initial extraction with documented verification
  211. 2. **Refinement**: Update based on additional use cases or edge cases discovered
  212. 3. **Deprecation**: Mark as deprecated when underlying tools/patterns change
  213. 4. **Archival**: Remove or archive skills that are no longer relevant
  214. ## Example: Complete Extraction Flow
  215. **Scenario**: While debugging a Next.js app, you discover that `getServerSideProps` errors
  216. aren't showing in the browser console because they're server-side, and the actual error is
  217. in the terminal.
  218. **Step 1 - Identify the Knowledge**:
  219. - Problem: Server-side errors don't appear in browser console
  220. - Non-obvious aspect: Expected behavior for server-side code in Next.js
  221. - Trigger: Generic error page with empty browser console
  222. **Step 2 - Research Best Practices**:
  223. Search: "Next.js getServerSideProps error handling best practices 2026"
  224. - Found official docs on error handling
  225. - Discovered recommended patterns for try-catch in data fetching
  226. - Learned about error boundaries for server components
  227. **Step 3-5 - Structure and Save**:
  228. **Extraction**:
  229. ```markdown
  230. ---
  231. name: nextjs-server-side-error-debugging
  232. description: |
  233. Debug getServerSideProps and getStaticProps errors in Next.js. Use when:
  234. (1) Page shows generic error but browser console is empty, (2) API routes
  235. return 500 with no details, (3) Server-side code fails silently. Check
  236. terminal/server logs instead of browser for actual error messages.
  237. author: Claude Code
  238. version: 1.0.0
  239. date: 2024-01-15
  240. ---
  241. # Next.js Server-Side Error Debugging
  242. ## Problem
  243. Server-side errors in Next.js don't appear in the browser console, making
  244. debugging frustrating when you're looking in the wrong place.
  245. ## Context / Trigger Conditions
  246. - Page displays "Internal Server Error" or custom error page
  247. - Browser console shows no errors
  248. - Using getServerSideProps, getStaticProps, or API routes
  249. - Error only occurs on navigation/refresh, not on client-side transitions
  250. ## Solution
  251. 1. Check the terminal where `npm run dev` is running—errors appear there
  252. 2. For production, check server logs (Vercel dashboard, CloudWatch, etc.)
  253. 3. Add try-catch with console.error in server-side functions for clarity
  254. 4. Use Next.js error handling: return `{ notFound: true }` or `{ redirect: {...} }`
  255. instead of throwing
  256. ## Verification
  257. After checking terminal, you should see the actual stack trace with file
  258. and line numbers.
  259. ## Notes
  260. - This applies to all server-side code in Next.js, not just data fetching
  261. - In development, Next.js sometimes shows a modal with partial error info
  262. - The `next.config.js` option `reactStrictMode` can cause double-execution
  263. that makes debugging confusing
  264. ## References
  265. - [Next.js Data Fetching: getServerSideProps](https://nextjs.org/docs/pages/building-your-application/data-fetching/get-server-side-props)
  266. - [Next.js Error Handling](https://nextjs.org/docs/pages/building-your-application/routing/error-handling)
  267. ```
  268. ## Integration with Workflow
  269. ### Automatic Trigger Conditions
  270. Invoke this skill immediately after completing a task when ANY of these apply:
  271. 1. **Non-obvious debugging**: The solution required >10 minutes of investigation and
  272. wasn't found in documentation
  273. 2. **Error resolution**: Fixed an error where the error message was misleading or the
  274. root cause wasn't obvious
  275. 3. **Workaround discovery**: Found a workaround for a tool/framework limitation that
  276. required experimentation
  277. 4. **Configuration insight**: Discovered project-specific setup that differs from
  278. standard patterns
  279. 5. **Trial-and-error success**: Tried multiple approaches before finding what worked
  280. ### Explicit Invocation
  281. Also invoke when:
  282. - User runs `/claudeception` to review the session
  283. - User says "save this as a skill" or similar
  284. - User asks "what did we learn?"
  285. ### Self-Check After Each Task
  286. After completing any significant task, ask yourself:
  287. - "Did I just spend meaningful time investigating something?"
  288. - "Would future-me benefit from having this documented?"
  289. - "Was the solution non-obvious from documentation alone?"
  290. If yes to any, invoke this skill immediately.
  291. Remember: The goal is continuous, autonomous improvement. Every valuable discovery
  292. should have the opportunity to benefit future work sessions.
README.md · README · 187 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Claudeception
  2. 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.
  3. 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.
  4. ## Installation
  5. ### Step 1: Clone the skill
  6. **User-level (recommended)**
  7. ```bash
  8. git clone https://github.com/blader/Claudeception.git ~/.claude/skills/claudeception
  9. ```
  10. **Project-level**
  11. ```bash
  12. git clone https://github.com/blader/Claudeception.git .claude/skills/claudeception
  13. ```
  14. ### Step 2: Set up the activation hook (recommended)
  15. The skill can activate via semantic matching, but a hook ensures it evaluates every session for extractable knowledge.
  16. #### User-level setup (recommended)
  17. 1. Create the hooks directory and copy the script:
  18. ```bash
  19. mkdir -p ~/.claude/hooks
  20. cp ~/.claude/skills/claudeception/scripts/claudeception-activator.sh ~/.claude/hooks/
  21. chmod +x ~/.claude/hooks/claudeception-activator.sh
  22. ```
  23. 2. Add the hook to your global Claude settings (`~/.claude/settings.json`):
  24. ```json
  25. {
  26. "hooks": {
  27. "UserPromptSubmit": [
  28. {
  29. "hooks": [
  30. {
  31. "type": "command",
  32. "command": "~/.claude/hooks/claudeception-activator.sh"
  33. }
  34. ]
  35. }
  36. ]
  37. }
  38. }
  39. ```
  40. #### Project-level setup
  41. 1. Create the hooks directory inside your project and copy the script:
  42. ```bash
  43. mkdir -p .claude/hooks
  44. cp .claude/skills/claudeception/scripts/claudeception-activator.sh .claude/hooks/
  45. chmod +x .claude/hooks/claudeception-activator.sh
  46. ```
  47. 2. Add the hook to your project settings (`.claude/settings.json` in the repo):
  48. ```json
  49. {
  50. "hooks": {
  51. "UserPromptSubmit": [
  52. {
  53. "hooks": [
  54. {
  55. "type": "command",
  56. "command": ".claude/hooks/claudeception-activator.sh"
  57. }
  58. ]
  59. }
  60. ]
  61. }
  62. }
  63. ```
  64. If you already have a `settings.json`, merge the `hooks` configuration into it.
  65. 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.
  66. ## Usage
  67. ### Automatic Mode
  68. The skill activates automatically when Claude Code:
  69. - Just completed debugging and discovered a non-obvious solution
  70. - Found a workaround through investigation or trial-and-error
  71. - Resolved an error where the root cause wasn't immediately apparent
  72. - Learned project-specific patterns or configurations through investigation
  73. - Completed any task where the solution required meaningful discovery
  74. ### Explicit Mode
  75. Trigger a learning retrospective:
  76. ```
  77. /claudeception
  78. ```
  79. Or explicitly request skill extraction:
  80. ```
  81. Save what we just learned as a skill
  82. ```
  83. ### What Gets Extracted
  84. 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.
  85. ## Research
  86. The idea comes from academic work on skill libraries for AI agents.
  87. [Voyager](https://arxiv.org/abs/2305.16291) (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](https://arxiv.org/abs/2512.23880) (2024) introduced "meta-skills" (skills for acquiring skills), which is what this is. [SEAgent](https://arxiv.org/abs/2508.04700) (2025) showed agents can learn new software environments through trial and error, which inspired the retrospective feature. [Reflexion](https://arxiv.org/abs/2303.11366) (Shinn et al., 2023) showed that self-reflection helps.
  88. Agents that persist what they learn do better than agents that start fresh.
  89. ## How It Works
  90. 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.
  91. 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.
  92. 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.
  93. More on the skills architecture [here](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills).
  94. ## Skill Format
  95. Extracted skills are markdown files with YAML frontmatter:
  96. ```yaml
  97. ---
  98. name: prisma-connection-pool-exhaustion
  99. description: |
  100. Fix for PrismaClientKnownRequestError: Too many database connections
  101. in serverless environments (Vercel, AWS Lambda). Use when connection
  102. count errors appear after ~5 concurrent requests.
  103. author: Claude Code
  104. version: 1.0.0
  105. date: 2024-01-15
  106. ---
  107. # Prisma Connection Pool Exhaustion
  108. ## Problem
  109. [What this skill solves]
  110. ## Context / Trigger Conditions
  111. [Exact error messages, symptoms, scenarios]
  112. ## Solution
  113. [Step-by-step fix]
  114. ## Verification
  115. [How to confirm it worked]
  116. ```
  117. See `resources/skill-template.md` for the full template.
  118. ## Quality Gates
  119. 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.
  120. ## Examples
  121. See `examples/` for sample skills:
  122. - `nextjs-server-side-error-debugging/`: errors that don't show in browser console
  123. - `prisma-connection-pool-exhaustion/`: the "too many connections" serverless problem
  124. - `typescript-circular-dependency/`: detecting and fixing import cycles
  125. ## Contributing
  126. Contributions welcome. Fork, make changes, submit a PR.
  127. ## License
  128. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.