raydocs avatar

evolution-skills

Self-evolving skills for Claude Code

version
0.1.0

Install

/plugin install evolution-skills@raydocs

Run it inside Claude Code after adding the marketplace with /plugin marketplace add raydocs/evolution-skills.

Contents

Discovered from source

Skills 1

通用自我进化系统

此 skill 让 Claude 在开发过程中持续学习并改进知识库。


自动触发规则

重要: 作为 Claude,你应该在适当时机自动执行这些行为。

自动 (无需用户请求)

机制何时触发
版本适配会话开始,检测 package.json/Cargo.toml/pubspec.yaml
个性化首次生成代码,扫描 2-3 个现有文件
自我修正当你建议的代码失败时立即触发
使用反馈每次使用已保存的模式后

半自动 (你提议,用户确认)

机制何时提议
自我进化解决非平凡问题后,问用户是否保存

手动 (用户请求)

机制触发短语
验证 skills"验证 skills" / "validate skills"
健康报告"skills 健康报告" / "pattern health report"

会话开始检查清单

开始任何开发会话时,静默执行:

  1. 检测技术栈版本

    • Flutter: 读取 pubspec.yaml
    • Node.js: 读取 package.json
    • Rust: 读取 Cargo.toml
    • Swift: 检查 Xcode 项目或 Package.swift
    • 设置内部上下文记住版本
  2. 扫描项目风格 (如果没做过)

    • 读取 2-3 个现有代码文件
    • 记录: 命名规范、模块结构、注释风格
  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} -->

冲突解决与合并

当多个模式同时匹配时,按以下顺序选择:

  1. tech + version 精确匹配
  2. 采样窗口内成功率更高
  3. last_used 更近
  4. 与项目风格更一致

合并记录标记:

<!-- merge: YYYY-MM-DD | from={old_id} | into={new_id} | reason={why} -->

变体处理: 在同一条目下追加 Variants 小节,不新增散乱文件。

自我修正流程

当你建议的代码导致错误时:

  1. 识别: "这个错误是因为我之前的建议有问题"

  2. 修复用户代码: 提供正确的解决方案

  3. 更新 skill 文件:

    找到错误的内容
    添加修正标记
    更新为正确内容
    
  4. 通知用户:

    "我也更新了 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%❌ 问题需修复或移除

健康报告计算规则 (确定性)

  1. 条目识别: 仅统计以 ## 模式 开头的条目。
  2. 反馈绑定: 仅关联条目前 3 行内的 feedback 标记; 缺失则标记为未追踪。
  3. 窗口优先: 使用 window_* 统计(90 天),缺失则回退到累计并标记 "窗口数据缺失"。
  4. 成功率: window_count > 0 时 window_success / window_count,否则为 N/A。
  5. 关注规则: 成功率 <70% 或 window_failed >= 3 或 last_used 超过 90 天或未追踪。
  6. 聚合: 技术栈优先来自 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}。正确写法是..."


个性化

首次代码生成时

静默扫描项目:

  1. 读取 2-3 个现有代码文件
  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