---
name: learner
description: 从当前对话中提取一个学到的技能
level: 7
---

# Learner Skill

这是一个 Level 7（可自我改进）的技能。它包含两个不同的部分：
- **Expertise**：关于什么构成优秀技能的领域知识。随着新模式被发现会自动更新。
- **Workflow**：稳定的提取流程。很少变化。

在改进周期中，只应更新 Expertise 部分。

---

## Expertise

> 本节包含会随着时间推移而改进的领域知识。
> 当发现新的模式时，它可以由 learner 自身更新。

### Core Principle

可复用的技能不是可直接复制粘贴的代码片段，而是能教会 Claude 如何思考一类问题的**原则和决策启发式方法**。

**区别如下：**
- BAD（模仿）：`When you see ConnectionResetError, add this try/except block`
- GOOD（可复用技能）：`In async network code, any I/O operation can fail independently due to client/server lifecycle mismatches. The principle: wrap each I/O operation separately, because failure between operations is the common case, not the exception.`

### Quality Gate

在提取技能之前，以下三项必须全部为真：
- `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

仅在以下情况之后提取：
- 解决了一个需要深入调查的棘手 bug
- 发现了一个仅适用于当前代码库的非显而易见的变通方案
- 找到了一个一旦忘记就会浪费大量时间的隐藏坑点
- 揭示了会影响本项目的未文档化行为

### What Makes a USEFUL Skill

1. **Non-Googleable**：你无法轻易通过搜索找到的内容
   - 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**：引用 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**：准确说明该做什么以及在哪里做
   - BAD：`Handle edge cases` ❌
   - GOOD：`When seeing 'Cannot find module' in dist/, check tsconfig.json moduleResolution matches package.json type field` ✓

4. **Hard-Won**：需要付出显著的调试努力才能发现
   - BAD：通用编程模式 ❌
   - GOOD：`Race condition in worker.ts - the Promise.all at line 89 needs await before the map callback returns` ✓

### Anti-Patterns (DO NOT EXTRACT)

- 通用编程模式（应使用文档）
- 重构技巧（这些是普适的）
- 库的使用示例（应使用库文档）
- 类型定义或样板代码
- 任何初级开发者 5 分钟内就能 Google 到的内容

---

## Workflow

> 本节包含稳定的提取流程。
> 在改进周期中不应更新它。

### Step 1: Gather Required Information

- **Problem Statement**：发生的具体错误、症状或困惑
  - 包含真实的错误消息、文件路径、行号
  - 示例：`TypeError in src/hooks/session.ts:45 when sessionId is undefined after restart`

- **Solution**：确切的修复方法，而不是泛泛建议
  - 包含代码片段、文件路径、配置变更
  - 示例：`Add null check before accessing session.user, regenerate session on 401`

- **Triggers**：当再次遇到这个问题时会出现的关键词
  - 使用错误消息片段、文件名、症状描述
  - 示例：`["sessionId undefined", "session.ts TypeError", "401 session"]`

- **Scope**：几乎总是 Project-level，除非它真的是一个普适洞见

### Step 2: Quality Validation

系统会拒绝以下技能：
- 过于泛化（没有文件路径、行号或具体错误消息）
- 容易被 Google 到（标准模式、库用法）
- 解决方案含糊（没有代码片段或精确说明）
- 触发词质量差（会匹配所有内容的泛用词）

### Step 3: Classify as Expertise or Workflow

在保存前，判断这次学习属于：
- **Expertise**（领域知识、模式、坑点）→ 保存为 `{topic}-expertise.md`
- **Workflow**（操作流程、步骤序列）→ 保存为 `{topic}-workflow.md`

这种分类可确保 expertise 能够独立更新，而不会破坏 workflow 的稳定性。

### Step 4: Save Location

- **User-level**：`~/.claude/skills/omc-learned/` - 罕见。仅用于真正可移植的洞见。
- **Project-level**：`.omc/skills/` - 默认。随仓库一起进行版本控制。

### Skill Body Template

```markdown
# [Skill Name]

## The Insight
What is the underlying PRINCIPLE you discovered? Not the code, but the mental model.

## Why This Matters
What goes wrong if you don't know this? What symptom led you here?

## Recognition Pattern
How do you know when this skill applies? What are the signs?

## The Approach
The decision-making heuristic, not just code. How should Claude THINK about this?

## Example (Optional)
If code helps, show it - but as illustration of the principle, not copy-paste material.
```

**Key**：如果 Claude 能将一个技能应用到新的情境中，而不仅仅是完全相同的情境，那么这个技能就是可复用的。

## Related Commands

- `/oh-my-claudecode:note` - 保存在压缩上下文后仍可保留的快速笔记（比 skills 更不正式）
- `/oh-my-claudecode:ralph` - 启动一个带有学习捕获的开发循环