Skip to content

Commit a0dbdc7

Browse files
justfinethankujustfinethanku
authored
Merge pull request NateBJones-Projects#87 from jaredirish/recipes/claudeception
[recipes] Claudeception: continuous learning system that creates new skills
2 parents c7f766d + b7fad41 commit a0dbdc7

3 files changed

Lines changed: 382 additions & 0 deletions

File tree

‎recipes/claudeception/README.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Claudeception
2+
3+
*Skills that create other skills.*
4+
5+
A continuous learning system that extracts reusable knowledge from work sessions and codifies it into new AI coding tool skills. When you discover something non-obvious (a debugging technique, a workaround, an error resolution), Claudeception evaluates whether it's worth preserving and creates a structured skill file automatically.
6+
7+
**This is the meta-skill.** Every other recipe in OB1 does a specific thing. This one creates new things from the act of working.
8+
9+
## What It Does
10+
11+
During normal work, Claudeception watches for extractable knowledge:
12+
13+
| Discovery Type | Example | What Gets Created |
14+
|----------------|---------|-------------------|
15+
| Non-obvious debugging | Spent 20 min finding that n8n Code node blocks `process.env` | Skill: "n8n-code-node-sandbox-limits" |
16+
| Error resolution | Misleading error led to wrong fix path | Skill with exact error message as trigger |
17+
| Workflow optimization | Found a 3-step process that replaces a 10-step one | Skill documenting the shortcut |
18+
| Tool integration | Discovered undocumented API behavior | Skill with the actual behavior documented |
19+
20+
Before creating, it searches Open Brain to check if the knowledge already exists. After creating, it captures the new skill to Open Brain so future sessions can find it.
21+
22+
## Prerequisites
23+
24+
- Working Open Brain setup ([guide](../../docs/01-getting-started.md))
25+
- Claude Code installed and working
26+
- Open Brain MCP tools connected (`search_thoughts`, `capture_thought`)
27+
28+
### Credential Tracker
29+
30+
```
31+
From your existing Open Brain setup:
32+
- Project URL: _______________
33+
- Open Brain MCP server connected: yes / no
34+
35+
No additional credentials needed for this recipe.
36+
```
37+
38+
## Steps
39+
40+
### 1. Create the skill directory
41+
42+
```bash
43+
mkdir -p ~/.claude/skills/claudeception
44+
```
45+
46+
### 2. Copy the skill file
47+
48+
```bash
49+
cp claudeception.skill.md ~/.claude/skills/claudeception/SKILL.md
50+
```
51+
52+
### 3. Verify Claude Code picks up the skill
53+
54+
Restart Claude Code. To verify, say "what did we learn?" or run `/claudeception` at the end of a work session. Claude should reference the Claudeception methodology.
55+
56+
### 4. Work normally
57+
58+
Claudeception fires automatically after tasks involving non-obvious investigation. You can also trigger it manually:
59+
60+
- `/claudeception` at end of session (retrospective mode)
61+
- "save this as a skill" after a discovery
62+
- "what did we learn?" to review the session
63+
64+
### 5. Review created skills
65+
66+
New skills appear in `~/.claude/skills/[skill-name]/SKILL.md`. Each includes:
67+
- Problem description
68+
- Trigger conditions (exact error messages, symptoms)
69+
- Step-by-step solution
70+
- Verification steps
71+
- Quality gate checklist
72+
73+
## Expected Outcome
74+
75+
When working correctly, you should see:
76+
77+
- After non-obvious debugging sessions, a prompt asking whether to extract the knowledge
78+
- Before creating a skill, an Open Brain search confirming no duplicate exists
79+
- New skill files appearing in `~/.claude/skills/` with structured content
80+
- After creation, the skill captured to Open Brain via `capture_thought`
81+
- In future sessions, the skill fires automatically when trigger conditions match
82+
83+
A typical week of active development produces 1-3 new skills. Not every session produces one, and that's correct. Over-extraction is an anti-pattern.
84+
85+
## Open Brain Integration
86+
87+
Claudeception connects to Open Brain at two points:
88+
89+
**Before creating (search):** Queries `search_thoughts` with keywords from the discovery. If related knowledge already exists in Open Brain, it updates the existing skill instead of creating a duplicate.
90+
91+
**After creating (capture):** Saves the new skill to Open Brain via `capture_thought` with tags like `skill-created`, the skill name, and relevant domain tags. This means future sessions across any project can find the skill via semantic search.
92+
93+
**Example flow:**
94+
95+
```
96+
Discovery: n8n Code node blocks process.env
97+
-> search_thoughts("n8n code node sandbox process.env")
98+
-> No match found
99+
-> Create skill: ~/.claude/skills/n8n-code-node-sandbox/SKILL.md
100+
-> capture_thought("New skill created: n8n-code-node-sandbox.
101+
n8n Code node v2 sandbox blocks process.env, fetch(), require().
102+
Only pure JS transforms on $input/$json work.")
103+
```
104+
105+
## Adapting for Other Tools
106+
107+
The core pattern (discover, evaluate, extract, verify) works with any AI coding tool that supports custom instructions or skill files:
108+
109+
- **Cursor:** Save to `.cursorrules` or project-level rules
110+
- **Windsurf:** Save to `.windsurfrules`
111+
- **Codex:** Save to `AGENTS.md` or codex instructions
112+
113+
The skill file format may differ, but the extraction process and quality criteria are universal.
114+
115+
## Troubleshooting
116+
117+
**Issue:** Claudeception fires too often, creating low-value skills.
118+
**Solution:** Check the quality criteria in the skill file. A skill must be reusable, non-trivial, specific, and verified. If it only helps with one instance and won't recur, it's not a skill.
119+
120+
**Issue:** Skills aren't being discovered in future sessions.
121+
**Solution:** Check the `description` field in the skill's frontmatter. It needs specific trigger conditions (error messages, symptoms, tool names) for Claude Code's semantic matching to surface it. Vague descriptions like "helps with React" won't match.
122+
123+
**Issue:** Open Brain search returns nothing but a similar skill exists locally.
124+
**Solution:** The skill may have been created before Open Brain integration was added. Run `/claudeception` in retrospective mode to capture existing skills to Open Brain.
125+
126+
**Issue:** Too many skills accumulating (30+).
127+
**Solution:** Review the 5 least-recently-modified skills. If they haven't fired in 30+ days, either the trigger conditions are too narrow (update them) or the knowledge is no longer relevant (deprecate). Add a `deprecated: true` note to the frontmatter rather than deleting.
128+
129+
---
130+
131+
*The meta-skill. Skills that create other skills.*

‎recipes/claudeception/claudeception.skill.md‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
---
2+
name: claudeception
3+
description: |
4+
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 skills
8+
when valuable, reusable knowledge is identified. Integrates with Open Brain to prevent
9+
duplicates and share knowledge across sessions.
10+
author: Jared Irish
11+
version: 2.0.0
12+
---
13+
14+
# Claudeception
15+
16+
A continuous learning system that extracts reusable knowledge from work sessions and
17+
codifies it into new skills. This enables autonomous improvement over time.
18+
19+
## Core Principle
20+
21+
When working on tasks, continuously evaluate whether the current work contains extractable
22+
knowledge worth preserving. Not every task produces a skill. Be selective about what's truly
23+
reusable and valuable.
24+
25+
## When to Extract
26+
27+
Extract when you encounter:
28+
29+
1. **Non-obvious Solutions**: Debugging that required significant investigation and wouldn't
30+
be immediately apparent to someone facing the same problem.
31+
2. **Error Resolution**: Specific error messages and their actual root causes, especially
32+
when the error message is misleading.
33+
3. **Tool Integration Knowledge**: How to properly use a tool, library, or API in ways
34+
that documentation doesn't cover well.
35+
4. **Workflow Optimizations**: Multi-step processes that can be streamlined.
36+
5. **Project-Specific Patterns**: Conventions or decisions specific to a codebase.
37+
38+
## Quality Criteria
39+
40+
Before extracting, verify:
41+
42+
- **Reusable**: Will this help with future tasks, not just this one instance?
43+
- **Non-trivial**: Does this require discovery, not just documentation lookup?
44+
- **Specific**: Can you describe exact trigger conditions and solution?
45+
- **Verified**: Has this solution actually worked?
46+
47+
## Extraction Process
48+
49+
### Step 1: Search Open Brain for Existing Knowledge
50+
51+
Before creating anything, check if this knowledge already exists:
52+
53+
```
54+
search_thoughts({ "query": "[keywords from the discovery]", "match_count": 5 })
55+
```
56+
57+
| Search Result | Action |
58+
|---------------|--------|
59+
| Strong match found | Update the existing skill instead of creating new |
60+
| Partial match | Create new, add "See also" cross-reference |
61+
| No match | Create new |
62+
63+
### Step 2: Check for Existing Skills
64+
65+
Search local skill directories for related skills:
66+
67+
```
68+
Look in:
69+
.claude/skills/ (project-level)
70+
~/.claude/skills/ (user-level)
71+
```
72+
73+
| Found | Action |
74+
|-------|--------|
75+
| Nothing related | Create new |
76+
| Same trigger, same fix | Update existing (bump version) |
77+
| Same trigger, different cause | Create new, link both ways |
78+
| Partial overlap | Update existing with new variant subsection |
79+
80+
### Step 3: Research Current Best Practices
81+
82+
When the topic involves specific technologies or tools, search the web for current documentation
83+
and best practices before creating the skill. Include a References section if external sources
84+
were consulted. Skip this for project-specific internal patterns.
85+
86+
### Step 4: Structure the Skill
87+
88+
```markdown
89+
---
90+
name: [descriptive-kebab-case-name]
91+
description: |
92+
[Precise description with: (1) exact use cases, (2) trigger conditions like
93+
specific error messages, (3) what problem this solves.]
94+
author: [your name]
95+
version: 1.0.0
96+
---
97+
98+
# [Skill Name]
99+
100+
## Problem
101+
[Clear description of the problem]
102+
103+
## Context / Trigger Conditions
104+
[When should this fire? Include exact error messages, symptoms, scenarios]
105+
106+
## Solution
107+
[Step-by-step solution]
108+
109+
## Verification
110+
[How to verify it worked]
111+
112+
## Example
113+
[Concrete example of applying this skill]
114+
115+
## Notes
116+
[Caveats, edge cases, related considerations]
117+
118+
## References
119+
[Links to docs or resources, if any]
120+
```
121+
122+
### Step 5: Save the Skill
123+
124+
Save to the appropriate location:
125+
- **Project-specific**: `.claude/skills/[skill-name]/SKILL.md`
126+
- **User-wide**: `~/.claude/skills/[skill-name]/SKILL.md`
127+
128+
### Step 6: Capture to Open Brain
129+
130+
After creating the skill, save it to Open Brain so future sessions can find it:
131+
132+
```
133+
capture_thought({
134+
"content": "New skill created: [skill-name]. [1-2 sentence summary of what it solves].
135+
Trigger: [exact trigger condition]. Location: ~/.claude/skills/[name]/SKILL.md"
136+
})
137+
```
138+
139+
### Step 7: Quality Gate Checklist
140+
141+
Before finalizing, verify:
142+
143+
- [ ] Description contains specific trigger conditions
144+
- [ ] Solution has been verified to work
145+
- [ ] Specific enough to be actionable
146+
- [ ] General enough to be reusable
147+
- [ ] No credentials or internal URLs included
148+
- [ ] Doesn't duplicate existing skills
149+
- [ ] Open Brain searched before creating
150+
- [ ] Open Brain captured after creating
151+
152+
## Retrospective Mode
153+
154+
When `/claudeception` is invoked at session end:
155+
156+
1. Review the session for extractable knowledge
157+
2. List candidates with brief justifications
158+
3. Focus on highest-value, most reusable knowledge
159+
4. Extract skills for top candidates (typically 1-3 per session)
160+
5. Report what was created and why
161+
162+
## Self-Reflection Prompts
163+
164+
Use during work to spot extraction opportunities:
165+
166+
- "What did I just learn that wasn't obvious before starting?"
167+
- "If I faced this exact problem again, what would I wish I knew?"
168+
- "What error message led me here, and what was the actual cause?"
169+
- "Is this pattern specific to this project, or would it help elsewhere?"
170+
171+
## Example: Complete Extraction Flow
172+
173+
**Scenario**: While deploying n8n workflows via API, you discover that the POST endpoint
174+
rejects requests containing a `tags` field (returns "request/body/tags is read-only"),
175+
even though the GET response includes tags. The API also uses a different key than
176+
what's stored in the server's .env file.
177+
178+
**Step 1 - Search Open Brain**: `search_thoughts("n8n workflow API tags read-only")`
179+
No match found.
180+
181+
**Step 2 - Check existing skills**: Search `~/.claude/skills/` for n8n-related skills.
182+
Found `n8n-docker-troubleshooting` but it covers different issues (Code node sandbox).
183+
184+
**Step 3 - Structure the skill**:
185+
186+
```markdown
187+
---
188+
name: n8n-workflow-api-quirks
189+
description: |
190+
Fix n8n REST API issues when importing/updating workflows. Use when:
191+
(1) POST /api/v1/workflows returns "tags is read-only",
192+
(2) API key from .env returns 401 but MCP config key works,
193+
(3) PATCH doesn't update workflow code (need delete + recreate).
194+
author: Jared Irish
195+
version: 1.0.0
196+
---
197+
# n8n Workflow API Quirks
198+
## Problem
199+
n8n's REST API has undocumented constraints...
200+
```
201+
202+
**Step 4 - Save**: `~/.claude/skills/n8n-workflow-api-quirks/SKILL.md`
203+
204+
**Step 5 - Capture to Open Brain**: Records the skill's existence for cross-session discovery.
205+
206+
## Anti-Patterns
207+
208+
- **Over-extraction**: Not every task deserves a skill. Mundane solutions don't need preserving.
209+
- **Vague descriptions**: "Helps with React" won't surface when needed.
210+
- **Unverified solutions**: Only extract what actually worked.
211+
- **Documentation duplication**: Don't recreate official docs. Link to them, add what's missing.
212+
- **Skill hoarding**: If you have 30+ skills, review the 5 least-recently-modified for deprecation.
213+
214+
## Skill Lifecycle
215+
216+
1. **Creation**: Initial extraction with verified solution
217+
2. **Refinement**: Update when additional use cases or edge cases are discovered
218+
3. **Deprecation**: Mark deprecated when tools or patterns change
219+
4. **Archival**: Remove skills that are no longer relevant
220+
221+
## Automatic Triggers
222+
223+
Invoke this skill after completing a task when ANY of these apply:
224+
225+
1. Solution required >10 minutes of investigation not found in documentation
226+
2. Fixed an error where the error message was misleading
227+
3. Found a workaround for a tool limitation that required experimentation
228+
4. Discovered configuration that differs from standard patterns
229+
5. Tried multiple approaches before finding what worked
230+
231+
Also invoke when the user runs `/claudeception`, says "save this as a skill", or asks "what did we learn?"

‎recipes/claudeception/metadata.json‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{
2+
"name": "Claudeception",
3+
"description": "Continuous learning system that extracts reusable knowledge from work sessions and creates new skills. Skills that create other skills. Integrates with Open Brain to search for existing knowledge before creating and capture new skills after.",
4+
"category": "recipes",
5+
"author": {
6+
"name": "Jared Irish",
7+
"github": "jaredirish"
8+
},
9+
"version": "1.0.0",
10+
"requires": {
11+
"open_brain": true,
12+
"services": [],
13+
"tools": ["Claude Code"]
14+
},
15+
"tags": ["skills", "learning", "extraction", "meta", "self-improving", "knowledge", "continuous-learning"],
16+
"difficulty": "intermediate",
17+
"estimated_time": "10 minutes",
18+
"created": "2026-03-19",
19+
"updated": "2026-03-19"
20+
}

0 commit comments

Comments
 (0)