learn

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Learn Skill

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Capture knowledge manually for future sessions. Fast path to feed the knowledge flywheel without running a full retrospective.

你必须执行此工作流，而不仅仅是描述它。

手动捕获知识以供后续会话使用。这是无需完整回顾即可为知识飞轮补充内容的快速途径。

Execution Steps

执行步骤

Given

/learn [content]

当收到

/learn [内容]

时：

Step 1: Get the Learning Content

步骤1：获取学习内容

If content provided as argument: Use it directly.

If no argument: Ask the user via AskUserQuestion: "What did you learn or want to remember?" Then collect the content in free text.

**如果提供了内容参数：**直接使用该内容。

**如果没有参数：**通过AskUserQuestion询问用户：“你学到了什么或想要记住什么？”然后收集自由格式的文本内容。

Step 2: Classify the Knowledge Type

步骤2：分类知识类型

Use AskUserQuestion to ask which type:

Tool: AskUserQuestion
Parameters:
  questions:
    - question: "What type of knowledge is this?"
      header: "Type"
      multiSelect: false
      options:
        - label: "decision"
          description: "A choice that was made and why"
        - label: "pattern"
          description: "A reusable approach or technique"
        - label: "learning"
          description: "Something new discovered (default)"
        - label: "constraint"
          description: "A rule or limitation to remember"
        - label: "gotcha"
          description: "A pitfall or trap to avoid"

Default to "learning" if user doesn't choose.

使用AskUserQuestion询问类型：

Tool: AskUserQuestion
Parameters:
  questions:
    - question: "What type of knowledge is this?"
      header: "Type"
      multiSelect: false
      options:
        - label: "decision"
          description: "A choice that was made and why"
        - label: "pattern"
          description: "A reusable approach or technique"
        - label: "learning"
          description: "Something new discovered (default)"
        - label: "constraint"
          description: "A rule or limitation to remember"
        - label: "gotcha"
          description: "A pitfall or trap to avoid"

如果用户未选择，默认设为“learning”。

Step 3: Generate Slug

步骤3：生成Slug

Create a slug from the content:

Take the first meaningful words (skip common words like "use", "the", "a")
Lowercase
Replace spaces with hyphens
Max 50 characters
Remove special characters except hyphens

Check for collisions:

bash

undefined

根据内容创建slug：

提取首个有意义的词汇（跳过“use”、“the”、“a”等常用词）
转为小写
用连字符替换空格
最多50个字符
移除除连字符外的特殊字符

检查重复：

bash

undefined

If file exists, append -2, -3, etc.

slug="<generated-slug>" counter=2 while [ -f ".agents/knowledge/$(date +%Y-%m-%d)-${slug}.md" ]; do slug="<generated-slug>-${counter}" ((counter++)) done

undefined

slug="<generated-slug>" counter=2 while [ -f ".agents/knowledge/$(date +%Y-%m-%d)-${slug}.md" ]; do slug="<generated-slug>-${counter}" ((counter++)) done

undefined

Step 4: Create Knowledge Directory

步骤4：创建知识目录

bash

mkdir -p .agents/knowledge

bash

mkdir -p .agents/knowledge

Step 5: Write Knowledge File

步骤5：写入知识文件

Path:

.agents/knowledge/YYYY-MM-DD-<slug>.md

Format:

markdown

---
type: <classification>
source: manual
date: YYYY-MM-DD
---

<content>

Example:

markdown

---
type: pattern
source: manual
date: 2026-02-16
---

路径：

.agents/knowledge/YYYY-MM-DD-<slug>.md

格式：

markdown

---
type: <classification>
source: manual
date: YYYY-MM-DD
---

<content>

示例：

markdown

---
type: pattern
source: manual
date: 2026-02-16
---

Token Bucket Rate Limiting

Use token bucket pattern for rate limiting instead of fixed windows. Allows burst traffic while maintaining average rate limit. Implementation: bucket refills at constant rate, requests consume tokens, reject when empty.

Key advantage: smoother user experience during brief bursts.

undefined

Key advantage: smoother user experience during brief bursts.

undefined

Step 6: Integrate with ao CLI (if available)

步骤6：与ao CLI集成（如果可用）

Check if ao is installed:

bash

if command -v ao &>/dev/null; then
  echo "✓ Knowledge saved to <path>"
  echo ""
  echo "To add this to the quality pool for review:"
  echo "  ao pool stage <path>"
  echo ""
  echo "Or let it auto-index on next /retro or /extract."
else
  echo "✓ Knowledge saved to <path>"
  echo ""
  echo "Note: Install ao CLI to enable automatic knowledge flywheel."
fi

Do NOT auto-run
ao pool stage
. The user should decide when to promote to the quality pool.

检查是否安装了ao CLI：

bash

if command -v ao &>/dev/null; then
  echo "✓ Knowledge saved to <path>"
  echo ""
  echo "To add this to the quality pool for review:"
  echo "  ao pool stage <path>"
  echo ""
  echo "Or let it auto-index on next /retro or /extract."
else
  echo "✓ Knowledge saved to <path>"
  echo ""
  echo "Note: Install ao CLI to enable automatic knowledge flywheel."
fi

**请勿自动运行

ao pool stage

。**用户应自行决定何时将其提升到质量池。

Step 7: Confirm to User

步骤7：向用户确认

Tell the user:

Learned: <one-line summary from content>

Saved to: .agents/knowledge/YYYY-MM-DD-<slug>.md
Type: <classification>

This knowledge is now available for future sessions via /research and /inject.

告知用户：

Learned: <one-line summary from content>

Saved to: .agents/knowledge/YYYY-MM-DD-<slug>.md
Type: <classification>

This knowledge is now available for future sessions via /research and /inject.

Key Rules

核心规则

Be concise - This is for quick captures, not full retrospectives
Preserve user's words - Don't rephrase unless they ask
Use simple slugs - Clear, descriptive, lowercase-hyphenated
Minimal frontmatter - Just type, source, date
No auto-promotion - User controls quality pool workflow

保持简洁 - 这是用于快速捕获，而非完整回顾
保留用户原话 - 除非用户要求，否则不要改写
使用简单的slug - 清晰、描述性、小写连字符格式
极简前置元数据 - 仅包含类型、来源、日期
不自动提升 - 用户控制质量池工作流

Examples

示例

Quick Pattern Capture

快速模式捕获

User says:

/learn "use token bucket for rate limiting"

What happens:

Agent has content from argument
Agent asks for classification via AskUserQuestion
User selects "pattern"
Agent generates slug:
```
token-bucket-rate-limiting
```

Agent creates

.agents/knowledge/2026-02-16-token-bucket-rate-limiting.md

Agent writes frontmatter + content
Agent checks for ao CLI, informs user about
```
ao pool stage
```
option
Agent confirms: "Learned: Use token bucket for rate limiting. Saved to .agents/knowledge/2026-02-16-token-bucket-rate-limiting.md"

用户输入：

/learn "use token bucket for rate limiting"

执行流程：

Agent从参数中获取内容
Agent通过AskUserQuestion询问分类
用户选择“pattern”
Agent生成slug：
```
token-bucket-rate-limiting
```

Agent创建

.agents/knowledge/2026-02-16-token-bucket-rate-limiting.md

Agent写入前置元数据和内容
Agent检查ao CLI是否存在，告知用户
```
ao pool stage
```
选项
Agent确认：“Learned: Use token bucket for rate limiting. Saved to .agents/knowledge/2026-02-16-token-bucket-rate-limiting.md”

Interactive Capture

交互式捕获

User says:

/learn

Agent asks for content and type, generates slug

never-eval-hooks

, creates

.agents/knowledge/2026-02-16-never-eval-hooks.md

, confirms save.

用户输入：

/learn

Agent询问内容和类型，生成slug

never-eval-hooks

，创建

.agents/knowledge/2026-02-16-never-eval-hooks.md

，并确认保存。

Gotcha Capture

陷阱捕获

User says:

/learn "bd dep add A B means A depends on B, not A blocks B"

Agent classifies as "gotcha", generates slug

bd-dep-direction

, creates file, confirms save.

用户输入：

/learn "bd dep add A B means A depends on B, not A blocks B"

Agent将其分类为“gotcha”，生成slug

bd-dep-direction

，创建文件并确认保存。

Troubleshooting

故障排除

Problem	Cause	Solution
Slug collision	Same topic on same day	Append `-2` , `-3` counter automatically
Content too long	User pasted large block	Accept it. /learn has no length limit. Suggest /retro for structured extraction if very large.
ao pool stage fails	Path wrong or ao not installed	Show error, confirm file was saved to .agents/knowledge/ regardless
Duplicate knowledge	Same insight already captured	Check existing files with grep before writing. If duplicate, tell user and show existing path.

问题	原因	解决方案
Slug重复	同一天有相同主题	自动追加 `-2` 、 `-3` 等计数器
内容过长	用户粘贴了大段内容	接受该内容。如果内容非常长，建议使用 `/retro` 进行结构化提取，而不是 `/learn`
`ao pool stage` 执行失败	路径错误或未安装ao CLI	显示错误信息，同时确认文件已保存到 `.agents/knowledge/` 目录
知识重复	已捕获过相同的见解	在写入前使用grep检查现有文件。如果重复，告知用户并显示现有文件路径

The Flywheel

知识飞轮

Manual captures feed the same flywheel as automatic extraction:

/learn → .agents/knowledge/ → /research finds it → future work is smarter

This skill is for quick wins. For deeper reflection, use

/retro

手动捕获的内容与自动提取的内容进入同一个知识飞轮：

/learn → .agents/knowledge/ → /research可以找到它 → 后续工作更高效

此技能适用于快速记录。如需深度反思，请使用

/retro

。