skill-evolution

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Evolution Manager

Skill进化管理器

Enables skills to automatically improve based on usage patterns, user edits, and success rates. Provides version control with safe rollback capability.

支持Skill基于使用模式、用户编辑内容和成功率自动改进。提供带有安全回退功能的版本控制。

Overview

概述

Reviewing how skills are performing across sessions
Identifying patterns in user edits to skill outputs
Applying learned improvements to skill templates
Rolling back problematic skill changes
Tracking skill version history and success rates

查看Skill在不同会话中的表现情况
识别用户对Skill输出内容的编辑模式
将习得的改进应用到Skill模板中
回退有问题的Skill变更
跟踪Skill的版本历史和成功率

Quick Reference

快速参考

Command	Description
`/ork:skill-evolution`	Show evolution report for all skills
`/ork:skill-evolution analyze <skill-id>`	Analyze specific skill patterns
`/ork:skill-evolution evolve <skill-id>`	Review and apply suggestions
`/ork:skill-evolution history <skill-id>`	Show version history
`/ork:skill-evolution rollback <skill-id> <version>`	Restore previous version

命令	描述
`/ork:skill-evolution`	显示所有Skill的进化报告
`/ork:skill-evolution analyze <skill-id>`	分析特定Skill的模式
`/ork:skill-evolution evolve <skill-id>`	查看并应用改进建议
`/ork:skill-evolution history <skill-id>`	显示版本历史
`/ork:skill-evolution rollback <skill-id> <version>`	恢复至先前版本

How It Works

工作原理

The skill evolution system operates in three phases:

COLLECT                    ANALYZE                    ACT
───────                    ───────                    ───
┌─────────────┐           ┌─────────────┐           ┌─────────────┐
│ PostTool    │──────────▶│ Evolution   │──────────▶│ /ork:skill  │
│ Edit        │  patterns │ Analyzer    │ suggest   │ evolve      │
│ Tracker     │           │ Engine      │           │ command     │
└─────────────┘           └─────────────┘           └─────────────┘
     │                          │                          │
     ▼                          ▼                          ▼
┌─────────────┐           ┌─────────────┐           ┌─────────────┐
│ edit-       │           │ evolution-  │           │ versions/   │
│ patterns.   │           │ registry.   │           │ snapshots   │
│ jsonl       │           │ json        │           │             │
└─────────────┘           └─────────────┘           └─────────────┘

Skill进化系统分为三个阶段运行：

COLLECT                    ANALYZE                    ACT
───────                    ───────                    ───
┌─────────────┐           ┌─────────────┐           ┌─────────────┐
│ PostTool    │──────────▶│ Evolution   │──────────▶│ /ork:skill  │
│ Edit        │  patterns │ Analyzer    │ suggest   │ evolve      │
│ Tracker     │           │ Engine      │           │ command     │
└─────────────┘           └─────────────┘           └─────────────┘
     │                          │                          │
     ▼                          ▼                          ▼
┌─────────────┐           ┌─────────────┐           ┌─────────────┐
│ edit-       │           │ evolution-  │           │ versions/   │
│ patterns.   │           │ registry.   │           │ snapshots   │
│ jsonl       │           │ json        │           │             │
└─────────────┘           └─────────────┘           └─────────────┘

Edit Pattern Categories

编辑模式分类

The system tracks these common edit patterns:

Pattern	Description	Detection
`add_pagination`	User adds pagination to API responses	`limit.offset` , `cursor.pagination`
`add_rate_limiting`	User adds rate limiting	`rate.?limit` , `throttl`
`add_error_handling`	User adds try/catch blocks	`try.*catch` , `except`
`add_types`	User adds TypeScript/Python types	`interface\s` , `Optional`
`add_validation`	User adds input validation	`validate` , `Pydantic` , `Zod`
`add_logging`	User adds logging/observability	`logger\.` , `console.log`
`remove_comments`	User removes generated comments	Pattern removal detection
`add_auth_check`	User adds authentication checks	`@auth` , `@require_auth`

系统会跟踪以下常见编辑模式：

模式	描述	检测规则
`add_pagination`	用户为API响应添加分页功能	`limit.offset` , `cursor.pagination`
`add_rate_limiting`	用户添加限流功能	`rate.?limit` , `throttl`
`add_error_handling`	用户添加try/catch块	`try.*catch` , `except`
`add_types`	用户添加TypeScript/Python类型定义	`interface\s` , `Optional`
`add_validation`	用户添加输入验证	`validate` , `Pydantic` , `Zod`
`add_logging`	用户添加日志/可观测性功能	`logger\.` , `console.log`
`remove_comments`	用户移除生成的注释	Pattern removal detection
`add_auth_check`	用户添加身份验证检查	`@auth` , `@require_auth`

Suggestion Thresholds

建议阈值

Threshold	Default	Description
Minimum Samples	5	Uses before generating suggestions
Add Threshold	70%	Frequency to suggest adding pattern
Auto-Apply Confidence	85%	Confidence for auto-application
Rollback Trigger	-20%	Success rate drop to trigger rollback

阈值	默认值	描述
Minimum Samples	5	生成建议前的最少使用次数
Add Threshold	70%	建议添加模式的频率阈值
Auto-Apply Confidence	85%	自动应用建议的置信度阈值
Rollback Trigger	-20%	触发回退的成功率下降幅度

Subcommand: Report (Default)

子命令：报告（默认）

Usage:

/ork:skill-evolution

Shows evolution report for all tracked skills.

用法：

/ork:skill-evolution

显示所有被跟踪Skill的进化报告。

Implementation

实现代码

bash

undefined

bash

undefined

Run the evolution engine report

运行进化引擎报告

"${CLAUDE_PROJECT_DIR}/.claude/scripts/evolution-engine.sh" report

undefined

"${CLAUDE_PROJECT_DIR}/.claude/scripts/evolution-engine.sh" report

undefined

Sample Output

示例输出

Skill Evolution Report
══════════════════════════════════════════════════════════════

Skills Summary:
┌────────────────────────────┬─────────┬─────────┬───────────┬────────────┐
│ Skill                      │ Uses    │ Success │ Avg Edits │ Suggestions│
├────────────────────────────┼─────────┼─────────┼───────────┼────────────┤
│ api-design-framework       │     156 │     94% │       1.8 │          2 │
│ database-schema-designer   │      89 │     91% │       2.1 │          1 │
│ fastapi-patterns           │      67 │     88% │       2.4 │          3 │
└────────────────────────────┴─────────┴─────────┴───────────┴────────────┘

Summary:
  Skills tracked: 3
  Total uses: 312
  Overall success rate: 91%

Top Pending Suggestions:
1. 93% | api-design-framework | add add_pagination
2. 88% | api-design-framework | add add_rate_limiting
3. 85% | fastapi-patterns | add add_error_handling

Skill Evolution Report
══════════════════════════════════════════════════════════════

Skills Summary:
┌────────────────────────────┬─────────┬─────────┬───────────┬────────────┐
│ Skill                      │ Uses    │ Success │ Avg Edits │ Suggestions│
├────────────────────────────┼─────────┼─────────┼───────────┼────────────┤
│ api-design-framework       │     156 │     94% │       1.8 │          2 │
│ database-schema-designer   │      89 │     91% │       2.1 │          1 │
│ fastapi-patterns           │      67 │     88% │       2.4 │          3 │
└────────────────────────────┴─────────┴─────────┴───────────┴────────────┘

Summary:
  Skills tracked: 3
  Total uses: 312
  Overall success rate: 91%

Top Pending Suggestions:
1. 93% | api-design-framework | add add_pagination
2. 88% | api-design-framework | add add_rate_limiting
3. 85% | fastapi-patterns | add add_error_handling

Subcommand: Analyze

子命令：分析

Usage:

/ork:skill-evolution analyze <skill-id>

Analyzes edit patterns for a specific skill.

用法：

/ork:skill-evolution analyze <skill-id>

分析特定Skill的编辑模式。

Implementation

实现代码

bash

undefined

bash

undefined

Run analysis for specific skill

运行特定Skill的分析

"${CLAUDE_PROJECT_DIR}/.claude/scripts/evolution-engine.sh" analyze "$SKILL_ID"

undefined

"${CLAUDE_PROJECT_DIR}/.claude/scripts/evolution-engine.sh" analyze "$SKILL_ID"

undefined

Sample Output

示例输出

Skill Analysis: api-design-framework
────────────────────────────────────
Uses: 156 | Success: 94% | Avg Edits: 1.8

Edit Patterns Detected:
┌──────────────────────────┬─────────┬──────────┬────────────┐
│ Pattern                  │ Freq    │ Samples  │ Confidence │
├──────────────────────────┼─────────┼──────────┼────────────┤
│ add_pagination           │    85%  │ 132/156  │       0.93 │
│ add_rate_limiting        │    72%  │ 112/156  │       0.88 │
│ add_error_handling       │    45%  │  70/156  │       0.56 │
└──────────────────────────┴─────────┴──────────┴────────────┘

Pending Suggestions:
1. 93% conf: ADD add_pagination to template
2. 88% conf: ADD add_rate_limiting to template

Run `/ork:skill-evolution evolve api-design-framework` to review

Skill Analysis: api-design-framework
────────────────────────────────────
Uses: 156 | Success: 94% | Avg Edits: 1.8

Edit Patterns Detected:
┌──────────────────────────┬─────────┬──────────┬────────────┐
│ Pattern                  │ Freq    │ Samples  │ Confidence │
├──────────────────────────┼─────────┼──────────┼────────────┤
│ add_pagination           │    85%  │ 132/156  │       0.93 │
│ add_rate_limiting        │    72%  │ 112/156  │       0.88 │
│ add_error_handling       │    45%  │  70/156  │       0.56 │
└──────────────────────────┴─────────┴──────────┴────────────┘

Pending Suggestions:
1. 93% conf: ADD add_pagination to template
2. 88% conf: ADD add_rate_limiting to template

Run `/ork:skill-evolution evolve api-design-framework` to review

Subcommand: Evolve

子命令：进化

Usage:

/ork:skill-evolution evolve <skill-id>

Interactive review and application of improvement suggestions.

用法：

/ork:skill-evolution evolve <skill-id>

交互式查看并应用改进建议。

Implementation

实现流程

When this subcommand is invoked:

Get Suggestions:

bash

SUGGESTIONS=$("${CLAUDE_PROJECT_DIR}/.claude/scripts/evolution-engine.sh" suggest "$SKILL_ID")

For Each Suggestion, Present Interactive Options:

Use

AskUserQuestion

to let the user decide on each suggestion:

json

{
  "questions": [{
    "question": "Apply suggestion: ADD add_pagination to template? (93% confidence, 132/156 users add this)",
    "header": "Evolution",
    "options": [
      {"label": "Apply", "description": "Add this pattern to the skill template"},
      {"label": "Skip", "description": "Skip for now, ask again later"},
      {"label": "Reject", "description": "Never suggest this again"}
    ],
    "multiSelect": false
  }]
}

On Apply:
- Create version snapshot first
- Apply the suggestion to skill files
- Update evolution registry
On Reject:
- Mark suggestion as rejected in registry
- Won't be suggested again

当调用此子命令时：

获取建议：

bash

SUGGESTIONS=$("${CLAUDE_PROJECT_DIR}/.claude/scripts/evolution-engine.sh" suggest "$SKILL_ID")

为每个建议提供交互式选项：

使用

AskUserQuestion

让用户对每个建议做出选择：

json

{
  "questions": [{
    "question": "Apply suggestion: ADD add_pagination to template? (93% confidence, 132/156 users add this)",
    "header": "Evolution",
    "options": [
      {"label": "Apply", "description": "Add this pattern to the skill template"},
      {"label": "Skip", "description": "Skip for now, ask again later"},
      {"label": "Reject", "description": "Never suggest this again"}
    ],
    "multiSelect": false
  }]
}

当用户选择应用时：
- 先创建版本快照
- 将建议应用到Skill文件中
- 更新进化注册表
当用户选择拒绝时：
- 在注册表中将该标记为已拒绝
- 后续不会再推荐此建议

Applying Suggestions

应用建议的方式

When a user accepts a suggestion, the implementation depends on the suggestion type:

For
add
suggestions to templates:

Add the pattern to the skill's template files
Update SKILL.md with new guidance

For
add
suggestions to references:

Create new reference file in
```
references/
```
directory

For
remove
suggestions:

Remove the identified content
Archive in version snapshot first

当用户接受建议后，具体实现方式取决于建议类型：

针对模板的
add
类建议：

将模式添加到Skill的模板文件中
在SKILL.md中更新相关指南

针对参考内容的
add
类建议：

在
```
references/
```
目录中创建新的参考文件

针对
remove
类建议：

移除指定内容
先将内容归档到版本快照中

Subcommand: History

子命令：历史

Usage:

/ork:skill-evolution history <skill-id>

Shows version history with performance metrics.

用法：

/ork:skill-evolution history <skill-id>

显示带有性能指标的版本历史。

Implementation

实现代码

bash

undefined

bash

undefined

Run version manager list

运行版本管理器列表命令

"${CLAUDE_PROJECT_DIR}/.claude/scripts/version-manager.sh" list "$SKILL_ID"

undefined

"${CLAUDE_PROJECT_DIR}/.claude/scripts/version-manager.sh" list "$SKILL_ID"

undefined

Sample Output

示例输出

Version History: api-design-framework
══════════════════════════════════════════════════════════════

Current Version: 1.2.0

┌─────────┬────────────┬─────────┬───────┬───────────┬────────────────────────────┐
│ Version │ Date       │ Success │ Uses  │ Avg Edits │ Changelog                  │
├─────────┼────────────┼─────────┼───────┼───────────┼────────────────────────────┤
│ 1.2.0   │ 2026-01-14 │    94%  │   156 │       1.8 │ Added pagination pattern   │
│ 1.1.0   │ 2026-01-05 │    89%  │    80 │       2.3 │ Added error handling ref   │
│ 1.0.0   │ 2025-11-01 │    78%  │    45 │       3.2 │ Initial release            │
└─────────┴────────────┴─────────┴───────┴───────────┴────────────────────────────┘

Version History: api-design-framework
══════════════════════════════════════════════════════════════

Current Version: 1.2.0

┌─────────┬────────────┬─────────┬───────┬───────────┬────────────────────────────┐
│ Version │ Date       │ Success │ Uses  │ Avg Edits │ Changelog                  │
├─────────┼────────────┼─────────┼───────┼───────────┼────────────────────────────┤
│ 1.2.0   │ 2026-01-14 │    94%  │   156 │       1.8 │ Added pagination pattern   │
│ 1.1.0   │ 2026-01-05 │    89%  │    80 │       2.3 │ Added error handling ref   │
│ 1.0.0   │ 2025-11-01 │    78%  │    45 │       3.2 │ Initial release            │
└─────────┴────────────┴─────────┴───────┴───────────┴────────────────────────────┘

Subcommand: Rollback

子命令：回退

Usage:

/ork:skill-evolution rollback <skill-id> <version>

Restores a skill to a previous version.

用法：

/ork:skill-evolution rollback <skill-id> <version>

将Skill恢复到先前版本。

Implementation

实现流程

Confirm with User:

Use

AskUserQuestion

for confirmation:

json

{
  "questions": [{
    "question": "Rollback api-design-framework from 1.2.0 to 1.0.0? Current version will be backed up.",
    "header": "Rollback",
    "options": [
      {"label": "Confirm Rollback", "description": "Restore version 1.0.0"},
      {"label": "Cancel", "description": "Keep current version"}
    ],
    "multiSelect": false
  }]
}

On Confirm:

bash

"${CLAUDE_PROJECT_DIR}/.claude/scripts/version-manager.sh" restore "$SKILL_ID" "$VERSION"

Report Result:

Restored api-design-framework to version 1.0.0
Previous version backed up to: versions/.backup-1.2.0-1736867234

向用户确认：

使用

AskUserQuestion

获取用户确认：

json

{
  "questions": [{
    "question": "Rollback api-design-framework from 1.2.0 to 1.0.0? Current version will be backed up.",
    "header": "Rollback",
    "options": [
      {"label": "Confirm Rollback", "description": "Restore version 1.0.0"},
      {"label": "Cancel", "description": "Keep current version"}
    ],
    "multiSelect": false
  }]
}

当用户确认后：

bash

"${CLAUDE_PROJECT_DIR}/.claude/scripts/version-manager.sh" restore "$SKILL_ID" "$VERSION"

报告结果：

Restored api-design-framework to version 1.0.0
Previous version backed up to: versions/.backup-1.2.0-1736867234

Data Files

数据文件

File	Purpose	Format
`.claude/feedback/edit-patterns.jsonl`	Raw edit pattern events	JSONL (append-only)
`.claude/feedback/evolution-registry.json`	Aggregated suggestions	JSON
`.claude/feedback/metrics.json`	Skill usage metrics	JSON
`skills/<cat>/<name>/versions/`	Version snapshots	Directory
`skills/<cat>/<name>/versions/manifest.json`	Version metadata	JSON

文件	用途	格式
`.claude/feedback/edit-patterns.jsonl`	原始编辑模式事件	JSONL (append-only)
`.claude/feedback/evolution-registry.json`	聚合后的建议数据	JSON
`.claude/feedback/metrics.json`	Skill使用指标	JSON
`skills/<cat>/<name>/versions/`	版本快照	目录
`skills/<cat>/<name>/versions/manifest.json`	版本元数据	JSON

Auto-Evolution Safety

自动进化安全机制

The system includes safety mechanisms:

Version Snapshots: Always created before changes
Rollback Triggers: Auto-alert if success rate drops >20%
Human Review: High-confidence suggestions require approval
Rejection Memory: Rejected suggestions aren't re-suggested

系统包含以下安全机制：

版本快照：在变更前始终创建版本快照
回退触发：当成功率下降超过20%时自动发出警报
人工审核：高置信度建议仍需人工批准
拒绝记忆：被拒绝的建议不会再次被推荐

Health Monitoring

健康监控

The system monitors skill health and can trigger warnings:

WARNING: api-design-framework success rate dropped from 94% to 71%
Consider: /ork:skill-evolution rollback api-design-framework 1.1.0

系统会监控Skill的健康状态，并在必要时触发警告：

WARNING: api-design-framework success rate dropped from 94% to 71%
Consider: /ork:skill-evolution rollback api-design-framework 1.1.0

skill-evolution

Original

Translation

Skill Evolution Manager

Skill进化管理器

Overview

概述

Quick Reference

快速参考

How It Works

工作原理

Edit Pattern Categories

编辑模式分类

Suggestion Thresholds

建议阈值

Subcommand: Report (Default)

子命令：报告（默认）

Implementation

实现代码

Run the evolution engine report

运行进化引擎报告

Sample Output

示例输出

Subcommand: Analyze

子命令：分析

Implementation

实现代码

Run analysis for specific skill

运行特定Skill的分析

Sample Output

示例输出

Subcommand: Evolve

子命令：进化

Implementation

实现流程

Applying Suggestions

应用建议的方式

Subcommand: History

子命令：历史

Implementation

实现代码

Run version manager list

运行版本管理器列表命令

Sample Output

示例输出

Subcommand: Rollback

子命令：回退

Implementation

实现流程

Data Files

数据文件

Auto-Evolution Safety

自动进化安全机制

Health Monitoring

健康监控

References

参考资料

Related Skills

相关Skill