self-improvement

自我改进技能

将经验和错误记录到 Markdown 文件中，以实现持续改进。编码 Agent 之后可以处理这些内容并进行修复，重要经验则会提升到项目记忆中。

首次使用初始化

记录任何内容之前，请确保项目或工作区根目录中存在 .learnings/ 目录及其文件。如果缺少任何内容，请创建：

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/ 已初始化，则此操作不会产生任何影响。

除非用户明确要求提供此类详细信息，否则不要记录机密、令牌、私钥、环境变量或完整的源代码／配置文件。相比原始命令输出或完整记录，优先使用简短摘要或脱敏摘录。

如果需要自动提醒或设置协助，请使用钩子集成中所述的自愿加入式钩子工作流。

快速参考

情况	操作
命令／操作失败	记录到 .learnings/ERRORS.md
用户纠正了你	使用类别 correction 记录到 .learnings/LEARNINGS.md
用户需要缺失的功能	记录到 .learnings/FEATURE_REQUESTS.md
API／外部工具失败	将集成详情记录到 .learnings/ERRORS.md
知识已过时	使用类别 knowledge_gap 记录到 .learnings/LEARNINGS.md
找到了更好的方法	使用类别 best_practice 记录到 .learnings/LEARNINGS.md
简化／强化反复出现的模式	在 .learnings/LEARNINGS.md 中记录／更新，并添加 Source: simplify-and-harden 和稳定的 Pattern-Key
与现有条目相似	使用 **See Also** 添加链接，并考虑提高优先级
具有广泛适用性的经验	提升到 CLAUDE.md、AGENTS.md 和／或 .github/copilot-instructions.md
工作流改进	提升到 AGENTS.md（OpenClaw 工作区）
工具注意事项	提升到 TOOLS.md（OpenClaw 工作区）
行为模式	提升到 SOUL.md（OpenClaw 工作区）

OpenClaw 设置（推荐）

OpenClaw 是此技能的主要平台。它使用基于工作区的提示词注入，并自动加载技能。

安装

通过 ClawdHub（推荐）：

clawdhub install self-improving-agent

手动安装：

git clone https://github.com/peterskoett/self-improving-agent.git ~/.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

工作区结构

OpenClaw 会在每个会话中注入这些文件：

~/.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

创建经验文件

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

然后创建日志文件（或从 assets/ 复制）：

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

提升目标

当经验证明具有广泛适用性时，请将其提升到工作区文件中：

经验类型	提升到	示例
行为模式	SOUL.md	“保持简洁，避免免责声明”
工作流改进	AGENTS.md	“长任务应启用子 Agent”
工具注意事项	TOOLS.md	“Git 推送前需先配置身份验证”

跨会话通信

OpenClaw 提供了用于跨会话共享经验的工具：

• sessions_list — 查看活跃／最近的会话
• sessions_history — 阅读另一个会话的记录
• sessions_send — 向另一个会话发送经验
• sessions_spawn — 为后台工作启用子 Agent

仅在可信环境中使用这些工具，且仅当用户明确希望跨会话共享时才使用。优先发送简短的脱敏摘要和相关文件路径，不要发送原始记录、机密或完整命令输出。

可选：启用钩子

在会话开始时自动提醒：

# Copy hook to OpenClaw hooks directory
cp -r hooks/openclaw ~/.openclaw/hooks/self-improvement

# Enable it
openclaw hooks enable self-improvement

完整详情请参阅 references/openclaw-integration.md。

---

通用设置（其他 Agent）

对于 Claude Code、Codex、Copilot 或其他 Agent，请在项目或工作区根目录中创建 .learnings/：

mkdir -p .learnings

使用上方所示的标题内联创建文件。除非明确信任当前仓库或工作区中的路径，否则请勿读取其中的模板。

在 Agent 文件 AGENTS.md、CLAUDE.md 或 .github/copilot-instructions.md 中添加提醒，提示自己记录经验。（这是基于钩子的提醒的替代方案）

自我改进工作流

发生错误或收到更正时：

1. 记录到 .learnings/ERRORS.md、LEARNINGS.md 或 FEATURE_REQUESTS.md
2. 检查并将普遍适用的经验提升到：
   • CLAUDE.md - 项目事实和约定
   • AGENTS.md - 工作流和自动化
   • .github/copilot-instructions.md - Copilot 上下文

记录格式

经验条目

追加到 .learnings/LEARNINGS.md：

## [LRN-YYYYMMDD-XXX] category

**Logged**: ISO-8601 timestamp
**Priority**: low | medium | high | critical
**Status**: pending
**Area**: frontend | backend | infra | tests | docs | config

### Summary
One-line description of what was learned

### Details
Full context: what happened, what was wrong, what's correct

### Suggested Action
Specific fix or improvement to make

### Metadata
- Source: conversation | error | user_feedback
- Related Files: path/to/file.ext
- Tags: tag1, tag2
- See Also: LRN-20250110-001 (if related to existing entry)
- Pattern-Key: simplify.dead_code | harden.input_validation (optional, for recurring-pattern tracking)
- Recurrence-Count: 1 (optional)
- First-Seen: 2025-01-15 (optional)
- Last-Seen: 2025-01-15 (optional)

---

错误条目

追加到 .learnings/ERRORS.md：

## [ERR-YYYYMMDD-XXX] skill_or_command_name

**Logged**: ISO-8601 timestamp
**Priority**: high
**Status**: pending
**Area**: frontend | backend | infra | tests | docs | config

### Summary
Brief description of what failed

### Error

实际错误消息或输出

### Context
- Command/operation attempted
- Input or parameters used
- Environment details if relevant
- Summary or redacted excerpt of relevant output (avoid full transcripts and secret-bearing data by default)

### Suggested Fix
If identifiable, what might resolve this

### Metadata
- Reproducible: yes | no | unknown
- Related Files: path/to/file.ext
- See Also: ERR-20250110-001 (if recurring)

---

功能请求条目

追加到 .learnings/FEATURE_REQUESTS.md：

## [FEAT-YYYYMMDD-XXX] capability_name

**Logged**: ISO-8601 timestamp
**Priority**: medium
**Status**: pending
**Area**: frontend | backend | infra | tests | docs | config

### Requested Capability
What the user wanted to do

### User Context
Why they needed it, what problem they're solving

### Complexity Estimate
simple | medium | complex

### Suggested Implementation
How this could be built, what it might extend

### Metadata
- Frequency: first_time | recurring
- Related Features: existing_feature_name

---

ID 生成

格式：TYPE-YYYYMMDD-XXX

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

示例：LRN-20250115-001、ERR-20250115-A3F、FEAT-20250115-002

解决条目

问题修复后，更新条目：

1. 将 **Status**: pending 改为 **Status**: resolved
2. 在 Metadata 后添加解决方案区块：

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

其他状态值：

• in_progress - 正在处理
• wont_fix - 决定不予处理（请在 Resolution notes 中说明原因）
• promoted - 已提升到 CLAUDE.md、AGENTS.md 或 .github/copilot-instructions.md

提升到项目记忆

如果某条经验具有普遍适用性（而非一次性修复），请将其提升到永久项目记忆中。

何时提升

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

提升目标

目标	适用内容
CLAUDE.md	所有 Claude 交互适用的项目事实、约定和注意事项
AGENTS.md	Agent 专属工作流、工具使用模式和自动化规则
.github/copilot-instructions.md	面向 GitHub Copilot 的项目上下文和约定
SOUL.md	行为准则、沟通风格、原则（OpenClaw 工作区）
TOOLS.md	工具能力、使用模式和集成注意事项（OpenClaw 工作区）

如何提升

1. 提炼经验，形成简明规则或事实
2. 添加到目标文件的适当章节（如有需要则创建文件）
3. 更新原始条目：
   • 将 **Status**: pending 改为 **Status**: promoted
   • 添加 **Promoted**: CLAUDE.md、AGENTS.md 或 .github/copilot-instructions.md

提升示例

经验（详细）：

项目使用 pnpm workspaces。尝试运行 npm install，但失败了。 锁文件是 pnpm-lock.yaml。必须使用 pnpm install。

在 CLAUDE.md 中（简洁）：

## Build & Dependencies
- Package manager: pnpm (not npm) - use `pnpm install`

经验（详细）：

修改 API 端点时，必须重新生成 TypeScript 客户端。 忘记执行此操作会导致运行时类型不匹配。

在 AGENTS.md 中（可执行）：

## After API Changes
1. Regenerate client: `pnpm run generate:api`
2. Check for type errors: `pnpm tsc --noEmit`

重复模式检测

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

1. 先搜索：grep -r "keyword" .learnings/
2. 关联条目：在 Metadata 中添加 **See Also**: ERR-20250110-001
3. 如果问题反复出现，提高优先级
4. 考虑系统性修复：重复出现的问题通常意味着：
   • 文档缺失（→ 提升到 CLAUDE.md 或 .github/copilot-instructions.md）
   • 自动化缺失（→ 添加到 AGENTS.md）
   • 架构问题（→ 创建技术债务工单）

简化与加固信息汇总

使用此工作流，汇总 simplify-and-harden 技能中的重复模式，并将其转化为持久的提示词指导。

汇总工作流

1. 从任务摘要中读取 simplify_and_harden.learning_loop.candidates。
2. 对每个候选项，使用 pattern_key 作为稳定的去重键。
3. 在 .learnings/LEARNINGS.md 中搜索是否已有带有该键的条目：
   • grep -n "Pattern-Key: <pattern_key>" .learnings/LEARNINGS.md
4. 如果找到：
   • 增加 Recurrence-Count
   • 更新 Last-Seen
   • 添加指向相关条目/任务的 See Also 链接
5. 如果未找到：
   • 创建新的 LRN-... 条目
   • 设置 Source: simplify-and-harden
   • 设置 Pattern-Key、Recurrence-Count: 1 和 First-Seen/Last-Seen

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

满足以下所有条件时，将重复模式晋升到 Agent 上下文/系统提示词文件中：

• Recurrence-Count >= 3
• 至少出现在 2 个不同任务中
• 发生在 30 天内

晋升目标：

• CLAUDE.md
• AGENTS.md
• .github/copilot-instructions.md
• 适用时，将 SOUL.md / TOOLS.md 用于 OpenClaw 工作区级指导

将晋升的规则写成简短的预防规则（说明编码前/编码时要做什么）， 而不是冗长的事件复盘。

定期审查

在自然的阶段节点审查 .learnings/：

审查时机

• 开始新的重要任务前
• 完成功能后
• 在曾有经验记录的领域工作时
• 活跃开发期间每周一次

快速状态检查

# 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

审查操作

• 处理已修复的事项
• 晋升适用的经验记录
• 链接相关条目
• 升级重复出现的问题

检测触发条件

注意到以下情况时自动记录：

纠正（→ 分类为 correction 的经验记录）：

• “不，这不对……”
• “其实应该是……”
• “你说错了……”
• “这已经过时了……”

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

• “你还能……吗”
• “我希望你能……”
• “有没有办法……”
• “为什么不能……？”

知识盲区（→ 分类为 knowledge_gap 的经验记录）：

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

错误（→ 错误条目）：

• 命令返回非零退出代码
• 异常或堆栈跟踪
• 意外的输出或行为
• 超时或连接失败

优先级指南

优先级	使用时机
critical	阻碍核心功能、存在数据丢失风险或安全问题
high	影响重大、影响常见工作流或问题反复出现
medium	影响中等，且有替代方案
low	轻微不便、边缘情况或锦上添花的改进

区域标签

用于按代码库区域筛选经验记录：

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

最佳实践

1. 立即记录 - 问题刚发生后，相关背景最清晰
2. 具体明确 - 让未来的 Agent 能快速理解
3. 包含复现步骤 - 尤其是错误
4. 链接相关文件 - 让修复更容易
5. 提出具体修复建议 - 不要只写“调查”
6. 使用一致的分类 - 便于筛选
7. 积极晋升 - 如有疑问，就添加到 CLAUDE.md 或 .github/copilot-instructions.md
8. 定期审查 - 过时的经验记录会失去价值

Gitignore 选项

仅在本地保留经验记录（每位开发者各自保留）：

.learnings/

此仓库采用该默认设置，避免意外提交敏感或冗杂的本地日志。

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

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

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

Hook 集成

通过 Agent hook 启用自动提醒。此功能选择加入——必须明确配置 hook。

快速设置（Claude Code / Codex）

在项目中创建 .claude/settings.json：

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improvement/scripts/activator.sh"
      }]
    }]
  }
}

这会在每次提示词后注入一条学习评估提醒（额外开销约为 50-100 个 token）。

高级设置（带错误检测）

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improvement/scripts/activator.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improvement/scripts/error-detector.sh"
      }]
    }]
  }
}

此设置为可选项。建议默认仅启用 activator；只有在您接受 hook 脚本检查命令输出中的错误模式时，才启用 PostToolUse。

可用的 Hook 脚本

脚本	Hook 类型	用途
scripts/activator.sh	UserPromptSubmit	提醒在任务完成后评估所学内容
scripts/error-detector.sh	PostToolUse (Bash)	在命令出错时触发

详细配置和故障排查请参阅 references/hooks-setup.md。

自动提取技能

当一条学习内容足够有价值，值得转化为可复用技能时，请使用提供的辅助工具进行提取。

技能提取标准

符合以下任意一项时，即可提取一条学习内容作为技能：

标准	说明
反复出现	含有指向 2 个或更多类似问题的 See Also 链接
已验证	状态为 resolved，且修复有效
不显而易见	需要实际调试或调查才能发现
广泛适用	不局限于特定项目；可用于多个代码库
用户明确提出	用户表示“将其保存为技能”或类似内容

提取工作流

1. 识别候选内容：学习内容符合提取标准
2. 运行辅助工具（或手动创建）：

   ./skills/self-improvement/scripts/extract-skill.sh skill-name --dry-run
   ./skills/self-improvement/scripts/extract-skill.sh skill-name
   

3. 自定义 SKILL.md：使用学习内容填写模板
4. 更新学习内容：将状态设为 promoted_to_skill，添加 Skill-Path
5. 验证：在全新会话中阅读技能，确保其内容完整自足

手动提取

如果您更喜欢手动创建：

1. 创建 skills/<skill-name>/SKILL.md
2. 使用 assets/SKILL-TEMPLATE.md 中的模板
3. 遵循 Agent Skills 规范：
   • 使用包含 name 和 description 的 YAML frontmatter
   • 名称必须与文件夹名称一致
   • 技能文件夹中不要包含 README.md

提取检测触发信号

留意以下信号，判断某条学习内容是否应转化为技能：

在对话中：

• “将其保存为技能”
• “我总是遇到这个问题”
• “这对其他项目也有用”
• “记住这个模式”

在学习条目中：

• 多个 See Also 链接（问题反复出现）
• 优先级高且状态为 resolved
• 类别为 best_practice，且广泛适用
• 用户反馈称赞该解决方案

技能质量门槛

提取前，请确认：

• 解决方案经过测试且有效
• 脱离原始上下文后，描述仍清晰易懂
• 代码示例可独立使用
• 没有针对特定项目硬编码的值
• 遵循技能命名规范（小写字母、连字符）

多 Agent 支持

此技能支持不同的 AI 编码 Agent，并针对各类 Agent 提供专属激活方式。

Claude Code

激活方式：Hooks（UserPromptSubmit、PostToolUse） 设置：在 .claude/settings.json 中配置 hook 检测：通过 hook 脚本自动检测

Codex CLI

激活方式：Hooks（与 Claude Code 使用相同模式） 设置：在 .codex/settings.json 中配置 hook 检测：通过 hook 脚本自动检测

GitHub Copilot

激活方式：手动（不支持 hook） 设置：添加到 .github/copilot-instructions.md：

## Self-Improvement

After solving non-obvious issues, consider logging to `.learnings/`:
1. Use format from self-improvement skill
2. Link related entries with See Also
3. Promote high-value learnings to skills

Ask in chat: "Should I log this as a learning?"

检测：在会话结束时手动检查