Learn Skill

Purpose

Analyze problem-solving patterns, debugging techniques, and workarounds from sessions to save them as reusable skills.

Core Principle: Recurring problem-solving → Pattern extraction → Skill creation → Reuse in future sessions

Activation Triggers

• After solving complex errors
• When discovering useful workarounds
• When establishing project-specific conventions
• Session end knowledge consolidation
• Explicit user request: /learn, remember this, save pattern

Pattern Extraction Focus

Gate question: Would a future session, starting cold, save real time because this was written down? If the answer is "it would have figured this out from the code or from general knowledge in under a minute", do not save it. Every saved line is prompt context; it has to earn its place.

Include ✅

Exclude ❌

Where it goes

Workflow

Step 1: Session Analysis

/learn

🔍 Analyzing session...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Messages: 47
Tool calls: 89
Errors resolved: 3 cases
Main task: Auth system implementation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 2: Pattern Identification

💡 Extractable patterns found
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. [HIGH VALUE] NextAuth + Prisma Session Type Extension
   - Problem: userId missing in Session type
   - Solution: Type extension in next-auth.d.ts
   - Reusability: ⭐⭐⭐⭐⭐

2. [MEDIUM VALUE] Supabase RLS Debugging Pattern
   - Problem: Empty results due to RLS policy
   - Solution: Test with service_role key, then fix policy
   - Reusability: ⭐⭐⭐⭐

3. [LOW VALUE] ESLint Rule Disable
   - Problem: unused-vars warning
   - Solution: .eslintrc modification
   - Reusability: ⭐⭐ (project-specific)

Select patterns to save [1,2,3 or all]:

Step 3: Skill Document Generation

📝 Generating skill document...

File: ~/.claude/skills/nextauth-prisma-session-type/SKILL.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# NextAuth + Prisma Session Type Extension

## Problem
Type error when accessing userId in NextAuth session
`Property 'userId' does not exist on type 'Session'`

## Solution
Create `types/next-auth.d.ts`:
\`\`\`typescript
import { DefaultSession } from "next-auth"

declare module "next-auth" {
  interface Session {
    user: {
      id: string
    } & DefaultSession["user"]
  }
}
\`\`\`

## When to Apply
- When using NextAuth + Prisma combination
- When adding custom fields to session

## Related
- NextAuth official docs: TypeScript section
- Prisma adapter configuration
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Skill saved

Step 4: Confirmation

View saved skill? [y/N]

Learned Skills Storage

Storage Location

One directory per learned skill, so the harness discovers it like any other skill (a flat .md under a shared folder is never loaded):

~/.claude/skills/
├── nextauth-prisma-session-type/SKILL.md
├── supabase-rls-debugging/SKILL.md
├── react-hydration-mismatch-fix/SKILL.md
└── vercel-edge-function-timeout/SKILL.md

Skill File Structure

---
name: pattern-name
description: Brief description
source: learn
learned_at: 2025-01-26
source_project: project-name
tags: [nextauth, prisma, typescript]
---

# Pattern Name

## Problem
Problem situation description

## Cause
Root cause analysis

## Solution
Resolution method (with code examples)

## When to Apply
Situations where this pattern applies

## Caveats
Warnings, edge cases

## Related
Related documentation, resource links

Auto-Learning (Stop Hook)

Automatic Session End Analysis

.claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "type": "command",
        "command": "~/.claude/scripts/evaluate-session.sh"
      }
    ]
  }
}

Auto-Learning Configuration

.claude/learn.config.json:

{
  "auto_learn": {
    "enabled": true,
    "min_session_length": 10,
    "extraction_threshold": "medium",
    "auto_approve": false
  },
  "storage": {
    "path": "~/.claude/skills/",
    "max_skills": 100
  },
  "filters": {
    "ignore_patterns": [
      "typo",
      "syntax_error",
      "one_time_fix"
    ],
    "focus_patterns": [
      "error_resolution",
      "debugging_technique",
      "workaround",
      "architecture_decision"
    ]
  }
}

Integration

With PM Agent

Integration with PM Agent's self-improvement layer:

Session complete
    │
    ├─→ /learn (pattern extraction)
    │
    └─→ PM Agent (documentation, knowledge base update)

With /checkpoint

/checkpoint create "before-experiment"
... experimental resolution attempts ...
... success! ...
/learn  # Save successful pattern

With Future Sessions

Saved skills auto-referenced when similar problems occur:

🔍 Similar pattern detected
━━━━━━━━━━━━━━━━━━━━━━━━━━
Previously learned pattern available:
- nextauth-prisma-session-type

Apply? [y/N]

Quality Filters

Value Assessment

Pre-save Checklist (all must be true)

• Project- or library-specific — not generic advice
• Not already obvious from the code, and not already in CLAUDE.md / RULES.md / CONVENTIONS.md
• Commands were actually run and work; file paths are real
• Expressed in the most concise form (one line per concept where possible)
• A new session would find it before needing it (name and tags are searchable)

Extraction Threshold

• Low: Extract most patterns (noisy)
• Medium: Medium+ value only (recommended)
• High: High-value patterns only (strict)

Commands

Best Practices

Good Pattern Example

# React Server Component Data Fetching

## Problem
Waterfall issue when fetching server data
in client components

## Solution
Fetch data in server component, pass as props
or use Suspense + parallel fetch

## Code Example
\`\`\`tsx
// ✅ Good: Server Component
async function Page() {
  const data = await fetchData()
  return <ClientComponent data={data} />
}
\`\`\`

Patterns to Avoid

# Fix Typo in Config  ❌
## Problem
Build failure due to typo
## Solution
Fix typo

→ No reuse value, do not save

# UserService  ❌
The `UserService` class handles user operations.

→ Obvious from the code, do not save

# JWT Authentication  ❌
JWT (JSON Web Tokens) are an open standard (RFC 7519) that defines a compact
and self-contained way for securely transmitting information ... (12 lines)

→ Verbose; the useful residue is one line: `Auth: JWT HS256, Bearer header`

Include/Exclude criteria and the bad examples above are adapted from Anthropic's claude-md-management plugin (update-guidelines.md, Apache 2.0) — see NOTICE.md.