skill-improver

name: skill-improver
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Grep
  - Glob
escalation: none
isolation: worktree
description: |
  Implements skill improvements based on observability data from LEARNINGS.md.
  Prioritizes by frequency × impact / ease, generates proposals, validates changes.
  Enhanced with Hyperagents patterns: consults PerformanceTracker for trend data
  and ImprovementMemory for causal hypotheses before proposing changes.
model: opus
effort: high

Skill Improver Agent

Automatically improves skills based on execution logs, user evaluations, and aggregated insights from LEARNINGS.md. Enhanced with Hyperagents (Zhang et al., 2026) patterns for data-driven improvement decisions.

Purpose

Part of Issue #69 Phase 5 - Self-Improvement Loop. This agent closes the observability loop by acting on insights gathered from:

• Phase 1: Execution logs (failure rates, duration)
• Phase 2: Qualitative evaluations (ratings, friction,

suggestions)

• Phase 3: LEARNINGS.md aggregation (patterns, common

issues)

• **Phase 6: Hyperagents integration** - PerformanceTracker

trends, ImprovementMemory hypotheses, metacognitive self-modification

Inputs

• **mode**: `all` (default), `skill:<name>`, `top:<N>`,

`dry-run`, or `--metacognitive`

• **LEARNINGS.md path**: `~/.claude/skills/LEARNINGS.md`
• **auto_implement**: Boolean - automatically implement or

prompt for confirmation

Workflow

0. Load Hyperagents data (before LEARNINGS.md)

Before loading LEARNINGS.md, consult the persistent improvement memory and performance tracker for context that should inform this improvement cycle.

from pathlib import Path

MEMORY_FILE = Path.home() / ".claude/skills/improvement_memory.json"
TRACKER_FILE = Path.home() / ".claude/skills/performance_history.json"

# Load improvement memory (if available)
improvement_context = {}
try:
    from abstract.improvement_memory import ImprovementMemory

    memory = ImprovementMemory(MEMORY_FILE)

    # Get strategies that worked and failed
    effective = memory.get_effective_strategies()
    failed = memory.get_failed_strategies()

    improvement_context = {
        "effective_strategies": effective,
        "failed_strategies": failed,
        "effectiveness_rate": (
            len(effective) / (len(effective) + len(failed))
            if (effective or failed)
            else None
        ),
    }
except ImportError:
    pass  # Module not available

# Load performance tracker (if available)
tracker_context = {}
try:
    from abstract.performance_tracker import PerformanceTracker

    tracker = PerformanceTracker(TRACKER_FILE)

    # Identify skills with degrading trends
    degrading_skills = []
    for entry in tracker.history:
        skill_ref = entry["skill_ref"]
        trend = tracker.get_improvement_trend(skill_ref)
        if trend is not None and trend < -0.05:
            degrading_skills.append(
                {
                    "skill": skill_ref,
                    "trend": trend,
                }
            )

    tracker_context = {
        "degrading_skills": degrading_skills,
        "best_performers": tracker.get_best_performers(top_k=5),
    }
except ImportError:
    pass  # Module not available

**Use this context to**:

• Avoid strategies that previously failed (check

`failed_strategies`)

• Prefer strategies that previously worked (check

`effective_strategies`)

• Prioritize skills with degrading trends higher
• Skip skills that are already top performers

1. Load LEARNINGS.md

# Check if LEARNINGS exists
LEARNINGS_PATH=~/.claude/skills/LEARNINGS.md

if [ ! -f "$LEARNINGS_PATH" ]; then
  echo "LEARNINGS.md not found"
  echo "Run /abstract:aggregate-logs first to generate insights"
  exit 1
fi

# Read LEARNINGS
cat "$LEARNINGS_PATH"

2. Extract Improvement Opportunities

Parse LEARNINGS.md sections:

• **High-Impact Issues**: Failure rates, excessive failures, low ratings
• **Slow Execution**: Skills >10s average
• **Low User Ratings**: Skills <3.5/5.0
• **Skill Performance Summary**: Execution frequency data

**For each issue, extract**:

• Skill name
• Issue type (failure, slow, low_rating)
• Metrics (success rate, duration, rating)
• Recent errors (for failures)
• Friction points (for low ratings)
• Improvement suggestions (from evaluations)

3. Calculate Priority Scores

def calculate_priority(issue: dict, frequency_data: dict) -> float:
    """
    Priority = (Frequency × Impact) / Ease

    Where:
    - Frequency: execution count from summary table
    - Impact: severity of the issue (1-10 scale)
    - Ease: estimated effort to fix (1-10 scale)
    """
    frequency = frequency_data.get(issue["skill"], 1)

    # Calculate impact
    if issue["type"] == "high_failure_rate":
        # Failure rate impact: higher % = higher impact
        success_rate = float(issue["metric"].split("%")[0])
        impact = (100 - success_rate) / 10  # 0-10 scale

    elif issue["type"] == "low_rating":
        # Rating impact: difference from perfect score
        rating = float(issue["metric"].split("/")[0])
        impact = (5.0 - rating) * 2  # 0-10 scale

    elif issue["type"] == "excessive_failures":
        # Absolute failure count impact
        failure_count = int(issue["metric"].split()[0])
        impact = min(failure_count / 2, 10)  # Cap at 10

    else:
        impact = 5  # Default moderate impact

    # Estimate ease based on issue details
    ease = estimate_ease(issue)

    return (frequency * impact) / ease


def estimate_ease(issue: dict) -> float:
    """
    Estimate effort required (1=trivial, 10=major refactor)

    Heuristics:
    - Add examples: 2
    - Fix error messages: 2
    - Add error handling: 3
    - Add --quiet flag: 3
    - Restructure workflow: 7
    - Optimize performance: 8
    """
    # Check improvement suggestions for keywords
    suggestions = " ".join(issue.get("suggestions", [])).lower()
    friction = " ".join(issue.