Back to Details

learner

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Learner Skill

Learner Skill

The Insight

核心洞察

Reusable skills are not code snippets to copy-paste, but principles and decision-making heuristics that teach Codex HOW TO THINK about a class of problems.
The difference:
  • BAD (mimicking): "When you see ConnectionResetError, add this try/except block"
  • GOOD (reusable skill): "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."
A good skill changes how Codex APPROACHES problems, not just what code it produces.
可复用的Skill并非用于复制粘贴的代码片段，而是指导Codex思考一类问题的原则与决策启发式方法。
区别：
  • 错误示范（模仿）："当遇到ConnectionResetError时，添加这个try/except块"
  • 正确示范（可复用Skill）："在异步网络代码中，任何I/O操作都可能因客户端/服务器生命周期不匹配而独立失败。原则：单独封装每个I/O操作，因为操作之间的失败是常见情况，而非异常。"
优质的Skill会改变Codex处理问题的方式，而不仅仅是它生成的代码。

Why This Matters

重要性

Before extracting a skill, ask yourself:
  • "Could someone Google this in 5 minutes?" → If yes, STOP. Don't extract.
  • "Is this specific to THIS codebase?" → If no, STOP. Don't extract.
  • "Did this take real debugging effort to discover?" → If no, STOP. Don't extract.
If a potential skill fails any of these questions, it's not worth saving.
在提取Skill之前，请先自问：
  • "有人能在5分钟内通过谷歌找到这个内容吗？"→ 如果是，停止提取。
  • "这是否特定于当前代码库？"→ 如果不是，停止提取。
  • "这是否需要实际调试才能发现？"→ 如果不是，停止提取。
如果某个潜在Skill不符合以上任意一条，就不值得保存。

Recognition Pattern

适用场景

Use /learner 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
仅在以下情况后使用 /learner 命令：
  • 解决了需要深入调查的棘手Bug
  • 发现了特定于当前代码库的非显而易见的解决方法
  • 找到了容易被遗忘且浪费时间的隐藏陷阱
  • 发现了影响当前项目的未文档化行为

The Approach

实施步骤

Extraction Process

提取流程

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: Save Location
  • User-level: ~/.codex/skills/omc-learned/ - Rare. Only for truly portable insights.
  • Project-level: .omx/skills/ - Default. Version-controlled with repo.
步骤1：收集必要信息
  • 问题描述：具体的错误、症状或困惑
    • 包含实际错误信息、文件路径、行号
    • 示例："重启后sessionId未定义时，src/hooks/session.ts:45处出现TypeError"
  • 解决方案：确切的修复方案，而非通用建议
    • 包含代码片段、文件路径、配置变更
    • 示例："在访问session.user前添加空值检查，遇到401时重新生成session"
  • 触发词：再次遇到该问题时会出现的关键词
    • 使用错误信息片段、文件名、症状描述
    • 示例：["sessionId undefined", "session.ts TypeError", "401 session"]
  • 范围：除非是真正通用的洞察，否则几乎都是项目级别的
步骤2：质量验证
系统会拒绝以下类型的Skill：
  • 过于通用（无文件路径、行号或具体错误信息）
  • 易通过谷歌搜索到（标准模式、库的使用方法）
  • 解决方案模糊（无代码片段或精确说明）
  • 触发词无效（匹配所有内容的通用词汇）
步骤3：保存位置
  • 用户级别：~/.codex/skills/omc-learned/ - 很少使用。仅用于真正可移植的洞察。
  • 项目级别：.omx/skills/ - 默认位置。随代码库进行版本控制。

What Makes a USEFUL Skill

实用Skill的特征

CRITICAL: Not every solution is worth saving. A good skill is:
  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" ✓
关键要点：并非所有解决方案都值得保存。优质的Skill需满足：
  1. 难以谷歌搜索到：无法轻易通过搜索找到的内容
    • 错误示范："如何在TypeScript中读取文件" ❌
    • 正确示范："此代码库在ESM中使用自定义路径解析，要求结合fileURLToPath与特定相对路径" ✓
  2. 特定于上下文：引用当前代码库中的实际文件、错误信息或模式
    • 错误示范："使用try/catch进行错误处理" ❌
    • 正确示范："server.py:42中的aiohttp代理会在ClientDisconnectedError时崩溃 - 将StreamResponse封装在try/except中" ✓
  3. 精准可执行：明确告诉你要做什么以及在哪里做
    • 错误示范："处理边缘情况" ❌
    • 正确示范："当在dist/中出现'Cannot find module'错误时，检查tsconfig.json的moduleResolution是否与package.json的type字段匹配" ✓
  4. 来之不易：需要大量调试工作才能发现
    • 错误示范：通用编程模式 ❌
    • 正确示范："worker.ts中的竞态条件 - 第89行的Promise.all需要在map回调返回前添加await" ✓

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
  • 通用编程模式（请参考文档）
  • 重构技巧（这些是通用的）
  • 库使用示例（请参考库文档）
  • 类型定义或样板代码
  • 初级开发者能在5分钟内谷歌到的任何内容

Skill Format

Skill格式

Skills are saved as markdown with this structure:
Skill以Markdown格式保存，结构如下：

YAML Frontmatter

YAML前置元数据

Standard metadata fields:
  • id, name, description, source, triggers, quality
标准元数据字段：
  • id, name, description, source, triggers, quality

Body Structure (Required)

主体结构（必填）

markdown
undefined
markdown
undefined

[Skill Name]

[Skill名称]

The Insight

核心洞察

What is the underlying PRINCIPLE you discovered? Not the code, but the mental model. Example: "Async I/O operations are independently failable. Client lifecycle != server lifecycle."
你发现的底层原则是什么？不是代码，而是思维模型。 示例："异步I/O操作可能独立失败。客户端生命周期 != 服务器生命周期。"

Why This Matters

重要性

What goes wrong if you don't know this? What symptom led you here? Example: "Proxy server crashes on client disconnect, taking down other requests."
如果不知道这一点会出现什么问题？是什么症状引导你找到这个解决方案？ 示例："代理服务器会在客户端断开连接时崩溃，导致其他请求也失败。"

Recognition Pattern

适用场景

How do you know when this skill applies? What are the signs? Example: "Building any long-lived connection handler (proxy, websocket, SSE)"
如何判断该Skill适用？有哪些迹象？ 示例："构建任何长连接处理程序（代理、WebSocket、SSE）"

The Approach

实施方法

The decision-making heuristic, not just code. How should Codex THINK about this? Example: "For each I/O operation, ask: what if this fails right now? Handle it locally."
决策启发式方法，而非仅仅是代码。Codex应该如何思考这个问题？ 示例："对于每个I/O操作，问自己：如果此时失败会怎样？在本地处理该错误。"

Example (Optional)

示例（可选）

If code helps, show it - but as illustration of the principle, not copy-paste material.

**Key**: A skill is REUSABLE if Codex can apply it to NEW situations, not just identical ones.
如果代码有帮助，可以展示代码 - 但仅作为原则的示例，而非复制粘贴的素材。

**关键**：如果Codex能将其应用于新场景而非仅相同场景，那么这个Skill就是可复用的。

Related Commands

相关命令

  • /note - Save quick notes that survive compaction (less formal than skills)
  • /ralph - Start a development loop with learning capture
  • /note - 保存可在压缩后保留的快速笔记（比Skill更不正式）
  • /ralph - 启动带有学习捕获功能的开发循环