learning

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Learning

知识管理

You are managing institutional knowledge — capturing insights, searching prior learnings, and promoting important patterns into CLAUDE.md for permanent reference.

你负责管理机构知识——捕获洞察、检索过往知识，并将重要模式推广至CLAUDE.md中作为永久参考。

When to Use

使用场景

This skill activates when:

User invokes
```
/learning
```
command
Another skill references
```
desplega:learning
```
User says "let's capture this," "what did we learn about X," or similar knowledge-management phrases

当出现以下情况时，该技能激活：

用户调用
```
/learning
```
命令
其他技能引用
```
desplega:learning
```
用户说出“我们记录下这个”、“关于X我们有哪些经验”或类似知识管理相关表述

Subcommand Routing

子命令路由

Parse the first argument to determine the flow:

Argument	Flow
(no args) or `status`	Setup / Status
`capture [insight]`	Capture
`recall <topic>`	Recall
`promote [id-or-topic]`	Promote
`review`	Review

解析第一个参数以确定执行流程：

参数	流程
无参数或 `status`	配置/状态查看
`capture [insight]`	知识捕获
`recall <topic>`	知识检索
`promote [id-or-topic]`	知识推广
`review`	知识审核

Setup / Status (

/learning

with no args)

配置/状态查看（无参数的

/learning

）

Check for config: Read
```
~/.agentic-learnings.json
```
If not found (first run):
- Explain the learning system briefly: "The learning skill captures, searches, and promotes institutional knowledge across sessions and projects. It stores learnings as markdown files with structured frontmatter."
- Create
```
~/.agentic-learnings.json
```
  with the default schema (see Config File Schema below), using the local backend
- Use AskUserQuestion: "Would you like to configure additional backends? (qmd for semantic search, agent-fs for remote team storage)" with options:
```
["Local only (default)", "Configure qmd", "Configure agent-fs", "Configure both"]
```
- If qmd selected:
  - Check if qmd MCP tools are available (try
```
mcp__qmd__status
```
    ). Note this in config as
```
"accessMode": "mcp"
```
    or
```
"cli"
```
    .
  - Use AskUserQuestion: "Which qmd collections should be searched for learnings? (enter comma-separated names, e.g., 'ai-toolbox, my-notes')"
- If agent-fs selected, walk through configuration step by step:
  - Use AskUserQuestion: "Do you have an agent-fs API key configured?" with options:
```
["Yes, it's set in my environment (AGENT_FS_API_KEY)", "Yes, I'll provide it now", "No, I need to set one up first"]
```
  - If providing now: use AskUserQuestion: "Enter your agent-fs API key"
  - If needs setup: explain how to get one and pause
  - Use AskUserQuestion: "Which agent-fs organization should learnings be stored in?" with options:
```
["Use existing org (I'll provide the name)", "Create a new org for learnings"]
```
  - If existing: use AskUserQuestion: "Enter the organization name"
  - If new: use AskUserQuestion: "What should the new organization be called?" — then run
```
agent-fs org create <name>
```
    via Bash
  - Use AskUserQuestion: "Which drive should learnings be stored in?" with options:
```
["Use existing drive (I'll provide the name)", "Create a new 'learnings' drive"]
```
  - If existing: use AskUserQuestion: "Enter the drive name"
  - If new: run
```
agent-fs drive create learnings --org <org>
```
    via Bash
- CLAUDE.md Bootstrap: After config creation, use AskUserQuestion: "Would you like me to add a Learning System section to your project CLAUDE.md so future sessions know about the learning system?" with options:
```
["Yes, add to project CLAUDE.md", "Yes, add to global ~/.claude/CLAUDE.md", "No, skip"]
```
- If yes, append the following section to the chosen CLAUDE.md:
  markdown
```
## Learning System
Use `/learning recall <topic>` before research/planning to check for prior learnings.
Use `/learning capture` to record significant insights, decisions, and gotchas.
Config: `~/.agentic-learnings.json`
```
If found (returning user):
- Show configured backends and their status (enabled/disabled)
- Count learnings per backend (local: Glob count, agent-fs:
```
agent-fs ls
```
  count)
- Show 5 most recent learnings (filename + topic from frontmatter)

检查配置文件：读取
```
~/.agentic-learnings.json
```
未找到配置文件（首次运行）：
- 简要说明知识管理系统：“Learning技能可跨会话与项目捕获、检索并推广机构知识，它将知识存储为带结构化前置元数据的markdown文件。”
- 使用本地后端创建默认架构的
```
~/.agentic-learnings.json
```
  （参见下方配置文件架构）
- 使用 AskUserQuestion：“是否要配置额外后端？（qmd用于语义检索，agent-fs用于远程团队存储）”，选项：
```
["仅本地（默认）", "配置qmd", "配置agent-fs", "同时配置两者"]
```
- 若选择qmd：
  - 检查qmd MCP工具是否可用（尝试调用
```
mcp__qmd__status
```
    ），在配置中记录为
```
"accessMode": "mcp"
```
    或
```
"cli"
```
  - 使用 AskUserQuestion：“应检索哪些qmd集合中的知识？（输入逗号分隔的名称，例如：'ai-toolbox, my-notes'）”
- 若选择agent-fs，逐步完成配置流程：
  - 使用 AskUserQuestion：“是否已配置agent-fs API密钥？”，选项：
```
["是，已在环境变量（AGENT_FS_API_KEY）中设置", "是，我现在提供", "否，我需要先设置"]
```
  - 若选择现在提供：使用 AskUserQuestion：“请输入你的agent-fs API密钥”
  - 若需要设置：说明获取方式并暂停流程
  - 使用 AskUserQuestion：“知识应存储到哪个agent-fs组织？”，选项：
```
["使用现有组织（我将提供名称）", "为知识创建新组织"]
```
  - 若选择现有：使用 AskUserQuestion：“请输入组织名称”
  - 若选择新建：使用 AskUserQuestion：“新组织名称是什么？”——随后通过Bash执行
```
agent-fs org create <name>
```
  - 使用 AskUserQuestion：“知识应存储到哪个驱动器？”，选项：
```
["使用现有驱动器（我将提供名称）", "创建名为'learnings'的新驱动器"]
```
  - 若选择现有：使用 AskUserQuestion：“请输入驱动器名称”
  - 若选择新建：通过Bash执行
```
agent-fs drive create learnings --org <org>
```
- CLAUDE.md初始化：配置完成后，使用 AskUserQuestion：“是否要在项目CLAUDE.md中添加知识管理系统章节，以便后续会话了解该系统？”，选项：
```
["是，添加到项目CLAUDE.md", "是，添加到全局~/.claude/CLAUDE.md", "否，跳过"]
```
- 若选择是，将以下章节追加到选定的CLAUDE.md中：
  markdown
```
## 知识管理系统
在研究/规划前使用 `/learning recall <topic>` 检索过往知识。
使用 `/learning capture` 记录重要洞察、决策与注意事项。
配置文件：`~/.agentic-learnings.json`
```
已找到配置文件（返回用户）：
- 显示已配置的后端及其状态（启用/禁用）
- 统计各后端的知识数量（本地：全局匹配计数，agent-fs：
```
agent-fs ls
```
  计数）
- 显示最近5条知识（文件名+前置元数据中的主题）

Capture (

/learning capture

)

知识捕获（

/learning capture

）

Step 1: Get the Insight

步骤1：获取洞察内容

If invoked with inline text (e.g.,
```
/learning capture "qmd requires manual update"
```
): use that as the insight
If no text provided: use AskUserQuestion: "What insight or learning would you like to capture?"

若调用时附带内联文本（例如：
```
/learning capture "qmd requires manual update"
```
）：直接使用该文本作为洞察内容
若无文本提供：使用 AskUserQuestion：“你想捕获哪些洞察或知识？”

Step 2: Significance Check

步骤2：重要性检查

Before proceeding, evaluate using these default heuristics:

Would this help someone else in a future session? (primary test)
Is this already documented in CLAUDE.md or code comments? (skip if yes)
Did the user correct the agent's approach? (always capture)
Was something surprisingly difficult or broken? (usually capture)

Override: If a

## Learning Capture Rules

section exists in project or global CLAUDE.md, those rules take precedence over the defaults above.

If the insight doesn't pass the significance threshold, mention this to the user but still offer to capture it — the user has final say.

在继续前，使用以下默认规则评估：

该内容是否能帮助未来会话中的其他人？（核心标准）
该内容是否已在CLAUDE.md或代码注释中记录？（若是则跳过）
用户是否纠正了Agent的方法？（始终捕获）
是否遇到了意外困难或故障？（通常需要捕获）

覆盖规则：若项目或全局CLAUDE.md中存在

## Learning Capture Rules

章节，该章节规则优先于上述默认规则。

若洞察未达到重要性阈值，需告知用户，但仍提供捕获选项——最终决定权在用户手中。

Step 3: Categorize

步骤3：分类

Use AskUserQuestion: "What category best fits this learning?" with options:

```
product-decisions
```
— architectural choices, trade-offs, why we chose X over Y
```
technical-gotchas
```
— bugs, footguns, surprising behavior, workarounds
```
human-nudges
```
— user corrections, workflow preferences, communication style
```
patterns
```
— reusable approaches, conventions, best practices discovered
```
mistakes
```
— things that went wrong and what to do differently

使用 AskUserQuestion：“该知识最适合哪个类别？”，选项：

```
product-decisions
```
—— 架构选择、权衡方案、选择X而非Y的原因
```
technical-gotchas
```
—— 漏洞、陷阱、意外行为、解决方案
```
human-nudges
```
—— 用户纠正、工作流偏好、沟通风格
```
patterns
```
—— 可复用方法、约定、已发现的最佳实践
```
mistakes
```
—— 出错的环节及改进方向

Step 4: Scope

步骤4：范围选择

Use AskUserQuestion: "Should this learning be personal or shared?" with options:

```
Personal
```
— saved to
```
thoughts/{user}/learnings/
```
, visible only in this user's context
```
Shared
```
— saved to
```
thoughts/shared/learnings/
```
, git-tracked, visible to all collaborators (human and agent)

使用 AskUserQuestion：“该知识应设为个人可见还是共享可见？”，选项：

```
Personal
```
—— 保存到
```
thoughts/{user}/learnings/
```
，仅当前用户可见
```
Shared
```
—— 保存到
```
thoughts/shared/learnings/
```
，受git追踪，所有协作者（人类与Agent）可见

Step 5: Write the Learning

步骤5：写入知识

Generate filename:
```
YYYY-MM-DD-<slug>.md
```
- Slug: derive from topic, lowercase, hyphens, max 50 chars
- When capturing to shared scope, include author name in slug to avoid multi-user conflicts (e.g.,
```
2026-03-19-taras-qmd-indexing.md
```
  )
Fill the template from
```
cc-plugin/base/skills/learning/template.md
```
with the collected information
Write using the Write tool to the appropriate path
Sync backends:
- If qmd backend enabled: run
```
qmd update
```
  via Bash
- If agent-fs backend enabled: run
```
agent-fs write /learnings/<filename> --content "<content>"
```
  via Bash
Confirm capture with file path

生成文件名：
```
YYYY-MM-DD-<slug>.md
```
- Slug：从主题衍生，小写字母、连字符分隔，最长50字符
- 若捕获到共享范围，slug中需包含作者名称以避免多用户冲突（例如：
```
2026-03-19-taras-qmd-indexing.md
```
  ）

使用收集到的信息填充

cc-plugin/base/skills/learning/template.md

中的模板

使用 Write 工具写入对应路径
同步后端：
- 若qmd后端启用：通过Bash执行
```
qmd update
```
- 若agent-fs后端启用：通过Bash执行
```
agent-fs write /learnings/<filename> --content "<content>"
```
返回文件路径确认捕获成功

Recall (

/learning recall

)

知识检索（

/learning recall

）

Step 1: Get the Topic

步骤1：获取检索主题

If invoked with a topic (e.g.,
```
/learning recall qmd indexing
```
): use that
If no topic: use AskUserQuestion: "What topic would you like to search for?"

若调用时附带主题（例如：
```
/learning recall qmd indexing
```
）：直接使用该主题
若无主题：使用 AskUserQuestion：“你想检索哪个主题？”

Step 2: Search All Configured Backends in Parallel

步骤2：并行检索所有已配置后端

Query all enabled backends simultaneously:

Local: Grep for the topic in

thoughts/{user}/learnings/

and

thoughts/shared/learnings/

qmd: Use

mcp__qmd__query

with

[{type:'lex', query:'<topic>'}, {type:'vec', query:'<topic>'}]

, scoped to configured collections

agent-fs: Run

agent-fs search --query "<topic>"

agent-fs fts --query "<topic>"

via Bash

同时查询所有启用的后端：

本地：在

thoughts/{user}/learnings/

和

thoughts/shared/learnings/

中匹配主题

qmd：使用

mcp__qmd__query

，参数为

[{type:'lex', query:'<topic>'}, {type:'vec', query:'<topic>'}]

，范围限定为已配置的集合

agent-fs：通过Bash执行

agent-fs search --query "<topic>"

或

agent-fs fts --query "<topic>"

Step 3: Present Results

步骤3：展示结果

Rank results by relevance (exact matches first, semantic matches second)
Show each result with: date, category, topic, and a 1-line summary
Include
```
file:line
```
references for local results
Offer to read the full learning or take action (promote, archive)

按相关性排序（精确匹配优先，语义匹配次之）
每条结果展示：日期、类别、主题、一行摘要
本地结果需包含
```
file:line
```
引用
提供读取完整知识或执行操作（推广、归档）的选项

Promote (

/learning promote

)

知识推广（

/learning promote

）

Step 1: Select a Learning

步骤1：选择待推广知识

If given a file path: read that learning directly
If given a topic: run recall first, then let the user select which learning to promote
If no argument: run recall with no topic (list recent), let user select

若提供文件路径：直接读取该知识
若提供主题：先执行检索流程，再让用户选择待推广的知识
若无参数：执行无主题检索（列出最近知识），让用户选择

Step 2: Choose Target

步骤2：选择目标位置

Use AskUserQuestion: "Where should this learning be promoted to?" with options:

```
Project CLAUDE.md
```
— add to the current project's CLAUDE.md
```
Global ~/.claude/CLAUDE.md
```
— add to the global CLAUDE.md

使用 AskUserQuestion：“该知识应推广至何处？”，选项：

```
Project CLAUDE.md
```
—— 添加到当前项目的CLAUDE.md
```
Global ~/.claude/CLAUDE.md
```
—— 添加到全局CLAUDE.md

Step 3: Format and Append

步骤3：格式化并追加

Read the full learning file
Format it as a concise rule (1-3 lines) suitable for CLAUDE.md
Use AskUserQuestion to confirm the formatted rule before writing
Append to the chosen CLAUDE.md under an appropriate section (create a section if needed)
Update the learning file's frontmatter: set
```
promoted_to:
```
to the target path (e.g.,
```
promoted_to: "CLAUDE.md"
```
or
```
promoted_to: "~/.claude/CLAUDE.md"
```
)

读取完整知识文件
将其格式化为适合CLAUDE.md的简洁规则（1-3行）
使用 AskUserQuestion 确认格式化后的规则再写入
将规则追加到选定CLAUDE.md的对应章节（若需则创建章节）
更新知识文件的前置元数据：设置
```
promoted_to:
```
为目标路径（例如：
```
promoted_to: "CLAUDE.md"
```
或
```
promoted_to: "~/.claude/CLAUDE.md"
```
）

Review (

/learning review

)

知识审核（

/learning review

）

Step 1: List All Learnings

步骤1：列出所有知识

List all learnings from the default backend (most recent first)
Show 1-line summaries: date, category, topic, promoted status

Use local backend: Glob

thoughts/{user}/learnings/*.md

thoughts/shared/learnings/*.md

从默认后端列出所有知识（按时间倒序）
展示一行摘要：日期、类别、主题、推广状态

使用本地后端：匹配

thoughts/{user}/learnings/*.md

thoughts/shared/learnings/*.md

Step 2: Select for Review

步骤2：选择待审核知识

Use AskUserQuestion (multiSelect): "Which learnings would you like to review?" with the list of learnings

使用 AskUserQuestion（多选）：“你想审核哪些知识？”，选项为知识列表

Step 3: Process Each Selected Learning

步骤3：处理每个选定知识

For each selected learning:

Show the full content
Use AskUserQuestion: "What would you like to do with this learning?" with options:
- ```
Keep
```
  — no changes
- ```
Promote
```
  — run the Promote flow for this learning
- ```
Archive
```
  — move to
```
thoughts/{user}/learnings/archive/
```
  (or shared equivalent)
- ```
Delete
```
  — remove the file entirely

对每个选定知识：

展示完整内容
使用 AskUserQuestion：“你想对该知识执行什么操作？”，选项：
- ```
Keep
```
  —— 不做修改
- ```
Promote
```
  —— 为该知识执行推广流程
- ```
Archive
```
  —— 移动到
```
thoughts/{user}/learnings/archive/
```
  （或共享目录对应位置）
- ```
Delete
```
  —— 彻底删除文件

Step 4: Alternative — File Review

步骤4：替代方案——文件批量审核

file-review

is available (check if the command exists), offer it as an alternative for batch review:

"Would you like to use file-review for a visual batch review instead?"
If yes: create a temporary summary file and launch file-review

若

file-review

命令可用（检查命令是否存在），提供批量审核的替代选项：

“是否使用file-review进行可视化批量审核？”
若选择是：创建临时摘要文件并启动file-review

Step 5: Report

步骤5：结果报告

After processing all selected learnings, report: "Kept N, promoted N, archived N, deleted N."

处理完所有选定知识后，报告：“保留N条，推广N条，归档N条，删除N条。”

Backend Adapter Reference

后端适配器参考

All backends support 4 operations: write, search, list, delete.

所有后端支持4种操作：write、search、list、delete。

Local Backend

本地后端

Operation	Implementation
write	Write tool to `thoughts/{user}/learnings/` or `thoughts/shared/learnings/`
search	Grep/Glob for topic across both personal and shared learnings directories
list	`Glob thoughts/{user}/learnings/.md` + `Glob thoughts/shared/learnings/.md`
delete	`Bash rm <path>` (learning file is just a local file)

操作	实现方式
write	使用Write工具写入 `thoughts/{user}/learnings/` 或 `thoughts/shared/learnings/`
search	在个人与共享知识目录中通过Grep/Glob匹配主题
list	`Glob thoughts/{user}/learnings/.md` + `Glob thoughts/shared/learnings/.md`
delete	通过Bash执行 `rm <path>` （知识文件为本地文件）

qmd Backend

qmd后端

qmd is a local search engine over markdown documents. It can be accessed via MCP tools (if configured as an MCP server) or via CLI.

Install:

npm install -g @tobilu/qmd

(or

bun install -g @tobilu/qmd

) — github.com/tobi/qmd

MCP access: Use
```
mcp__qmd__query
```
,
```
mcp__qmd__get
```
,
```
mcp__qmd__multi_get
```
tools (available when qmd MCP server is configured)
CLI access: Run
```
qmd query
```
,
```
qmd get
```
,
```
qmd update
```
via Bash (always available if installed)

Operation	Implementation
write	Same as local (qmd indexes local files), then `qmd update` via Bash to re-index
search	MCP: `mcp__qmd__query` with lex+vec sub-queries, scoped to configured collections. CLI: `qmd query --collection <name> "<topic>"` via Bash
list	MCP: `mcp__qmd__multi_get` with glob pattern (e.g., `learnings/.md` ). CLI: `qmd get "learnings/.md"` via Bash
delete	Delete local file + `qmd update` via Bash (qmd re-indexes, removing the entry)

Prefer MCP tools when available (richer output, no shell escaping). Fall back to CLI if MCP is not configured.

qmd 是针对markdown文档的本地搜索引擎，可通过MCP工具（若配置为MCP服务器）或CLI访问。

安装：

npm install -g @tobilu/qmd

（或

bun install -g @tobilu/qmd

）—— github.com/tobi/qmd

MCP访问：使用
```
mcp__qmd__query
```
、
```
mcp__qmd__get
```
、
```
mcp__qmd__multi_get
```
工具（配置qmd MCP服务器后可用）
CLI访问：通过Bash执行
```
qmd query
```
、
```
qmd get
```
、
```
qmd update
```
（安装后始终可用）

操作	实现方式
write	与本地后端相同（qmd会索引本地文件），随后通过Bash执行 `qmd update` 重新索引
search	MCP：使用带lex+vec子查询的 `mcp__qmd__query` ，范围限定为已配置集合。CLI：通过Bash执行 `qmd query --collection <name> "<topic>"`
list	MCP：使用通配符模式的 `mcp__qmd__multi_get` （例如： `learnings/.md` ）。CLI：通过Bash执行 `qmd get "learnings/.md"`
delete	删除本地文件 + 通过Bash执行 `qmd update` （qmd重新索引并移除该条目）

优先使用MCP工具（输出更丰富，无需转义shell），若未配置MCP则回退到CLI。

agent-fs Backend

agent-fs后端

agent-fs provides remote, team-wide file storage with semantic search. Accessed via CLI only.

Install:
```
bun add -g @desplega.ai/agent-fs
```
— github.com/desplega-ai/agent-fs
CLI access: All operations use
```
agent-fs <command>
```
via Bash

Operation	Implementation
write	`agent-fs write /learnings/<filename> --content "<content>"` via Bash
search	`agent-fs search --query "<topic>"` (semantic) or `agent-fs fts --query "<topic>"` (keyword) via Bash
list	`agent-fs ls /learnings/` via Bash
delete	`agent-fs rm /learnings/<filename>` via Bash

agent-fs 提供支持语义检索的远程团队文件存储，仅可通过CLI访问。

安装：
```
bun add -g @desplega.ai/agent-fs
```
—— github.com/desplega-ai/agent-fs
CLI访问：所有操作通过Bash执行
```
agent-fs <command>
```

操作	实现方式
write	通过Bash执行 `agent-fs write /learnings/<filename> --content "<content>"`
search	通过Bash执行 `agent-fs search --query "<topic>"` （语义检索）或 `agent-fs fts --query "<topic>"` （关键词检索）
list	通过Bash执行 `agent-fs ls /learnings/`
delete	通过Bash执行 `agent-fs rm /learnings/<filename>`

Config File Schema

配置文件架构

The config file lives at

~/.agentic-learnings.json

json

{
  "defaultBackend": "local",
  "backends": {
    "local": { "enabled": true, "basePath": "thoughts/{user}/learnings/" },
    "qmd": { "enabled": false, "accessMode": "mcp", "collections": [] },
    "agentFs": { "enabled": false, "apiKey": "", "org": "", "drive": "" }
  }
}

```
defaultBackend
```
: which backend to use for writes (always "local" initially)
```
backends.local.basePath
```
: path template —
```
{user}
```
is replaced at runtime with the current user's name
```
backends.qmd.accessMode
```
:
```
"mcp"
```
(preferred, uses MCP tools) or
```
"cli"
```
(fallback, uses qmd CLI via Bash)
```
backends.qmd.collections
```
: list of qmd collection names to search
```
backends.agentFs
```
: agent-fs connection details (only needed if using remote team storage)
```
backends.agentFs.apiKey
```
: API key — can be set here or via
```
AGENT_FS_API_KEY
```
env var

配置文件位于

~/.agentic-learnings.json

：