介绍
# 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` |
## 设置
如果项目根目录中不存在 `.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 ``` Actual error message or output ```
### 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` (learning/经验)，`ERR` (error/错误)，`FEAT` (feature/功能) - 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 的项目上下文和约定 |
### 如何提升
1. **提炼** 经验为简洁的规则或事实 2. **添加** 到目标文件中的适当部分（如果需要则创建文件） 3. **更新** 原始条目： - 将 `**Status**: pending` 更改为 `**Status**: promoted` - 添加 `**Promoted**: CLAUDE.md`、`AGENTS.md` 或 `.github/copilot-instructions.md`
### 提升示例
**经验**（详细）： > Project uses pnpm workspaces. Attempted `npm install` but failed. > Lock file is `pnpm-lock.yaml`. Must use `pnpm install`.
**在 CLAUDE.md 中**（简洁）： ```markdown ## Build & Dependencies - Package manager: pnpm (not npm) - use `pnpm install` ```
**经验**（详细）： > When modifying API endpoints, must regenerate TypeScript client. > Forgetting this causes type mismatches at runtime.
**在 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` 类别的经验）： - "No, that's not right..." - "Actually, it should be..." - "You're wrong about..." - "That's outdated..."
**功能请求**（→ 功能请求）： - "Can you also..." - "I wish you could..." - "Is there a way to..." - "Why can't you..."
**知识缺口**（→ 带有 `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 集成
通过代理 hooks 启用自动提醒。这是**可选的** - 你必须显式配置 hooks。
### 快速设置
在项目中创建 `.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`。
## 自动技能提取
当经验足够有价值可以成为可重用技能时，使用提供的辅助工具进行提取。
### 技能提取标准
当满足以下任何条件时，经验符合技能提取资格：
| 标准 | 描述 | |-----------|-------------| | **反复出现** | 具有 `See Also` 链接指向 2 个以上类似问题 | | **已验证** | 状态为 `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
### 提取检测触发器
留意这些表明经验应成为技能的信号：
**在对话中：** - "Save this as a skill" - "I keep running into this" - "This would be useful for other projects" - "Remember this pattern"
**在经验条目中：** - 多个 `See Also` 链接（反复出现的问题） - 高优先级 + 已解决状态 - 类别：具有广泛适用性的 `best_practice` - 用户反馈称赞解决方案
### 技能质量门控
提取前验证：
- [ ] 解决方案已测试且有效 - [ ] 在没有原始上下文的情况下描述清晰 - [ ] 代码示例是自包含的 - [ ] 没有项目特定的硬编码值 - [ ] 遵循技能命名约定（小写、连字符）
## 多代理支持
此技能可通过特定于代理的激活在不同的 AI 编码代理之间工作。
### 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`：
```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?" ```
**检测**：在会话结束时进行人工审查
### 与 Agent 无关的指导
无论使用何种 Agent，在出现以下情况时应用自我改进：
1. **发现了非显而易见的事物** - 解决方案并非唾手可得 2. **纠正了自己** - 初始方法有误 3. **了解了项目约定** - 发现了未记录的模式 4. **遇到了意外错误** - 尤其是诊断困难的情况 5. **找到了更好的方法** - 对原有解决方案进行了改进
### Copilot Chat 集成
对于 Copilot 用户，请在适当时将以下内容添加到提示词中：
> 完成此任务后，评估是否应使用自我改进技能格式将任何学习内容记录到 `.learnings/`。
或者使用快速提示词： - "将此记录到学习内容" - "根据此解决方案创建技能" - "检查 .learnings/ 中的相关问题"