diff --git a/SKILL.md b/SKILL.md index 9e17b46..11ded91 100644 --- a/SKILL.md +++ b/SKILL.md @@ -2,12 +2,12 @@ name: claudeception description: | 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. + Always asks for user confirmation before creating any skill. 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. Identifies valuable knowledge and requests approval before saving. author: Claude Code -version: 3.0.0 +version: 4.1.0 allowed-tools: - Read - Write @@ -23,328 +23,184 @@ allowed-tools: # Claudeception -You are Claudeception: a continuous learning system that extracts reusable knowledge from work sessions and -codifies it into new Claude Code skills. This enables autonomous improvement over time. +A continuous learning system that extracts reusable knowledge from work sessions and codifies it into Claude Code skills, enabling autonomous improvement over time. -## Core Principle: Skill Extraction +## Core Principle -When working on tasks, continuously evaluate whether the current work contains extractable -knowledge worth preserving. Not every task produces a skill—be selective about what's truly -reusable and valuable. +Continuously evaluate whether current work contains extractable knowledge worth preserving. Be selective—not every task produces a skill. -## When to Extract a Skill +## User Confirmation Required -Extract a skill when you encounter: +**IMPORTANT**: Never create a skill without explicit user approval. Before writing any skill file: -1. **Non-obvious Solutions**: Debugging techniques, workarounds, or solutions that required - significant investigation and wouldn't be immediately apparent to someone facing the same - problem. +1. Identify the extractable knowledge +2. Present a brief summary to the user: + - What knowledge was identified + - Proposed skill name + - Why it's worth preserving +3. Ask: "Would you like me to create a skill for this?" +4. Only proceed if the user confirms -2. **Project-Specific Patterns**: Conventions, configurations, or architectural decisions - specific to this codebase that aren't documented elsewhere. +This ensures users maintain control over their skill library and prevents unwanted skill creation. -3. **Tool Integration Knowledge**: How to properly use a specific tool, library, or API in - ways that documentation doesn't cover well. +## When to Extract -4. **Error Resolution**: Specific error messages and their actual root causes/fixes, - especially when the error message is misleading. +Extract a skill when encountering: -5. **Workflow Optimizations**: Multi-step processes that can be streamlined or patterns - that make common tasks more efficient. +| Type | Description | +|------|-------------| +| **Non-obvious Solutions** | Debugging techniques or workarounds requiring significant investigation | +| **Project Patterns** | Codebase-specific conventions not documented elsewhere | +| **Tool Integration** | Undocumented ways to use tools, libraries, or APIs | +| **Error Resolution** | Misleading error messages with non-obvious root causes | +| **Workflow Optimizations** | Multi-step processes that can be streamlined | -## Skill Quality Criteria +## Quality Criteria -Before extracting, verify the knowledge meets these criteria: +Before extracting, verify the knowledge is: -- **Reusable**: Will this help with future tasks? (Not just this one instance) -- **Non-trivial**: Is this knowledge that requires discovery, not just documentation lookup? -- **Specific**: Can you describe the exact trigger conditions and solution? -- **Verified**: Has this solution actually worked, not just theoretically? +- **Reusable** — Helps future tasks, not just this instance +- **Non-trivial** — Requires discovery, not documentation lookup +- **Specific** — Has exact trigger conditions and solution +- **Verified** — Actually worked, not theoretical ## Extraction Process ### Step 1: Identify the Knowledge Analyze what was learned: -- What was the problem or task? +- What was the problem? - What was non-obvious about the solution? -- What would someone need to know to solve this faster next time? -- What are the exact trigger conditions (error messages, symptoms, contexts)? - -### Step 2: Research Best Practices (When Appropriate) - -Before creating the skill, search the web for current information when: - -**Always search for:** -- Technology-specific best practices (frameworks, libraries, tools) -- Current documentation or API changes -- Common patterns or solutions for similar problems -- Known gotchas or pitfalls in the problem domain -- Alternative approaches or solutions - -**When to search:** -- The topic involves specific technologies, frameworks, or tools -- You're uncertain about current best practices -- The solution might have changed after January 2025 (knowledge cutoff) -- There might be official documentation or community standards -- You want to verify your understanding is current - -**When to skip searching:** -- Project-specific internal patterns unique to this codebase -- Solutions that are clearly context-specific and wouldn't be documented -- Generic programming concepts that are stable and well-understood -- Time-sensitive situations where the skill needs to be created immediately - -**Search strategy:** -``` -1. Search for official documentation: "[technology] [feature] official docs 2026" -2. Search for best practices: "[technology] [problem] best practices 2026" -3. Search for common issues: "[technology] [error message] solution 2026" -4. Review top results and incorporate relevant information -5. Always cite sources in a "References" section of the skill -``` +- What are the exact trigger conditions (error messages, symptoms)? -**Example searches:** -- "Next.js getServerSideProps error handling best practices 2026" -- "Claude Code skill description semantic matching 2026" -- "React useEffect cleanup patterns official docs 2026" +### Step 2: Research Best Practices -**Integration with skill content:** -- Add a "References" section at the end of the skill with source URLs -- Incorporate best practices into the "Solution" section -- Include warnings about deprecated patterns in the "Notes" section -- Mention official recommendations where applicable +For technology-specific topics, search the web for current best practices before creating the skill. See `resources/research-workflow.md` for detailed search strategies. + +Skip searching for project-specific internal patterns or stable programming concepts. ### Step 3: Structure the Skill -Create a new skill with this structure: +Use the template in `resources/skill-template.md`. Key sections: ```markdown --- -name: [descriptive-kebab-case-name] +name: descriptive-kebab-case-name description: | - [Precise description including: (1) exact use cases, (2) trigger conditions like - specific error messages or symptoms, (3) what problem this solves. Be specific - enough that semantic matching will surface this skill when relevant.] -author: [original-author or "Claude Code"] + [Precise description with: (1) exact use cases, (2) trigger conditions + like error messages, (3) what problem this solves] +author: Claude Code version: 1.0.0 -date: [YYYY-MM-DD] +date: YYYY-MM-DD --- -# [Skill Name] +# Skill Name ## Problem -[Clear description of the problem this skill addresses] - -## Context / Trigger Conditions -[When should this skill be used? Include exact error messages, symptoms, or scenarios] - +## Context / Trigger Conditions ## Solution -[Step-by-step solution or knowledge to apply] - ## Verification -[How to verify the solution worked] - -## Example -[Concrete example of applying this skill] - ## Notes -[Any caveats, edge cases, or related considerations] - ## References -[Optional: Links to official documentation, articles, or resources that informed this skill] ``` ### Step 4: Write Effective Descriptions -The description field is critical for skill discovery. Include: +The description enables semantic discovery. Include: -- **Specific symptoms**: Exact error messages, unexpected behaviors -- **Context markers**: Framework names, file types, tool names +- **Specific symptoms**: Exact error messages, behaviors +- **Context markers**: Framework names, file types, tools - **Action phrases**: "Use when...", "Helps with...", "Solves..." -Example of a good description: -``` +**Good example:** +```yaml description: | - Fix for "ENOENT: no such file or directory" errors when running npm scripts - in monorepos. Use when: (1) npm run fails with ENOENT in a workspace, - (2) paths work in root but not in packages, (3) symlinked dependencies - cause resolution failures. Covers node_modules resolution in Lerna, - Turborepo, and npm workspaces. + Fix for "ENOENT: no such file or directory" in monorepo npm scripts. + Use when: (1) npm run fails with ENOENT in workspace, (2) paths work + in root but not packages. Covers Lerna, Turborepo, npm workspaces. ``` -### Step 5: Save the Skill - -Save new skills to the appropriate location: - -- **Project-specific skills**: `.claude/skills/[skill-name]/SKILL.md` -- **User-wide skills**: `~/.claude/skills/[skill-name]/SKILL.md` - -Include any supporting scripts in a `scripts/` subdirectory if the skill benefits from -executable helpers. - -## Retrospective Mode - -When `/claudeception` is invoked at the end of a session: - -1. **Review the Session**: Analyze the conversation history for extractable knowledge -2. **Identify Candidates**: List potential skills with brief justifications -3. **Prioritize**: Focus on the highest-value, most reusable knowledge -4. **Extract**: Create skills for the top candidates (typically 1-3 per session) -5. **Summarize**: Report what skills were created and why - -## Self-Reflection Prompts - -Use these prompts during work to identify extraction opportunities: - -- "What did I just learn that wasn't obvious before starting?" -- "If I faced this exact problem again, what would I wish I knew?" -- "What error message or symptom led me here, and what was the actual cause?" -- "Is this pattern specific to this project, or would it help in similar projects?" -- "What would I tell a colleague who hits this same issue?" - -## Memory Consolidation - -When extracting skills, also consider: - -1. **Combining Related Knowledge**: If multiple related discoveries were made, consider - whether they belong in one comprehensive skill or separate focused skills. - -2. **Updating Existing Skills**: Check if an existing skill should be updated rather than - creating a new one. - -3. **Cross-Referencing**: Note relationships between skills in their documentation. - -## Quality Gates - -Before finalizing a skill, verify: +### Step 5: Request User Confirmation -- [ ] Description contains specific trigger conditions -- [ ] Solution has been verified to work -- [ ] Content is specific enough to be actionable -- [ ] Content is general enough to be reusable -- [ ] No sensitive information (credentials, internal URLs) is included -- [ ] Skill doesn't duplicate existing documentation or skills -- [ ] Web research conducted when appropriate (for technology-specific topics) -- [ ] References section included if web sources were consulted -- [ ] Current best practices (post-2025) incorporated when relevant +Before creating the skill, present a summary and ask for approval: -## Anti-Patterns to Avoid - -- **Over-extraction**: Not every task deserves a skill. Mundane solutions don't need preservation. -- **Vague descriptions**: "Helps with React problems" won't surface when needed. -- **Unverified solutions**: Only extract what actually worked. -- **Documentation duplication**: Don't recreate official docs; link to them and add what's missing. -- **Stale knowledge**: Mark skills with versions and dates; knowledge can become outdated. - -## Skill Lifecycle +``` +I identified extractable knowledge: -Skills should evolve: +**Topic**: [brief description] +**Proposed skill**: `[skill-name]` +**Why**: [1-2 sentence justification] -1. **Creation**: Initial extraction with documented verification -2. **Refinement**: Update based on additional use cases or edge cases discovered -3. **Deprecation**: Mark as deprecated when underlying tools/patterns change -4. **Archival**: Remove or archive skills that are no longer relevant +Would you like me to create this skill? +``` -## Example: Complete Extraction Flow +**Only proceed if the user confirms.** If declined, do not create the skill. -**Scenario**: While debugging a Next.js app, you discover that `getServerSideProps` errors -aren't showing in the browser console because they're server-side, and the actual error is -in the terminal. +### Step 6: Save the Skill -**Step 1 - Identify the Knowledge**: -- Problem: Server-side errors don't appear in browser console -- Non-obvious aspect: Expected behavior for server-side code in Next.js -- Trigger: Generic error page with empty browser console +After user approval: -**Step 2 - Research Best Practices**: -Search: "Next.js getServerSideProps error handling best practices 2026" -- Found official docs on error handling -- Discovered recommended patterns for try-catch in data fetching -- Learned about error boundaries for server components +- **Project-specific**: `.claude/skills/[skill-name]/SKILL.md` +- **User-wide**: `~/.claude/skills/[skill-name]/SKILL.md` -**Step 3-5 - Structure and Save**: +Include supporting scripts in a `scripts/` subdirectory when helpful. -**Extraction**: +## Retrospective Mode -```markdown ---- -name: nextjs-server-side-error-debugging -description: | - Debug getServerSideProps and getStaticProps errors in Next.js. Use when: - (1) Page shows generic error but browser console is empty, (2) API routes - return 500 with no details, (3) Server-side code fails silently. Check - terminal/server logs instead of browser for actual error messages. -author: Claude Code -version: 1.0.0 -date: 2024-01-15 ---- +When `/claudeception` is invoked: -# Next.js Server-Side Error Debugging +1. **Review** — Analyze conversation history for extractable knowledge +2. **Identify** — List potential skills with brief justifications +3. **Prioritize** — Focus on highest-value, most reusable knowledge +4. **Confirm** — Present candidates and ask which ones to create +5. **Extract** — Create only the skills the user approved +6. **Summarize** — Report what was created and why -## Problem -Server-side errors in Next.js don't appear in the browser console, making -debugging frustrating when you're looking in the wrong place. +## Automatic Triggers -## Context / Trigger Conditions -- Page displays "Internal Server Error" or custom error page -- Browser console shows no errors -- Using getServerSideProps, getStaticProps, or API routes -- Error only occurs on navigation/refresh, not on client-side transitions +Invoke this skill immediately after completing a task when ANY apply: -## Solution -1. Check the terminal where `npm run dev` is running—errors appear there -2. For production, check server logs (Vercel dashboard, CloudWatch, etc.) -3. Add try-catch with console.error in server-side functions for clarity -4. Use Next.js error handling: return `{ notFound: true }` or `{ redirect: {...} }` - instead of throwing +- Solution required >10 minutes of investigation not found in docs +- Fixed an error where the message was misleading +- Found a workaround requiring experimentation +- Discovered project-specific setup differing from standard patterns +- Tried multiple approaches before finding what worked -## Verification -After checking terminal, you should see the actual stack trace with file -and line numbers. +## Explicit Invocation -## Notes -- This applies to all server-side code in Next.js, not just data fetching -- In development, Next.js sometimes shows a modal with partial error info -- The `next.config.js` option `reactStrictMode` can cause double-execution - that makes debugging confusing +Also invoke when: +- User runs `/claudeception` +- User says "save this as a skill" or similar +- User asks "what did we learn?" -## References -- [Next.js Data Fetching: getServerSideProps](https://nextjs.org/docs/pages/building-your-application/data-fetching/get-server-side-props) -- [Next.js Error Handling](https://nextjs.org/docs/pages/building-your-application/routing/error-handling) -``` +## Self-Check -## Integration with Workflow +After completing significant tasks, ask: +- "Did I spend meaningful time investigating something?" +- "Would future-me benefit from this documented?" +- "Was the solution non-obvious from documentation alone?" -### Automatic Trigger Conditions +If yes to any, invoke this skill immediately. -Invoke this skill immediately after completing a task when ANY of these apply: +## Additional Resources -1. **Non-obvious debugging**: The solution required >10 minutes of investigation and - wasn't found in documentation -2. **Error resolution**: Fixed an error where the error message was misleading or the - root cause wasn't obvious -3. **Workaround discovery**: Found a workaround for a tool/framework limitation that - required experimentation -4. **Configuration insight**: Discovered project-specific setup that differs from - standard patterns -5. **Trial-and-error success**: Tried multiple approaches before finding what worked +### Reference Files -### Explicit Invocation +Consult these for detailed guidance: -Also invoke when: -- User runs `/claudeception` to review the session -- User says "save this as a skill" or similar -- User asks "what did we learn?" +| File | Contents | +|------|----------| +| `resources/skill-template.md` | Complete skill template with checklist | +| `resources/research-workflow.md` | Web research strategies and citation format | +| `resources/quality-guidelines.md` | Quality gates, anti-patterns, skill lifecycle | +| `resources/research-references.md` | Academic background (Voyager, CASCADE, etc.) | -### Self-Check After Each Task +### Working Examples -After completing any significant task, ask yourself: -- "Did I just spend meaningful time investigating something?" -- "Would future-me benefit from having this documented?" -- "Was the solution non-obvious from documentation alone?" +Real extracted skills in `examples/`: -If yes to any, invoke this skill immediately. +- `nextjs-server-side-error-debugging/` — Server-side error debugging +- `prisma-connection-pool-exhaustion/` — Database connection issues +- `typescript-circular-dependency/` — Import cycle resolution -Remember: The goal is continuous, autonomous improvement. Every valuable discovery -should have the opportunity to benefit future work sessions. +Study these as models for effective skill structure. diff --git a/resources/quality-guidelines.md b/resources/quality-guidelines.md new file mode 100644 index 0000000..30691b4 --- /dev/null +++ b/resources/quality-guidelines.md @@ -0,0 +1,137 @@ +# Quality Guidelines + +Comprehensive guidance for maintaining skill quality throughout the lifecycle. + +## Quality Gates + +Before finalizing a skill, verify: + +### Content Quality +- [ ] Description contains specific trigger conditions +- [ ] Solution has been verified to work +- [ ] Content is specific enough to be actionable +- [ ] Content is general enough to be reusable +- [ ] No sensitive information (credentials, internal URLs) included + +### Research Quality +- [ ] Web research conducted when appropriate (for technology-specific topics) +- [ ] References section included if web sources were consulted +- [ ] Current best practices incorporated when relevant +- [ ] Skill doesn't duplicate existing documentation + +### Structure Quality +- [ ] Name is descriptive and uses kebab-case +- [ ] Description enables semantic matching +- [ ] All template sections completed +- [ ] Code examples are complete and tested +- [ ] Verification steps are included + +## Anti-Patterns to Avoid + +### Over-extraction +Not every task deserves a skill. Mundane solutions don't need preservation. + +**Signs of over-extraction:** +- The solution is in official documentation +- It took <5 minutes to figure out +- It's a one-off fix unlikely to recur + +### Vague Descriptions +"Helps with React problems" won't surface when needed. + +**Bad:** `description: Helps with database issues` +**Good:** `description: Fix for "Connection pool exhausted" in Prisma with serverless. Use when: (1) queries timeout after cold start...` + +### Unverified Solutions +Only extract what actually worked. + +**Before extracting, confirm:** +- The solution resolved the original problem +- No new issues were introduced +- The fix is reproducible + +### Documentation Duplication +Don't recreate official docs; link to them and add what's missing. + +**Instead of copying docs:** +- Link to official documentation +- Add context about when the documented solution doesn't work +- Include gotchas not mentioned in docs + +### Stale Knowledge +Mark skills with versions and dates; knowledge becomes outdated. + +**Include in every skill:** +- `version: 1.0.0` in frontmatter +- `date: YYYY-MM-DD` of creation +- Technology versions in Notes section + +## Skill Lifecycle + +### 1. Creation +Initial extraction with documented verification. + +**Checklist:** +- Problem clearly identified +- Solution verified working +- Trigger conditions documented +- Quality gates passed + +### 2. Refinement +Update based on additional use cases or edge cases discovered. + +**When to refine:** +- New edge cases discovered +- Better solutions found +- Related problems identified +- User feedback received + +### 3. Deprecation +Mark as deprecated when underlying tools/patterns change. + +**Deprecation notice format:** +```markdown +> **DEPRECATED (YYYY-MM-DD)**: This skill applies to [tool] v1.x. +> For v2.x and later, see `[new-skill-name]`. +``` + +### 4. Archival +Remove or archive skills that are no longer relevant. + +**Archive when:** +- Technology is no longer used +- Better alternatives exist +- Problem no longer occurs in modern versions + +## Self-Reflection Prompts + +Use these during work to identify extraction opportunities: + +- "What did I just learn that wasn't obvious before starting?" +- "If I faced this exact problem again, what would I wish I knew?" +- "What error message or symptom led me here, and what was the actual cause?" +- "Is this pattern specific to this project, or would it help in similar projects?" +- "What would I tell a colleague who hits this same issue?" + +## Memory Consolidation + +When extracting skills, consider: + +### Combining Related Knowledge +If multiple related discoveries were made, evaluate whether they belong in: +- One comprehensive skill (if tightly coupled) +- Separate focused skills (if independently useful) + +### Updating Existing Skills +Check if an existing skill should be updated rather than creating a new one: +- Search existing skills for related topics +- Prefer updating over duplicating +- Note relationships between skills + +### Cross-Referencing +Document relationships between skills: +```markdown +## Related Skills +- `related-skill-name` — Handles the X case +- `another-skill` — Alternative approach for Y +``` diff --git a/resources/research-workflow.md b/resources/research-workflow.md new file mode 100644 index 0000000..f04bf74 --- /dev/null +++ b/resources/research-workflow.md @@ -0,0 +1,85 @@ +# Research Workflow + +Detailed guidance for conducting web research before creating skills. + +## When to Search + +**Always search for:** +- Technology-specific best practices (frameworks, libraries, tools) +- Current documentation or API changes +- Common patterns or solutions for similar problems +- Known gotchas or pitfalls in the problem domain +- Alternative approaches or solutions + +**When to search:** +- The topic involves specific technologies, frameworks, or tools +- Uncertainty about current best practices +- The solution might have changed after knowledge cutoff +- There might be official documentation or community standards +- Verification of understanding is needed + +**When to skip searching:** +- Project-specific internal patterns unique to this codebase +- Solutions that are clearly context-specific and wouldn't be documented +- Generic programming concepts that are stable and well-understood +- Time-sensitive situations where the skill needs to be created immediately + +## Search Strategy + +``` +1. Search for official documentation: "[technology] [feature] official docs [year]" +2. Search for best practices: "[technology] [problem] best practices [year]" +3. Search for common issues: "[technology] [error message] solution [year]" +4. Review top results and incorporate relevant information +5. Always cite sources in a "References" section of the skill +``` + +## Example Searches + +- "Next.js getServerSideProps error handling best practices 2026" +- "Claude Code skill description semantic matching 2026" +- "React useEffect cleanup patterns official docs 2026" +- "Prisma connection pool serverless best practices 2026" + +## Integrating Research into Skills + +### References Section + +Add a "References" section at the end of the skill with source URLs: + +```markdown +## References + +- [Official Documentation Title](https://example.com/docs) +- [Helpful Blog Post](https://example.com/blog/post) +- [Stack Overflow Answer](https://stackoverflow.com/questions/...) +``` + +### Best Practices Integration + +- Incorporate best practices into the "Solution" section +- Include warnings about deprecated patterns in the "Notes" section +- Mention official recommendations where applicable +- Note when community practices differ from official guidance + +### Citation Format + +For academic references: + +``` +@misc{skill-name, + title={Skill Title}, + author={Claude Code}, + year={2026}, + note={Based on [technology] documentation and community best practices} +} +``` + +## Quality Indicators + +Good research produces skills that: + +- Reference current (not outdated) documentation +- Include official recommendations where available +- Note version-specific caveats +- Distinguish between official guidance and community practices