Claudeception

Continuous learning system that extracts reusable knowledge from work sessions into Claude Code skills. Each extracted skill makes future sessions smarter.

When to Extract

Extract when you encounter:

1. Non-obvious solutions — Required >10 min investigation, not in docs
2. Error resolution — Misleading error messages, non-obvious root causes
3. Workaround discovery — Tool/framework limitations requiring experimentation
4. Configuration insights — Project-specific setups differing from standard
5. Trial-and-error success — Multiple approaches before finding what worked
6. Self-critique catches — A predicted risk actually materialized (high-value signal)
7. Path efficiency insights — A systemic execution pattern worth improving

Dual-Track Classification

Before creating, classify the knowledge:

This determines the skill's section structure.

Extraction Process

Step 1: Overlap Detection (BEFORE creating)

Search existing skills for overlap across 5 dimensions:

Scoring: Count matching dimensions.

Why: Two skills describing the same problem will drift apart. Update rather than duplicate.

Step 2: Research (When Appropriate)

Search the web when the topic involves specific technologies, frameworks, or APIs. Skip for project-specific internal patterns. Cite sources in a References section.

Step 3: Structure the Skill

Use this template — adapt sections based on track:

---
name: [descriptive-kebab-case-name]
description: |
  [Trigger conditions ONLY. Start with "Use when...". Include specific symptoms,
  error messages, contexts. NEVER summarize the skill's workflow here.]
---

# [Skill Name]

## Problem / Context
[Bug track: What broke. Knowledge track: What situation prompted this.]

## Symptoms / When to Apply
[Bug track: Observable symptoms. Knowledge track: Conditions where this applies.]

## Solution / Guidance
[Step-by-step fix or recommended practice with code examples.]

## Prevention / Why This Matters
[Bug track: How to avoid recurrence. Knowledge track: Impact of following/not following.]

## Notes
[Caveats, edge cases, See also: links to related skills]

## References
[Optional: URLs to official docs or resources]

Step 4: Write Effective Descriptions (CSO)

Description = Triggering conditions ONLY. Never summarize the workflow.

Why: Testing revealed that descriptions summarizing workflow cause agents to follow the description instead of reading the full skill. A description saying "code review between tasks" caused agents to do ONE review, when the skill required two.

# BAD: Summarizes workflow — agent shortcuts to this
description: Use when executing plans — dispatches subagent per task with code review

# GOOD: Trigger conditions only — agent reads the full skill
description: Use when executing implementation plans with independent tasks

Format rules:

• Start with "Use when..."
• Include specific symptoms, error messages, contexts
• Keep under 500 characters
• Third person (injected into system prompt)
• Include technology names if skill is technology-specific

Step 5: Discoverability Check

After creating a skill, verify:

1. The description contains keywords someone would search for
2. The name is descriptive (verb-first preferred: fixing-X, not X-fix)
3. If the project has a CLAUDE.md, consider whether it should reference this skill category

Step 6: Save

• Project-specific: .claude/skills/[skill-name]/SKILL.md
• User-wide: ~/.claude/skills/[skill-name]/SKILL.md
• Heavy reference (>100 lines) goes in references/ subdirectory
• Reusable scripts go in scripts/ subdirectory

Quality Gates

Before finalizing:

• Description is trigger-only, no workflow summary (CSO)
• Solution verified to work (not theoretical)
• Specific enough to be actionable
• General enough to be reusable
• No sensitive information
• Overlap check completed (Step 1)
• No duplicate of existing skill or official docs

Anti-Patterns

Retrospective Mode

When /claudeception is invoked at session end:

1. Review conversation for extractable knowledge
2. List candidates with brief justifications
3. Prioritize highest-value, most reusable (1-3 per session)
4. Extract using the process above
5. Summarize what was created and why
6. Path Efficiency Analysis (enhanced retrospective):

Path Efficiency Analysis

After extracting skills, analyze the session's execution trajectory:

Path Efficiency Questions:
  1. Recovery Rate: Did I recover from errors efficiently?
     - Count error paths that led to correct recovery vs total errors
  2. Repetitiveness: Did I repeat any failed approach?
     - Flag any approach tried more than once without modification
  3. Most Expensive Wrong Path: What was the costliest detour?
     - Could it have been avoided with a Self-Critique Checkpoint?
     - What early warning signal was missed?
  4. Simulate-Before-Execute: Would pre-simulation have helped?
     - Identify decisions where simulating 2-3 options would have saved time

If Path Efficiency Analysis reveals a systemic issue (not just a one-off mistake), extract it as a skill with trigger conditions for future sessions.

Self-Critique Checkpoint (Proactive Evolution)

Before executing any non-trivial step during a session, briefly evaluate:

1. "What is the theoretical basis for this approach?"
2. "What are the top 3 risks?"
3. "What signal would tell me this is wrong BEFORE I finish?"

After getting intermediate results:

4. "Did any predicted risks materialize?"
5. "Is the intermediate result consistent with expectations?"
6. "Should I continue or pivot?"

If a Self-Critique Catchpoint catches a risk that actually materialized, the insight is high-priority for extraction — it means the agent predicted correctly but didn't act on its own prediction.

Self-Check Prompts

After completing any significant task:

• "Did I just spend meaningful time investigating something?"
• "Would future-me benefit from having this documented?"
• "Was the solution non-obvious from documentation alone?"
• "Did I simulate before executing? If not, would it have helped?"
• "What was my most expensive wrong path this session?"

If yes to any of the first three, extract now.

Integration with Other Skills