Learner

Quality Gate

Before extracting a skill, ALL three must be true:

• "Could someone Google this in 5 minutes?" → NO
• "Is this specific to THIS codebase?" → YES
• "Did this take real debugging effort to discover?" → YES

Recognition Signals

Extract ONLY after:

• Solving a tricky bug that required deep investigation
• Discovering a non-obvious workaround specific to this codebase
• Finding a hidden gotcha that wastes time when forgotten
• Uncovering undocumented behavior that affects this project

What Makes a USEFUL Skill

1. Non-Googleable: Something you couldn't easily find via search

   • BAD: "How to read files in TypeScript" ❌
   • GOOD: "This codebase uses custom path resolution in ESM that requires fileURLToPath + specific relative paths" ✓

2. Context-Specific: References actual files, error messages, or patterns from THIS codebase

   • BAD: "Use try/catch for error handling" ❌
   • GOOD: "The aiohttp proxy in server.py:42 crashes on ClientDisconnectedError - wrap StreamResponse in try/except" ✓

3. Actionable with Precision: Tells you exactly WHAT to do and WHERE

   • BAD: "Handle edge cases" ❌
   • GOOD: "When seeing 'Cannot find module' in dist/, check tsconfig.json moduleResolution matches package.json type field" ✓

4. Hard-Won: Took significant debugging effort to discover

   • BAD: Generic programming patterns ❌
   • GOOD: "Race condition in worker.ts - the Promise.all at line 89 needs await before the map callback returns" ✓

Anti-Patterns (DO NOT EXTRACT)

• Generic programming patterns (use documentation instead)
• Refactoring techniques (these are universal)
• Library usage examples (use library docs)
• Type definitions or boilerplate
• Anything a junior dev could Google in 5 minutes

Workflow

This section contains the stable extraction procedure. It should NOT be updated during improvement cycles.

Step 1: Gather Required Information

• Problem Statement: The SPECIFIC error, symptom, or confusion that occurred

  • Include actual error messages, file paths, line numbers
  • Example: "TypeError in src/hooks/session.ts:45 when sessionId is undefined after restart"

• Solution: The EXACT fix, not general advice

  • Include code snippets, file paths, configuration changes
  • Example: "Add null check before accessing session.user, regenerate session on 401"

• Triggers: Keywords that would appear when hitting this problem again

  • Use error message fragments, file names, symptom descriptions
  • Example: ["sessionId undefined", "session.ts TypeError", "401 session"]

• Scope: Almost always Project-level unless it's a truly universal insight

Step 2: Quality Validation

The system REJECTS skills that are:

• Too generic (no file paths, line numbers, or specific error messages)
• Easily Googleable (standard patterns, library usage)
• Vague solutions (no code snippets or precise instructions)
• Poor triggers (generic words that match everything)

Step 3: Classify as Expertise or Workflow

Before saving, determine if the learning is:

• Expertise (domain knowledge, pattern, gotcha) → Save as {topic}-expertise.md
• Workflow (operational procedure, step sequence) → Save as {topic}-workflow.md

This classification ensures expertise can be updated independently without destabilizing workflows.

Step 4: Save Location

• User-level: ${CLAUDE_CONFIG_DIR:-~/.claude}/skills/omc-learned/<skill-name>.md - Rare. Only for truly portable insights.
• Project-level: .omc/skills/<skill-name>.md - Default. Version-controlled with repo.

Required File Format

Every learned skill file MUST start with YAML frontmatter so learned-skill flat-file discovery can load it. Do not write plain markdown without frontmatter.

Minimum required frontmatter:

---