# EulerCopilot-witty agentic skill self-evolution

**Repository Path**: hert6156/euler-copilot-witty-agentic-skill-self-evolution

## Basic Information

- **Project Name**: EulerCopilot-witty agentic skill self-evolution
- **Description**: AI Agent Skill management framework with structural self-evolution capabilities, implementing full lifecycle dynamic control over skills including Rewrite, Prune, Compose, Select, and Merge operations
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-03-02
- **Last Updated**: 2026-03-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# witty agentic skill self-evolution system

witty agentic skill self-evolution system is an AI Agent Skill management framework with structural self-evolution capabilities, implementing full lifecycle dynamic control over skills including Rewrite, Prune, Compose, Select, and Merge operations.

## 🎯 System Vision

This innovative technology proposes an Agent Skill management mechanism with structural self-evolution capabilities. By continuously monitoring multidimensional signals such as execution results, failure patterns, invocation frequency, and confidence stability, the system automatically determines whether skills need structural rewriting, whether inefficient skills should be pruned and deleted, whether multiple basic skills can be composed into higher-level composite capabilities, and how to select and route the optimal skills among multiple candidates.

Through this mechanism, skills are no longer static and rigid execution units but become dynamic capability modules that can be continuously optimized, refactored, and evolved, achieving a critical transition from fixed-strategy systems to adaptive structural systems.

## 🔧 Main Self-Evolution Functions

### 1. **Rewrite**
- **Trigger Mechanism**: Multidimensional assessment based on failure rate, repeated error patterns, and trace counts (see evolution rule configurations in `skills/skill-evolution/scripts/orchestrator.py`)
- **Operation Content**: Structurally refactor skill execution flow, preserve core modules, add enhanced validation and intelligent repair modules
- **Dashboard Display**: Structural skill refactoring

### 2. **Prune**
- **Trigger Mechanism**: Inefficient skill detection based on usage rate, overall score, and trace counts (see pruning rules in `skills/skill-evolution/scripts/structure_evolver.py`)
- **Operation Content**: Mark inefficient skills for deletion, preserve historical data for analysis
- **Dashboard Display**: Prune inefficient skills

### 3. **Compose**
- **Trigger Mechanism**: Cross-skill analysis based on frequently collaborative workflows (see skill composition logic in `skills/skill-evolution/scripts/structure_evolver.py`)
- **Operation Content**: Create composite skill templates, combine multiple basic skills into higher-level capabilities
- **Dashboard Display**: Create composite skills

### 4. **Select**
- **Trigger Mechanism**: Automatic optimal skill selection during task routing (see skill routing logic in `skills/skill-evolution/scripts/orchestrator.py`)
- **Operation Content**: Select optimal skills for given tasks based on success rate, usage frequency, confidence stability, and other indicators
- **Dashboard Display**: Optimal skill routing

### 5. **Merge**
- **Trigger Mechanism**: Similar skill merging detection based on historical performance (see merging rules in `skills/skill-evolution/scripts/orchestrator.py`, to be developed)
- **Operation Content**: Merge two similar skills, using the dominant skill as the base and absorbing assets from the weaker skill
- **Dashboard Display**: Skill merging (to be developed)

## 🏗️ System Architecture

```
┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐
│ Execute │→│ Record  │→│ Evaluate│→│ Diagnose│
└─────────┘  └─────────┘  └─────────┘  └─────────┘
       ↑                                  │
       └──────────────────────────────────┘
              ┌─────────┐
              │ Update  │←──────────────┐
              └─────────┘               │
                                        │
       ┌────────────────────────────────┴──────┐
       │        Knowledge Base & Experience    │
       └────────────────────────────────────────┘
```

### Update Operations Detailed Explanation
**Update** is the core self-evolution link of the system, performing structural improvements to skills based on diagnostic results, containing five intelligent operations:

1. **Rewrite** - Structurally refactor skills with high failure rates and repeated errors
2. **Prune** - Trim inefficient skills with low usage rates and poor overall scores
3. **Compose** - Combine frequently collaborating basic skills into higher-level composite capabilities
4. **Select** - Select optimal skills for tasks based on success rate, usage frequency, and other indicators
5. **Merge** - Merge two similar skills based on historical performance, using the dominant skill as the base and absorbing assets from the weaker skill (implemented, requires manual triggering)

The specific trigger mechanisms for each operation are defined in the evolution rule logic in `skills/skill-evolution/scripts/orchestrator.py` and `structure_evolver.py`.

### Monitoring Dimensions
Decisions are based on the following multidimensional signals:
- Execution results (success/failure rate)
- Failure pattern clustering analysis
- Invocation frequency and confidence stability
- Boundary condition coverage
- Skill usage trajectory data

### Skill-Specific Metrics and Evolution Mechanism
The system defines domain-specific evaluation metrics (skill-specific metrics) for each skill. These metrics are directly related to skill evolution goals and directions. Skill-specific metrics are stored in a registry and used to guide targeted optimization and evolution of skills.

#### Skill-Specific Metrics Registry
Each skill registers its domain-specific evaluation metrics in `skills/skill-evolution/scripts/skill_metric_definitions.py` using `SkillMetricRegistry.register_skill()`. Registration includes metric definitions, weights, ideal ranges, and evaluation criteria.

**Registered Skill Metric Definitions**:
- **PDF Processing**: Text extraction quality, table extraction accuracy, operation success rate, performance efficiency
- **DOCX Processing**: Document processing quality, redlining accuracy, template processing effectiveness
- **XLSX Processing**: Data processing accuracy, format preservation, validation efficacy, performance
- **Frontend Design**: Design quality, usability, implementation fidelity
- **Code Formatter**: Formatting compliance, code quality improvement, performance efficiency
- **PPTX Processing**: Presentation processing quality, presentation generation, operation reliability, performance

**New Skill Registration Example**:
```python
SkillMetricRegistry.register_skill(
    "skill-name",
    {
        "name": "Skill Display Name",
        "description": "Skill description",
        "metrics": {
            "metric_category": {
                "description": "Metric category description",
                "weight": 0.3,
                "indicators": [...]
            }
        }
    }
)
```

#### Evolution Goals and Directions
Based on skill-specific metric evaluation results, the system defines evolution directions and goals for each skill:
- **Metric Weights**: Each metric has a weight reflecting its importance in skill evaluation
- **Evolution Priority**: Lower-scoring metrics receive higher evolution priority
- **Targeted Optimization**: Evolution operations (Rewrite, Prune, Compose, Select, Merge) target improvement of specific metrics
- **Goal Alignment**: Ensure skill evolution directions align with best practices in their functional domains

#### Evolution Mechanism Workflow
1. **Metric Calculation**: `MetricsCalculator.calculate_skill_specific_metrics()` calculates skill-specific metrics based on execution traces
2. **Evaluation Analysis**: Analyze gaps between metric scores and ideal ranges to identify improvement opportunities
3. **Decision Making**: `orchestrator.py` makes evolution decisions based on metric evaluation results
4. **Targeted Evolution**: Execute targeted evolution operations to improve specific metrics
5. **Effect Verification**: Verify metric improvement of evolved skills, forming a closed-loop feedback

#### Skill Metrics Database
The system maintains a skill metrics history database `~/.witty/skill_metrics_history.json`, recording:

**Data Structure**:
- **Time-series Data**: Skill metric snapshots recorded by timestamp
- **Skill Metric Entries**: Each skill includes `success_rate`, `health_status`, `process_score`, `reliability_score`, `efficiency_score`
- **Skill-Specific Metrics**: `skill_specific_metrics` field stores domain-specific evaluation results
- **System Summary**: Overall health status, average success rate, total skill count

**Data Retention**:
- Automatically retains last 100 data points (prevents file bloat)
- Daily automatic recording (when dashboard is generated)
- Supports trend analysis and historical comparison

**Skill-Specific Metrics Storage Format**:
```json
{
  "skill_name": "pdf",
  "skill_specific_metrics": {
    "has_skill_specific_metrics": true,
    "skill_name": "pdf",
    "metrics": {
      "text_extraction_quality": {
        "score": 0.31,
        "interpretation": "Needs Improvement",
        "weight": 0.3,
        "description": "Quality of text extraction from PDFs"
      }
    },
    "summary": {
      "overall_score": 0.32,
      "interpretation": "Needs Improvement",
      "metric_count": 4,
      "success_rate": 0.25
    }
  }
}
```

## 🚀 Optional Operations

### 📊 Dashboard Operations

```bash
# 1. Generate enhanced static dashboard (recommended)
python skills/skill-evolution/scripts/enhanced_dashboard.py

# 2. Generate original static dashboard
python skills/skill-evolution/scripts/generate_dashboard.py

# 3. Start real-time dashboard server
python skills/skill-evolution/scripts/dashboard_server.py --port 8080
# Access URLs:
# - http://localhost:8080/           # Static dashboard
# - http://localhost:8080/live       # Real-time dashboard (auto-refreshes every 30 seconds)
# - http://localhost:8080/api/health # System health API
# - http://localhost:8080/api/metrics # Skill metrics API

# 4. View enhanced dashboard
start ~/.witty/enhanced_dashboard.html  # Windows
open ~/.witty/enhanced_dashboard.html   # macOS
xdg-open ~/.witty/enhanced_dashboard.html  # Linux

# 5. View original dashboard
start ~/.witty/skill_evolution_dashboard.html  # Windows
open ~/.witty/skill_evolution_dashboard.html   # macOS
xdg-open ~/.witty/skill_evolution_dashboard.html  # Linux

# 4. Analyze skill traces
python skills/skill-evolution/scripts/analyze_traces.py

# 5. Generate evolution report
python skills/skill-evolution/scripts/generate_report.py --skill <skill_name>
```

### 👥 User Management

```bash
# 1. Check current user
python user_manager.py current

# 2. Switch user
python user_manager.py switch <user_id>

# 3. List all users
python user_manager.py list

# 4. Create new user
python user_manager.py create <user_id> --username <display_name> --email <email>

# Available users (presets):
# - admin     - Business style (PPTX: business, DOCX: formal)
# - alice     - Academic style (PPTX: academic, DOCX: academic)
# - bob       - Creative style (PPTX: creative, DOCX: casual)
# - guest     - Default style (PPTX: simple, DOCX: default)
```

### 🎨 Personalization Configuration

```bash
# 1. Set user skill personalization
python skills/skill-personalization/scripts/personalize_cli.py set \
  --user <user_id> \
  --skill <skill_name> \
  --set "parameters.extract_text.language=zh-CN"

# 2. Get user personalization configuration
python skills/skill-personalization/scripts/personalize_cli.py get \
  --user <user_id> \
  --skill <skill_name>

# 3. List all user personalization configurations
python skills/skill-personalization/scripts/personalize_cli.py list \
  --user <user_id>

# 4. Execute skills with personalization
python skills/skill-personalization/scripts/personalize_cli.py execute \
  --user <user_id> \
  --skill <skill_name> \
  --task "Task description"
```

## 📈 Dashboard Recording Rules

- Record self-evolution operation statistics in dashboards, ensuring Rewrite, Prune, Compose, Select, and other operations are visually displayed in the skill evolution framework dashboard
- Dashboards should show specific optimization content and improvement details for each skill, not just statistical numbers
- Detect and display manual refactoring events, even if these operations were not recorded through formal evolution processes

## 📊 Dashboard Features

### Enhanced Dashboard (`enhanced_dashboard.py`)
The latest enhanced dashboard provides comprehensive skill evolution monitoring and visualization capabilities:

#### 🎨 Core Visual Design
- **Icon Integration**: Each evolution type has dedicated icons (✏️Rewrite, ✂️Prune, 🧩Compose, 🎯Select)
- **Color Coding**: Card borders and backgrounds in colors: Rewrite(blue), Prune(red), Compose(green), Select(orange)
- **Gradient Effects**: Gradient title bars, progress bars, medal rankings
- **Hover Interactions**: Card hover animations, table row highlighting effects
- **Responsive Layout**: Adapts to different screen sizes

#### 📋 Five Core Components
1. **System Overview Cards** (5)
   - 📈 System Health Status (with circular progress bars)
   - ✅ Healthy Skills (count and health rate)
   - ⚠️ Skills Needing Attention (count and attention rate)
   - 🔄 Evolution Events (successful evolution count)
   - 👤 User Preferences (current user and style settings)

2. **Top Performing Skills**
   - 🏆 Medal Rankings (gold/silver/bronze)
   - Skill success rate visualization progress bars
   - Health status indicators (🟢Excellent, 🟡Good, etc.)

3. **Key Improvement Areas**
   - Poor Confidence Calibration (6 skills)
   - Insufficient Boundary Handling (6 skills)
   - Poor Process Quality (5 skills)
   - Low Success Rate (1 skill)
   - Low Reliability (1 skill)

4. **Self-Evolution Operation Statistics**
   - Rewrite/Prune/Compose/Select operation counts and percentages
   - Affected skill list (pdf, code-formatter, pptx, etc.)
   - Operation distribution visualization progress bars

5. **Recent Evolution Details** (new feature)
   - 🔍 Display detailed change information for the 5 most recent evolution operations
   - Include skill name, evolution type, timestamp, applied rules
   - Specific change summaries and optimization details (e.g., code-formatter: "Comprehensive refactoring based on Huawei Cloud Python programming standards...")
   - Pre-evolution performance metric comparisons (success rate, overall score)

#### 🔗 RCA Algorithm Integration
- **Unified Data Layer skill** shows `RCA: 38.0%` label
- **Footer Summary**: Overall accuracy 38.0%, time prediction accuracy 30.8%, component identification accuracy 12.5%, cause identification accuracy 56.0%
- Based on evaluation results from 50 queries, detects system bias patterns

#### 📊 Detailed Skill Metrics Table
- **22 skills** complete performance data
- **Health Status**: Excellent(green), Good(blue), Fair(yellow), Needs Attention(orange), Poor(red)
- **Core Metrics**: Success rate, efficiency, process quality, reliability, trace count
- **RCA Integration**: RCA label only displayed on `unified-data-layer` skill row

#### 🚀 Usage
```bash
# Generate enhanced dashboard
python skills/skill-evolution/scripts/enhanced_dashboard.py

# Output file: ~/.witty/enhanced_dashboard.html (~63KB)
# Open in browser: start ~/.witty/enhanced_dashboard.html
```

#### 🛠 Technical Features
- **No External Dependencies**: Uses inline CSS for cross-environment compatibility, solves Tailwind CSS CDN issues
- **Real Data Integration**: Loads real-time data from `skill_metrics_history.json`, `evolution_orchestrator_history.json`, `rca_accuracy_results_all.csv`
- **Frontend Design Principles**: Follows aesthetic guidelines from `frontend-design` skill
- **Template Safety**: Uses string construction to avoid f-string HTML escaping issues

## 📁 Data File Locations

### Main Data Directory: `~/.witty/` (User Home Directory)

| File | Content | Purpose |
|------|---------|---------|
| **Raw Execution Data** | | |
| `skill_traces.json` | Raw tracking records of all skill executions | Analyze skill execution processes, tool calls, execution times, results |
| `active_traces.json` | Currently active execution traces | Monitor ongoing skill executions |
| `skill_traces_sample.json` | Trace data sample | Testing and demonstration purposes |
| **Metrics History Data** | | |
| `skill_metrics_history.json` | **Core metrics file** - Historical evaluation metrics for all skills | View success rates, health status, skill-specific metrics, trend analysis |
| `skill_usage.json` | Skill usage statistics | Analyze skill invocation frequency and patterns |
| **Evolution & Routing History** | | |
| `evolution_orchestrator_history.json` | Skill evolution operation history (Rewrite, Prune, Compose, Select, Merge) | Track evolution decisions and execution processes |
| `skill_routing_history.json` | Skill routing decision history | Analyze task routing accuracy and efficiency |
| **Dashboard & Visualization** | | |
| `enhanced_dashboard.html` | Enhanced dashboard (recommended) | Visualize system status, skill health, evolution history |
| `simple_dashboard.html` | Simple dashboard | Basic monitoring interface |
| `skill_evolution_dashboard.html` | Skill evolution dashboard | Detailed evolution analysis and trend visualization |
| **Configuration & Status** | | |
| `skill_personalization.db` | SQLite database, stores personalization data | User preferences and skill personalization configurations |
| `global_config.json` | Global configuration | System-level settings and parameters |
| `skill_backups/` | Skill backup directory | Stores skill version backups |
| `skill_templates/` | Skill template directory | Stores skill template files |

### Project Data Directory: `~/witty/` (Project Root Directory)

| File/Directory | Content | Purpose |
|----------------|---------|---------|
| `skills/skill-evolution/scripts/skill_metric_definitions.py` | **Skill-specific metric definitions** - Domain-specific metrics for 24 skills | Defines evaluation standards for PDF, DOCX, XLSX, code-formatter, topic-identifier, etc. |
| `output/30min_processing/` | 30-minute processing task output data | Stores `30min_overall.json` and per-minute detailed data |
| `skills/` | All skill implementations | Each skill has its own `SKILL.md` documentation and `scripts/` implementation |

### Data Flow Example
```
Raw Execution → skill_traces.json → Metric Calculation → skill_metrics_history.json → Dashboard Display
      ↓                                        ↓
skill_metric_definitions.py ← Evolution Decisions ← evolution_orchestrator_history.json
```

### Skill-Specific Metrics Data Storage

Skill-specific metrics are managed in the following locations:
1. **Definition Location**: `skills/skill-evolution/scripts/skill_metric_definitions.py` - Metric registration and calculation logic
2. **Calculation Logic**: `skills/skill-evolution/scripts/metrics_calculator.py` - `calculate_skill_specific_metrics()` method
3. **Storage Location**: `~/.witty/skill_metrics_history.json` - Historical metric data (includes `skill_specific_metrics` field)
4. **Real-time Viewing**: `~/.witty/enhanced_dashboard.html` - Visual display

### Registered Skill-Specific Metrics (24 Skills)
- **PDF Processing**: Text extraction quality, table extraction accuracy, operation success rate, performance efficiency
- **DOCX Processing**: Document processing quality, redlining accuracy, template processing effectiveness
- **XLSX Processing**: Data processing accuracy, format preservation, validation efficacy, performance
- **Frontend Design**: Design quality, usability, implementation fidelity
- **Code Formatter**: Formatting compliance, code quality improvement, performance efficiency
- **PPTX Processing**: Presentation processing quality, presentation generation, operation reliability, performance
- **Topic Identifier**: Identification accuracy, question relevance, efficiency, impact
- **Skill Router**: Routing accuracy, response relevance, efficiency

## 🔍 How to View Skill Evaluation Metrics

### 1. Using Simple Script (Recommended)
```bash
cd ~/witty
cat > show_metrics.py << 'EOF'
import json
from pathlib import Path
history_file = Path.home() / ".witty" / "skill_metrics_history.json"
with open(history_file, "r", encoding="utf-8") as f:
    history = json.load(f)
latest = history[-1]
for skill_name, metrics in sorted(latest.get("skill_metrics", {}).items()):
    print(f"Skill: {skill_name}")
    print(f"  Success Rate: {metrics.get('success_rate', 0):.1%}")
    print(f"  Health Status: {metrics.get('health_status', 'UNKNOWN')}")
    skill_specific = metrics.get("skill_specific_metrics")
    if skill_specific and isinstance(skill_specific, dict):
        if skill_specific.get("has_skill_specific_metrics", False):
            print("  Skill-Specific Metrics:")
            for metric_name, metric_data in skill_specific.get("metrics", {}).items():
                print(f"    - {metric_name}: {metric_data.get('score', 0):.2f}")
EOF
python show_metrics.py
```

### 2. View Enhanced Dashboard
```bash
cd ~/witty
python skills/skill-evolution/scripts/enhanced_dashboard.py
# Then open in browser: file:///C:/Users/Aubrey/.witty/enhanced_dashboard.html
```

### 3. Directly View JSON Files
```bash
# View latest metrics
jq '.[-1]' ~/.witty/skill_metrics_history.json | jq '.skill_metrics | keys'
# View specific skill metrics
jq '.[-1].skill_metrics["pdf"]' ~/.witty/skill_metrics_history.json
```

## 🔄 Skill Execution Rules

- When executing skills, do not simulate execution but execute realistically to collect actual trajectory data and performance metrics
- All skill executions should be recorded via the `@trace_skill` decorator for subsequent evolution analysis
- Skill execution results (success/failure, execution time, error patterns) should be completely recorded and used for skill health status assessment

## 🎪 Current System Status

Based on latest enhanced dashboard (`enhanced_dashboard.html`) statistics:

### 📈 System Health Overview
- **Total Skills**: 24 (new: topic-identifier, skill-router)
- **Healthy Skills**: 5 (20.8% health rate)
- **Skills Needing Attention**: 19 (79.2% attention rate)
- **System Health Score**: 38% (needs attention status)

### 🔄 Evolution Operation Statistics
- **Total Evolution Events**: 9
- **Most Recent Evolution**: 2026-02-26 (code-formatter rewrite)
- **Self-Evolution Operation Distribution**:
  - Rewrite: 5 times (55.6%)
  - Prune: 2 times (22.2%)
  - Compose: 2 times (22.2%)
  - Select: 0 times (0.0%)
- **Affected Skills Count**: 9

### 🎯 Recent Evolution Details (5 most recent)
1. **pptx** - Rewrite (version 1.1) - 2026-02-26 09:47
2. **pptx** - Rewrite (version 1.1) - 2026-02-26 09:46
3. **code-formatter** - Rewrite (version 3.0) - 2026-02-26 02:05
   - Comprehensive refactoring based on Huawei Cloud Python programming standards, expanding from 14 to 20 core standards
   - Integrated skill evolution tracking, added skill-specific metric calculation
4. **composite-pdf-docx** - Compose (version 1.0) - 2026-02-25 09:50
5. **test-skill** - Prune (version 1.1) - 2026-02-25 09:50

### 📊 RCA Algorithm Performance
- **Overall Accuracy**: 38.0%
- **Time Prediction Accuracy**: 30.8%
- **Component Identification Accuracy**: 12.5%
- **Cause Identification Accuracy**: 56.0%
- **Evaluation Queries**: 50
- **Bias Detection**: System bias toward Tomcat/MySQL component identification

## 📝 Context Management Rules

- When context usage exceeds 70%, automatically perform context compression (compact) operations
- Compression operations should preserve key information: system status, current task, important decision basis
- Compression strategy: Summarize completed work, retain core context, remove outdated details

## 📊 Example: PPT Generation Skill

As an example of skill library usage rules, we created a new PPT generation skill to generate introduction presentations for the skill self-evolution framework:

**Skill Location**: `skills/pptx/scripts/generate_skill_evolution_ppt.py`  
**Function**: Automatically generates 11-slide presentations based on current user style preferences (business, academic, creative, simple)  
**Integration Features**:
- Uses `@trace_skill` decorator to automatically record execution traces
- Follows skill library usage rules in `rules.md`, prioritizing existing skill library functions
- Integrates personalization configuration system, automatically applying styles based on user preferences
- Generated content includes: system vision, five core operations, trigger conditions, system architecture, skill library usage rules, etc.

**Usage**:
```bash
# Generate default business style PPT
python skills/pptx/scripts/generate_skill_evolution_ppt.py --output framework.pptx

# Specify academic style
python skills/pptx/scripts/generate_skill_evolution_ppt.py --style academic

# Auto-open after generation
python skills/pptx/scripts/generate_skill_evolution_ppt.py --open
```

This skill demonstrates how to follow skill library usage rules to create new functionality, avoid reinventing the wheel, while ensuring full integration with the self-evolution framework.

## 🔧 Quick Start

1. **Check Current Status**:
   ```bash
   python user_manager.py current
   python skills/skill-evolution/scripts/enhanced_dashboard.py
   ```

2. **Run Skills and Collect Traces**:
   ```bash
   # Skills automatically record via @trace_skill decorator
   python test_pptx_styles.py
   ```

3. **View Evolution Effects**:
   ```bash
   # Start real-time dashboard
   python skills/skill-evolution/scripts/dashboard_server.py
   # Open browser and visit http://localhost:8080/live
   ```

4. **Manage Personalization Configuration**:
   ```bash
   # Set personalization preferences
   python skills/skill-personalization/scripts/personalize_cli.py set \
     --user admin \
     --skill pptx \
     --set "style=business"
   ```

---

> **Note**: This system follows the global rules defined in `rules.md`, always responding in Chinese, supporting both Plan (analysis) and Build (execution) modes.