SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsskill-evolution

skill-evolution

Agents & models

View repository

Updated 10-16 05:07

About this skill

Skill Evolution Manager

The "evolution hub" of the Skill system. Responsible for persisting lessons learned from conversations and retaining them across versions and projects.

Core Value

Problem: When a Skill is updated, the best practices accumulated by users are lost; experience cannot be shared between different projects.

Solution:

  1. Store user experience in an independent evolution.json file
  2. Automatically write experience into SKILL.md through intelligent stitching
  3. After a Skill is updated, restore experience through full alignment
  4. Three-tier architecture: Supports separation and merging of experience at the upstream tier, global tier, and project tier

Three-tier Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                          三层经验架构                                │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────────┐                                               │
│  │   上游层 (Upstream)  │  skills-repo 原始仓库的经验                │
│  │   evolution.json     │  来自社区/原作者的最佳实践                 │
│  │   位置: skills-repo/skills/<skill>/evolution.json                │
│  └─────────┬────────┘                                               │
│            │ 继承                                                    │
│            ▼                                                         │
│  ┌──────────────────┐                                               │
│  │   全局层 (Global)    │  你个人的通用经验                          │
│  │   evolution.json     │  可选择性提交 PR 到上游                    │
│  │   位置: ~/.claude/evolutions/<skill>/evolution.json              │
│  └─────────┬────────┘                                               │
│            │ 继承                                                    │
│            ▼                                                         │
│  ┌──────────────────┐                                               │
│  │   项目层 (Project)   │  项目特定经验                              │
│  │   <skill>.json       │  不提交到版本控制                          │
│  │   位置: <project>/.claude/evolutions/<skill>.json                │
│  └──────────────────┘                                               │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Merge Priority

最终生效的经验 = merge(
    上游层,      # 最低优先级
    全局层,      # 中等优先级
    项目层       # 最高优先级
)
  • List fields (preferences, fixes, contexts): append and deduplicate
  • custom_prompts: Project tier > Global tier > Upstream tier (override)

Core Features

  1. Retrospective diagnosis: Analyze problem points and successful solutions in the conversation
  2. Experience extraction: Convert unstructured feedback into structured JSON
  3. Incremental merge: Deduplicate and merge new experience into evolution.json
  4. Intelligent stitching: Automatically write experience into a dedicated section of SKILL.md
  5. Cross-version alignment: Re-stitch experience after a Skill is updated
  6. Cross-project management: promote/pull commands synchronize experience between tiers

Use Cases

Trigger Methods:

  • /skill-evolution or /evolve
  • "Retrospective on the conversation just now"
  • "Record this experience"
  • "Save this tip to the Skill"
  • "Remember the solution to this problem"

Workflow

Step 1: Retrospective Diagnosis

The Agent analyzes the current conversation and identifies:

  • Problem points: Errors, parameter mistakes, incorrect style
  • Successful solutions: Effective solutions, best practices
  • User preferences: Preferences explicitly expressed by the user

Step 2: Generate Structured JSON

The Agent converts the extracted experience into JSON format:

{
  "preferences": [
    "用户希望下载时默认静音",
    "优先使用 mp4 格式"
  ],
  "fixes": [
    "Windows 下路径需要转义",
    "某些参数在 v2.0 后已弃用"
  ],
  "contexts": [
    "批量操作时需要添加 --batch 参数",
    "处理大文件时增加超时时间"
  ],
  "custom_prompts": "在执行前总是先打印预估耗时"
}

Step 3: Select the Save Tier

The Agent asks the user:

  • Global tier: General experience shared by all projects
  • Project tier: Specific experience used only by the current project

Step 4: Incremental Merge

Run scripts/merge_evolution.py to merge the experience:

# 传统模式（保存到 skill 目录）
python scripts/merge_evolution.py <skill_dir> '<json_string>'

# 分层模式（保存到全局层）
python scripts/merge_evolution.py <skill_name> '<json_string>' --layer global

# 分层模式（保存到项目层）
python scripts/merge_evolution.py <skill_name> '<json_string>' --layer project --project /path/to/project

Step 5: Intelligent Stitching

Run scripts/smart_stitch.py to write the experience into SKILL.md:

# 单层模式
python scripts/smart_stitch.py <skill_dir>

# 分层模式（合并三层经验）
python scripts/smart_stitch.py <skill_dir> --layered --project /path/to/project

Step 6: Cross-version Alignment

When skill-manager updates the Skill, run full alignment to restore experience:

python scripts/align_all.py <skills_dir>

Script Description

Script Function Parameters
layered_merge.py Core of layered experience management <action> <skill_name> [options]
merge_evolution.py Incremental experience merge <skill_dir> <json> [--layer] [--project]
smart_stitch.py Sew into SKILL.md <skill_dir> [--layered] [--project]
align_all.py Full alignment <skills_dir> [--dry-run] [--backup]

layered_merge.py command

# 查看经验状态
python scripts/layered_merge.py status <skill_name> [--project <path>]

# 合并三层经验（查看结果）
python scripts/layered_merge.py merge <skill_name> [--project <path>]

# 将项目经验提升到全局层
python scripts/layered_merge.py promote <skill_name> [--project <path>] [--fields f1,f2]

# 从全局层拉取经验到项目层
python scripts/layered_merge.py pull <skill_name> [--project <path>]

# 保存经验到指定层
python scripts/layered_merge.py save <skill_name> <layer> '<json>' [--project <path>]

evolution.json format

{
  "preferences": ["string"],
  "fixes": ["string"],
  "contexts": ["string"],
  "custom_prompts": "string",
  "last_updated": "ISO-8601 datetime",
  "last_evolved_hash": "commit hash"
}
Field Description
preferences User preference list
fixes Known issue fix solutions
contexts Specific use case descriptions
custom_prompts Custom instruction injection
last_updated Last update time
last_evolved_hash source_hash at the time of the last evolution

Best practices

  1. Modify via evolution.json: Do not directly edit the experience section in SKILL.md
  2. Regular review: Whenever you encounter a problem or discover a technique while using a Skill, record it promptly
  3. Align after updates: After each skill-manager update to a Skill, run align_all.py
  4. Back up important experience: Use the --backup option to protect important experience data
  5. Choose the level reasonably:
    • General experience → global level
    • Project-specific experience → project level
    • High-quality experience → consider a PR upstream

Examples

Example 1: Record user preferences to the global level

用户: 记录一下，我希望下载视频时默认不带字幕，这个是通用设置

Agent:
1. 识别这是一个用户偏好，且是通用设置
2. 生成 JSON: {"preferences": ["下载视频时默认不带字幕"]}
3. 运行 merge_evolution.py --layer global 合并到全局层
4. 运行 smart_stitch.py --layered 更新 SKILL.md

Example 2: Record project-specific fixes

用户: 这个项目的路径比较特殊，记住要用绝对路径

Agent:
1. 识别这是项目特定的修复方案
2. 生成 JSON: {"fixes": ["此项目必须使用绝对路径"]}
3. 运行 merge_evolution.py --layer project 合并到项目层

Example 3: Promote experience to global

用户: 把这个项目里学到的经验提升到全局，其他项目也能用

Agent:
1. 运行 layered_merge.py promote <skill_name>
2. 项目层的经验被复制到全局层
3. 报告提升结果

Example 4: New project initialization

用户: 这是新项目，把全局经验拉下来

Agent:
1. 运行 layered_merge.py pull <skill_name>
2. 全局层的经验被复制到项目层
3. 可以在此基础上继续积累项目特定经验

Collaboration with other Skills

  • skill-factory: Created Skills automatically enable evolution (evolution_enabled: true）
  • skill-manager: After updating a Skill, align_all.py should be called to restore experience; provides promote/pull commands
  • skill-creator: Follow the same experience section format