Motivation

The current MCP tool set has a gap between fully automatic evolution (inside execute_task) and manual repair (fix_skill for a known broken skill). There is no way for a host agent to proactively inspect which skills could benefit from evolution and make its own decisions about whether and when to act.

The data already exists — SkillStore accumulates ExecutionAnalysis records with evolution_suggestions, and SkillRecord tracks usage statistics (completion_rate, fallback_rate, etc.). This information is just not exposed through an MCP tool.

Proposal

Add a new MCP tool scan_evolution_opportunities that:

1. Loads evolution candidate analyses from the store
2. Enriches each candidate with the corresponding SkillRecord statistics
3. Returns a structured JSON report with prioritized suggestions

This enables a powerful pattern for all host agents (Claude Code, Codex, nanobot, Cursor, etc.):

• Periodic/cron-based skill health scanning
• Agent reviews the report and decides which evolutions to trigger
• Agent calls fix_skill (or future evolve_skill) on selected candidates

This is the "agent-in-the-loop" complement to the existing fully automatic evolution pipeline.

API Design

@mcp.tool()
async def scan_evolution_opportunities(
    skill_dirs: list[str] | None = None,
    max_candidates: int = 10,
) -> str:
    """Scan skill execution history and return evolution opportunities.
    
    Returns a structured report of skills that may benefit from evolution
    (FIX, DERIVED, or CAPTURED), with usage statistics and specific
    suggestions. The caller decides whether to act on any suggestion.
    """

Return shape

{
  "candidates": [
    {
      "skill_id": "...",
      "skill_name": "...",
      "description": "...",
      "stats": {
        "total_selections": 10,
        "completion_rate": 0.6,
        "fallback_rate": 0.3,
        ...
      },
      "suggestions": [
        {
          "type": "fix",
          "direction": "...",
          "target_skill": "..."
        }
      ],
      "source_task_id": "...",
      "analyzed_at": "..."
    }
  ],
  "total_candidates": 5,
  "total_active_skills": 42,
  "scan_summary": "Found 5 evolution candidates: 3 FIX, 1 DERIVED, 1 CAPTURED"
}

Implementation

• Reuses existing _get_store() and _get_openspace() patterns
• Calls SkillStore.load_evolution_candidates() + load_record() for enrichment
• No new dependencies; pure composition of existing APIs