介绍
# Self-Improvement Skill
将学到的东西和错误记录到 Markdown 文件中，以实现持续改进。编码代理稍后可以将这些处理为修复，重要的学习内容将被提升到项目记忆中。
## 快速参考
| 情况 | 操作 | |-----------|--------| | 命令/操作失败 | 记录到 `.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` | | 与现有条目相似 | 使用 `**See Also**` 链接，考虑提升优先级 | | 广泛适用的学习 | 提升到 `CLAUDE.md`、`AGENTS.md` 和/或 `.github/copilot-instructions.md` | | 工作流改进 | 提升到 `AGENTS.md` (clawdbot 工作区) | | 工具陷阱 | 提升到 `TOOLS.md` (clawdbot 工作区) | | 行为模式 | 提升到 `SOUL.md` (clawdbot 工作区) |
## 设置
如果项目根目录中不存在 `.learnings/` 目录，则创建它：
```bash mkdir -p .learnings ```
从 `assets/` 复制模板或创建带有标题的文件。
## 记录格式
### 学习条目
追加到 `.learnings/LEARNINGS.md`：
```markdown ## [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)
--- ```
### 错误条目
追加到 `.learnings/ERRORS.md`：
```markdown ## [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
### 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`：
```markdown ## [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. 在元数据之后添加解决方案块：
```markdown ### Resolution - **Resolved**: 2025-01-16T09:00:00Z - **Commit/PR**: abc123 or #42 - **Notes**: Brief description of what was done ```
其他状态值： - `in_progress` - 正在进行中 - `wont_fix` - 决定不处理（在解决方案说明中添加原因） - `promoted` - 提升到 CLAUDE.md、AGENTS.md 或 .github/copilot-instructions.md
## 提升到项目记忆
当学习内容广泛适用（非一次性修复）时，将其提升为永久的项目记忆。
### 何时提升
- 学习内容适用于多个文件/功能 - 任何贡献者（人类或 AI）都应该知道的知识 - 防止重复错误 - 记录项目特定的约定
### 提升目标
| 目标 | 包含内容 | |--------|-------------------| | `CLAUDE.md` | 项目事实、约定、所有 Claude 交互的注意事项 | | `AGENTS.md` | 特定于代理的工作流、工具使用模式、自动化规则 | | `.github/copilot-instructions.md` | GitHub Copilot 的项目上下文和约定 | | `SOUL.md` | 行为准则、沟通风格、原则 | | `TOOLS.md` | 工具功能、使用模式、集成注意事项 |
### 如何提升
1. **提炼** 学习内容，使其成为简洁的规则或事实 2. **添加** 到目标文件中的适当部分（如需要则创建文件） 3. **更新** 原始条目： - 更改 `**Status**: pending` → `**Status**: promoted` - 添加 `**Promoted**: CLAUDE.md`、`AGENTS.md` 或 `.github/copilot-instructions.md`
### 提升示例
**学习**（冗长）： > 项目使用 pnpm 工作区。尝试了 `npm install` 但失败了。 > 锁定文件是 `pnpm-lock.yaml`。必须使用 `pnpm install`。
**在 CLAUDE.md 中**（简洁）： ```markdown ## Build & Dependencies - Package manager: pnpm (not npm) - use `pnpm install` ```
**学习**（冗长）： > 修改 API 端点时，必须重新生成 TypeScript 客户端。 > 忘记这样做会导致运行时类型不匹配。
**在 AGENTS.md 中**（可执行）： ```markdown ## After API Changes 1. Regenerate client: `pnpm run generate:api` 2. Check for type errors: `pnpm tsc --noEmit` ```
## 重复模式检测
如果记录的内容与现有条目相似：
1. **先搜索**：`grep -r "keyword" .learnings/` 2. **链接条目**：在元数据中添加 `**See Also**: ERR-20250110-001` 3. **提高优先级**，如果问题持续重复 4. **考虑系统性修复**：重复问题通常表明： - 缺少文档（→ 提升到 CLAUDE.md 或 .github/copilot-instructions.md） - 缺少自动化（→ 添加到 AGENTS.md） - 架构问题（→ 创建技术债务票据）
## 定期审查
在自然的停顿点审查 `.learnings/`：
### 何时审查 - 开始新的主要任务之前 - 完成功能之后 - 在有过去学习记录的领域工作时 - 活跃开发期间每周一次
### 快速状态检查 ```bash # 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. **具体明确** - 未来的代理需要快速理解 3. **包含复现步骤** - 特别是对于错误 4. **链接相关文件** - 使修复更容易 5. **提出具体修复方案** - 而不仅仅是“调查” 6. **使用一致的类别** - 便于筛选 7. **积极提升** - 如果有疑问，添加到 CLAUDE.md 或 .github/copilot-instructions.md 8. **定期审查** - 陈旧的学习内容会失去价值
## Gitignore 选项
**保持学习内容本地化**（每位开发者）： ```gitignore .learnings/ ```
**在仓库中跟踪学习内容**（团队范围）： 不要添加到 .gitignore - 学习内容将成为共享知识。
**混合模式**（跟踪模板，忽略条目）： ```gitignore .learnings/*.md !.learnings/.gitkeep ```
## Hook 集成
通过代理 Hook 启用自动提醒。这是**可选的** - 你必须明确配置 Hook。
### 快速设置
在项目中创建 `.claude/settings.json`：
```json { "hooks": { "UserPromptSubmit": [{ "matcher": "", "hooks": [{ "type": "command", "command": "./skills/self-improvement/scripts/activator.sh" }] }] } } ```
这会在每次提示后注入学习评估提醒（约 50-100 个 token 开销）。
### 完整设置（带错误检测）
```json { "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" }] }] } } ```
### 可用的 Hook 脚本
| 脚本 | Hook 类型 | 用途 | |--------|-----------|---------| | `scripts/activator.sh` | UserPromptSubmit | 提醒在任务后评估学习内容 | | `scripts/error-detector.sh` | PostToolUse (Bash) | 在命令错误时触发 |
详细配置和故障排除请参阅 `references/hooks-setup.md`。
## 自动技能提取
当学习内容足够有价值成为可重用的技能时，使用提供的辅助工具进行提取。
### 技能提取标准
当满足以下任一条件时，学习内容有资格进行技能提取：
| 标准 | 描述 | |-----------|-------------| | **重复发生** | 具有 2 个或更多类似问题的 `See Also` 链接 | | **已验证** | 状态为 `resolved` 且有有效的修复 | | **非显而易见** | 需要实际调试/调查才能发现 | | **广泛适用** | 非项目特定；在代码库中有用 | | **用户标记** | 用户说“将此保存为技能”或类似的话 |
### 提取工作流
1. **确定候选**：学习内容符合提取标准 2. **运行辅助工具**（或手动创建）： ```bash ./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 规范](https://agentskills.io/specification)： - 带有 `name` 和 `description` 的 YAML 前置数据 - 名称必须与文件夹名称匹配 - 技能文件夹内没有 README.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`：
```markdown ## 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?" ```
**检测**：会话结束时手动审查
### Clawdbot
**激活方式**：工作区注入 + 代理间消息传递 **设置**：在 `~/.clawdbot/clawdbot.json` 中配置工作区路径 **检测**：通过会话工具和工作区文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`）
Clawdbot 使用基于工作区的模型，并注入提示文件。有关详细设置，请参阅 `references/clawdbot-integration.md`。
### 代理无关指导
无论使用哪种代理，在以下情况下应用自我改进：
1. **发现非显而易见的事物** - 解决方案并不显而易见 2. **自我纠正** - 初始方法有误 3. **学习项目约定** - 发现了未记录的模式 4. **遇到意外错误** - 尤其是当诊断较为困难时 5. **找到更好的方法** - 改进了原始解决方案
### Copilot Chat 集成
对于 Copilot 用户，在相关时将以下内容添加到您的提示中：
> 完成此任务后，评估是否应使用自我改进技能格式将任何学习内容记录到 `.learnings/`。
或使用快速提示： - "将此内容记录到 learnings" - "基于此解决方案创建技能" - "检查 .learnings/ 中是否存在相关问题"
## Clawdbot 集成
Clawdbot 使用基于工作区的提示注入，并针对不同关注点使用专用文件。
### 工作区结构
``` ~/clawd/ # Default workspace (configurable) ├── AGENTS.md # Multi-agent workflows, delegation patterns ├── SOUL.md # Behavioral guidelines, communication style ├── TOOLS.md # Tool capabilities, MCP integrations └── sessions/ # Session transcripts (auto-managed) ```
### Clawdbot 提升目标
| 学习类型 | 提升至 | 示例 | |--------------|------------|---------| | 代理协调 | `AGENTS.md` | "将文件搜索委托给探索代理" | | 沟通风格 | `SOUL.md` | "保持简洁，避免免责声明" | | 工具注意事项 | `TOOLS.md` | "MCP 服务器 X 需要身份验证刷新" | | 项目事实 | `CLAUDE.md` | 标准项目约定 |
### 代理间学习
Clawdbot 支持基于会话的通信： - **sessions_list** - 查看活动/最近的会话 - **sessions_history** - 读取其他会话的记录 - **sessions_send** - 向其他会话发送消息
### 混合设置（Claude Code + Clawdbot）
同时使用两者时： 1. 将 `.learnings/` 用于特定于项目的学习内容 2. 使用 clawdbot 工作区文件用于跨项目模式 3. 将高价值学习内容同步到两个系统
有关完整设置、提升格式和故障排除，请参阅 `references/clawdbot-integration.md`。