Convert an existing codebase in the current working directory into a ShinkaEvolve task directory by snapshotting the relevant code, adding evolve blocks, and generating `evaluate.py` plus Shinka runner/config files. Use when the user wants to optimize existing code with Shinka instead of creating a brand-new task from a natural-language description.
Use this skill to turn an existing project into a Shinka-ready task.
This is the alternative starting point to shinka-setup:
shinka-setup: new task from natural-language task descriptionshinka-convert: existing codebase to Shinka task conversionAfter conversion, the user should still be able to use shinka-run.
Invoke this skill when the user:
metrics.json, correct.json, or EVOLVE-BLOCK markersDo not use this skill when:
evaluate.py and initial.<ext> already exist and the user only wants to launch evolution; use shinka-runStart from freeform instructions, then ask follow-ups only if high-impact details are missing.
Collect:
Generate a sidecar task directory at ./shinka_task/ unless the user requests another path.
The task directory should contain:
evaluate.pyrun_evo.pyshinka.yamlinitial.<ext>Do not edit the original source tree unless the user explicitly requests in-place conversion.
./shinka_task/initial.<ext> so shinka-run can detect it.EVOLVE-BLOCK-START / EVOLVE-BLOCK-END markers.run_experiment(...) and use run_shinka_eval.subprocess and write metrics.json plus correct.json.run_evo.py and shinka.yaml.
init_program_path and language match the candidate file.shinka-run.python evaluate.py --program_path <initial file> --results_dir /tmp/shinka_convert_smokeshinka-run skillrun_experiment(...) in the snapshot and evaluate via run_shinka_evalevaluate.py as the Shinka entrypointmetrics.json and correct.json in results_dirMetrics must include:
combined_scorepublicprivateextra_datatext_feedbackCorrectness must include:
correcterrorHigher combined_score values indicate better performance unless the user explicitly defines an inverted metric that you transform during aggregation.
Prefer shaping the copied program like this:
from __future__ import annotations
# EVOLVE-BLOCK-START
def optimize_me(...):
...
# EVOLVE-BLOCK-END
def run_experiment(random_seed: int | None = None, **kwargs):
...
return score, text_feedback
And the evaluator:
from shinka.core import run_shinka_eval
def main(program_path: str, results_dir: str):
metrics, correct, err = run_shinka_eval(
program_path=program_path,
results_dir=results_dir,
experiment_fn_name="run_experiment",
num_runs=3,
get_experiment_kwargs=get_kwargs,
aggregate_metrics_fn=aggregate_fn,
validate_fn=validate_fn,
)
if not correct:
raise RuntimeError(err or "Evaluation failed")
Use evaluate.py to run the candidate and write outputs:
import json
import os
from pathlib import Path
def main(program_path: str, results_dir: str):
os.makedirs(results_dir, exist_ok=True)
metrics = {
"combined_score": 0.0,
"public": {},
"private": {},
"extra_data": {},
"text_feedback": "",
}
correct = {"correct": False, "error": ""}
(Path(results_dir) / "metrics.json").write_text(json.dumps(metrics, indent=2))
(Path(results_dir) / "correct.json").write_text(json.dumps(correct, indent=2))
scripts/run_evo.py as the starting runner templatescripts/shinka.yaml as the starting config templateshinka-run