
evolution-skills
Self-evolving skills for Claude Code
- version
- 0.1.0
Install
/plugin install evolution-skills@raydocsRun it inside Claude Code after adding the marketplace with /plugin marketplace add raydocs/evolution-skills.
Contents
Discovered from sourceSkills 1
通用自我进化系统
此 skill 让 Claude 在开发过程中持续学习并改进知识库。
自动触发规则
重要: 作为 Claude,你应该在适当时机自动执行这些行为。
自动 (无需用户请求)
| 机制 | 何时触发 |
|---|---|
| 版本适配 | 会话开始,检测 package.json/Cargo.toml/pubspec.yaml |
| 个性化 | 首次生成代码,扫描 2-3 个现有文件 |
| 自我修正 | 当你建议的代码失败时立即触发 |
| 使用反馈 | 每次使用已保存的模式后 |
半自动 (你提议,用户确认)
| 机制 | 何时提议 |
|---|---|
| 自我进化 | 解决非平凡问题后,问用户是否保存 |
手动 (用户请求)
| 机制 | 触发短语 |
|---|---|
| 验证 skills | "验证 skills" / "validate skills" |
| 健康报告 | "skills 健康报告" / "pattern health report" |
会话开始检查清单
开始任何开发会话时,静默执行:
-
检测技术栈版本
- Flutter: 读取
pubspec.yaml - Node.js: 读取
package.json - Rust: 读取
Cargo.toml - Swift: 检查 Xcode 项目或 Package.swift
- 设置内部上下文记住版本
- Flutter: 读取
-
扫描项目风格 (如果没做过)
- 读取 2-3 个现有代码文件
- 记录: 命名规范、模块结构、注释风格
-
加载相关 skills
- 读取
~/.claude/skills/{tech}-*.md - 如果不存在,准备创建
- 读取
不要宣布这些操作,除非与用户问题直接相关。
Skill 文件结构
~/.claude/skills/
├── evolution/
│ └── SKILL.md # 本文件
├── {tech}-patterns.md # UI/组件模式
├── {tech}-troubleshooting.md # 错误解决
├── {tech}-architecture.md # 架构模式
├── {tech}-layout.md # 布局/响应式
├── {tech}-build.md # 构建/部署
├── {tech}-fundamentals.md # 核心概念/API
└── project-styles/
└── {project}.md # 项目风格档案
其中 {tech} 是: flutter, swiftui, react, vue, rust, python 等。
进化触发条件
当发生以下情况时,考虑保存知识:
| 触发 | 目标文件 | 优先级 |
|---|---|---|
| 发现新 UI 模式 | {tech}-patterns.md | 高 |
| 解决编译/运行错误 | {tech}-troubleshooting.md | 高 |
| 学到架构技术 | {tech}-architecture.md | 高 |
| 找到布局方案 | {tech}-layout.md | 中 |
| 解决构建问题 | {tech}-build.md | 中 |
| 理清核心概念/API | {tech}-fundamentals.md | 低 |
进化前的自我检查
问自己:
- ✅ 这是可复用的模式吗?(不是项目特定的)
- ✅ 花了很大力气才弄清楚吗?
- ✅ 会帮助未来的开发吗?
- ✅ 还没记录在 skills 中吗?
如果都是肯定的,提议给用户:
"这个解决方案可能值得保存到 skills。要我添加吗?"
目标文件映射 (tech + category)
| category | 目标文件 |
|---|---|
| patterns | {tech}-patterns.md |
| troubleshooting | {tech}-troubleshooting.md |
| architecture | {tech}-architecture.md |
| layout | {tech}-layout.md |
| build | {tech}-build.md |
| fundamentals | {tech}-fundamentals.md |
去重与编号规则
- 模式编号: 读取目标文件中已有的
## 模式 N:,取最大 N + 1。 - 去重判定: 标题规范化(小写、去标点、空格折叠)相同视为同一模式;标题不同但核心步骤或代码签名一致时合并。
- 更新策略: 优先更新原条目并补充边缘情况;需要纠正时添加
correction标记,不新增重复条目。
内容格式
统一元数据块 (所有条目通用)
日期格式统一为 YYYY-MM-DD。新条目遵循以下规则:
- 必须包含
evolution。 - 模式条目必须包含
feedback;问题解决条目可选。 version/correction仅在需要时添加。category取值: patterns / troubleshooting / architecture / layout / build / fundamentals。lifecycle标记生命周期状态;scope标记通用性;revision用于回滚链路。
<!-- evolution: YYYY-MM-DD | source: {project} | trigger: {what-happened} | tech: {tech} | category: {category} -->
<!-- feedback: count=0 | success=0 | failed=0 | last_used=YYYY-MM-DD -->
<!-- version: {framework} {constraint} | runtime: {runtime} | tool: {tool} -->
<!-- lifecycle: state=active | since=YYYY-MM-DD | reason={reason} -->
<!-- scope: level=project | projects={projectA,projectB} -->
<!-- revision: id={rev_id} | parent={rev_id} -->
<!-- correction: YYYY-MM-DD | was: {old} | now: {new} | reason: {why} -->
模式格式
<!-- evolution: YYYY-MM-DD | source: {project} | trigger: {what-happened} | tech: {tech} | category: patterns -->
<!-- feedback: count=0 | success=0 | failed=0 | last_used=YYYY-MM-DD -->
<!-- version: {framework} {constraint} | runtime: {runtime} | tool: {tool} -->
<!-- lifecycle: state=active | since=YYYY-MM-DD | reason={reason} -->
<!-- scope: level=project | projects={projectA,projectB} -->
<!-- revision: id={rev_id} | parent={rev_id} -->
## 模式 N: {名称}
{一句话描述这个模式解决什么问题}
### 代码
\```{language}
// 完整可运行的代码示例
\```
### 使用场景
- 场景 1: 具体描述
- 场景 2: 具体描述
### 注意事项
- 版本要求: {framework} >= {version}
- 其他注意点
问题解决格式
<!-- evolution: YYYY-MM-DD | source: {project} | trigger: fixed-error | tech: {tech} | category: troubleshooting -->
<!-- version: {framework} {constraint} | runtime: {runtime} | tool: {tool} -->
<!-- lifecycle: state=active | since=YYYY-MM-DD | reason={reason} -->
<!-- scope: level=project | projects={projectA,projectB} -->
<!-- revision: id={rev_id} | parent={rev_id} -->
### {错误消息或类型}
**症状**: 开发者看到什么现象
**原因**: 为什么会发生 (技术解释)
**解决方案**:
\```{language}
// 修复代码
\```
**相关版本**: {framework} {version}
条目生命周期
状态流转: draft -> active -> deprecated -> removed,异常时可进入 quarantined。
active才能默认推荐。deprecated仅在用户明确要求或迁移提示时使用。quarantined不推荐,需修复或回滚后恢复。removed保留墓碑并指向替代条目。
元数据示例:
<!-- lifecycle: state=active | since=YYYY-MM-DD | reason={reason} -->
冲突解决与合并
当多个模式同时匹配时,按以下顺序选择:
- tech + version 精确匹配
- 采样窗口内成功率更高
last_used更近- 与项目风格更一致
合并记录标记:
<!-- merge: YYYY-MM-DD | from={old_id} | into={new_id} | reason={why} -->
变体处理: 在同一条目下追加 Variants 小节,不新增散乱文件。
自我修正流程
当你建议的代码导致错误时:
-
识别: "这个错误是因为我之前的建议有问题"
-
修复用户代码: 提供正确的解决方案
-
更新 skill 文件:
找到错误的内容 添加修正标记 更新为正确内容 -
通知用户:
"我也更新了 skills 文件,这样以后不会再犯同样的错误。"
修正标记
<!-- correction: YYYY-MM-DD | was: {旧内容摘要} | now: {新内容摘要} | reason: {原因} -->
自动回滚
触发条件 (采样窗口内任一满足):
failed >= 3- 成功率 < 50%
回滚行为:
- 回退到最近
active且成功率最高的revision。 - 将当前条目标记为
quarantined。 - 追加回滚标记并记录原因。
回滚标记:
<!-- rollback: YYYY-MM-DD | from_rev={r2} | to_rev={r1} | trigger={failed>=3} | reason={why} -->
revision 规则: rev_id 使用 YYYYMMDD-<hash>,每次内容变更必须更新 revision。
使用反馈跟踪
当使用 skills 中的模式时:
幂等更新规则
- pattern_id = 模式标题规范化结果(小写、去标点、空格折叠)。
- 为当前会话维护
usage_set,键为{pattern_id}:{outcome}:{target}。 - 若键已存在,不重复计数;仅当计数发生变化时更新
last_used。 count必须等于success + failed;不一致时在健康报告中标记为 "数据不一致"。
采样窗口
- 默认窗口: 最近 90 天。
- 记录窗口内
window_count/window_success/window_failed,无窗口数据时回退到累计值并标记 "窗口数据缺失"。
成功时
- 心里记录: success += 1
- 更新 feedback 标记
失败时
- 心里记录: failed += 1
- 触发自我修正流程
- 更新 feedback 标记
反馈标记
<!-- feedback: count=10 | success=8 | failed=2 | last_used=2026-01-10 -->
健康判断
| 成功率 | 状态 | 动作 |
|---|---|---|
| > 90% | ✅ 健康 | 无需动作 |
| 70-90% | 🔶 良好 | 可选审查 |
| 50-70% | ⚠️ 需审查 | 检查边缘情况 |
| < 50% | ❌ 问题 | 需修复或移除 |
健康报告计算规则 (确定性)
- 条目识别: 仅统计以
## 模式开头的条目。 - 反馈绑定: 仅关联条目前 3 行内的
feedback标记; 缺失则标记为未追踪。 - 窗口优先: 使用
window_*统计(90 天),缺失则回退到累计并标记 "窗口数据缺失"。 - 成功率:
window_count > 0时window_success / window_count,否则为 N/A。 - 关注规则: 成功率 <70% 或
window_failed >= 3或last_used超过 90 天或未追踪。 - 聚合: 技术栈优先来自
tech元数据,缺失时由文件名推断。
版本适配
检测版本
会话开始时静默检测:
Flutter: pubspec.yaml → flutter sdk 版本
React: package.json → react 版本
Swift: Xcode 项目 → iOS deployment target
Rust: Cargo.toml → edition, dependencies
版本特定内容
在 skill 文件中标记版本:
<!-- version: flutter>=3.0 -->
\```dart
// Flutter 3.0+ 写法
\```
<!-- version: flutter<3.0 -->
\```dart
// Flutter 3.0 之前写法
\```
版本不匹配警告
如果用户代码使用了旧版 API:
"注意:你使用的是 {old-version} 的写法,项目是 {new-version}。正确写法是..."
个性化
首次代码生成时
静默扫描项目:
- 读取 2-3 个现有代码文件
- 记录命名规范、模块结构、注释风格
- 后续代码生成匹配项目风格
项目风格档案
保存到 ~/.claude/skills/project-styles/{project}.md:
# {Project} 风格档案
- **命名规范**: camelCase / snake_case
- **模块组织**: feature-first / layer-first
- **状态管理**: BLoC / Provider / Redux
- **注释风格**: 详细 / 简洁
- **复杂度偏好**: 小组件 / 大组件
跨会话上下文存储
缓存文件: ~/.claude/skills/.evolution-context.json
{
"schema_version": 2,
"projects": {
"{project_id}": {
"root": "/abs/path",
"tech_versions": { "flutter": "3.19.0" },
"style_profile": { "naming": "camelCase", "structure": "feature-first" },
"deps_signature": "{hash}",
"updated_at": "YYYY-MM-DD",
"pattern_stats": {
"{pattern_id}": {
"generality_level": "project",
"source_projects": ["projectA", "projectB"],
"window_days": 90,
"window_count": 0,
"window_success": 0,
"window_failed": 0,
"window_updated_at": "YYYY-MM-DD"
}
}
}
}
}
失效规则:
- 兼容: 缺失
pattern_stats时默认generality_level=project,window_days=90。 - 依赖文件签名变化(package.json/Cargo.toml/pubspec.yaml/Package.swift/xcodeproj)→ 重新检测版本
- project root 变化 → 新 project_id
- style_profile 超过 180 天未更新 → 重新扫描 2-3 个文件
跨项目通用性
满足任一条件才可提升到全局 skills:
- 至少 2 个不同项目验证通过
- 明确的框架官方行为/稳定 API
- 有最小复现与通过步骤
否则保留在 project-styles/{project}.md 或条目内 Variants。
通用性标记:
<!-- scope: level=project | projects={projectA,projectB} -->
质量标准
应该保存 ✅
- 通用、可复用的模式
- 常见错误及清晰解决方案
- 经过验证的技术
- 平台特定注意事项
- 性能优化
不应该保存 ❌
- 项目特定的代码
- 未验证的解决方案
- 重复内容
- 不完整的示例
- 无理由的个人偏好
进化提示语
在开发过程中,这些短语触发进化:
- "这个解决方案值得保存"
- "把这个加到 skills"
- "记住这个模式"
- "以后可能还会用到"
持续改进检查清单
每次开发会话后,考虑:
- 发现了新的组件/模式吗?
- 解决了棘手的问题吗?
- 遇到并修复了令人困惑的错误吗?
- 找到了更好的代码组织方式吗?
- 学到了构建/部署相关的东西吗?
如果有,提议保存!
命令
用户可用的命令:
/evolve [tech] [name]- 保存知识/skills-health- 健康报告/validate-skills- 验证准确性
Commands 3
自我进化
将当前会话中学到的知识保存到 ~/.claude/skills/。
输入
$ARGUMENTS
接受:
- 空: 回顾当前会话,提议要保存的内容
<tech>: 指定技术栈 (flutter, swiftui, react, rust 等)<tech> <name>: 直接添加指定的模式
示例:
/evolve- 回顾会话并提议保存/evolve flutter- 保存 Flutter 相关发现/evolve flutter pull-to-refresh- 保存下拉刷新模式
工作流
1. 识别值得保存的知识
回顾当前会话:
- 解决了什么非平凡的问题?
- 发现了什么可复用的模式?
- 有什么错误和解决方案值得记录?
2. 确定目标文件
~/.claude/skills/{tech}-patterns.md # UI/组件模式
~/.claude/skills/{tech}-troubleshooting.md # 错误解决
~/.claude/skills/{tech}-architecture.md # 架构模式
~/.claude/skills/{tech}-build.md # 构建/部署
3. 检查现有内容
cat ~/.claude/skills/{tech}-patterns.md 2>/dev/null || echo "文件不存在,将创建"
4. 格式化并写入
模式格式:
<!-- evolution: {date} | source: {project} | trigger: {trigger} -->
<!-- feedback: count=0 | success=0 | failed=0 | last_used={date} -->
## 模式 N: {名称}
{描述}
### 代码
\```{language}
// 代码
\```
### 使用场景
- 场景
### 注意事项
- 注意点
问题解决格式:
<!-- evolution: {date} | source: {project} | trigger: fixed-error -->
### {错误消息}
**症状**: ...
**原因**: ...
**解决方案**:
\```{language}
// 修复
\```
5. 确认
✅ 已保存到 ~/.claude/skills/{tech}-{category}.md
- 内容: {name}
- 来源: {project}
相关
/skills-health- 查看模式健康报告/validate-skills- 验证 skills 准确性- 完整文档:
~/.claude/skills/evolution/SKILL.md
Skills 健康报告
显示所有保存的 skills 的使用统计和健康状态。
工作流
1. 扫描所有 skill 文件
ls ~/.claude/skills/*.md 2>/dev/null
2. 提取反馈标记
从每个文件提取 <!-- feedback: ... --> 标记。
3. 生成报告
## Skills 健康报告
生成时间: {当前日期}
### 按技术栈
| 技术栈 | 模式数 | 平均成功率 | 状态 |
|-------|-------|-----------|------|
| flutter | 5 | 85% | ✅ |
| swiftui | 3 | 60% | ⚠️ |
### 模式详情
| 模式 | 使用 | 成功 | 失败 | 成功率 | 状态 |
|------|-----|------|------|-------|------|
| Flutter 下拉刷新 | 10 | 9 | 1 | 90% | ✅ 健康 |
### 需要关注
- ❌ 成功率 <50% 的模式
- ⚠️ 成功率 50-70% 的模式
### 建议
1. 修复失败率高的模式
2. 审查边缘情况
3. 移除长期未使用的模式
健康状态定义
| 成功率 | 状态 | 建议 |
|---|---|---|
| > 90% | ✅ 健康 | 无需动作 |
| 70-90% | 🔶 良好 | 可选审查 |
| 50-70% | ⚠️ 需审查 | 检查边缘情况 |
| < 50% | ❌ 问题 | 需修复或移除 |
验证 Skills
验证所有保存的 skills 内容是否仍然准确。
工作流
1. 扫描所有 skill 文件
find ~/.claude/skills -name "*.md" -type f
2. 提取代码块
从每个文件提取所有代码块。
3. 验证检查清单
## 验证报告
### 代码示例
- [ ] 所有代码示例语法正确
- [ ] 所有模式可以编译/运行
### API 准确性
- [ ] API 方法名正确
- [ ] 参数签名正确
### 版本兼容性
- [ ] 标记的版本要求准确
- [ ] 没有使用已废弃的 API
### 完整性
- [ ] 没有缺少关键步骤
- [ ] 示例代码完整可用
4. 报告问题
### 发现的问题
1. **{file}**: {问题描述}
- 行号: {line}
- 建议: {fix}
2. ...
5. 提供修复选项
发现 N 个问题。
1. 自动修复所有
2. 逐个审查修复
3. 只显示报告
验证后
添加验证标记到文件:
<!-- validated: YYYY-MM-DD | status: pass|issues | by: claude -->
Sponsors
Details
- Marketplace
- raydocs/evolution-skills
- Source
- claude-code
- Author
- raydocs
- Category
- Community
- License
- MIT
- Keywords
- skills, evolution, patterns, health, claude-code