Skill: andylue/ai-self-evolution (version 1.0.1)

--- name: ai-self-evolution description: "记录经验、错误与修正，持续改进。触发场景：命令失败 | 操作出错 | 用户纠正（不对、实际上、你错了） | 功能请求（能不能、我希望、有没有办法） | API或工具失败 | 知识过时 | 发现更优做法 | 重复模式 | 非显而易见的问题。执行重大任务前先回顾历史经验。会话开始时回顾，会话结束时总结。" metadata: --- # 自我改进技能 将经验与错误记录到 `.learnings/` 目录，形成持续改进闭环。高价值经验沉淀到项目记忆。 > 安装/配置/Hook/多代理适配 → 见 `references/` 目录 ## 快速参考 | 场景 | 操作 | |------|------| | 命令/操作失败 | 记录到 `ERRORS.md` | | 用户纠正你 | 记录到 `LEARNINGS.md`，分类 `correction` | | 用户提出新需求 | 记录到 `FEATURE_REQUESTS.md` | | API/外部工具失败 | 记录到 `ERRORS.md`，补充集成细节 | | 知识已过时 | 记录到 `LEARNINGS.md`，分类 `knowledge_gap` | | 发现更好做法 | 记录到 `LEARNINGS.md`，分类 `best_practice` | | 重复模式（simplify-and-harden） | 记录或更新 `LEARNINGS.md`，设 `Pattern-Key` | | 与已有条目相似 | 用 `See Also` 关联，必要时提高优先级 | | 可广泛复用的经验 | 提升到 `CLAUDE.md` / `AGENTS.md` | | 工作流/工具/行为类 | 提升到 `AGENTS.md` / `TOOLS.md` / `SOUL.md`（OpenClaw 工作区） | 所有日志文件位于 `.learnings/` 目录（项目级或 `~/.openclaw/workspace/.learnings/`）。 --- ## 会话开始：自动回顾 每次会话开始或执行重大任务前，执行以下回顾流程： 1. **检查待处理条目**： ```bash grep -c "Status\*\*: pending" .learnings/*.md 2>/dev/null ``` 2. **扫描高优先级问题**： ```bash grep -B3 "Priority\*\*: high\|Priority\*\*: critical" .learnings/*.md | grep "^## \[" ``` 3. **检查与当前任务相关的历史经验**：根据任务涉及的 Area 和关键词搜索 4. **加载最近条目**（最近 7 天内创建的）：快速浏览最新 3-5 条记录 5. **输出回顾摘要**（内部执行，不打扰用户）：待处理数 / 高优数 / 相关经验 > 如果 `.learnings/` 不存在或为空，跳过回顾，正常工作。 --- ## 会话结束：经验总结 在会话即将结束时（用户明确结束、任务完成、长时间无新指令），执行： 1. **回顾本次会话**：检查是否有未记录的错误、纠正或新发现 2. **补录遗漏条目**：将本次会话中遗漏的经验补充记录 3. **更新已解决条目**：本次修复的问题，将状态改为 `resolved` 4. **输出会话经验摘要**（简短告知用户）： - 本次新增条目数 / 关闭条目数 - 建议提升的高价值经验（如有） 5. **触发归档检查**：如果条目总数超过阈值，执行归档流程 --- ## 自动合并与归档 ### 触发条件（满足任一即执行） - 单个文件超过 50 条 pending 条目 - 存在超过 90 天未更新的 pending 条目 - 会话结束总结时检测到条目膨胀 ### 归档流程 1. **合并重复条目**：相同 `Pattern-Key` 或高度相似 Summary → 合并为一条，累加 `Recurrence-Count`，保留最新 `Last-Seen`，用 `See Also` 记录被合并的原始 ID 2. **归档已关闭条目**：`resolved` / `wont_fix` / `promoted` 超过 30 天 → 移动到 `.learnings/archive/YYYY-MM.md` 3. **清理低价值条目**：`low` 优先级 + `pending` 超过 60 天 → 标记 `stale`；`stale` 超过 30 天 → 归档 --- ## 检测触发器 观察到以下信号时**立即记录**： | 类型 | 信号 | 记录到 | |------|------|--------| | **纠正** | "不对" "实际上应该" "你这里错了" "已经过时了" | `LEARNINGS.md` 分类 `correction` | | **功能请求** | "你还能不能" "我希望你可以" "有没有办法" "为什么你不能" | `FEATURE_REQUESTS.md` | | **知识缺口** | 用户提供你不知道的信息、文档过时、API 行为不一致 | `LEARNINGS.md` 分类 `knowledge_gap` | | **错误** | 非零退出码、异常堆栈、输出异常、超时、连接失败 | `ERRORS.md` | | **更优做法** | 发现比当前方案更好的实现 | `LEARNINGS.md` 分类 `best_practice` | --- ## 记录格式 ### Learning 条目（追加到 `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 一行描述学到了什么 ### Details 完整上下文：发生了什么、哪里错了、正确做法是什么 ### Suggested Action 可执行的修复或改进建议 ### Metadata - Source: conversation | error | user_feedback | simplify-and-harden - Related Files: path/to/file.ext - Tags: tag1, tag2 - See Also: LRN-20250110-001 - Pattern-Key: simplify.dead_code（可选） - Recurrence-Count: 1（可选） - First-Seen / Last-Seen: 2025-01-15（可选） --- ``` ### Error 条目（追加到 `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 失败情况简述 ### Error 实际错误信息或输出 ### Context - 尝试执行的命令/操作 - 使用的输入或参数 ### Suggested Fix 潜在修复方式 ### Metadata - Reproducible: yes | no | unknown - Related Files: path/to/file.ext - See Also: ERR-20250110-001 --- ``` ### Feature Request 条目（追加到 `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 用户希望实现的能力 ### User Context 用户为什么需要它 ### Complexity Estimate simple | medium | complex ### Suggested Implementation 可行实现思路 ### Metadata - Frequency: first_time | recurring - Related Features: existing_feature_name --- ``` --- ## ID 与状态 **ID 格式**：`TYPE-YYYYMMDD-XXX`（TYPE: LRN/ERR/FEAT，XXX: 顺序号或随机 3 位） **状态流转**： - `pending` → `in_progress` → `resolved`（附 Resolution 块） - `pending` → `wont_fix`（附原因） - `pending` / `resolved` → `promoted`（已提升到项目记忆） - `pending` → `promoted_to_skill`（已抽取为独立 skill） - `pending` → `stale` → 归档 **关闭条目时**，在 Metadata 后添加： ```markdown ### Resolution - **Resolved**: ISO-8601 timestamp - **Commit/PR**: abc123 or #42 - **Notes**: 简述 ``` --- ## 重复模式检测 记录前先搜索已有条目： 1. `grep -r "关键词" .learnings/` 2. 若已有相似条目：添加 `See Also` 关联，增加 `Recurrence-Count` 3. 重复 3 次以上 → 提高优先级，考虑系统性修复 4. 系统性修复方向：文档缺失 → 提升到 CLAUDE.md；自动化缺失 → 写入 AGENTS.md；架构问题 → 创建技术债任务 ### Simplify & Harden 吸收 1. 从任务摘要读取 `simplify_and_harden.learning_loop.candidates` 2. 以 `pattern_key` 去重，搜索 `LEARNINGS.md` 3. 已存在 → 增加 `Recurrence-Count`，更新 `Last-Seen` 4. 不存在 → 新建条目，设 `Source: simplify-and-harden` --- ## 提升到项目记忆 ### 何时提升 - 经验适用于多个文件/功能 - 任何贡献者都应知晓 - 能避免重复犯错 - 重复模式满足：`Recurrence-Count >= 3` + 涉及 2+ 任务 + 30 天窗口内 ### 提升目标 | 经验类型 | 提升到 | |----------|--------| | 项目事实、通用约定 | `CLAUDE.md` | | 工作流、自动化规则 | `AGENTS.md` | | 行为准则、沟通风格 | `SOUL.md`（OpenClaw） | | 工具能力、集成坑点 | `TOOLS.md`（OpenClaw） | ### 如何提升 1. **提炼**为简洁预防规则（编码前/编码中该做什么），而非事故复盘 2. **写入**目标文件对应章节 3. **更新**原条目状态为 `promoted`，添加 `Promoted: <目标文件>` ### Skill 抽取 当经验满足以下任一条件时，可抽取为独立 skill： - 通过 `See Also` 关联到 2+ 相似问题 - 状态为 `resolved` 且修复已验证 - 非项目特定，可跨代码库复用 - 用户明确要求"保存成 skill" 抽取流程与模板 → 见 `references/skill-extraction.md` --- ## 优先级与 Area | 优先级 | 适用场景 | |--------|----------| | `critical` | 阻塞核心功能、数据丢失风险、安全问题 | | `high` | 影响显著、常用流程、重复出现 | | `medium` | 影响中等、有可行绕过方案 | | `low` | 轻微不便、边缘场景 | | Area | 范围 | |------|------| | `frontend` | UI、组件、客户端 | | `backend` | API、服务端 | | `infra` | CI/CD、部署、Docker | | `tests` | 测试文件、覆盖率 | | `docs` | 文档、README | | `config` | 配置、环境、参数 | --- ## 最佳实践 1. **立即记录** — 问题刚发生时上下文最完整 2. **具体明确** — 便于后续代理快速理解 3. **包含复现步骤** — 尤其是错误类条目 4. **关联相关文件** — 提高修复效率 5. **给出可执行建议** — 避免仅写"需要调查" 6. **记录前先搜索** — 避免重复，优先关联已有条目 7. **积极提升** — 有疑问时优先沉淀到项目记忆 8. **定期归档** — 保持日志文件精简高效

path: _meta.json
content: ownerId: kn70cjr952qdec1nx70zs6wefn7ynq2t
slug: ai-self-evolution
version: 1.0.0
publishedAt: 1773230308177

path: references/examples.md
content: # Entry Examples

Concrete examples of well-formatted entries with all fields.

## Learning: Correction

```markdown
## [LRN-20250115-001] correction

**Logged**: 2025-01-15T10:30:00Z
**Priority**: high
**Status**: pending
**Area**: tests

### Summary
Incorrectly assumed pytest fixtures are scoped to function by default

### Details
When writing test fixtures, I assumed all fixtures were function-scoped. 
User corrected that while function scope is the default, the codebase 
convention uses module-scoped fixtures for database connections to 
improve test performance.

### Suggested Action
When creating fixtures that involve expensive setup (DB, network), 
check existing fixtures for scope patterns before defaulting to function scope.

### Metadata
- Source: user_feedback
- Related Files: tests/conftest.py
- Tags: pytest, testing, fixtures

---
```

## Learning: Knowledge Gap (Resolved)

```markdown
## [LRN-20250115-002] knowledge_gap

**Logged**: 2025-01-15T14:22:00Z
**Priority**: medium
**Status**: resolved
**Area**: config

### Summary
Project uses pnpm not npm for package management

### Details
Attempted to run `npm install` but project uses pnpm workspaces.
Lock file is `pnpm-lock.yaml`, not `package-lock.json`.

### Suggested Action
Check for `pnpm-lock.yaml` or `pnpm-workspace.yaml` before assuming npm.
Use `pnpm install` for this project.

### Metadata
- Source: error
- Related Files: pnpm-lock.yaml, pnpm-workspace.yaml
- Tags: package-manager, pnpm, setup

### Resolution
- **Resolved**: 2025-01-15T14:30:00Z
- **Commit/PR**: N/A - knowledge update
- **Notes**: Added to CLAUDE.md for future reference

---
```

## Learning: Promoted to CLAUDE.md

```markdown
## [LRN-20250115-003] best_practice

**Logged**: 2025-01-15T16:00:00Z
**Priority**: high
**Status**: promoted
**Promoted**: CLAUDE.md
**Area**: backend

### Summary
API responses must include correlation ID from request headers

### Details
All API responses should echo back the X-Correlation-ID header from 
the request. This is required for distributed tracing. Responses 
without this header break the observability pipeline.

### Suggested Action
Always include correlation ID passthrough in API handlers.

### Metadata
- Source: user_feedback
- Related Files: src/middleware/correlation.ts
- Tags: api, observability, tracing

---
```

## Learning: Promoted to AGENTS.md

```markdown
## [LRN-20250116-001] best_practice

**Logged**: 2025-01-16T09:00:00Z
**Priority**: high
**Status**: promoted
**Promoted**: AGENTS.md
**Area**: backend

### Summary
Must regenerate API client after OpenAPI spec changes

### Details
When modifying API endpoints, the TypeScript client must be regenerated.
Forgetting this causes type mismatches that only appear at runtime.
The generate script also runs validation.

### Suggested Action
Add to agent workflow: after any API changes, run `pnpm run generate:api`.

### Metadata
- Source: error
- Related Files: openapi.yaml, src/client/api.ts
- Tags: api, codegen, typescript

---
```

## Error Entry

```markdown
## [ERR-20250115-A3F] docker_build

**Logged**: 2025-01-15T09:15:00Z
**Priority**: high
**Status**: pending
**Area**: infra

### Summary
Docker build fails on M1 Mac due to platform mismatch

### Error
```
error: failed to solve: python:3.11-slim: no match for platform linux/arm64
```

### Context
- Command: `docker build -t myapp .`
- Dockerfile uses `FROM python:3.11-slim`
- Running on Apple Silicon (M1/M2)

### Suggested Fix
Add platform flag: `docker build --platform linux/amd64 -t myapp .`
Or update Dockerfile: `FROM --platform=linux/amd64 python:3.11-slim`

### Metadata
- Reproducible: yes
- Related Files: Dockerfile

---
```

## Error Entry: Recurring Issue

```markdown
## [ERR-20250120-B2C] api_timeout

**Logged**: 2025-01-20T11:30:00Z
**Priority**: critical
**Status**: pending
**Area**: backend

### Summary
Third-party payment API timeout during checkout

### Error
```
TimeoutError: Request to payments.example.com timed out after 30000ms
```

### Context
- Command: POST /api/checkout
- Timeout set to 30s
- Occurs during peak hours (lunch, evening)

### Suggested Fix
Implement retry with exponential backoff. Consider circuit breaker pattern.

### Metadata
- Reproducible: yes (during peak hours)
- Related Files: src/services/payment.ts
- See Also: ERR-20250115-X1Y, ERR-20250118-Z3W

---
```

## Feature Request

```markdown
## [FEAT-20250115-001] export_to_csv

**Logged**: 2025-01-15T16:45:00Z
**Priority**: medium
**Status**: pending
**Area**: backend

### Requested Capability
Export analysis results to CSV format

### User Context
User runs weekly reports and needs to share results with non-technical 
stakeholders in Excel. Currently copies output manually.

### Complexity Estimate
simple

### Suggested Implementation
Add `--output csv` flag to the analyze command. Use standard csv module.
Could extend existing `--output json` pattern.

### Metadata
- Frequency: recurring
- Related Features: analyze command, json output

---
```

## Feature Request: Resolved

```markdown
## [FEAT-20250110-002] dark_mode

**Logged**: 2025-01-10T14:00:00Z
**Priority**: low
**Status**: resolved
**Area**: frontend

### Requested Capability
Dark mode support for the dashboard

### User Context
User works late hours and finds the bright interface straining.
Several other users have mentioned this informally.

### Complexity Estimate
medium

### Suggested Implementation
Use CSS variables for colors. Add toggle in user settings.
Consider system preference detection.

### Metadata
- Frequency: recurring
- Related Features: user settings, theme system

### Resolution
- **Resolved**: 2025-01-18T16:00:00Z
- **Commit/PR**: #142
- **Notes**: Implemented with system preference detection and manual toggle

---
```

## Learning: Promoted to Skill

```markdown
## [LRN-20250118-001] best_practice

**Logged**: 2025-01-18T11:00:00Z
**Priority**: high
**Status**: promoted_to_skill
**Skill-Path**: skills/docker-m1-fixes
**Area**: infra

### Summary
Docker build fails on Apple Silicon due to platform mismatch

### Details
When building Docker images on M1/M2 Macs, the build fails because
the base image doesn't have an ARM64 variant. This is a common issue
that affects many developers.

### Suggested Action
Add `--platform linux/amd64` to docker build command, or use
`FROM --platform=linux/amd64` in Dockerfile.

### Metadata
- Source: error
- Related Files: Dockerfile
- Tags: docker, arm64, m1, apple-silicon
- See Also: ERR-20250115-A3F, ERR-20250117-B2D

---
```

## Extracted Skill Example

When the above learning is extracted as a skill, it becomes:

**File**: `skills/docker-m1-fixes/SKILL.md`

```markdown
---
name: docker-m1-fixes
description: "Fixes Docker build failures on Apple Silicon (M1/M2). Use when docker build fails with platform mismatch errors."
---

# Docker M1 Fixes

Solutions for Docker build issues on Apple Silicon Macs.

## Quick Reference

| Error | Fix |
|-------|-----|
| `no match for platform linux/arm64` | Add `--platform linux/amd64` to build |
| Image runs but crashes | Use emulation or find ARM-compatible base |

## The Problem

Many Docker base images don't have ARM64 variants. When building on
Apple Silicon (M1/M2/M3), Docker attempts to pull ARM64 images by
default, causing platform mismatch errors.

## Solutions

### Option 1: Build Flag (Recommended)

Add platform flag to your build command:

\`\`\`bash
docker build --platform linux/amd64 -t myapp .
\`\`\`

### Option 2: Dockerfile Modification

Specify platform in the FROM instruction:

\`\`\`dockerfile
FROM --platform=linux/amd64 python:3.11-slim
\`\`\`

### Option 3: Docker Compose

Add platform to your service:

\`\`\`yaml
services:
  app:
    platform: linux/amd64
    build: .
\`\`\`

## Trade-offs

| Approach | Pros | Cons |
|----------|------|------|
| Build flag | No file changes | Must remember flag |
| Dockerfile | Explicit, versioned | Affects all builds |
| Compose | Convenient for dev | Requires compose |

## Performance Note

Running AMD64 images on ARM64 uses Rosetta 2 emulation. This works
for development but may be slower. For production, find ARM-native
alternatives when possible.

## Source

- Learning ID: LRN-20250118-001
- Category: best_practice
- Extraction Date: 2025-01-18
```


path: references/agent-setup.md
content: # 多代理配置指南

为不同 AI 编码代理配置 ai-self-evolution 技能的安装与集成说明。

## OpenClaw（推荐）

OpenClaw 是本技能的主要平台，详见 `openclaw-integration.md`。

## Claude Code

**激活方式**：Hooks（UserPromptSubmit、PostToolUse）
**配置位置**：`.claude/settings.json`

详见 `hooks-setup.md`。

## Codex CLI

**激活方式**：Hooks（与 Claude Code 相同模式）
**配置位置**：`.codex/settings.json`

详见 `hooks-setup.md`。

## 国产模型适配说明

Kimi、MiniMax 等国产模型目前不支持 Hook 或 Agent Skills 规范，但可通过系统提示词注入的方式实现类似效果。

### 通用适配方式

在系统提示词（System Prompt）中加入以下内容：

```
## 自我改进工作流

当你在工作过程中遇到以下情况时，自动记录到项目 .learnings/ 目录：
- 命令失败或操作出错 → 记录到 .learnings/ERRORS.md
- 用户纠正你的理解 → 记录到 .learnings/LEARNINGS.md
- 用户提出新的能力需求 → 记录到 .learnings/FEATURE_REQUESTS.md
- 发现知识过时或更优做法 → 记录到 .learnings/LEARNINGS.md

条目格式：## [TYPE-YYYYMMDD-XXX] 标题，包含 Summary、Details、Suggested Action。
高价值经验应提升到 CLAUDE.md 或 AGENTS.md。
```

### Kimi（Moonshot）

- Kimi 的长上下文能力强，适合将 SKILL.md 全文作为系统提示注入
- 通过 Kimi API 的 `system` 角色消息传入自我改进指令
- Kimi 支持文件读写，可直接操作 `.learnings/` 目录

### MiniMax

- 通过 MiniMax API 的系统提示词注入
- MiniMax 的函数调用（Function Calling）能力可用于封装记录操作
- 建议将记录动作封装为 function tool，降低遗漏概率

### 适配要点

| 能力 | 有 Hook 支持 | 无 Hook 支持 |
|------|-------------|-------------|
| 触发记录 | 自动（Hook 检测） | 手动（系统提示词引导） |
| 错误检测 | PostToolUse 自动捕获 | 依赖模型自身判断 |
| 会话回顾 | Hook 在 bootstrap 注入 | 在系统提示词中要求"开始时回顾" |
| 经验提升 | 自动提醒 | 在系统提示词中要求"定期提升" |

> 核心原则：无论模型是否支持 Hook，只要模型能读写文件，就能使用本技能的记录格式和提升流程。差异仅在于触发方式（自动 vs 提示词引导）。

## 通用配置（任意代理）

在项目中创建 `.learnings/`：

```bash
mkdir -p .learnings
```

从 `assets/` 复制模板，或手动创建带表头的文件。

### 在 AGENTS.md / CLAUDE.md 中添加引用

```markdown
## 自我改进工作流

出现错误或纠正时：
1. 记录到 `.learnings/ERRORS.md`、`LEARNINGS.md` 或 `FEATURE_REQUESTS.md`
2. 将可广泛复用的经验提升到：
   - `CLAUDE.md` - 项目事实与约定
   - `AGENTS.md` - 工作流与自动化
```

### 代理无关实践

无论使用哪种代理，以下情况都应启用自我改进流程：

1. **发现非显而易见的问题** - 方案并非立即可得
2. **发生自我纠正** - 初始做法被证明错误
3. **学到项目约定** - 发现未文档化但稳定存在的模式
4. **遇到意外错误** - 尤其是诊断成本较高时
5. **找到更优方案** - 相比最初方案有明显提升

## Gitignore 方案

**仅本地保存经验**（按开发者隔离）：
```gitignore
.learnings/
```

**在仓库中共享经验**（团队共用）：
不要加入 .gitignore，让经验成为共享知识。

**混合模式**（跟踪模板，忽略具体条目）：
```gitignore
.learnings/*.md
!.learnings/.gitkeep
```


path: references/openclaw-integration.md
content: # OpenClaw 集成指南

将 ai-self-evolution skill 集成到 OpenClaw 的完整配置与使用说明。

## 概览

OpenClaw 通过“工作区注入 + 事件驱动 Hook”提供上下文能力：  
会话启动时注入工作区文件，Hook 可在生命周期事件上触发提醒。

## 工作区结构

```
~/.openclaw/
├── workspace/                   # 工作目录
│   ├── AGENTS.md               # 多代理协作模式
│   ├── SOUL.md                 # 行为准则与风格
│   ├── TOOLS.md                # 工具能力与使用坑点
│   ├── MEMORY.md               # 长期记忆（仅主会话）
│   └── memory/                 # 每日记忆文件
│       └── YYYY-MM-DD.md
├── skills/                      # 已安装 skills
│   └── <skill-name>/
│       └── SKILL.md
└── hooks/                       # 自定义 hooks
    └── <hook-name>/
        ├── HOOK.md
        └── handler.ts
```

## 快速配置

### 1. 安装 Skill

```bash
clawdhub install ai-self-evolution
```

或手动复制：

```bash
cp -r ai-self-evolution ~/.openclaw/skills/
```

### 2. 安装 Hook（可选）

将 hook 复制到 OpenClaw hooks 目录：

```bash
cp -r hooks/openclaw ~/.openclaw/hooks/ai-self-evolution
```

启用 hook：

```bash
openclaw hooks enable ai-self-evolution
```

### 3. 创建 Learning 文件

在工作区创建 `.learnings/`：

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

或在 skill 目录下创建：

```bash
mkdir -p ~/.openclaw/skills/ai-self-evolution/.learnings
```

## 注入的提示文件

### AGENTS.md

用途：多代理工作流与委派模式。

```markdown
# Agent Coordination

## Delegation Rules
- Use explore agent for open-ended codebase questions
- Spawn sub-agents for long-running tasks
- Use sessions_send for cross-session communication

## Session Handoff
When delegating to another session:
1. Provide full context in the handoff message
2. Include relevant file paths
3. Specify expected output format
```

### SOUL.md

用途：行为规范与沟通风格。

```markdown
# Behavioral Guidelines

## Communication Style
- Be direct and concise
- Avoid unnecessary caveats and disclaimers
- Use technical language appropriate to context

## Error Handling
- Admit mistakes promptly
- Provide corrected information immediately
- Log significant errors to learnings
```

### TOOLS.md

用途：工具能力、集成注意事项、本地配置信息。

```markdown
# Tool Knowledge

## ai-self-evolution Skill
Log learnings to `.learnings/` for continuous improvement.

## Local Tools
- Document tool-specific gotchas here
- Note authentication requirements
- Track integration quirks
```

## Learning 工作流

### 记录 Learnings

1. **会话内**：按常规写入 `.learnings/`
2. **跨会话**：将可复用内容提升到工作区文件

### 提升决策树

```
该 learning 是否项目特定？
├── 是 → 保留在 .learnings/
└── 否 → 是否属于行为/风格？
    ├── 是 → 提升到 SOUL.md
    └── 否 → 是否属于工具使用？
        ├── 是 → 提升到 TOOLS.md
        └── 否 → 提升到 AGENTS.md（工作流）
```

### 提升格式示例

**From learning:**
> Git push to GitHub fails without auth configured - triggers desktop prompt

**To TOOLS.md:**
```markdown
## Git
- Don't push without confirming auth is configured
- Use `gh auth status` to check GitHub CLI auth
```

## 代理间通信

OpenClaw 提供跨会话通信工具：

### sessions_list

查看活跃与近期会话：
```
sessions_list(activeMinutes=30, messageLimit=3)
```

### sessions_history

读取其他会话记录：
```
sessions_history(sessionKey="session-id", limit=50)
```

### sessions_send

向其他会话发送消息：
```
sessions_send(sessionKey="session-id", message="Learning: API requires X-Custom-Header")
```

### sessions_spawn

启动后台子代理：
```
sessions_spawn(task="Research X and report back", label="research")
```

## 可用 Hook 事件

| 事件 | 触发时机 |
|-------|---------------|
| `agent:bootstrap` | 工作区文件注入之前 |
| `command:new` | 执行 `/new` 命令时 |
| `command:reset` | 执行 `/reset` 命令时 |
| `command:stop` | 执行 `/stop` 命令时 |
| `gateway:startup` | gateway 启动时 |

## 检测触发器

### 标准触发器
- 用户纠正（如 “No, that's wrong...”）
- 命令失败（非零退出码）
- API 错误
- 知识缺口

### OpenClaw 特定触发器

| 触发器 | 动作 |
|---------|--------|
| 工具调用错误 | 记录到 TOOLS.md，并标注工具名 |
| 会话交接混乱 | 记录到 AGENTS.md，并补充委派模式 |
| 模型行为异常 | 记录到 SOUL.md，并标注预期与实际 |
| Skill 问题 | 记录到 .learnings/ 或向上游反馈 |

## 验证

检查 hook 是否已注册：

```bash
openclaw hooks list
```

检查 skill 是否已加载：

```bash
openclaw status
```

## 故障排查

### Hook 不触发

1. 确认配置中已启用 hooks
2. 修改配置后重启 gateway
3. 查看 gateway 日志排查错误

### Learnings 未持久化

1. 确认 `.learnings/` 目录存在
2. 检查文件权限
3. 确认 workspace 路径配置正确

### Skill 未加载

1. 确认 skill 位于 skills 目录
2. 检查 SKILL.md frontmatter 是否正确
3. 运行 `openclaw status` 查看加载状态


path: references/skill-extraction.md
content: # Skill 抽取指南

将高价值经验抽取为独立可复用 skill 的完整流程。

## 抽取判定标准

满足以下任一条件即可视为可抽取：

| 标准 | 说明 |
|------|------|
| **Recurring** | 通过 `See Also` 关联到 2+ 相似问题 |
| **Verified** | 状态为 `resolved` 且修复已验证有效 |
| **Non-obvious** | 需要真实调试/排查才能发现 |
| **Broadly applicable** | 非项目特定，可跨代码库复用 |
| **User-flagged** | 用户明确说"把这个保存成 skill" |

## 抽取触发信号

**在对话中：**
- "把这个保存成一个 skill"
- "我总是遇到这个问题"
- "这个对其他项目也有用"
- "记住这个模式"

**在经验条目中：**
- 出现多个 `See Also` 链接（重复问题）
- 高优先级且已 resolved
- 分类为 `best_practice` 且可广泛复用
- 用户反馈明确认可方案质量

## 抽取流程

### 使用辅助脚本

```bash
# 预览将要创建的内容
./scripts/extract-skill.sh skill-name --dry-run

# 执行创建
./scripts/extract-skill.sh skill-name
```

### 手动创建

1. 创建 `skills/<skill-name>/SKILL.md`
2. 使用 `assets/SKILL-TEMPLATE.md` 模板
3. 遵循 [Agent Skills 规范](https://agentskills.io/specification)：
   - YAML frontmatter 至少含 `name` 和 `description`
   - name 必须与目录名一致
   - skill 目录内不要放 README.md

### 创建后

1. **定制 SKILL.md**：将模板替换为实际经验内容
2. **更新原经验**：状态改为 `promoted_to_skill`，补充 `Skill-Path`
3. **验证**：在新会话读取该 skill，确认其可独立理解

## Skill 质量门槛

抽取前检查：

- [ ] 方案已测试并可运行
- [ ] 脱离原上下文也能理解描述
- [ ] 代码示例可独立运行/阅读
- [ ] 不含项目特定硬编码值
- [ ] 命名符合规范（小写+连字符）

## 命名规范

- **Skill 名称**：全小写，单词间使用连字符
  - Good: `docker-m1-fixes`, `api-timeout-patterns`
  - Bad: `Docker_M1_Fixes`, `APITimeoutPatterns`

- **Description**：以动作动词开头，明确触发条件
  - Good: "Handles Docker build failures on Apple Silicon. Use when builds fail with platform mismatch."
  - Bad: "Docker stuff"

- **文件结构**：
  - `SKILL.md` - 必填，主文档
  - `scripts/` - 可选，可执行代码
  - `references/` - 可选，详细文档
  - `assets/` - 可选，模板资源


path: references/hooks-setup.md
content: # Hook 配置指南

为 AI 编码代理配置自动化自我改进触发器。

## 概览

通过 Hook 可以在关键时刻主动提醒记录经验：
- **UserPromptSubmit**：每次提交提示词后提醒评估 learnings
- **PostToolUse (Bash)**：命令失败时触发错误检测提醒

## Claude Code 配置

### 方案 1：项目级配置

在项目根目录创建 `.claude/settings.json`：

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

### 方案 2：用户级配置

将配置写入 `~/.claude/settings.json`，全局生效：

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/skills/ai-self-evolution/scripts/activator.sh"
          }
        ]
      }
    ]
  }
}
```

### 最小配置（仅 activator）

若想降低开销，可只启用 UserPromptSubmit：

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

## Codex CLI 配置

Codex 的 Hook 配置方式与 Claude Code 相同。创建 `.codex/settings.json`：

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

## 验证

### 测试 Activator Hook

1. 启用 Hook 配置
2. 新开一个 Claude Code 会话
3. 发送任意提示词
4. 确认上下文里出现 `<ai-self-evolution-reminder>`

### 测试 Error Detector Hook

1. 为 Bash 启用 PostToolUse Hook
2. 运行失败命令：`ls /nonexistent/path`
3. 确认出现 `<error-detected>` 提醒

### 抽取脚本 Dry Run

```bash
./skills/ai-self-evolution/scripts/extract-skill.sh test-skill --dry-run
```

预期会输出将要创建的 skill 脚手架信息。

## 故障排查

### Hook 未触发

1. **检查脚本权限**：`chmod +x scripts/*.sh`
2. **确认路径正确**：使用绝对路径或相对项目根路径
3. **确认配置位置**：项目级还是用户级
4. **重启会话**：Hook 在会话启动时加载

### Permission Denied

```bash
chmod +x ./skills/ai-self-evolution/scripts/activator.sh
chmod +x ./skills/ai-self-evolution/scripts/error-detector.sh
chmod +x ./skills/ai-self-evolution/scripts/extract-skill.sh
```

### Script Not Found

如果使用相对路径，请确认当前目录正确；或改用绝对路径：

```json
{
  "command": "/absolute/path/to/skills/ai-self-evolution/scripts/activator.sh"
}
```

### 开销过高

若 activator 触发过于频繁：

1. **使用最小配置**：仅启用 UserPromptSubmit，关闭 PostToolUse
2. **增加 matcher 过滤**：仅对特定提示词触发：

```json
{
  "matcher": "fix|debug|error|issue",
  "hooks": [...]
}
```

## Hook 输出预算

activator 设计为轻量提醒：
- **目标**：每次触发约 50-100 tokens
- **内容**：结构化提醒，不提供冗长说明
- **格式**：使用 XML 标签便于解析

如需进一步降低开销，可精简 `activator.sh` 输出内容。

## 安全注意事项

- Hook 脚本与 Claude Code 以同等权限运行
- 脚本仅输出文本，不主动修改文件或执行额外命令
- error detector 读取 `CLAUDE_TOOL_OUTPUT` 环境变量
- 所有脚本均为显式启用（未配置则不会运行）

## 关闭 Hook

临时停用且保留配置可用以下方式：

1. **在 settings 中注释对应项**：
```json
{
  "hooks": {
    // "UserPromptSubmit": [...]
  }
}
```

2. **删除 settings 文件**：无配置时 Hook 不会运行


path: hooks/openclaw/handler.js
content: /**
 * ai-self-evolution Hook for OpenClaw
 * 
 * Injects a reminder to evaluate learnings during agent bootstrap.
 * Fires on agent:bootstrap event before workspace files are injected.
 */

const REMINDER_CONTENT = `
## 自我改进提醒

任务完成后，请评估是否需要记录经验：

**以下情况建议记录：**
- 用户纠正了你 → \`.learnings/LEARNINGS.md\`
- 命令/操作失败 → \`.learnings/ERRORS.md\`
- 用户提出当前缺失能力 → \`.learnings/FEATURE_REQUESTS.md\`
- 你发现原有认知有误 → \`.learnings/LEARNINGS.md\`
- 你找到了更优做法 → \`.learnings/LEARNINGS.md\`

**模式稳定后建议提升：**
- 行为模式 → \`SOUL.md\`
- 工作流改进 → \`AGENTS.md\`
- 工具使用坑点 → \`TOOLS.md\`

条目尽量简洁：日期、标题、发生了什么、下次怎么做。
`.trim();

const handler = async (event) => {
  // Safety checks for event structure
  if (!event || typeof event !== 'object') {
    return;
  }

  // Only handle agent:bootstrap events
  if (event.type !== 'agent' || event.action !== 'bootstrap') {
    return;
  }

  // Safety check for context
  if (!event.context || typeof event.context !== 'object') {
    return;
  }

  // Skip sub-agent sessions to avoid bootstrap issues
  const sessionKey = event.sessionKey || '';
  if (sessionKey.includes(':subagent:')) {
    return;
  }

  // Inject the reminder as a virtual bootstrap file
  // Check that bootstrapFiles is an array before pushing
  if (Array.isArray(event.context.bootstrapFiles)) {
    event.context.bootstrapFiles.push({
      path: 'AI_SELF_EVOLUTION_REMINDER.md',
      content: REMINDER_CONTENT,
      virtual: true,
    });
  }
};

module.exports = handler;
module.exports.default = handler;


path: hooks/openclaw/HOOK.md
content: ---
name: ai-self-evolution
description: "Injects ai-self-evolution reminder during agent bootstrap"
metadata: {"openclaw":{"emoji":"🧠","events":["agent:bootstrap"]}}
---

# 自我改进 Hook

在代理启动阶段注入一条提醒，用于评估是否需要记录 learnings。

## 功能说明

- 在 `agent:bootstrap` 触发（工作区文件注入之前）
- 添加提醒块，检查 `.learnings/` 中是否有相关条目
- 提示代理记录纠正、错误和新发现

## 配置

无需额外配置，执行以下命令启用：

```bash
openclaw hooks enable ai-self-evolution
```


path: hooks/openclaw/handler.ts
content: /**
 * ai-self-evolution Hook for OpenClaw
 * 
 * Injects a reminder to evaluate learnings during agent bootstrap.
 * Fires on agent:bootstrap event before workspace files are injected.
 */

import type { HookHandler } from 'openclaw/hooks';

const REMINDER_CONTENT = `## 自我改进提醒

任务完成后，请评估是否需要记录经验：

**以下情况建议记录：**
- 用户纠正了你 → \`.learnings/LEARNINGS.md\`
- 命令/操作失败 → \`.learnings/ERRORS.md\`
- 用户提出当前缺失能力 → \`.learnings/FEATURE_REQUESTS.md\`
- 你发现原有认知有误 → \`.learnings/LEARNINGS.md\`
- 你找到了更优做法 → \`.learnings/LEARNINGS.md\`

**模式稳定后建议提升：**
- 行为模式 → \`SOUL.md\`
- 工作流改进 → \`AGENTS.md\`
- 工具使用坑点 → \`TOOLS.md\`

条目尽量简洁：日期、标题、发生了什么、下次怎么做。`;

const handler: HookHandler = async (event) => {
  // Safety checks for event structure
  if (!event || typeof event !== 'object') {
    return;
  }

  // Only handle agent:bootstrap events
  if (event.type !== 'agent' || event.action !== 'bootstrap') {
    return;
  }

  // Safety check for context
  if (!event.context || typeof event.context !== 'object') {
    return;
  }

  // Skip sub-agent sessions to avoid bootstrap issues
  // Sub-agents have sessionKey patterns like "agent:main:subagent:..."
  const sessionKey = event.sessionKey || '';
  if (sessionKey.includes(':subagent:')) {
    return;
  }

  // Inject the reminder as a virtual bootstrap file
  // Check that bootstrapFiles is an array before pushing
  if (Array.isArray(event.context.bootstrapFiles)) {
    event.context.bootstrapFiles.push({
      path: 'AI_SELF_EVOLUTION_REMINDER.md',
      content: REMINDER_CONTENT,
      virtual: true,
    });
  }
};

export default handler;


path: scripts/activator.sh
content: #!/bin/bash
# ai-self-evolution Activator Hook
# Triggers on UserPromptSubmit to remind Claude about learning capture
# Keep output minimal (~80-120 tokens) to minimize overhead

set -e

# Check for pending items count (if .learnings/ exists)
PENDING_COUNT=0
HIGH_COUNT=0
LEARNINGS_DIR=".learnings"

if [ -d "$LEARNINGS_DIR" ]; then
    PENDING_COUNT=$(grep -rch "Status\*\*: pending" "$LEARNINGS_DIR"/*.md 2>/dev/null | awk '{s+=$1} END {print s+0}')
    HIGH_COUNT=$(grep -rch "Priority\*\*: high\|Priority\*\*: critical" "$LEARNINGS_DIR"/*.md 2>/dev/null | awk '{s+=$1} END {print s+0}')
fi

# Output reminder as system context
cat << EOF
<ai-self-evolution-reminder>
任务完成后，评估是否出现可沉淀的经验：
- 非显而易见的解法？排查后的绕过方案？
- 项目特有的可复用模式？需要调试的错误？
- 用户纠正了你？发现了知识缺口？

若是：按 ai-self-evolution 技能格式记录到 .learnings/。
若价值高（重复出现、可广泛复用）：考虑提升到项目记忆或抽取为 skill。
待处理: ${PENDING_COUNT} 条 | 高优: ${HIGH_COUNT} 条
</ai-self-evolution-reminder>
EOF


path: scripts/extract-skill.sh
content: #!/bin/bash
# Skill Extraction Helper
# Creates a new skill from a learning entry
# Usage: ./extract-skill.sh <skill-name> [--dry-run]

set -e

# Configuration
SKILLS_DIR="./skills"

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

usage() {
    cat << EOF
Usage: $(basename "$0") <skill-name> [options]

Create a new skill from a learning entry.

Arguments:
  skill-name     Name of the skill (lowercase, hyphens for spaces)

Options:
  --dry-run      Show what would be created without creating files
  --output-dir   Relative output directory under current path (default: ./skills)
  -h, --help     Show this help message

Examples:
  $(basename "$0") docker-m1-fixes
  $(basename "$0") api-timeout-patterns --dry-run
  $(basename "$0") pnpm-setup --output-dir ./skills/custom

The skill will be created in: \$SKILLS_DIR/<skill-name>/
EOF
}

log_info() {
    echo -e "${GREEN}[INFO]${NC} $1"
}

log_warn() {
    echo -e "${YELLOW}[WARN]${NC} $1"
}

log_error() {
    echo -e "${RED}[ERROR]${NC} $1" >&2
}

# Parse arguments
SKILL_NAME=""
DRY_RUN=false

while [[ $# -gt 0 ]]; do
    case $1 in
        --dry-run)
            DRY_RUN=true
            shift
            ;;
        --output-dir)
            if [ -z "${2:-}" ] || [[ "${2:-}" == -* ]]; then
                log_error "--output-dir requires a relative path argument"
                usage
                exit 1
            fi
            SKILLS_DIR="$2"
            shift 2
            ;;
        -h|--help)
            usage
            exit 0
            ;;
        -*)
            log_error "Unknown option: $1"
            usage
            exit 1
            ;;
        *)
            if [ -z "$SKILL_NAME" ]; then
                SKILL_NAME="$1"
            else
                log_error "Unexpected argument: $1"
                usage
                exit 1
            fi
            shift
            ;;
    esac
done

# Validate skill name
if [ -z "$SKILL_NAME" ]; then
    log_error "Skill name is required"
    usage
    exit 1
fi

# Validate skill name format (lowercase, hyphens, no spaces)
if ! [[ "$SKILL_NAME" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]]; then
    log_error "Invalid skill name format. Use lowercase letters, numbers, and hyphens only."
    log_error "Examples: 'docker-fixes', 'api-patterns', 'pnpm-setup'"
    exit 1
fi

# Validate output path to avoid writes outside current workspace.
if [[ "$SKILLS_DIR" = /* ]]; then
    log_error "Output directory must be a relative path under the current directory."
    exit 1
fi

if [[ "$SKILLS_DIR" =~ (^|/)\.\.(/|$) ]]; then
    log_error "Output directory cannot include '..' path segments."
    exit 1
fi

SKILLS_DIR="${SKILLS_DIR#./}"
SKILLS_DIR="./$SKILLS_DIR"

SKILL_PATH="$SKILLS_DIR/$SKILL_NAME"

# Check if skill already exists
if [ -d "$SKILL_PATH" ] && [ "$DRY_RUN" = false ]; then
    log_error "Skill already exists: $SKILL_PATH"
    log_error "Use a different name or remove the existing skill first."
    exit 1
fi

# Dry run output
if [ "$DRY_RUN" = true ]; then
    log_info "Dry run - would create:"
    echo "  $SKILL_PATH/"
    echo "  $SKILL_PATH/SKILL.md"
    echo ""
    echo "Template content would be:"
    echo "---"
    cat << TEMPLATE
name: $SKILL_NAME
description: "[TODO: Add a concise description of what this skill does and when to use it]"
---

# $(echo "$SKILL_NAME" | sed 's/-/ /g' | awk '{for(i=1;i<=NF;i++) $i=toupper(substr($i,1,1)) tolower(substr($i,2))}1')

[TODO: Brief introduction explaining the skill's purpose]

## Quick Reference

| Situation | Action |
|-----------|--------|
| [Trigger condition] | [What to do] |

## Usage

[TODO: Detailed usage instructions]

## Examples

[TODO: Add concrete examples]

## Source Learning

This skill was extracted from a learning entry.
- Learning ID: [TODO: Add original learning ID]
- Original File: .learnings/LEARNINGS.md
TEMPLATE
    echo "---"
    exit 0
fi

# Create skill directory structure
log_info "Creating skill: $SKILL_NAME"

mkdir -p "$SKILL_PATH"

# Create SKILL.md from template
cat > "$SKILL_PATH/SKILL.md" << TEMPLATE
---
name: $SKILL_NAME
description: "[TODO: Add a concise description of what this skill does and when to use it]"
---

# $(echo "$SKILL_NAME" | sed 's/-/ /g' | awk '{for(i=1;i<=NF;i++) $i=toupper(substr($i,1,1)) tolower(substr($i,2))}1')

[TODO: Brief introduction explaining the skill's purpose]

## Quick Reference

| Situation | Action |
|-----------|--------|
| [Trigger condition] | [What to do] |

## Usage

[TODO: Detailed usage instructions]

## Examples

[TODO: Add concrete examples]

## Source Learning

This skill was extracted from a learning entry.
- Learning ID: [TODO: Add original learning ID]
- Original File: .learnings/LEARNINGS.md
TEMPLATE

log_info "Created: $SKILL_PATH/SKILL.md"

# Suggest next steps
echo ""
log_info "Skill scaffold created successfully!"
echo ""
echo "Next steps:"
echo "  1. Edit $SKILL_PATH/SKILL.md"
echo "  2. Fill in the TODO sections with content from your learning"
echo "  3. Add references/ folder if you have detailed documentation"
echo "  4. Add scripts/ folder if you have executable code"
echo "  5. Update the original learning entry with:"
echo "     **Status**: promoted_to_skill"
echo "     **Skill-Path**: skills/$SKILL_NAME"


path: scripts/error-detector.sh
content: #!/bin/bash
# ai-self-evolution Error Detector Hook
# Triggers on PostToolUse for Bash to detect command failures
# Reads CLAUDE_TOOL_OUTPUT and CLAUDE_EXIT_CODE environment variables

set -e

# Check exit code first (most reliable signal)
EXIT_CODE="${CLAUDE_EXIT_CODE:-0}"
OUTPUT="${CLAUDE_TOOL_OUTPUT:-}"

# If exit code is non-zero, it's definitely an error
if [ "$EXIT_CODE" != "0" ]; then
    cat << 'EOF'
<error-detected>
命令以非零退出码结束。若满足以下任一条件，建议记录到 .learnings/ERRORS.md：
- 错误是非预期或不明显的
- 需要排查才能定位或解决
- 在类似场景中可能再次出现
- 解决方案对后续会话有参考价值

使用格式：[ERR-YYYYMMDD-XXX]
记录前先搜索已有条目：grep -r "关键词" .learnings/
</error-detected>
EOF
    exit 0
fi

# Patterns indicating errors in output (even with exit code 0)
ERROR_PATTERNS=(
    "error:"
    "Error:"
    "ERROR:"
    "failed"
    "FAILED"
    "command not found"
    "No such file"
    "Permission denied"
    "fatal:"
    "Exception"
    "Traceback"
    "npm ERR!"
    "ModuleNotFoundError"
    "SyntaxError"
    "TypeError"
    "ReferenceError"
    "ImportError"
    "ConnectionRefused"
    "ECONNREFUSED"
    "ENOENT"
    "ETIMEDOUT"
    "panic:"
    "segfault"
    "core dumped"
    "killed"
    "OOM"
    "out of memory"
)

# Check if output contains any error pattern
contains_error=false
for pattern in "${ERROR_PATTERNS[@]}"; do
    if [[ "$OUTPUT" == *"$pattern"* ]]; then
        contains_error=true
        break
    fi
done

# Only output reminder if error detected
if [ "$contains_error" = true ]; then
    cat << 'EOF'
<error-detected>
检测到命令输出中包含错误信息。若满足以下任一条件，建议记录到 .learnings/ERRORS.md：
- 错误是非预期或不明显的
- 需要排查才能定位或解决
- 在类似场景中可能再次出现
- 解决方案对后续会话有参考价值

使用格式：[ERR-YYYYMMDD-XXX]
记录前先搜索已有条目：grep -r "关键词" .learnings/
</error-detected>
EOF
fi


path: assets/SKILL-TEMPLATE.md
content: # Skill 模板

用于从 learnings 中抽取 skill 的模板，可复制后按需定制。

---

## SKILL.md 标准模板

```markdown
---
name: skill-name-here
description: "简要说明此 skill 何时使用、用于解决什么问题，并包含触发条件。"
---

# Skill 名称

简要介绍该 skill 解决的问题及其来源背景。

## 快速参考

| 场景 | 操作 |
|-----------|--------|
| [触发条件 1] | [执行动作 1] |
| [触发条件 2] | [执行动作 2] |

## 背景

说明这条知识为何重要、能避免哪些问题、以及原始 learning 的上下文。

## 解决方案

### 分步执行

1. 第一步（可附代码或命令）
2. 第二步
3. 验证步骤

### 代码示例

\`\`\`language
// 演示解决方案的示例代码
\`\`\`

## 常见变体

- **变体 A**：说明及处理方式
- **变体 B**：说明及处理方式

## 注意事项

- 常见问题或风险点 #1
- 常见问题或风险点 #2

## 相关内容

- 相关文档链接
- 相关 skill 链接

## 来源

从 learning 条目抽取。
- **Learning ID**: LRN-YYYYMMDD-XXX
- **原始分类**: correction | insight | knowledge_gap | best_practice
- **抽取日期**: YYYY-MM-DD
```

---

## 精简模板

适用于结构简单、无需完整章节的 skill：

```markdown
---
name: skill-name-here
description: "说明此 skill 的用途与触发时机。"
---

# Skill 名称

[一句话问题描述]

## Solution

[直接给出解决方案与代码/命令]

## Source

- Learning ID: LRN-YYYYMMDD-XXX
```

---

## 含脚本模板

适用于包含可执行辅助脚本的 skill：

```markdown
---
name: skill-name-here
description: "说明此 skill 的用途与触发时机。"
---

# Skill 名称

[简介]

## 快速参考

| 命令 | 作用 |
|---------|---------|
| `./scripts/helper.sh` | [功能说明] |
| `./scripts/validate.sh` | [功能说明] |

## 使用方式

### 自动化（推荐）

\`\`\`bash
./skills/skill-name/scripts/helper.sh [args]
\`\`\`

### 手动步骤

1. 步骤一
2. 步骤二

## 脚本说明

| 脚本 | 描述 |
|--------|-------------|
| `scripts/helper.sh` | 主工具脚本 |
| `scripts/validate.sh` | 校验脚本 |

## 来源

- Learning ID: LRN-YYYYMMDD-XXX
```

---

## 命名规范

- **Skill 名称**：全小写，单词间使用连字符
  - Good: `docker-m1-fixes`, `api-timeout-patterns`
  - Bad: `Docker_M1_Fixes`, `APITimeoutPatterns`

- **Description**：以动作动词开头，并明确触发条件
  - Good: "Handles Docker build failures on Apple Silicon. Use when builds fail with platform mismatch."
  - Bad: "Docker stuff"

- **文件结构**：
  - `SKILL.md` - 必填，主文档
  - `scripts/` - 可选，可执行代码
  - `references/` - 可选，详细文档
  - `assets/` - 可选，模板资源

---

## 抽取检查清单

从 learning 创建 skill 之前：

- [ ] Learning 已验证（status: resolved）
- [ ] 方案具备通用性（非一次性问题）
- [ ] 内容完整（包含必要上下文）
- [ ] 名称符合规范
- [ ] 描述简洁且信息充分
- [ ] 快速参考表可执行
- [ ] 代码示例已验证
- [ ] 已记录来源 Learning ID

创建之后：

- [ ] 回写原 learning 状态为 `promoted_to_skill`
- [ ] 在 learning Metadata 中添加 `Skill-Path: skills/skill-name`
- [ ] 在新会话中读取并验证该 skill 可独立使用


path: assets/LEARNINGS.md
content: # 经验模板

用于记录开发过程中的纠正、洞察与知识缺口。

**Categories**: correction | insight | knowledge_gap | best_practice
**Areas**: frontend | backend | infra | tests | docs | config
**Statuses**: pending | in_progress | resolved | wont_fix | promoted | promoted_to_skill

## 状态定义

| 状态 | 含义 |
|--------|---------|
| `pending` | 尚未处理 |
| `in_progress` | 正在处理 |
| `resolved` | 问题已修复或知识已吸收 |
| `wont_fix` | 决定不处理（原因写入 Resolution） |
| `promoted` | 已提升到 CLAUDE.md 或 AGENTS.md |
| `promoted_to_skill` | 已抽取为可复用 skill |

## Skill 抽取字段

当某条 learning 提升为 skill 时，补充以下字段：

```markdown
**Status**: promoted_to_skill
**Skill-Path**: skills/skill-name
```

示例：
```markdown
## [LRN-20250115-001] best_practice

**Logged**: 2025-01-15T10:00:00Z
**Priority**: high
**Status**: promoted_to_skill
**Skill-Path**: skills/docker-m1-fixes
**Area**: infra

### Summary
Apple Silicon 上 Docker 构建因平台不匹配而失败
...
```

---


path: .learnings/FEATURE_REQUESTS.md
content: # 功能请求

记录用户提出但当前尚未支持的能力诉求。

---


path: .learnings/ERRORS.md
content: # 错误记录

记录命令失败、异常与非预期行为。

---


path: .learnings/LEARNINGS.md
content: # 经验记录

记录学习收获、纠正与关键发现。执行重大任务前建议先回顾。

---


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)