Claudeception

每次你使用 AI 编码助手时，它都会从零开始。你花上一小时调试一个晦涩的错误，助手最终找到了解决方案，会话就结束了。下次再遇到同样的问题？又得花上一小时。

这个技能就能解决这个问题。当 Claude Code 发现一些不那么显而易见的事情（比如调试技巧、绕过方案或特定项目的模式）时，它会将这些知识保存为一项新技能。下次再遇到类似的问题，这项技能就会自动加载。

安装

第一步：克隆技能

用户级别（推荐）

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

项目级别

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

第二步：设置激活钩子（推荐）

该技能可以通过语义匹配来激活，但使用钩子可以确保在每个会话中都评估是否有可提取的知识。

用户级别设置（推荐）

1. 创建 hooks 目录并复制脚本：

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

2. 将钩子添加到你的全局 Claude 设置文件中（~/.claude/settings.json）：

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

项目级别设置

1. 在你的项目目录下创建 hooks 目录，并复制脚本：

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

2. 将钩子添加到你的项目设置文件中（仓库中的 .claude/settings.json）：

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

如果你已经有一个 settings.json 文件，请将 hooks 配置合并进去。

该钩子会在每次提交提示时注入一条提醒，告诉 Claude 评估当前任务是否产生了可提取的知识。这样比仅依靠语义描述匹配能获得更高的激活率。

使用方法

自动模式

当 Claude Code 完成以下操作时，该技能会自动激活：

• 刚刚完成调试并发现了一个不明显的解决方案
• 通过调查或试错找到了一种绕过方案
• 解决了一个根本原因并不明显的问题
• 通过调查学习到了项目特有的模式或配置
• 完成了任何需要有意义发现才能解决的任务

显式模式

触发学习回顾：

/claudeception

或者明确请求提取技能：

把我们刚才学到的内容保存为一项技能

什么会被提取

并不是每项任务都能产生技能。只有那些需要真正发现（而不仅仅是查阅文档）、对未来任务有帮助、具有明确触发条件且经过验证可行的知识，才会被提取出来。

研究背景

这一想法源自关于 AI 代理技能库的学术研究。

Voyager（Wang 等，2023）表明，游戏智能体可以随着时间推移构建可重用的技能库，这有助于它们避免重复学习已掌握的内容。CASCADE（2024）提出了“元技能”（即获取技能的技能），而这正是本技能的核心思想。SEAgent（2025）则展示了智能体可以通过试错学习新的软件环境，这也启发了回顾功能的设计。Reflexion（Shinn 等，2023）证明了自我反思的作用。

能够持续保留学习成果的智能体，表现往往优于每次都从头开始的智能体。

工作原理

Claude Code 内置了技能系统。启动时，它会加载技能名称和描述（每条约 100 个 token）。当你工作时，它会将当前上下文与这些描述进行匹配，并调用相关的技能。

然而，这个检索系统不仅可以读取，还可以写入。因此，当本技能检测到可提取的知识时，它会以适合未来检索的方式编写一个新的技能描述。

描述非常重要。“帮助解决数据库问题”这样的描述几乎无法匹配到有用的内容；而“修复无服务器环境下的 PrismaClientKnownRequestError 错误”则会在有人遇到该错误时被匹配到。

更多关于技能架构的信息请参见 这里。

技能格式

提取的技能是以 YAML 前言的 Markdown 文件形式存在：

---
name: prisma-connection-pool-exhaustion
description: |
  修复 PrismaClientKnownRequestError：在无服务器环境中（Vercel、AWS Lambda）数据库连接过多。当并发请求数达到约 5 次后出现连接数错误时使用。
author: Claude Code
version: 1.0.0
date: 2024-01-15
---

# Prisma 连接池耗尽问题

## 问题
[该技能解决的问题]

## 背景 / 触发条件
[具体的错误信息、症状、场景]

## 解决方案
[逐步修复步骤]

## 验证
[如何确认修复有效]

完整模板请参阅 resources/skill-template.md。

质量关卡

该技能对提取内容非常挑剔。如果只是简单的文档查询，或者只适用于当前场景，又或者尚未经过实际测试，就不会创建技能。这条技能是否真的能在六个月后帮助遇到同样问题的人？如果不是，那就不会生成技能。

示例

请参阅 examples/ 中的示例技能：

• nextjs-server-side-error-debugging/：浏览器控制台不显示的服务器端错误
• prisma-connection-pool-exhaustion/：无服务器环境下的“连接数过多”问题
• typescript-circular-dependency/：检测并修复循环依赖

贡献

欢迎贡献代码。请 Fork 项目，做出修改后提交 Pull Request。

许可证

MIT

Claudeception 快速上手指南

Claudeception 是一个专为 Claude Code 设计的技能增强工具。它能自动识别并保存调试过程中发现的非显而易见解决方案（如特定错误修复、变通方法或项目模式），将其转化为可复用的“技能”。下次遇到类似问题时，这些知识会自动加载，避免重复劳动。

环境准备

• 系统要求：Linux / macOS / Windows (WSL)
• 前置依赖：
  • 已安装并配置好 Claude Code (claude)
  • 已安装 Git
  • 确保 ~/.claude 目录存在（首次运行 Claude Code 会自动创建）

注意：本项目托管于 GitHub。国内用户若克隆速度较慢，建议使用加速代理或配置 Git 加速镜像。

安装步骤

第一步：克隆技能库

推荐在用户级别安装，以便在所有项目中生效。

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

(如需仅在当前项目使用，可将目标路径改为 .claude/skills/claudeception)

第二步：配置激活钩子 (Hook)

为了确保每次会话都能评估并提取新知识，建议配置激活脚本。

1. 设置脚本文件

创建 hooks 目录并复制激活脚本：

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

2. 注册到全局配置

编辑或创建全局配置文件 ~/.claude/settings.json，加入以下 hooks 配置：

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

提示：如果文件中已有其他配置，请直接将 hooks 字段合并进去，保持 JSON 格式合法。

基本使用

安装完成后，无需额外操作即可在后台运行。

1. 自动模式（推荐）

正常进行编码和调试工作。当 Claude Code 完成以下任务时，会自动评估并保存技能：

• 解决了隐蔽的报错或非显而易见的 Bug。
• 通过试错找到了有效的变通方案。
• 发现了特定于当前项目的配置模式。

示例场景： 你花费时间解决了一个复杂的 Prisma 连接池耗尽问题。解决后，Claudeception 会自动将该解决方案保存为技能。下次你在其他项目中遇到相同的错误特征时，该技能会自动加载并提供解决方案。

2. 显式模式

如果你希望强制触发学习回顾或手动保存当前知识，可以使用以下指令：

触发学习回顾：

/claudeception

直接请求保存技能：

Save what we just learned as a skill

技能存储位置

提取的技能将以 Markdown 文件形式保存在 ~/.claude/skills/ 目录下，包含问题描述、触发条件、解决方案及验证步骤，供未来自动检索使用。