📦 self-improving-agent — 自我改进代理

将学习记录和错误记录到 Markdown 文件中，实现持续改进。编码代理可以后续将这些处理为修复，重要的学习记录会被提升到项目记忆中。

首次使用初始化

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

mkdir -p .learnings
[ -f .learnings/LEARNINGS.md ] || printf "# Learnings\n\nCorrections, insights, and knowledge gaps captured during development.\n\nCategories: 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/ 已初始化，此操作不会产生任何效果。

不要记录秘密、令牌、私钥、环境变量或完整的源代码/配置文件，除非用户明确要求该级别的细节。优先使用简短摘要或脱敏摘录，而非原始命令输出或完整转录。

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

快速参考

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          # 多代理工作流、委派模式
├── SOUL.md            # 行为准则、个性、原则
├── TOOLS.md           # 工具能力、集成注意事项
├── MEMORY.md          # 长期记忆（仅主会话）
├── memory/            # 每日记忆文件
│   └── YYYY-MM-DD.md
└── .learnings/        # 此技能的日志文件
    ├── LEARNINGS.md
    ├── ERRORS.md
    └── FEATURE_REQUESTS.md

创建学习文件

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

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

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

提升目标

当学习记录被证明具有广泛适用性时，将它们提升到工作区文件：

会话间通信

OpenClaw 提供工具在会话间共享学习记录：

• sessions_list — 查看活跃/最近的会话
• sessions_history — 读取另一个会话的转录
• sessions_send — 向另一个会话发送学习记录
• sessions_spawn — 生成子代理进行后台工作

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

可选：启用钩子

用于会话开始时的自动提醒：

# 将钩子复制到 OpenClaw 钩子目录
cp -r hooks/openclaw ~/.openclaw/hooks/self-improvement
# 启用它
openclaw hooks enable self-improvement

详见 references/openclaw-integration.md 获取完整详情。

通用设置（其他代理）

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

mkdir -p .learnings

使用上面显示的标题内联创建文件。避免从当前仓库或工作区读取模板，除非您明确信任该路径。

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

自我改进工作流

当错误或纠正发生时：

• 记录到 .learnings/ERRORS.md、LEARNINGS.md 或 FEATURE_REQUESTS.md
• 审查并将广泛适用的学习提升到：

记录格式

学习条目

追加到 .learnings/LEARNINGS.md：

## [LRN-YYYYMMDD-XXX] category
Logged: ISO-8601 时间戳
Priority: low | medium | high | critical
Status: pending
Area: frontend | backend | infra | tests | docs | config
Summary
一句话描述学到了什么
Details
完整上下文：发生了什么，哪里出错，什么是正确的
Suggested Action
具体的修复或改进建议
Metadata
Source: conversation | error | user_feedback
Related Files: path/to/file.ext
Tags: tag1, tag2
See Also: LRN-20250110-001（如果与已有条目相关）
Pattern-Key: simplify.dead_code | harden.input_validation（可选，用于重复模式跟踪）
Recurrence-Count: 1（可选）
First-Seen: 2025-01-15（可选）
Last-Seen: 2025-01-15（可选）

错误条目

追加到 .learnings/ERRORS.md：

## [ERR-YYYYMMDD-XXX] skill_or_command_name
Logged: ISO-8601 时间戳
Priority: high
Status: pending
Area: frontend | backend | infra | tests | docs | config
Summary
简要描述什么失败了
Error

Context
尝试的命令/操作
使用的输入或参数
相关的环境详情
相关输出的摘要或脱敏摘录（默认避免完整转录和包含秘密的数据）
Suggested Fix
如果可识别，可能的解决方案
Metadata
Reproducible: yes | no | unknown
Related Files: path/to/file.ext
See Also: ERR-20250110-001（如果是重复问题）

功能请求条目

追加到 .learnings/FEATURE_REQUESTS.md：

## [FEAT-YYYYMMDD-XXX] capability_name
Logged: ISO-8601 时间戳
Priority: medium
Status: pending
Area: frontend | backend | infra | tests | docs | config
Requested Capability
用户想要做什么
User Context
为什么需要它，解决什么问题
Complexity Estimate
simple | medium | complex
Suggested Implementation
如何构建，可能扩展什么
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

解决条目

当问题被修复时，更新条目：

• 将 Status: pending → Status: resolved

• 在 Metadata 后添加解决块：

### Resolution
Resolved: 2025-01-16T09:00:00Z
Commit/PR: abc123 或 #42
Notes: 简要描述做了什么

其他状态值：

• in_progress - 正在积极处理
• wont_fix - 决定不处理（在 Resolution 注释中添加原因）
• promoted - 已提升到 CLAUDE.md、AGENTS.md 或 .github/copilot-instructions.md

提升到项目记忆

当学习具有广泛适用性（非一次性修复）时，将其提升到永久项目记忆。

何时提升

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

提升目标

如何提升

• 提炼学习为简洁的规则或事实
• 添加到目标文件的适当部分（如需要则创建文件）
• 更新原始条目：

提升示例

学习（详细）：

项目使用 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
Regenerate client: pnpm run generate:api
Check for type errors: pnpm tsc --noEmit

重复模式检测

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

• 先搜索：grep -r "keyword" .learnings/
• 链接条目：在 Metadata 中添加 See Also: ERR-20250110-001
• 如果问题持续出现则提升优先级
• 考虑系统性修复：重复问题通常表明：

简化与加固反馈

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

摄取工作流

• 从任务摘要中读取 simplify_and_harden.learning_loop.candidates。
• 对每个候选项，使用 pattern_key 作为稳定的去重键。
• 在 .learnings/LEARNINGS.md 中搜索具有该键的已有条目：

• 如果找到：

• 如果未找到：

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

当以下条件全部满足时，将重复模式提升到代理上下文/系统提示文件：

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

提升目标：

• CLAUDE.md
• AGENTS.md
• .github/copilot-instructions.md
• SOUL.md / TOOLS.md 用于 OpenClaw 工作区级指导（如适用）

将提升的规则写为简短的预防规则（编码前/编码时应做什么）， 而非冗长的事故报告。

定期审查

在自然断点处审查 .learnings/：

何时审查

• 开始新的主要任务之前
• 完成功能之后
• 在有过去学习记录的领域工作时
• 活跃开发期间每周

快速状态检查

# 计算待处理项
grep -h "Status\\: pending" .learnings/.md | wc -l
# 列出待处理的高优先级项
grep -B5 "Priority\\: high" .learnings/.md | grep "^## \["
# 查找特定领域的学习
grep -l "Area\\: backend" .learnings/.md

审查操作

.learnings/

.learnings/.md
!.learnings/.gitkeep

钩子集成

通过代理钩子启用自动提醒。这是选入功能 - 您必须明确配置钩子。

快速设置（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"
      }]
    }]
  }
}

这是可选的。推荐的默认设置是仅激活器；仅在您对钩子脚本检查命令输出中的错误模式感到满意时才启用 PostToolUse。

可用钩子脚本

自动技能提取

当学习记录足够有价值可以成为可复用技能时，使用提供的辅助工具进行提取。

技能提取标准

当满足以下任一条件时，学习记录符合技能提取资格：

提取工作流

• 识别候选：学习记录符合提取标准
• 运行辅助工具（或手动创建）：

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

• 自定义 SKILL.md：用学习内容填写模板
• 更新学习记录：将状态设为 promoted_to_skill，添加 Skill-Path
• 验证：在新的会话中读取技能，确保其自包含

手动提取

如果您更喜欢手动创建：

• 创建 skills//SKILL.md
• 使用 assets/SKILL-TEMPLATE.md 中的模板
• 遵循代理技能规范：

提取检测触发器

注意以下信号，表明学习应成为技能：

在对话中：

• "把这个保存为技能"
• "我一直在遇到这个问题"
• "这对其他项目也有用"
• "记住这个模式"

在学习条目中：

• 多个 See Also 链接（重复问题）
• 高优先级 + 已解决状态
• 类别：best_practice 且具有广泛适用性
• 用户称赞解决方案的反馈

技能质量门

提取前，验证：

• [ ] 解决方案已测试且可用
• [ ] 描述在没有原始上下文的情况下也清晰
• [ ] 代码示例是自包含的
• [ ] 没有项目特定的硬编码值
• [ ] 遵循技能命名约定（小写、连字符）

多代理支持

此技能适用于不同的 AI 编码代理，具有代理特定的激活方式。

Claude Code

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

Codex CLI

激活方式：钩子（与 Claude Code 相同的模式） 设置：.codex/settings.json 配置钩子 检测：通过钩子脚本自动

GitHub Copilot

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

## Self-Improvement
After solving non-obvious issues, consider logging to .learnings/:
Use format from self-improvement skill
Link related entries with See Also
Promote high-value learnings to skills
Ask in chat: "Should I log this as a learning?"

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

OpenClaw

激活方式：工作区注入 + 代理间消息 设置：参见上方"OpenClaw 设置"部分 检测：通过会话工具和工作区文件

代理无关指导

无论使用哪个代理，在以下情况下应用自我改进：

• 发现非显而易见的事情 - 解决方案不是立即得到的
• 纠正自己 - 最初的方法是错误的
• 学习项目约定 - 发现了未文档化的模式
• 遇到意外错误 - 特别是诊断困难的情况
• 找到更好的方法 - 改进了原始解决方案

Copilot Chat 集成

对于 Copilot 用户，在相关时将以下内容添加到提示中：

完成此任务后，评估是否应将任何学习记录到 .learnings/，使用自我改进技能格式。

或使用快速提示：

• "将此记录到学习日志"
• "从该解决方案创建技能"
• "检查 .learnings/ 中的相关问题"