Skip to content

Evoskill

EvoSkill — self-improving agent framework for G6.

Cluster: Uncategorised | Type: component | MCP Tools: 9

Overview

EvoSkill is a bounded reliability workflow for proposing, testing, and validating skill or prompt improvements. It maintains a frontier store of top-performing program variants, proposes candidate mutations from failure traces, and replays selected candidates through the validated learning_layer so outputs include mutation-disabled validation evidence (learning_validation) and a conservative launch_ready signal.

Use as a guided reliability workflow

EvoSkill should not be presented as fully autonomous "self-training magic." It is most useful when wrapped in a guided workflow: run a reliability check, review failures, apply a suggested improvement, validate on holdout/frozen data, and export the resulting harness. Product claims should be based on emitted validation evidence, not on the fact that a mutation entered the frontier.

When to use:

  • Guided improvement of solver or agent skills from failure traces
  • Running evolutionary search over skill variants in a controlled budget
  • Producing learning-layer validation evidence for a proposed improvement
  • Connecting the hyperdistillation pipeline to a living skill improvement loop

Example:

from mvp.evoskill import EvoSkillBlock, EvoSkillInput

block = EvoSkillBlock(name="evoskill")
result = block.infer(EvoSkillInput(
    op="evolve",
    task_name="math_reasoning",
    dataset=[{"input": "2+2", "expected": "4"}],
))
# result.ok -> True
# result.value -> EvoSkillOutput with best_program, frontier,
# learning_validation, and launch_ready

Works well with: learning_layer, hyperdistillation, solver, cegis

Public API

AgentTrace(Generic[T])

Trace of a single agent execution — compatible with EvoSkill's AgentTrace.

Field Type Default
uuid str ''
session_id str ''
model str ''
tools list[str] field(default_factory=list)
duration_ms int 0
total_cost_usd float 0.0
num_turns int 1
usage dict[str, Any] field(default_factory=dict)
result str ''
is_error bool False
output T \| None None
parse_error str \| None None
raw_structured_output Any None
messages list[Any] field(default_factory=list)

Methods:

summarize(head_chars: int = 2000, tail_chars: int = 500) -> str

Summarize trace for proposer context.

model_dump() -> dict[str, Any]

Serialize for caching.

model_validate(data: dict[str, Any]) -> AgentTrace

Deserialize from cache.

EvoAgent(Generic[T])

Wraps G6's AgentClaudeBlock for use in EvoSkill's evolution loop.

Constructor:

Parameter Type Default
response_model Type[T] \| None None
system_prompt str ''
model str 'claude-sonnet-4-20250514'
max_tokens int 4096
tools list[dict[str, Any]] \| None None

Methods:

run(query: str) -> AgentTrace[T]

Execute query and return trace.

EvoSkillBlock(AIBlock['EvoSkillInput', 'EvoSkillOutput', dict])

Self-improving agent evolution block.

Field Type Default
name str 'evoskill'
resource_bounds ResourceBounds \| None None
usage ResourceUsage field(default_factory=ResourceUsage)
workspace_dir str ''
model str 'claude-sonnet-4-20250514'

Methods:

infer(data: EvoSkillInput) -> Result[EvoSkillOutput]

Dispatch to the appropriate operation.

health() -> dict

Return health status for production monitoring.

FeedbackDescentResult(Generic[T])

Final result of the optimization loop.

Field Type Default
best T required
feedback_history List[FeedbackEntry[T]] required
iterations int required
improved bool required

FeedbackDescent(Generic[T])

Core Feedback Descent optimization loop.

Constructor:

Parameter Type Default
proposer Proposer[T] required
evaluator Evaluator[T] required
max_iterations int 10
no_improvement_limit int 3

Methods:

run(problem: str) -> FeedbackDescentResult[T]

Run the feedback descent optimization loop.

AgentTrace(Protocol)

Lightweight protocol for agent traces used by loop helpers.

Methods:

summarize(head_chars: int = 60000, tail_chars: int = 60000) -> str

Return a truncated summary of the trace.

AgentTrace(Protocol)

Lightweight protocol replacing the concrete AgentTrace from EvoSkill's agent_profiles.base.

Methods:

model_dump() -> dict[str, Any]

Serialize to dict (Pydantic-compatible).

model_validate(data: dict[str, Any]) -> 'AgentTrace'

Deserialize from dict (Pydantic-compatible).

EvolutionConfig(BaseModel)

Configuration for an evolution run.

Field Type Default
max_iterations int Field(default=5, ge=1, le=100)
frontier_size int Field(default=3, ge=1, le=20)
no_improvement_limit int Field(default=5, ge=1)
concurrency int Field(default=4, ge=1, le=16, description='Accepted for API stability; currently deferred in the synchronous evolution loop and disclosed by evoskill_capabilities.')
evolution_mode Literal['skill_only', 'prompt_only'] 'skill_only'
selection_strategy Literal['best', 'random', 'round_robin'] Field(default='best', description='Active when selecting from the frontier during evolution.')
failure_sample_count int Field(default=3, ge=1)
tolerance float Field(default=0.0, ge=0.0, le=1.0)
cache_enabled bool Field(default=True, description='Accepted for API stability; currently deferred for the main synchronous loop and disclosed by evoskill_capabilities.')
reset_feedback bool True
learning_layer_enabled bool True
learning_layer_phase Literal['train', 'holdout', 'frozen'] 'holdout'

EvoSkillInput(BaseModel)

Input for EvoSkillBlock.infer().

Field Type Default
op Literal['evolve', 'propose_skill', 'generate_skill', 'evaluate', 'list_programs', 'get_frontier', 'feedback_descent', 'list_patterns', 'evoskill_capabilities', 'ops', 'help'] 'evolve'
run_mode Literal['beta', 'production'] 'beta'
reviewer_signature str ''
task_name str ''
dataset list[dict[str, Any]] Field(default_factory=list)
config EvolutionConfig Field(default_factory=EvolutionConfig)
feedback_descent_problem str ''
initial_candidate str ''
candidate_pool list[str] Field(default_factory=list)
target_answer str ''
failure_traces list[str] Field(default_factory=list)
existing_skills list[str] Field(default_factory=list)
feedback_history str ''
proposal str ''
program_name str ''
validation_data list[dict[str, Any]] Field(default_factory=list)
request_id str ''
task_id str ''
run_id str ''

EvoSkillOutput(BaseModel)

Output from EvoSkillBlock.infer().

Field Type Default
ok bool True
message str ''
best_program str ''
best_score float 0.0
frontier list[dict[str, Any]] Field(default_factory=list)
iterations_completed int 0
learning_validation dict[str, Any] Field(default_factory=dict)
launch_ready bool False
best_candidate str ''
feedback_descent_history list[dict[str, Any]] Field(default_factory=list)
improved bool False
proposed_skill str ''
justification str ''
action str ''
generated_skill str ''
reasoning str ''
safe bool \| None None
safety_reasons list[str] Field(default_factory=list)
score float 0.0
programs list[dict[str, Any]] Field(default_factory=list)
patterns list[dict[str, Any]] Field(default_factory=list)
metadata dict[str, Any] Field(default_factory=dict)
agentic_evidence dict[str, Any] \| None None
degraded bool False
degradation_reason str \| None None
completion_state Literal['verified', 'qualified-draft', 'blocked-escalated'] 'qualified-draft'
warning_card dict[str, Any] Field(default_factory=dict)
evidence dict[str, Any] Field(default_factory=dict)
request_id str ''
task_id str ''
run_id str ''
code str ''

MCP Tools

Operation Source
evolve_skills evoskill_mcp
propose_skill evoskill_mcp
generate_skill evoskill_mcp
evaluate_program evoskill_mcp
list_programs evoskill_mcp
get_frontier evoskill_mcp
feedback_descent_run evoskill_mcp
list_patterns evoskill_mcp
evoskill_capabilities evoskill_mcp