From 2f3e06c9658fef0572cedda1ece50fefc564e90b Mon Sep 17 00:00:00 2001 From: Ethan Stark Date: Mon, 26 Jan 2026 16:21:43 -0500 Subject: [PATCH 01/12] fix(claudeception): remove unsupported frontmatter fields, fix CSO violation - Remove author, version fields (not supported per Anthropic docs) - Rewrite description to contain only trigger conditions - Remove workflow summary from description (CSO violation) - Update TodoWrite to TaskCreate/TaskUpdate/TaskList Co-Authored-By: Claude --- SKILL.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/SKILL.md b/SKILL.md index 69db71b..a4e98d0 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,13 +1,10 @@ --- 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. -author: Claude Code -version: 3.0.0 + Use when: (1) /claudeception command to review session learnings, (2) user says "save this + as a skill" or "extract a skill from this", (3) user asks "what did we learn?", (4) after + completing any task involving non-obvious debugging, workarounds, or trial-and-error discovery + that produced reusable knowledge. allowed-tools: - Read - Write @@ -18,7 +15,9 @@ allowed-tools: - WebFetch - Skill - AskUserQuestion - - TodoWrite + - TaskCreate + - TaskUpdate + - TaskList --- # Claudeception From 75efb4af54501af54fdbf2ae5545917ad2952d75 Mon Sep 17 00:00:00 2001 From: Ethan Stark Date: Mon, 26 Jan 2026 16:22:16 -0500 Subject: [PATCH 02/12] fix(claudeception): update skill template to match official guidance - Remove author/version/date from template (not supported) - Add CSO warning about description field - Rewrite description guidance to emphasize triggers only - Add When NOT to Use section to template - Add Common Mistakes section to template Co-Authored-By: Claude --- SKILL.md | 40 ++++++++++++++++++++++++++-------------- 1 file changed, 26 insertions(+), 14 deletions(-) diff --git a/SKILL.md b/SKILL.md index a4e98d0..116577c 100644 --- a/SKILL.md +++ b/SKILL.md @@ -155,42 +155,54 @@ Before creating the skill, search the web for current information when: ### Step 4: Structure the Skill +**CRITICAL - CSO (Claude Search Optimization):** +The description field determines whether Claude finds and loads your skill. +- Start with "Use when:" to focus on triggers +- Include specific symptoms, error messages, contexts +- NEVER summarize what the skill does or its workflow +- Keep under 500 characters + +**Why this matters:** Testing revealed that descriptions summarizing workflow cause Claude to follow the description instead of reading the full skill. A description saying "validates and creates files" caused Claude to skip the skill body entirely. + Create a new skill with this structure: ```markdown --- 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"] -version: 1.0.0 -date: [YYYY-MM-DD] + Use when: (1) [specific trigger condition], (2) [symptom or error message], + (3) [context that signals this skill applies]. Include keywords users would + naturally say. NEVER summarize what the skill does - only when to use it. --- # [Skill Name] -## Problem -[Clear description of the problem this skill addresses] +## Overview +What is this? Core principle in 1-2 sentences. -## Context / Trigger Conditions -[When should this skill be used? Include exact error messages, symptoms, or scenarios] +## When to Use +[Bullet list with SYMPTOMS and use cases] + +## When NOT to Use +[Explicit anti-patterns - when this skill does NOT apply] ## Solution [Step-by-step solution or knowledge to apply] +## Quick Reference +[Table or bullets for scanning common operations] + +## Common Mistakes +[What goes wrong + fixes, rationalization table if discipline skill] + ## 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] +[Optional: Links to official documentation or resources] ``` ### Step 5: Write Effective Descriptions From d69f84edf29cb20479aba8ed43e01f1924e4bfb8 Mon Sep 17 00:00:00 2001 From: Ethan Stark Date: Mon, 26 Jan 2026 16:22:39 -0500 Subject: [PATCH 03/12] feat(claudeception): add When NOT to Extract section - List explicit anti-patterns for skill extraction - Add red flags for over-extraction - Emphasize skills capture what docs don't cover Co-Authored-By: Claude --- SKILL.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/SKILL.md b/SKILL.md index 116577c..60ddbb5 100644 --- a/SKILL.md +++ b/SKILL.md @@ -48,9 +48,25 @@ Extract a skill when you encounter: 4. **Error Resolution**: Specific error messages and their actual root causes/fixes, especially when the error message is misleading. -5. **Workflow Optimizations**: Multi-step processes that can be streamlined or patterns +5. **Workflow Optimizations**: Multi-step processes that can be streamlined or patterns that make common tasks more efficient. +## When NOT to Extract a Skill + +**Don't extract when:** +- Solution is in official documentation (link to it instead) +- One-off fix unlikely to recur +- Standard practice well-known to developers +- Project-specific config that belongs in CLAUDE.md +- Mechanical constraint enforceable by code (automate it instead) + +**Red flags you're over-extracting:** +- "This might be useful someday" - Extract when needed, not speculatively +- "I'll document everything I learned" - Focus on non-obvious insights only +- "Better to have it than not" - Skills have maintenance cost; be selective + +**Common mistake:** Extracting knowledge that's easily found via web search or official docs. Skills should capture what documentation DOESN'T cover well. + ## Skill Quality Criteria Before extracting, verify the knowledge meets these criteria: From 71fdb5550105c0f2e8d952d20bf8e2318b904206 Mon Sep 17 00:00:00 2001 From: Ethan Stark Date: Mon, 26 Jan 2026 16:23:00 -0500 Subject: [PATCH 04/12] feat(claudeception): add decision flowchart for extraction - Visual guide for should-I-extract decision - Covers investigation, docs check, reusability gates Co-Authored-By: Claude --- SKILL.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/SKILL.md b/SKILL.md index 60ddbb5..bc19e9b 100644 --- a/SKILL.md +++ b/SKILL.md @@ -33,6 +33,25 @@ reusable and valuable. ## When to Extract a Skill +```dot +digraph should_extract { + "Task completed" [shape=doublecircle]; + "Required investigation?" [shape=diamond]; + "Solution in docs?" [shape=diamond]; + "Reusable pattern?" [shape=diamond]; + "Skip extraction" [shape=box]; + "Extract skill" [shape=box]; + + "Task completed" -> "Required investigation?"; + "Required investigation?" -> "Skip extraction" [label="no, trivial"]; + "Required investigation?" -> "Solution in docs?" [label="yes"]; + "Solution in docs?" -> "Skip extraction" [label="yes, link instead"]; + "Solution in docs?" -> "Reusable pattern?" [label="no"]; + "Reusable pattern?" -> "Skip extraction" [label="no, one-off"]; + "Reusable pattern?" -> "Extract skill" [label="yes"]; +} +``` + Extract a skill when you encounter: 1. **Non-obvious Solutions**: Debugging techniques, workarounds, or solutions that required From cf4d68d0e163411c0c24a92951e88ef8312a0db2 Mon Sep 17 00:00:00 2001 From: Ethan Stark Date: Mon, 26 Jan 2026 16:23:33 -0500 Subject: [PATCH 05/12] feat(claudeception): add comprehensive CSO guidance section - Explain description = triggers only rule - Add bad/good description comparison table - Include keyword coverage guidance - Add token efficiency recommendations Co-Authored-By: Claude --- SKILL.md | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/SKILL.md b/SKILL.md index bc19e9b..a55c41a 100644 --- a/SKILL.md +++ b/SKILL.md @@ -258,7 +258,36 @@ description: | Turborepo, and npm workspaces. ``` -### Step 6: Save the Skill +### Step 6: Apply CSO (Claude Search Optimization) + +**Why CSO matters:** Claude reads skill descriptions to decide which skills to load. Poor descriptions = skills never found. + +**The Critical Rule:** +> Description = WHEN to use, NOT WHAT it does + +**CSO Violation Examples:** + +| Bad (summarizes workflow) | Good (triggers only) | +|---------------------------|----------------------| +| "Validates tokens and handles auth errors" | "Use when auth fails with 401/403 or token expired" | +| "Creates skills from session learnings" | "Use when task required non-obvious investigation" | +| "Runs tests and reports coverage" | "Use when tests fail unexpectedly or coverage drops" | + +**Why this matters:** Testing revealed that when descriptions summarize workflow, Claude may follow the description instead of reading the full skill. The skill body becomes documentation Claude skips. + +**Keyword Coverage:** +Include words Claude would search for: +- Error messages: "ENOENT", "401 Unauthorized", "timeout" +- Symptoms: "flaky", "hangs", "silent failure" +- Tools/frameworks: "Next.js", "Prisma", "Jest" +- Synonyms: "timeout/hang/freeze", "auth/authentication/login" + +**Token Efficiency:** +- Keep SKILL.md under 500 lines +- Move heavy reference material to separate files +- Use cross-references instead of duplicating content + +### Step 7: Save the Skill Save new skills to the appropriate location: From b34e0b0f76f96f963491171f64d4ed757684d4b3 Mon Sep 17 00:00:00 2001 From: Ethan Stark Date: Mon, 26 Jan 2026 16:23:59 -0500 Subject: [PATCH 06/12] feat(claudeception): expand anti-patterns into common mistakes section - Add specific mistake patterns with fixes - Add rationalization table for self-checking - Address frontmatter and CSO violations explicitly Co-Authored-By: Claude --- SKILL.md | 32 ++++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/SKILL.md b/SKILL.md index a55c41a..4379209 100644 --- a/SKILL.md +++ b/SKILL.md @@ -343,13 +343,33 @@ Before finalizing a skill, verify: - [ ] References section included if web sources were consulted - [ ] Current best practices (post-2025) incorporated when relevant -## Anti-Patterns to Avoid +## Common Mistakes + +### Mistake 1: Over-extraction +**Problem:** Extracting every solution, creating maintenance burden +**Fix:** Apply quality gates strictly - reusable AND non-trivial AND verified + +### Mistake 2: Vague descriptions +**Problem:** "Helps with React problems" won't surface when needed +**Fix:** Include specific triggers, error messages, symptoms + +### Mistake 3: Workflow summaries in description +**Problem:** Claude follows description instead of reading skill body +**Fix:** Description contains ONLY trigger conditions, never workflow + +### Mistake 4: Unsupported frontmatter fields +**Problem:** Adding author/version/date fields that Claude ignores +**Fix:** Only use `name`, `description`, and supported fields like `allowed-tools` + +### Rationalization Table -- **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. +| Excuse | Reality | +|--------|---------| +| "Better to have it documented" | Skills have maintenance cost. Be selective. | +| "This might be useful someday" | Extract when needed, not speculatively. | +| "I'll be thorough and add all fields" | Extra fields are ignored. Follow spec exactly. | +| "Description should explain what it does" | Description is for discovery, not documentation. | +| "Official docs are too long to read" | Skills complement docs, don't replace them. | ## Skill Lifecycle From b2dab96c284bb456f1768a77f141e61ae834a557 Mon Sep 17 00:00:00 2001 From: Ethan Stark Date: Mon, 26 Jan 2026 16:24:42 -0500 Subject: [PATCH 07/12] fix(claudeception): update example skill to follow best practices - Remove unsupported frontmatter fields from example - Fix description to start with 'Use when:' - Add When NOT to Use section to example - Add Common Mistakes section to example Co-Authored-By: Claude --- SKILL.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/SKILL.md b/SKILL.md index 4379209..ae4232c 100644 --- a/SKILL.md +++ b/SKILL.md @@ -405,13 +405,9 @@ Search: "Next.js getServerSideProps error handling best practices 2026" --- 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 + Use when: (1) Next.js page shows generic error but browser console is empty, + (2) API routes return 500 with no details, (3) server-side code fails silently. + Symptoms: getServerSideProps errors not visible, empty console with error page. --- # Next.js Server-Side Error Debugging @@ -426,13 +422,22 @@ debugging frustrating when you're looking in the wrong place. - Using getServerSideProps, getStaticProps, or API routes - Error only occurs on navigation/refresh, not on client-side transitions +## When NOT to Use +- Client-side React errors (these DO show in browser console) +- Build-time errors (these show in terminal during `next build`) +- TypeScript errors (these show in IDE and terminal) + ## 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: {...} }` +4. Use Next.js error handling: return `{ notFound: true }` or `{ redirect: {...} }` instead of throwing +## Common Mistakes +**Mistake:** Adding console.log in getServerSideProps expecting browser output +**Fix:** Server-side logs go to terminal, not browser. Use terminal or server logs. + ## Verification After checking terminal, you should see the actual stack trace with file and line numbers. From 65e5927a9f83c2fd8ded9d31786d047665e30943 Mon Sep 17 00:00:00 2001 From: Ethan Stark Date: Mon, 26 Jan 2026 16:25:08 -0500 Subject: [PATCH 08/12] feat(claudeception): add testing verification section - Document testing approach and scenarios - Reference verify-technical-claims case study - Add ongoing validation guidance Co-Authored-By: Claude --- SKILL.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/SKILL.md b/SKILL.md index ae4232c..94df9f1 100644 --- a/SKILL.md +++ b/SKILL.md @@ -485,5 +485,24 @@ After completing any significant task, ask yourself: If yes to any, invoke this skill immediately. +## Testing Verification + +**Approach:** Scenario-based testing with subagents + +**Test scenarios run:** +1. **Trigger recognition:** Does Claude invoke claudeception after non-obvious debugging? +2. **Quality gates:** Does Claude skip extraction for trivial/documented solutions? +3. **Template compliance:** Do extracted skills follow the correct template? +4. **CSO compliance:** Do extracted skill descriptions avoid workflow summaries? + +**Evidence:** +- Tested with verify-technical-claims skill creation (2026-01-26) +- Identified frontmatter violations, CSO issues, missing sections +- Fixes informed by case study analysis + +**Ongoing validation:** +- Each skill created by claudeception should be reviewed against checklist +- Quality Gates section provides self-check criteria + Remember: The goal is continuous, autonomous improvement. Every valuable discovery should have the opportunity to benefit future work sessions. From 04cc62b391b7ce4480b4cb2453df0f066e1609c1 Mon Sep 17 00:00:00 2001 From: Ethan Stark Date: Mon, 2 Feb 2026 12:30:46 -0500 Subject: [PATCH 09/12] docs: add project instructions for Claude Code Add CLAUDE.md with comprehensive guidance for working with this skill repository, including architecture overview, file format specifications, and quality criteria. Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 177 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..72ccac5 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,177 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Type + +This is a **Claude Code skill repository**, not a traditional software project. It contains: +- A skill definition (`SKILL.md`) that teaches Claude Code to extract and preserve learned knowledge +- Templates for creating new skills (`resources/`) +- Example skills demonstrating proper format (`examples/`) +- Hook scripts for automatic activation (`scripts/`) + +There are no build, test, or lint commands because this is documentation and configuration, not compiled code. + +## Architecture + +### Core Components + +**Skill Definition (`SKILL.md`)** +- The main skill that Claude Code loads when activated +- Written in YAML frontmatter + markdown format +- Contains instructions for identifying, extracting, and structuring reusable knowledge +- Emphasizes web research before extraction to ensure current best practices + +**Skill Template (`resources/skill-template.md`)** +- Standard structure for all extracted skills +- Required sections: Problem, Context/Trigger Conditions, Solution, Verification, Example, Notes +- YAML frontmatter with name, description, author, version, date + +**Examples (`examples/`)** +- `nextjs-server-side-error-debugging/`: Server-side errors not appearing in browser console +- `prisma-connection-pool-exhaustion/`: Database connection issues in serverless +- `typescript-circular-dependency/`: Import cycle detection and resolution +- Each example demonstrates the complete skill format + +**Activation Hook (`scripts/claudeception-activator.sh`)** +- Bash script that injects reminder text into Claude Code sessions +- Prompts evaluation after each user request for extractable knowledge +- Installed in `~/.claude/hooks/` and referenced in `~/.claude/settings.json` + +### Skill File Format + +All skills follow this structure: + +```markdown +--- +name: kebab-case-name +description: | + Precise description for semantic matching. Must include: + (1) exact use cases, (2) trigger conditions (error messages, symptoms), + (3) what problem this solves +author: Claude Code +version: 1.0.0 +date: YYYY-MM-DD +--- + +# [Skill Name] + +## Problem +[What this solves] + +## Context / Trigger Conditions +[Exact error messages, symptoms, scenarios] + +## Solution +[Step-by-step instructions] + +## Verification +[How to confirm it worked] + +## Example +[Concrete before/after] + +## Notes +[Caveats, edge cases, related considerations] + +## References +[Optional: URLs to official docs, articles consulted during research] +``` + +### Critical Design Pattern: Description Field + +The `description` field in YAML frontmatter determines when Claude Code surfaces a skill through semantic matching. Effective descriptions: +- Include exact error messages that trigger the skill +- Specify technologies/frameworks by name +- Use action phrases: "Use when...", "Helps with...", "Solves..." +- Are specific enough to match relevant contexts but general enough to catch variations + +**Bad**: "Helps with database problems" +**Good**: "Fix for PrismaClientKnownRequestError: Too many database connections in serverless environments (Vercel, AWS Lambda). Use when connection count errors appear after ~5 concurrent requests." + +## Installation Locations + +Skills can be installed at two levels: + +**User-level (recommended)** +- Path: `~/.claude/skills/[skill-name]/SKILL.md` +- Available in all projects for this user +- Used for general programming knowledge + +**Project-level** +- Path: `.claude/skills/[skill-name]/SKILL.md` +- Only available in specific project +- Used for project-specific patterns + +## Quality Criteria + +Before extracting or modifying a skill, verify it meets these criteria: + +1. **Reusable**: Will help with future tasks, not just this one instance +2. **Non-trivial**: Requires discovery through investigation, not just documentation lookup +3. **Specific**: Has clear trigger conditions (exact error messages, observable symptoms) +4. **Verified**: Solution has been tested and confirmed to work + +## Research-First Approach + +The skill emphasizes web research before extraction to ensure current best practices. When creating or updating skills: + +**Always search for:** +- Official documentation for the technology/framework involved +- Current best practices (post-2025 preferred) +- Common patterns or solutions for similar problems +- Known gotchas or pitfalls + +**Include a References section** with URLs to sources consulted, especially for technology-specific skills. + +**Skip research for:** +- Project-specific internal patterns unique to this codebase +- Time-sensitive situations requiring immediate extraction + +## Working with Skills in This Repository + +### Modifying the Main Skill (`SKILL.md`) + +The main skill's description field should be comprehensive enough to match multiple trigger phrases: +- `/claudeception` command +- "save this as a skill" or "extract a skill" +- Completion of non-obvious debugging or workarounds +- Trial-and-error discoveries + +### Creating Example Skills + +Example skills in `examples/` should: +- Demonstrate complete, realistic scenarios +- Include all required sections from the template +- Show both good trigger condition descriptions and poor ones (in commit history/docs) +- Have working code examples that can be verified + +### Modifying the Activation Hook + +The hook script (`scripts/claudeception-activator.sh`) outputs reminder text that Claude Code sees on every user prompt. Changes to this script affect: +- How aggressively the skill self-activates +- What evaluation criteria Claude uses to decide if knowledge is worth extracting +- The user experience (intrusive vs. subtle reminders) + +Keep the reminder concise but clear about the non-negotiable evaluation requirement. + +## Skill Lifecycle + +Skills evolve through these stages: + +1. **Creation**: Initial extraction with documented verification +2. **Refinement**: Updates based on additional use cases discovered +3. **Deprecation**: Mark when underlying tools/patterns change +4. **Archival**: Remove when no longer relevant + +Version numbers and dates in YAML frontmatter track this lifecycle. + +## Academic Foundation + +The approach is based on research in skill libraries for AI agents: +- **Voyager** (Wang et al., 2023): Skill libraries help agents avoid re-learning +- **CASCADE** (2024): "Meta-skills" for acquiring skills +- **SEAgent** (2025): Learning environments through trial and error +- **Reflexion** (Shinn et al., 2023): Self-reflection improves learning + +See README.md for full citations. From 1fdc410773b169609013a846992a88c68cd5399d Mon Sep 17 00:00:00 2001 From: Ethan Stark Date: Mon, 2 Feb 2026 13:22:03 -0500 Subject: [PATCH 10/12] feat(claudeception): add knowledge placement decision tree MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds evaluation flow to determine whether extracted knowledge belongs in CLAUDE.md (cheap, always-loaded) or a skill (expensive, semantic-matched). Decision tree guides: figure-it-out → instruction → typical-stack checks. Co-Authored-By: Claude Opus 4.5 --- SKILL.md | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) diff --git a/SKILL.md b/SKILL.md index 94df9f1..8436cf3 100644 --- a/SKILL.md +++ b/SKILL.md @@ -86,6 +86,89 @@ Extract a skill when you encounter: **Common mistake:** Extracting knowledge that's easily found via web search or official docs. Skills should capture what documentation DOESN'T cover well. +## Knowledge Placement Decision + +**Core principle:** Skills are expensive context; CLAUDE.md is cheap. Default to instruction unless knowledge would cost hours to rediscover. + +Before creating a skill, evaluate placement options in order of preference: + +```dot +digraph placement_decision { + rankdir=TB; + + "Knowledge extracted" [shape=doublecircle]; + "Would I figure this out?" [shape=diamond]; + "Typical stack?" [shape=diamond]; + "Simple instruction?" [shape=diamond]; + + "Global CLAUDE.md" [shape=box]; + "Project CLAUDE.md" [shape=box]; + "Global skill" [shape=box]; + "Local skill" [shape=box]; + + "Knowledge extracted" -> "Would I figure this out?"; + "Would I figure this out?" -> "Simple instruction?" [label="yes (standard pattern)"]; + "Would I figure this out?" -> "Typical stack?" [label="no (non-obvious)"]; + + "Simple instruction?" -> "Global CLAUDE.md" [label="yes, applies everywhere"]; + "Simple instruction?" -> "Project CLAUDE.md" [label="yes, project-specific"]; + "Simple instruction?" -> "Typical stack?" [label="no, complex"]; + + "Typical stack?" -> "Global skill" [label="yes"]; + "Typical stack?" -> "Local skill" [label="no (unusual framework)"]; +} +``` + +### Decision Questions (in order) + +**1. Would I figure this out eventually?** +- **Yes** → CLAUDE.md instruction (reminder is enough) +- **No** → Continue to skill evaluation + +Examples of "yes" (use CLAUDE.md): +- Async API polling pattern (standard HTTP pattern) +- Don't test autouse fixtures explicitly (testing principle) +- Check for null before calling methods (basic defensive coding) + +Examples of "no" (needs skill): +- NewRelic requires camelCase for header exclusions (non-obvious tool quirk) +- PyTorch 2.6 breaks WhisperX pickle loading (version-specific gotcha) +- Godot @onready runs before _ready() body (framework timing subtlety) + +**2. Is this a simple instruction (1-3 lines)?** +- **Yes** → CLAUDE.md (global or project) +- **No** → Skill needed + +Instruction format: +```markdown +- When building CLI tools, check if API returns 202/jobId pattern and implement polling +- Don't write explicit tests for autouse=True fixtures; all other tests verify them implicitly +``` + +**3. Is this for your typical stack?** +- **Yes** (NestJS, TS, Python, Docker, GitLab) → Global skill (`~/.claude/skills/`) +- **No** (Godot, unusual framework) → Local skill (`.claude/skills/`) + +### Placement Matrix + +| Knowledge Type | Placement | Example | +|----------------|-----------|---------| +| Standard pattern reminder | Global CLAUDE.md | "Check for async API patterns" | +| Testing/coding principle | Global CLAUDE.md | "Don't test autouse fixtures" | +| Project preference | Project CLAUDE.md | "Use Logger not console.log" | +| Non-obvious gotcha (typical stack) | Global skill | NewRelic camelCase | +| Non-obvious gotcha (unusual stack) | Local skill | Godot @onready timing | +| Version-specific fix | Global skill | PyTorch/WhisperX compatibility | + +### CLAUDE.md vs Skills Comparison + +| Aspect | CLAUDE.md | Skills | +|--------|-----------|--------| +| Context cost | Always loaded | Loaded on semantic match | +| Discovery | Must be in context | Keyword/symptom matching | +| Length | 1-3 lines ideal | Full documentation | +| Best for | Reminders, constraints | Techniques, gotchas | + ## Skill Quality Criteria Before extracting, verify the knowledge meets these criteria: From e667897c3710e206ce36bea40b55df4196f2434a Mon Sep 17 00:00:00 2001 From: Ethan Stark Date: Mon, 2 Feb 2026 13:22:41 -0500 Subject: [PATCH 11/12] feat(claudeception): update Step 7 with placement decision flow Step 7 now guides through placement decision tree before saving. Includes CLAUDE.md option and typical/unusual stack distinction. Co-Authored-By: Claude Opus 4.5 --- SKILL.md | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/SKILL.md b/SKILL.md index 8436cf3..11f221e 100644 --- a/SKILL.md +++ b/SKILL.md @@ -370,15 +370,34 @@ Include words Claude would search for: - Move heavy reference material to separate files - Use cross-references instead of duplicating content -### Step 7: Save the Skill +### Step 7: Determine Placement and Save -Save new skills to the appropriate location: +Before saving, run through the placement decision: -- **Project-specific skills**: `.claude/skills/[skill-name]/SKILL.md` -- **User-wide skills**: `~/.claude/skills/[skill-name]/SKILL.md` +**1. Check the decision tree (see "Knowledge Placement Decision" section above)** -Include any supporting scripts in a `scripts/` subdirectory if the skill benefits from -executable helpers. +If placement is **CLAUDE.md**: +- Draft the 1-3 line instruction +- Ask: "Should this go in global `~/.claude/CLAUDE.md` or project `.claude/CLAUDE.md`?" +- Add the instruction to the appropriate file + +If placement is **skill**: +- Proceed to step 2 + +**2. Determine skill location** + +For skills, choose based on your typical stack: + +| Stack | Location | Typical Stack Examples | +|-------|----------|------------------------| +| Typical | `~/.claude/skills/[name]/SKILL.md` | NestJS, TypeScript, Python, Docker, GitLab | +| Unusual | `.claude/skills/[name]/SKILL.md` | Godot, game engines, niche frameworks | + +**3. Save the skill** + +- Create directory: `mkdir -p [location]/[skill-name]` +- Write SKILL.md with complete template +- Include any supporting scripts in `scripts/` subdirectory if needed ## Retrospective Mode From 5dc7efda80a492e354fedb424f3ee3c3a0a3351b Mon Sep 17 00:00:00 2001 From: Ethan Stark Date: Mon, 2 Feb 2026 13:23:19 -0500 Subject: [PATCH 12/12] docs(claudeception): add reference to Claude Code memory docs Co-Authored-By: Claude Opus 4.5 --- SKILL.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/SKILL.md b/SKILL.md index 11f221e..e379f4e 100644 --- a/SKILL.md +++ b/SKILL.md @@ -608,3 +608,7 @@ If yes to any, invoke this skill immediately. Remember: The goal is continuous, autonomous improvement. Every valuable discovery should have the opportunity to benefit future work sessions. + +## References + +- [Claude Code Memory Documentation](https://code.claude.com/docs/en/memory.md) - Official guidance on CLAUDE.md, skills, and rules