Learn

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.

Core Principle: Skill Extraction

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.

TDD Mapping for Skill Extraction

Skill extraction follows the same discipline as Test-Driven Development:

The key insight: When extracting from a session, the RED phase already happened—you discovered something non-obvious. Now write the skill (GREEN) and verify it (REFACTOR).

When to Extract a Skill

Extract a skill when you encounter:

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.

2. •

   Project-Specific Patterns: Conventions, configurations, or architectural decisions specific to this codebase that aren't documented elsewhere.

3. •

   Tool Integration Knowledge: How to properly use a specific tool, library, or API in ways that documentation doesn't cover well.

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 that make common tasks more efficient.

Skill Types

Different skill types serve different purposes:

• •Technique: Concrete method with steps to follow (debugging patterns, testing approaches)
• •Pattern: Mental model for problem-solving (architectural decisions, design patterns)
• •Reference: API docs, syntax guides, tool documentation
• •Error Resolution: Specific error message → root cause → fix mapping

Classification helps determine verification approach (see Verification by Skill Type below).

Skill Quality Criteria

Before extracting, verify the knowledge meets these criteria:

• •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?

Extraction Process

Step 1: Identify the Knowledge

Analyze what was learned:

• •What was the problem or task?
• •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

Example searches:

• •"Next.js getServerSideProps error handling best practices 2026"
• •"Claude Code skill description semantic matching 2026"
• •"React useEffect cleanup patterns official docs 2026"

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

Step 3: Structure the Skill

Save the skill to the appropriate location:

• •If .claude/skiller.toml exists: .claude/rules/[skill-name].mdc
• •Otherwise: .claude/skills/[skill-name]/SKILL.md

Use MDC frontmatter:

---
name: skill-name-with-hyphens
description: |
  Use when [specific triggering conditions]. Triggers: (1) exact symptom,
  (2) error message, (3) scenario. [What problem this solves, written in third person.]
---

# [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]

## 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:

• •Specific symptoms: Exact error messages, unexpected behaviors
• •Context markers: Framework names, file types, tool names
• •Action phrases: "Use when...", "Helps with...", "Solves..."

Example of a good description:

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.

Claude Search Optimization (CSO)

Critical for discovery—future Claude needs to FIND your skill.

Description Field

• •Start with "Use when..." to focus on triggering conditions
• •Describe the problem (race conditions, flaky tests) not language-specific symptoms
• •Write in third person (injected into system prompt)
• •Keep under 500 characters if possible

Keyword Coverage

Use words Claude would search for:

• •Error messages: "Hook timed out", "ENOTEMPTY", "race condition"
• •Symptoms: "flaky", "hanging", "zombie", "pollution"
• •Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach"
• •Tools: Actual commands, library names, file types

Token Efficiency

Skills load into context. Be concise but complete.

• •Move heavy reference (100+ lines) to separate files
• •Use cross-references instead of repeating content
• •Don't sacrifice clarity for brevity

Step 5: Deploy

After creating the skill, run:

npx skiller@latest apply

Retrospective Mode

When /learn 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:

• • 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

Verification by Skill Type

Different skill types need different verification:

Technique Skills (how-to guides)

• •Apply to real scenario in current session
• •Does skill guide correctly?
• •Are edge cases covered?

Pattern Skills (mental models)

• •Does skill explain when pattern applies?
• •Are counter-examples clear (when NOT to apply)?

Reference Skills (documentation)

• •Is information findable?
• •Are common use cases covered?

Error Resolution Skills

• •Does symptom → cause → fix mapping hold?
• •Are related errors mentioned?

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

Skills should evolve:

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

Example: Complete Extraction Flow

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 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

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

Step 3-5 - Structure and Save:

Extraction:

---
description: |
  Use when debugging Next.js server-side errors. Triggers: (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.
---

# Next.js Server-Side Error Debugging

## 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.

## 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

## 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

## Verification

After checking terminal, you should see the actual stack trace with file
and line numbers.

## 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

## 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)

Integration with Workflow

Automatic Trigger Conditions

Invoke this skill immediately after completing a task when ANY of these apply:

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

Explicit Invocation

Also invoke when:

• •User runs /learn to review the session
• •User says "save this as a skill" or similar
• •User asks "what did we learn?"

Self-Check After Each Task

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?"

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.