self-improving-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Self-Improvement Skill

自我改进 Skill

Log learnings and errors to markdown files for continuous improvement. Agents can later process these into fixes, and important learnings get promoted to workspace memory. This version of the skill is built for OpenClaw only — for other agents, see the original multi-agent version at https://github.com/pskoett/pskoett-ai-skills.

Capture, review, reuse, promotion, and maintenance are self-contained here: no companion skill, service, plugin, memory backend, or OpenClaw core change is required. The optional hook only reminds and captures possible errors; it does not enforce this workflow or revalidate claims.

将经验和错误记录到 markdown 文件中，以实现持续改进。Agent 之后可以处理这些记录并将其转化为修复方案，重要经验会被提升到 workspace 记忆中。此版本的 skill 仅为 OpenClaw 构建——对于其他 Agent，请参阅原始的多 Agent 版本：https://github.com/pskoett/pskoett-ai-skills。

捕获、审查、复用、提升和维护均在此自包含完成：无需配套 skill、服务、plugin、记忆后端，也无需更改 OpenClaw core。可选 hook 只会提醒并捕获潜在错误；它不会强制执行此工作流，也不会重新验证声明。

First-Use Initialisation

首次使用初始化

Before logging anything, ensure the

.learnings/

directory and files exist in the project or workspace root. If any are missing, create them:

bash

mkdir -p .learnings
[ -f .learnings/LEARNINGS.md ] || printf "# Learnings\n\nCorrections, insights, and knowledge gaps captured during development.\n\n**Categories**: correction | insight | knowledge_gap | best_practice\n\n---\n" > .learnings/LEARNINGS.md
[ -f .learnings/ERRORS.md ] || printf "# Errors\n\nCommand failures and integration errors.\n\n---\n" > .learnings/ERRORS.md
[ -f .learnings/FEATURE_REQUESTS.md ] || printf "# Feature Requests\n\nCapabilities requested by the user.\n\n---\n" > .learnings/FEATURE_REQUESTS.md

Never overwrite existing files. This is a no-op if

.learnings/

is already initialised.

Do not log secrets, tokens, private keys, environment variables, or full source/config files unless the user explicitly asks for that level of detail. Prefer short summaries or redacted excerpts over raw command output or full transcripts.

If you want automatic reminders and session-end error detection, enable the opt-in hook described in Optional: Enable Hook.

在记录任何内容之前，确保项目或 workspace 根目录中存在

.learnings/

目录及文件。如果缺少任何一项，请创建：

bash

mkdir -p .learnings
[ -f .learnings/LEARNINGS.md ] || printf "# Learnings\n\nCorrections, insights, and knowledge gaps captured during development.\n\n**Categories**: correction | insight | knowledge_gap | best_practice\n\n---\n" > .learnings/LEARNINGS.md
[ -f .learnings/ERRORS.md ] || printf "# Errors\n\nCommand failures and integration errors.\n\n---\n" > .learnings/ERRORS.md
[ -f .learnings/FEATURE_REQUESTS.md ] || printf "# Feature Requests\n\nCapabilities requested by the user.\n\n---\n" > .learnings/FEATURE_REQUESTS.md

绝不覆盖现有文件。如果

.learnings/

已经初始化，则此操作为空操作。

除非用户明确要求达到该详细程度，否则不要记录 secrets、tokens、private keys、environment variables 或完整的 source/config 文件。优先使用简短摘要或脱敏摘录，而不是原始命令输出或完整对话记录。

如果希望获得自动提醒和 session 结束时的错误检测，请启用可选：启用 Hook中介绍的 hook。

Quick Reference

快速参考

Situation	Action
Command/operation fails	Log to `.learnings/ERRORS.md`
User corrects you	Log to `.learnings/LEARNINGS.md` with category `correction`
User wants missing feature	Log to `.learnings/FEATURE_REQUESTS.md`
API/external tool fails	Log to `.learnings/ERRORS.md` with integration details
Knowledge was outdated	Log to `.learnings/LEARNINGS.md` with category `knowledge_gap`
Found better approach	Log to `.learnings/LEARNINGS.md` with category `best_practice`
Simplify/Harden recurring patterns	Log/update `.learnings/LEARNINGS.md` with `Source: simplify-and-harden` and a stable `Pattern-Key`
Similar to existing entry	Search by `Pattern-Key` , confirm the same claim/scope; count only a new occurrence
Reusing or promoting saved knowledge	Review relevant/due claims using Maintenance below, including one-off/unpromoted entries
Source, decision, dependency, or task changes	Revalidate affected claims; do not expire them by age
Workflow improvements	Promote to `AGENTS.md` (workspace)
Tool gotchas	Promote to `TOOLS.md` (workspace)
Behavioral patterns	Promote to `SOUL.md` (workspace)

情况	操作
命令/操作失败	记录到 `.learnings/ERRORS.md`
用户纠正你的假设	记录到 `.learnings/LEARNINGS.md` ，类别为 `correction`
用户需要缺失的功能	记录到 `.learnings/FEATURE_REQUESTS.md`
API/外部工具失败	记录到 `.learnings/ERRORS.md` ，并附集成详情
知识已过时	记录到 `.learnings/LEARNINGS.md` ，类别为 `knowledge_gap`
找到更好的方法	记录到 `.learnings/LEARNINGS.md` ，类别为 `best_practice`
简化/强化重复出现的模式	记录/更新 `.learnings/LEARNINGS.md` ，设置 `Source: simplify-and-harden` 和稳定的 `Pattern-Key`
与现有条目相似	按 `Pattern-Key` 搜索，确认是否为相同声明/范围；仅将新的发生计为一次重复
复用或提升已保存知识	使用下方 Maintenance 审查相关/到期声明，包括一次性/未提升的条目
来源、决策、依赖项或任务发生变化	重新验证受影响的声明；不要因时间久远而使其失效
工作流改进	提升至 workspace 的 `AGENTS.md`
工具使用陷阱	提升至 workspace 的 `TOOLS.md`
行为模式	提升至 workspace 的 `SOUL.md`

OpenClaw Setup

OpenClaw 设置

OpenClaw uses workspace-based prompt injection with automatic skill loading.

OpenClaw 使用基于 workspace 的提示词注入，并自动加载 skill。

Installation

安装

Via OpenClaw's built-in installer (recommended) — installs into the active OpenClaw workspace:

bash

openclaw skills install @pskoett/self-improving-agent

Via the ClawHub CLI (

npm i -g clawhub

) — installs into

./skills

under the current working directory, not the workspace:

bash

clawhub install @pskoett/self-improving-agent

Manual (the skill lives in the repo's

self-improving-agent/

subfolder; copy that folder, not the repo root):

bash

git clone https://github.com/pskoett/self-improving-agent.git /tmp/self-improving-agent-repo
cp -r /tmp/self-improving-agent-repo/self-improving-agent ~/.openclaw/skills/self-improving-agent

Remade for openclaw from original repo : https://github.com/pskoett/pskoett-ai-skills - https://github.com/pskoett/pskoett-ai-skills/tree/main/skills/self-improvement

通过 OpenClaw 内置安装器（推荐）——安装到当前活跃的 OpenClaw workspace：

bash

openclaw skills install @pskoett/self-improving-agent

通过 ClawHub CLI（

npm i -g clawhub

）——安装到当前工作目录下的

./skills

，而不是 workspace：

bash

clawhub install @pskoett/self-improving-agent

手动安装（该 skill 位于仓库的

self-improving-agent/

子文件夹中；请复制该文件夹，而非仓库根目录）：

bash

git clone https://github.com/pskoett/self-improving-agent.git /tmp/self-improving-agent-repo
cp -r /tmp/self-improving-agent-repo/self-improving-agent ~/.openclaw/skills/self-improving-agent

已根据原仓库为 OpenClaw 重新制作：https://github.com/pskoett/pskoett-ai-skills - https://github.com/pskoett/pskoett-ai-skills/tree/main/skills/self-improvement

Workspace Structure

Workspace 结构

OpenClaw injects these files into every session:

~/.openclaw/workspace/
├── AGENTS.md          # Multi-agent workflows, delegation patterns
├── SOUL.md            # Behavioral guidelines, personality, principles
├── TOOLS.md           # Tool capabilities, integration gotchas
├── MEMORY.md          # Long-term memory (main session only)
├── memory/            # Daily memory files
│   └── YYYY-MM-DD.md
└── .learnings/        # This skill's log files
    ├── LEARNINGS.md
    ├── ERRORS.md
    └── FEATURE_REQUESTS.md

OpenClaw 会将以下文件注入每个 session：

~/.openclaw/workspace/
├── AGENTS.md          # Multi-agent workflows, delegation patterns
├── SOUL.md            # Behavioral guidelines, personality, principles
├── TOOLS.md           # Tool capabilities, integration gotchas
├── MEMORY.md          # Long-term memory (main session only)
├── memory/            # Daily memory files
│   └── YYYY-MM-DD.md
└── .learnings/        # This skill's log files
    ├── LEARNINGS.md
    ├── ERRORS.md
    └── FEATURE_REQUESTS.md

Create Learning Files

创建经验文件

bash

mkdir -p ~/.openclaw/workspace/.learnings

Then create the log files (or copy from

assets/

```
LEARNINGS.md
```
— corrections, knowledge gaps, best practices
```
ERRORS.md
```
— command failures, exceptions
```
FEATURE_REQUESTS.md
```
— user-requested capabilities

bash

mkdir -p ~/.openclaw/workspace/.learnings

然后创建日志文件（或从

assets/

复制）：

```
LEARNINGS.md
```
——纠正、知识缺口、最佳实践
```
ERRORS.md
```
——命令失败、异常
```
FEATURE_REQUESTS.md
```
——用户请求的功能

Promotion Targets

提升目标

When learnings prove broadly applicable, promote them to workspace files:

Learning Type	Promote To	Example
Behavioral patterns	`SOUL.md`	"Be concise, avoid disclaimers"
Workflow improvements	`AGENTS.md`	"Spawn sub-agents for long tasks"
Tool gotchas	`TOOLS.md`	"Git push needs auth configured first"

当经验被证明具有广泛适用性时，将其提升到 workspace 文件：

经验类型	提升目标	示例
行为模式	`SOUL.md`	“要简洁，避免免责声明”
工作流改进	`AGENTS.md`	“为长任务创建 sub-agent”
工具使用陷阱	`TOOLS.md`	“Git push 需要先配置认证”

Inter-Session Communication

跨 Session 通信

OpenClaw provides tools to share learnings across sessions:

sessions_list — View active/recent sessions
sessions_history — Read another session's transcript
sessions_send — Send a learning to another session
sessions_spawn — Spawn a sub-agent for background work

Use these only in trusted environments and only when the user explicitly wants cross-session sharing. Prefer sending a short sanitized summary and relevant file paths, not raw transcripts, secrets, or full command output.

OpenClaw 提供用于跨 session 共享经验的工具：

sessions_list——查看活跃/最近的 session
sessions_history——读取另一个 session 的 transcript
sessions_send——向另一个 session 发送经验
sessions_spawn——创建 sub-agent 以在后台执行任务

仅在受信任环境中，且仅当用户明确希望跨 session 共享时使用它们。优先发送简短、经过清理的摘要和相关文件路径，而不是原始 transcript、secrets 或完整命令输出。

Optional: Enable Hook

可选：启用 Hook

For automatic reminders at session start and error detection at session end, follow Install or Upgrade the Hook, then enable with

openclaw hooks enable self-improvement

. Select the actual skill/hook paths, review local patches, and preserve the old copy before replacing it.

Fires on

agent:bootstrap

(injects the reminder, plus a pending-triage note when auto-detected errors await review) and on

command:new

command:reset

(sweeps the ended session's transcript for error patterns into

<workspace>/.learnings/ERRORS.md

; opt-in — runs only when

.learnings/

exists). Internal

HOOK.md

events have no per-tool-call callback, so this integration detects errors at session end. OpenClaw's typed plugin hooks separately expose

after_tool_call

. See hook systems and limitations.

如果希望在 session 开始时自动提醒并在 session 结束时检测错误，请按照安装或升级 Hook中的说明操作，然后启用

openclaw hooks enable self-improvement

。选择实际的 skill/hook 路径，审查本地补丁，并在替换前保留旧副本。

它会在

agent:bootstrap

时触发（注入提醒；当自动检测到有待分诊的错误时，还会添加待分诊备注），并在

command:new

command:reset

时触发（扫描已结束 session 的 transcript，将错误模式写入

<workspace>/.learnings/ERRORS.md

；这是可选功能——仅在

.learnings/

存在时运行）。内部

HOOK.md

事件没有逐次工具调用回调，因此此集成在 session 结束时检测错误。OpenClaw 的类型化 plugin hooks 另行提供

after_tool_call

。请参阅 hook 系统及其限制。

Logging Format

记录格式

Append an entry using the templates in assets/LEARNINGS.md, assets/ERRORS.md, or assets/FEATURE_REQUESTS.md. Keep the observation, context, suggested action, and metadata. See examples for completed entries.

At capture, add the Maintenance block below for each reusable claim. If no inference is established yet, record

Claim: unknown — needs triage

rather than inventing a rule. Legacy entries remain valid log records: initialize metadata only when captured or touched in relevant review, without bulk migration.

使用 assets/LEARNINGS.md、assets/ERRORS.md 或 assets/FEATURE_REQUESTS.md 中的模板追加条目。保留观察结果、上下文、建议操作和元数据。请参阅示例了解完整条目。

捕获时，为每个可复用声明添加下方的 Maintenance 块。如果尚未确定推断，请记录

Claim: unknown — needs triage

，而不是凭空编造规则。旧版条目仍然是有效的日志记录：仅在捕获或在相关审查中触及旧条目时初始化元数据，不要批量迁移。

Maintenance: Cause-Aware Context Decay

Maintenance：基于原因感知的上下文衰减

Historical observations do not expire. Maintain the reusable inference or instruction, not whether the incident happened. This applies to all three

.learnings/

files, including one-off and unpromoted entries. Truth and usefulness are separate: a true fact may be irrelevant to this task; a useful workaround may no longer be correct.

历史观察记录不会过期。维护的是可复用的推断或指导，而不是事件是否发生过。这适用于全部三个

.learnings/

文件，包括一次性条目和未提升条目。真实性与有用性相互独立：一个事实可能真实但与当前任务无关；一个有用的 workaround 可能已不再正确。

Type determines HOW to revalidate

类型决定如何重新验证

Type	Check
`reality`	Read the current authoritative source or inspect the current environment for the scoped fact.
`decision`	Find an authoritative, applicable superseding decision; confirm its scope and effective state. Age or a different team's choice does not supersede it.
`dependency`	Establish the relevant version/configuration, then perform representative behavioral verification in that environment. An upgrade triggers a check, not automatic retirement.
`relevance`	Assess applicability and usefulness for the current task/project. Disuse does not prove falsehood.

Use

unknown

when the cause is not established. If a claim has multiple causes, check each or split distinct claims into named Maintenance blocks. Do not infer semantic type/rate from priority, status, recurrence, or

Pattern-Key

regex matches. Session sweeps may mix unrelated errors: classify claims during triage, preserving and linking the original sweep.

类型	检查方式
`reality`	阅读当前权威来源，或在限定范围内检查当前环境，以确认事实。
`decision`	查找权威且适用的替代决策；确认其范围和生效状态。时间久远或另一团队的选择不会使其失效。
`dependency`	确定相关版本/配置，然后在相应环境中执行有代表性的行为验证。升级会触发检查，而不是自动退役。
`relevance`	评估其对当前任务/项目的适用性和有用性。不再使用并不能证明其为假。

当原因尚未确定时使用

unknown

。如果一个声明存在多个原因，请分别检查每个原因，或将不同声明拆分为具名的 Maintenance 块。不要根据 priority、status、recurrence 或

Pattern-Key

正则匹配来推断语义类型/速率。Session 扫描可能混入不相关的错误：在分诊期间对其进行分类，并保留和关联原始扫描。

Rate determines WHEN to review

速率决定何时审查

```
fast
```
: volatile; check near each relevant use.
```
medium
```
: revisit at relevant task/project milestones during active work.
```
slow
```
: stable; review occasionally at relevant major changes or milestones.
```
durable
```
: expected to persist; review when authority, assumptions, or applicability is challenged.
```
unknown
```
: no supported cadence yet; triage before relying on it.

These are qualitative rates, not universal half-lives, expiry dates, or deletion rules. Record a concrete trigger for the claim. Relevant events (source updates, superseding decisions, dependency/configuration changes, project/task shifts, contradictions) override cadence, even for

durable

claims. No scheduler or autonomous background revalidation is needed.

```
fast
```
：易变；在每次相关使用前检查。
```
medium
```
：在活跃工作期间的相关任务/项目里程碑处重新检查。
```
slow
```
：稳定；在相关重大变更或里程碑处偶尔检查。
```
durable
```
：预计会长期存在；当权威性、假设或适用性受到质疑时检查。
```
unknown
```
：尚无依据的审查节奏；在依赖它之前先分诊。

这些是定性速率，而不是通用半衰期、过期日期或删除规则。为声明记录具体的触发条件。相关事件（来源更新、替代决策、依赖项/配置变更、项目/任务转向、矛盾）优先于速率，即使对于

durable

声明也是如此。不需要调度器或自主后台重新验证。

Lightweight metadata beside the original entry

原始条目旁的轻量元数据

markdown

undefined

markdown

undefined

Maintenance

Claim: reusable inference/instruction, or unknown — needs triage
Scope: applicable project/task/environment and limits, or unknown
Authority: source path/section, decision ID, environment, or unknown
Decay: reality | decision | dependency | relevance | unknown / fast | medium | slow | durable | unknown
Revalidate: event/cadence; specific check to perform
Validation: pending | verified | unresolved | contradicted
Evidence: none yet; when checked, actual date, source/version/configuration, check and result (including failures/conflicts)
Disposition: retain | revise | externalize | retire; reason and task applicability
Guidance: none, or target file + section and source-learning ID


Start with `Validation: pending`, `Evidence: none yet`, and `Disposition: retain — provisional, not validated` unless actual evidence supports more. An attempted review is not validation: unavailable or conflicting evidence stays `unresolved`, with the attempt date, blocker, and next check; do not advance a successful validation date. Keep past evidence dated and scoped when appending later results. `Status` tracks issue resolution/promotion, `Validation` tracks support for the claim, and `Disposition` tracks active guidance; none implies the others.

Claim: reusable inference/instruction, or unknown — needs triage
Scope: applicable project/task/environment and limits, or unknown
Authority: source path/section, decision ID, environment, or unknown
Decay: reality | decision | dependency | relevance | unknown / fast | medium | slow | durable | unknown
Revalidate: event/cadence; specific check to perform
Validation: pending | verified | unresolved | contradicted
Evidence: none yet; when checked, actual date, source/version/configuration, check and result (including failures/conflicts)
Disposition: retain | revise | externalize | retire; reason and task applicability
Guidance: none, or target file + section and source-learning ID


初始时使用 `Validation: pending`、`Evidence: none yet` 和 `Disposition: retain — provisional, not validated`，除非实际证据支持更进一步的结论。尝试审查不等于验证：证据不可用或存在冲突时保持 `unresolved`，并记录尝试日期、阻碍因素和下次检查时间；不要推进成功的验证日期。追加后续结果时，保留过去证据的日期和范围。`Status` 跟踪问题解决/提升状态，`Validation` 跟踪声明的支持情况，`Disposition` 跟踪当前有效指导；三者互不蕴含。

Review, reuse, and promotion loop

审查、复用和提升循环

Select entries relevant to the current task by area, files, keywords, or source IDs, plus affected/due claims at natural breakpoints. Do not audit the whole log every turn or select only pending/promoted/repeated entries.
Triage legacy/mixed entries: identify the reusable claim, scope, authority, type/rate, and trigger. Keep unknowns explicit. A resolved incident, successful recovery, or repeated occurrence does not prove a universally valid rule.
Check applicability and whether the trigger fired or evidence is due before reuse or promotion. Run the type-appropriate check when needed; record actual evidence, not an intended command. If evidence is missing/conflicting, do not present or promote the claim as verified. State uncertainty and seek the source or use an appropriately scoped fallback; do not remove safeguards while blocked.
Choose
```
retain
```
(supported and useful, or explicitly provisional while blocked),
```
revise
```
(correct/narrow with evidence),
```
externalize
```
(replace volatile detail with a usable retrieval instruction), or
```
retire
```
(exclude from active guidance with an evidenced reason). Externalization names where to look, what to read/test, and what to do if inaccessible/conflicting; a vague “check docs” is insufficient. Verify that the retrieval path is usable before treating it as validated.
Record and propagate: append a dated review note with the outcome, reason, evidence, and old → new claim when changed. Preserve original observations, resolution, promotion targets/dates, and prior reviews. Update affected promoted guidance using its source link; keep its source-learning ID beside the revised rule (or a retirement note pointing to the preserved history). Never inflate
```
Recurrence-Count
```
/
```
Last-Seen
```
just because a review ran.

Never erase learning/promotion history or delete by age. Never change user preferences, weaken security policies, or rewrite skill assets merely because they are old or unused. Skill creation/modification requires explicit scoped approval; approval for this integration does not authorize future skill rewrites. If a needed target edit is outside granted scope, record the proposed change as pending in the source entry and report the still-active guidance rather than silently claiming it is updated.

For worked review outcomes and provenance, read maintenance examples. To evaluate the maintenance instructions, use the isolated scenarios in maintenance behavioral evaluations. These are evaluation fixtures, not checks to run during ordinary learning capture.

选择当前任务相关的条目，依据领域、文件、关键字或来源 ID 进行筛选，同时在自然断点处检查受影响/到期的声明。不要每轮审查整个日志，也不要只选择待处理/已提升/重复出现的条目。
分诊旧版/混合条目：确定可复用声明、范围、权威来源、类型/速率和触发条件。明确保留未知项。问题已解决、恢复成功或重复发生，都不能证明存在普遍有效的规则。
检查适用性以及在复用或提升前触发条件是否已经触发或证据是否到期。必要时执行与类型匹配的检查；记录实际证据，而不是计划执行的命令。如果证据缺失/冲突，不要把该声明表述或提升为已验证。说明不确定性并寻找来源，或采用范围适当的 fallback；在受阻时不要移除安全防护。
选择
```
retain
```
（有证据支持且有用，或在受阻时明确作为临时规则）、
```
revise
```
（根据证据进行纠正或收窄）、
```
externalize
```
（用可用的检索说明替换易变细节）或
```
retire
```
（基于已有证据将其排除出当前指导）。Externalization 必须指明去哪里查看、读取/测试什么，以及无法访问/存在冲突时该怎么做；仅仅说“查看文档”是不够的。在将检索路径视为已验证之前，确认其可用。
记录并传播：追加带日期的审查说明，其中包含结果、原因、证据，以及发生变更时的旧声明 → 新声明。保留原始观察、解决情况、提升目标/日期和先前审查结果。更新受影响的已提升指导时使用其来源链接；在修订后的规则旁保留其来源学习 ID（或使用指向已保留历史的退役说明）。不要仅仅因为执行了审查就增加
```
Recurrence-Count
```
/
```
Last-Seen
```
。

绝不删除学习/提升历史，也不要因时间久远而删除条目。绝不因为 skill 资产较旧或未使用，就更改用户偏好、削弱安全策略或重写 skill 资产。创建/修改 skill 需要明确且范围明确的批准；批准此次集成并不授权未来重写 skill。如果所需的目标编辑不在授权范围内，请在来源条目中将拟议更改记录为 pending，并报告仍然有效的指导，而不是在未实际更新时声称其已更新。

有关已完成的审查结果和溯源信息，请阅读维护示例。要评估维护说明，请使用维护行为评估中的隔离场景。这些是评估 fixtures，而非普通经验捕获过程中需要运行的检查。

ID Generation

ID 生成

Format:

TYPE-YYYYMMDD-XXX

TYPE:
```
LRN
```
(learning),
```
ERR
```
(error),
```
FEAT
```
(feature)
YYYYMMDD: Current date
XXX: Sequential number or random 3 chars (e.g.,
```
001
```
,
```
A7B
```
)

Examples:

LRN-20250115-001

ERR-20250115-A3F

FEAT-20250115-002

格式：

TYPE-YYYYMMDD-XXX

TYPE：
```
LRN
```
（经验）、
```
ERR
```
（错误）、
```
FEAT
```
（功能）
YYYYMMDD：当前日期
XXX：顺序编号或随机的 3 个字符（例如
```
001
```
、
```
A7B
```
）

示例：

LRN-20250115-001

、

ERR-20250115-A3F

、

FEAT-20250115-002

Resolving Entries

解决条目

When an issue is fixed, update the entry:

Change
```
**Status**: pending
```
→
```
**Status**: resolved
```
Add resolution block after Metadata:

markdown

undefined

问题修复后，更新条目：

将
```
**Status**: pending
```
→
```
**Status**: resolved
```
在 Metadata 之后添加 Resolution 块：

markdown

undefined

Resolution

Resolved: 2025-01-16T09:00:00Z
Commit/PR: abc123 or #42
Notes: Brief description of what was done


Other status values:
- `in_progress` - Actively being worked on
- `wont_fix` - Decided not to address (add reason in Resolution notes)
- `promoted` - Elevated to a workspace file (`SOUL.md`, `TOOLS.md`, `AGENTS.md`)

Keep the Resolution block when promoting. A working fix establishes what happened in that incident; validate any reusable rule separately through Maintenance.

Resolved: 2025-01-16T09:00:00Z
Commit/PR: abc123 or #42
Notes: Brief description of what was done


其他 status 值：
- `in_progress`——正在处理
- `wont_fix`——已决定不处理（在 Resolution 说明中注明原因）
- `promoted`——已提升到 workspace 文件（`SOUL.md`、`TOOLS.md`、`AGENTS.md`）

提升时保留 Resolution 块。有效的修复可以确定该次事件中发生了什么；任何可复用规则需通过 Maintenance 单独验证。

Promoting to Workspace Memory

提升到 Workspace 记忆

When a learning is broadly applicable (not a one-off fix), promote it to a workspace file so every session inherits it.

当某项经验具有广泛适用性（而非一次性修复）时，将其提升到 workspace 文件，使每个 session 都能继承。

When to Promote

何时提升

Learning applies across multiple files/features
Knowledge any contributor (human or AI) should know
Prevents recurring mistakes
Documents project-specific conventions

经验适用于多个文件/功能
记录任何贡献者（人或 AI）都应了解的知识
防止重复犯错
记录项目特定约定

Promotion Targets

提升目标

Target	What Belongs There
`SOUL.md`	Behavioral guidelines, communication style, principles
`TOOLS.md`	Tool capabilities, usage patterns, integration gotchas
`AGENTS.md`	Workflows, delegation patterns, automation rules

When the learning is specific to a project repo you work in (not the workspace), promote to that project's own agent file (e.g. its

AGENTS.md

) instead.

目标	适用内容
`SOUL.md`	行为指导、沟通风格、原则
`TOOLS.md`	工具能力、使用模式、集成陷阱
`AGENTS.md`	工作流、委派模式、自动化规则

如果你处理的项目仓库特定（而非 workspace），则将其提升到该项目自己的 Agent 文件（例如其

AGENTS.md

）。

How to Promote

如何提升

Review the scoped claim through Maintenance first. Promote only supported, useful guidance, not unresolved assumptions or recurrence alone.
Distill and add a concise scoped rule or usable retrieval instruction to the appropriate target. Include
```
Source: .learnings/<file>.md#<entry-ID>
```
beside it (use the actual relative path from the target; the ID is searchable even if the renderer's anchor differs).
Update the original entry: set
```
**Status**: promoted
```
, append the promotion date and target file/section, and set
```
Guidance
```
to that location. Preserve any resolution and earlier promotion history. Future revisions follow this two-way link.

先通过 Maintenance 审查限定范围的声明。仅提升有证据支持且有用的指导，不要提升未解决的假设或仅仅因为重复出现的内容。
将简洁、范围明确的规则或可用的检索说明提炼并添加到合适的目标文件。在旁边附上
```
Source: .learnings/<file>.md#<entry-ID>
```
（使用相对于目标文件的实际路径；即使渲染器生成的 anchor 不同，ID 仍可搜索）。
更新原始条目：将
```
**Status**: promoted
```
，追加提升日期和目标文件/章节，并将
```
Guidance
```
设为该位置。保留任何 resolution 和早期提升历史。后续修订遵循这个双向链接。

Promotion Examples

提升示例

Learning (verbose):

Project uses pnpm workspaces. Attempted
npm install
but failed. Lock file is
pnpm-lock.yaml
. Must use
pnpm install
.

In TOOLS.md (externalized after checking the retrieval path):

markdown

undefined

经验（冗长）：

项目使用 pnpm workspaces。尝试
npm install
但失败。锁文件为
pnpm-lock.yaml
。必须使用
pnpm install
。

在 TOOLS.md 中（检查检索路径后进行 externalize）：

markdown

undefined

Build & Dependencies

Before installing, read this repo's
```
package.json
```
```
packageManager
```
field and lockfile. Use the declared manager; if missing or conflicting, consult the build instructions/maintainer before installing. Source: .learnings/LEARNINGS.md#LRN-20250115-002


**Learning** (verbose):
> When modifying API endpoints, must regenerate TypeScript client.
> Forgetting this causes type mismatches at runtime.

**In AGENTS.md** (actionable):
```markdown

Before installing, read this repo's
```
package.json
```
```
packageManager
```
field and lockfile. Use the declared manager; if missing or conflicting, consult the build instructions/maintainer before installing. Source: .learnings/LEARNINGS.md#LRN-20250115-002


**经验**（冗长）：
> 修改 API endpoints 时，必须重新生成 TypeScript client。
> 忘记执行此操作会导致运行时出现类型不匹配。

**在 AGENTS.md 中**（可执行）：
```markdown

After API Changes

Regenerate client:
```
pnpm run generate:api
```
Check for type errors:
```
pnpm tsc --noEmit
```
Source: .learnings/LEARNINGS.md#LRN-20250116-001 (scope: this repo's current generator/configuration)

undefined

Regenerate client:
```
pnpm run generate:api
```
Check for type errors:
```
pnpm tsc --noEmit
```
Source: .learnings/LEARNINGS.md#LRN-20250116-001 (scope: this repo's current generator/configuration)

undefined

Pattern-Key Taxonomy

Pattern-Key 分类体系

Pattern-Key

is the stable dedup and recurrence key for entries in all three log files: keyword grep misses semantically identical but differently-worded entries, a shared key does not — and reliable keys are what make

Recurrence-Count

and the promotion rule work.

Format:

area.symptom

— exactly two levels, lowercase, hyphenated (e.g.

deps.module-not-found

). Keep symptoms generic enough to recur: no file names, versions, or hostnames in keys.

Area	Scope	Example Keys
`api`	External API/service behavior	`api.rate-limit` , `api.schema-mismatch` , `api.missing-endpoint`
`auth`	Credentials, tokens, scopes	`auth.token-expired` , `auth.missing-scope`
`build`	Compilation, bundling, CI	`build.type-error` , `build.missing-artifact`
`config`	Config files, env vars, settings	`config.missing-env` , `config.invalid-json`
`deps`	Package managers, dependencies	`deps.module-not-found` , `deps.npm-error` , `deps.version-conflict`
`fs`	Filesystem	`fs.no-such-file` , `fs.permission-denied`
`net`	Network connectivity	`net.connection-refused` , `net.timeout`
`runtime`	Language/runtime errors not covered above	`runtime.type-error` , `runtime.python-exception`
`shell`	Shell/CLI mechanics	`shell.command-not-found` , `shell.nonzero-exit`
`vcs`	Git and other version control	`vcs.fatal-error` , `vcs.merge-conflict`
`simplify` / `harden`	Code-quality patterns from the simplify-and-harden feed	`simplify.dead_code` , `harden.input_validation`

Rules:

Reuse before minting:
```
grep -rh "Pattern-Key:" .learnings/ | sort -u
```
— a near-match beats a new key.
One key per manual entry; auto-swept OpenClaw entries may carry several — triage unrelated claims separately and link to the preserved sweep.
Mint new areas sparingly — only when several entries would share one.
Generic sweep keys (
```
runtime.error
```
,
```
runtime.failure
```
) mean "unclassified" — replace with a specific key during triage.

Pattern-Key

是所有三个日志文件中用于去重和记录复发的稳定键：仅使用关键字 grep 会遗漏语义相同但措辞不同的条目，而共享键不会遗漏——可靠的键是让

Recurrence-Count

和提升规则发挥作用的关键。

格式：

area.symptom

——必须恰好为两级、小写、连字符分隔（例如

deps.module-not-found

）。症状应足够通用，以便重复出现：键中不要包含文件名、版本或主机名。

领域	范围	示例键
`api`	外部 API/服务行为	`api.rate-limit` 、 `api.schema-mismatch` 、 `api.missing-endpoint`
`auth`	凭据、tokens、scopes	`auth.token-expired` 、 `auth.missing-scope`
`build`	编译、打包、CI	`build.type-error` 、 `build.missing-artifact`
`config`	配置文件、环境变量、设置	`config.missing-env` 、 `config.invalid-json`
`deps`	包管理器、依赖项	`deps.module-not-found` 、 `deps.npm-error` 、 `deps.version-conflict`
`fs`	文件系统	`fs.no-such-file` 、 `fs.permission-denied`
`net`	网络连接	`net.connection-refused` 、 `net.timeout`
`runtime`	未被上述类别覆盖的语言/运行时错误	`runtime.type-error` 、 `runtime.python-exception`
`shell`	Shell/CLI 机制	`shell.command-not-found` 、 `shell.nonzero-exit`
`vcs`	Git 和其他版本控制系统	`vcs.fatal-error` 、 `vcs.merge-conflict`
`simplify` / `harden`	来自 simplify-and-harden feed 的代码质量模式	`simplify.dead_code` 、 `harden.input_validation`

规则：

复用优先于新建：
```
grep -rh "Pattern-Key:" .learnings/ | sort -u
```
——近似匹配优于创建新键。
每个手动条目使用一个键；自动扫描生成的 OpenClaw 条目可以携带多个键——分别分诊不相关的声明，并关联到已保留的扫描记录。
谨慎创建新领域——仅当多个条目需要共享同一领域时才创建。
通用扫描键（
```
runtime.error
```
、
```
runtime.failure
```
）表示“未分类”——在分诊期间将其替换为具体键。

Recurring Pattern Detection

重复模式检测

If logging something similar to an existing entry:

Search by key first:
```
grep -n "Pattern-Key: area.symptom" .learnings/*.md
```
— this is the default dedup check and catches rewordings that keyword search misses
Fallback keyword search:
```
grep -ri "keyword" .learnings/
```
for entries logged without a key
Fold, don't duplicate: confirm the same claim and scope, not just a key match. For a genuinely new occurrence, bump
```
Recurrence-Count
```
, set
```
Last-Seen
```
, and link the evidence; review/re-reading is not recurrence
Bump priority if issue keeps recurring
Consider systemic fix: Recurring issues often indicate:
- Missing knowledge (→ promote to
```
TOOLS.md
```
  or
```
SOUL.md
```
  )
- Missing automation (→ add to
```
AGENTS.md
```
  )
- Architectural problem (→ create tech debt ticket)

如果记录的内容与现有条目相似：

首先按键搜索：
```
grep -n "Pattern-Key: area.symptom" .learnings/*.md
```
——这是默认的去重检查，可发现关键字搜索遗漏的不同措辞
后备关键字搜索：
```
grep -ri "keyword" .learnings/
```
用于搜索没有键的已记录条目
合并而非重复：确认是相同声明和范围，而不只是键匹配。对于真正的新发生情况，增加
```
Recurrence-Count
```
，更新
```
Last-Seen
```
并关联证据；审查/重读不算重复发生
如果问题持续重复出现，则提高 priority
考虑系统性修复：重复出现的问题通常表明：
- 缺少知识（→ 提升至
```
TOOLS.md
```
  或
```
SOUL.md
```
  ）
- 缺少自动化（→ 添加到
```
AGENTS.md
```
  ）
- 存在架构问题（→ 创建技术债 ticket）

Simplify & Harden Feed

If a task supplies simplify/harden candidates, ingest them here; no other skill is required. Manual capture uses the same recurrence and maintenance rules.

如果任务提供了 simplify/harden 候选项，则在此摄取；不需要其他 skill。手动捕获遵循相同的重复与维护规则。

Ingestion Workflow

摄取工作流

Read

simplify_and_harden.learning_loop.candidates

from the task summary.

For each candidate, use
```
pattern_key
```
as the stable dedupe key.

.learnings/LEARNINGS.md

for an existing entry with that key:

grep -n "Pattern-Key: <pattern_key>" .learnings/LEARNINGS.md

If found:
- Increment
```
Recurrence-Count
```
  and update
```
Last-Seen
```
  only for a new occurrence of the same scoped claim
- Add
```
See Also
```
  links to related entries/tasks

If not found:

Create a new
```
LRN-...
```
entry
Set
```
Source: simplify-and-harden
```

Set

Pattern-Key

Recurrence-Count: 1

, and

First-Seen

Last-Seen

从任务摘要中读取

simplify_and_harden.learning_loop.candidates

。

对每个候选项，使用
```
pattern_key
```
作为稳定的去重键。

在

.learnings/LEARNINGS.md

中搜索具有相同键的现有条目：

grep -n "Pattern-Key: <pattern_key>" .learnings/LEARNINGS.md

如果找到：
- 仅针对同一限定范围声明的新发生情况，增加
```
Recurrence-Count
```
  并更新
```
Last-Seen
```
- 添加指向相关条目/任务的
```
See Also
```
  链接

如果未找到：

创建新的
```
LRN-...
```
条目
设置
```
Source: simplify-and-harden
```

设置

Pattern-Key

、

Recurrence-Count: 1

以及

First-Seen

Last-Seen

Promotion Rule (System Prompt Feedback)

提升规则（系统提示词反馈）

Consider recurring patterns for promotion when all are true:

```
Recurrence-Count >= 3
```
Seen across at least 2 distinct tasks
Occurred within a 30-day window

These are candidate signals, not proof or expiry rules. Apply Maintenance before promotion; one-off learnings still receive maintenance without meeting these thresholds.

Promotion targets:

SOUL.md

TOOLS.md

, or

AGENTS.md

(workspace), or the project's own agent file when the pattern is project-specific.

Write promoted rules as short prevention rules (what to do before/while coding), not long incident write-ups.

当以下条件全部成立时，将重复模式视为提升候选：

```
Recurrence-Count >= 3
```
出现在至少 2 个不同任务中
发生在 30 天的时间窗口内

这些只是候选信号，并非证明或过期规则。应用 Maintenance 后再提升；即使一次性经验不满足这些阈值，也仍需进行维护。

提升目标：workspace 中的

SOUL.md

、

TOOLS.md

或

AGENTS.md

；如果模式特定于某个项目，则使用该项目自己的 Agent 文件。

将提升后的规则写成简短的预防规则（编码前/过程中该做什么），而不是冗长的事件记录。

Periodic Review

定期审查

Review relevant/due claims using Maintenance at natural breakpoints; not the entire log every turn:

在自然断点处使用 Maintenance 审查相关/到期声明；不要每轮审查整个日志：

When to Review

何时审查

Before starting a new major task
After completing a feature
When working in an area with past learnings
Weekly during active development

开始新的重大任务前
完成一个功能后
在存在历史经验的领域工作时
活跃开发期间每周

Quick Status Check

快速状态检查

bash

undefined

bash

undefined

Count pending items

grep -h "Status**: pending" .learnings/*.md | wc -l

List pending high-priority items

grep -B5 "Priority**: high" .learnings/*.md | grep "^## ["

Find learnings for a specific area

grep -l "Area**: backend" .learnings/*.md

undefined

grep -l "Area**: backend" .learnings/*.md

undefined

Review Actions

审查操作

Resolve fixed items
Revalidate relevant/due claims of any status, including one-off/unpromoted learnings
Retain, revise, externalize, or retire active guidance while preserving history
Promote supported, applicable learnings with source links
Link related entries
Escalate recurring issues

解决已修复项
重新验证任何状态的相关/到期声明，包括一次性/未提升的经验
在保留历史的同时，保留、修订、externalize 或 retire 当前有效指导
提升有证据支持且适用的经验，并附来源链接
关联相关条目
升级处理重复出现的问题

Detection Triggers

检测触发条件

Evaluate the event in context before logging. The phrases below are cues, not automatic logging commands; ordinary questions and follow-up tasks alone do not justify persistent entries.

Corrections (→ learning with

correction

category):

"No, that's not right..."
"Actually, it should be..."
"You're wrong about..."
"That's outdated..."

Feature Requests (→ feature request):

Log only a requested capability shown to be missing from the relevant tool/version. Record evidence and limits.
"Can you also..." or "Is there a way to..." is not evidence of a missing feature. Use existing capabilities normally; do not log ordinary follow-ups.
If availability is unclear, check documentation or tool behavior, or ask. Do not create a feature request based on wording alone.

Knowledge Gaps (→ learning with

knowledge_gap

category):

User provides information you didn't know
Documentation you referenced is outdated
API behavior differs from your understanding

Errors (→ error entry):

Command returns non-zero exit code
Exception or stack trace
Unexpected output or behavior
Timeout or connection failure

记录前结合上下文评估事件。以下短语只是提示，不是自动记录命令；普通问题和后续任务本身不足以证明需要持久化条目。

纠正（→ 类别为

correction

的经验）：

“不，不对……”
“实际上，它应该是……”
“你错了……”
“那已经过时了……”

功能请求（→ 功能请求）：

仅记录相关工具/版本中确实缺失的、被用户请求的功能。记录证据和限制。
“你还能……”或“有没有办法……”并不是相关工具/版本缺少功能的证据。正常情况下使用现有能力；不要仅根据措辞记录功能请求。
如果可用性不明确，请检查文档或工具行为，或进行询问。不要仅根据措辞创建功能请求。

知识缺口（→ 类别为

knowledge_gap

的经验）：

用户提供了你不知道的信息
你引用的文档已过时
API 行为与你的理解不同

错误（→ 错误条目）：

命令返回非零退出码
出现异常或 stack trace
出现意外输出或行为
超时或连接失败

Priority Guidelines

Priority 指南

Priority	When to Use
`critical`	Blocks core functionality, data loss risk, security issue
`high`	Significant impact, affects common workflows, recurring issue
`medium`	Moderate impact, workaround exists
`low`	Minor inconvenience, edge case, nice-to-have

Priority	使用场景
`critical`	阻碍核心功能、存在数据丢失风险或安全问题
`high`	影响显著、影响常用工作流、问题重复出现
`medium`	影响中等、存在 workaround
`low`	轻微不便、边缘情况、可选改进

Area Tags

领域标签

Use to filter learnings by codebase region:

Area	Scope
`frontend`	UI, components, client-side code
`backend`	API, services, server-side code
`infra`	CI/CD, deployment, Docker, cloud
`tests`	Test files, testing utilities, coverage
`docs`	Documentation, comments, READMEs
`config`	Configuration files, environment, settings

使用以下标签按代码库区域筛选经验：

领域	范围
`frontend`	UI、组件、客户端代码
`backend`	API、服务、服务器端代码
`infra`	CI/CD、部署、Docker、cloud
`tests`	测试文件、测试工具、覆盖率
`docs`	文档、注释、README
`config`	配置文件、环境、设置

Best Practices

最佳实践

Log immediately - context is freshest right after the issue
Be specific - future agents need to understand quickly
Include reproduction steps - especially for errors
Link related files - makes fixes easier
Suggest concrete fixes - not just "investigate"
Use consistent categories - enables filtering
Promote supported guidance - validate scope and usefulness first; preserve provenance
Review by cause and rate - age alone proves neither falsehood nor uselessness

立即记录——问题刚发生时上下文最鲜活
具体明确——未来的 Agent 需要快速理解
包含复现步骤——尤其是错误
关联相关文件——便于修复
提出具体修复方案——不要只写“调查”
使用一致的类别——便于筛选
提升有证据支持的指导——先验证范围和有用性；保留溯源信息
根据原因和速率审查——仅凭时间久远既不能证明声明为假，也不能证明其无用

Gitignore Options

Gitignore 选项

Keep learnings local (per-developer):

gitignore

.learnings/

This repo uses that default to avoid committing sensitive or noisy local logs by accident.

Track learnings in repo (team-wide): Don't add to .gitignore - learnings become shared knowledge.

Hybrid (track templates, ignore entries):

gitignore

.learnings/*.md
!.learnings/.gitkeep

保持经验本地化（按开发者）：

gitignore

.learnings/

此仓库默认采用该方式，以避免意外提交敏感或嘈杂的本地日志。

在仓库中跟踪经验（团队共享）：不要添加到 .gitignore——经验将成为共享知识。

混合模式（跟踪模板，忽略条目）：

gitignore

.learnings/*.md
!.learnings/.gitkeep

Upgrading & Uninstalling

升级与卸载

Read

CHANGELOG.md

before upgrading — it carries per-version notes, and hook changes require re-copying the hook and restarting the gateway. To disable or remove the skill, follow

references/uninstall.md

: disabling and uninstalling preserve

.learnings/

and promoted workspace rules. Permanent data deletion or edits to promoted guidance require separate, explicit authorization; they are not part of uninstalling.

升级前阅读

CHANGELOG.md

——其中包含各版本的说明，而且 hook 变更需要重新复制 hook 并重启 gateway。要禁用或移除此 skill，请遵循 references/uninstall.md：禁用和卸载会保留

.learnings/

和已提升的 workspace 规则。永久删除数据或编辑已提升的指导需要单独、明确的授权；它们不属于卸载操作。

Skill Extraction (Approval Required)

Skill 提取（需要批准）

When a learning may justify a reusable skill, use assets/SKILL-TEMPLATE.md. Extracting is optional, never a dependency of maintenance. Obtain explicit scoped approval before creating or modifying skill assets.

The template includes candidate criteria, helper commands, quality gates, and two-way provenance. Review the scoped claim before extraction; a resolved incident or recurrence alone is not verification. Later asset changes require their own scoped approval.

当某项经验可能足以形成一个可复用 skill 时，使用 assets/SKILL-TEMPLATE.md。提取是可选的，永远不是维护流程的依赖项。在创建或修改 skill 资产前取得明确且范围明确的批准。

该模板包含候选项标准、辅助命令、质量门禁和双向溯源。在提取前审查限定范围的声明；问题已解决或重复出现本身并不构成验证。后续资产变更需要各自独立的明确批准。