File size: 5,229 Bytes
d7b3a74 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 | # Agentic Usage Guide
This guide shows how to run Shinka with coding agents using the project skills:
- `shinka-setup`: scaffold task files (`evaluate.py`, `initial.<ext>`, optional run config)
- `shinka-run`: launch and iterate evolution batches via `shinka_run`
- `shinka-inspect`: load top-performing programs into a compact context bundle
It covers:
- installing Shinka
- installing Claude Code and/or Codex CLI
- copying skill files to the right skill directories
- running a practical setup -> run -> inspect loop
## 1) Install Shinka
From a clean machine:
```bash
git clone https://github.com/SakanaAI/ShinkaEvolve.git
cd ShinkaEvolve
uv venv --python 3.11
source .venv/bin/activate
uv pip install -e .
```
Set API keys (example):
```bash
cp .env.example .env 2>/dev/null || true
# Edit .env and add OPENAI_API_KEY / ANTHROPIC_API_KEY as needed
```
## 2) Install Agent CLI(s)
Install one or both.
### Claude Code
```bash
npm install -g @anthropic-ai/claude-code
claude --version
```
### Codex CLI
```bash
npm install -g @openai/codex
codex --version
```
## 3) Copy Skills to Agent Skill Folders
Skill source files in this repo:
- `skills/shinka-setup/SKILL.md`
- `skills/shinka-run/SKILL.md`
- `skills/shinka-inspect/SKILL.md`
- optional helper scripts for setup skill:
- `skills/shinka-setup/scripts/run_evo.py`
- `skills/shinka-setup/scripts/shinka.yaml`
- helper script for inspect skill:
- `skills/shinka-inspect/scripts/inspect_best_programs.py`
### Claude Code skill path
```bash
mkdir -p ~/.claude/skills/shinka-setup ~/.claude/skills/shinka-run ~/.claude/skills/shinka-inspect
cp skills/shinka-setup/SKILL.md ~/.claude/skills/shinka-setup/SKILL.md
cp -R skills/shinka-setup/scripts ~/.claude/skills/shinka-setup/
cp skills/shinka-run/SKILL.md ~/.claude/skills/shinka-run/SKILL.md
cp skills/shinka-inspect/SKILL.md ~/.claude/skills/shinka-inspect/SKILL.md
cp -R skills/shinka-inspect/scripts ~/.claude/skills/shinka-inspect/
```
### Codex skill path
```bash
mkdir -p ~/.codex/skills/shinka-setup ~/.codex/skills/shinka-run ~/.codex/skills/shinka-inspect
cp skills/shinka-setup/SKILL.md ~/.codex/skills/shinka-setup/SKILL.md
cp -R skills/shinka-setup/scripts ~/.codex/skills/shinka-setup/
cp skills/shinka-run/SKILL.md ~/.codex/skills/shinka-run/SKILL.md
cp skills/shinka-inspect/SKILL.md ~/.codex/skills/shinka-inspect/SKILL.md
cp -R skills/shinka-inspect/scripts ~/.codex/skills/shinka-inspect/
```
## 4) Setup Skill Walkthrough (`shinka-setup`)
Ask the agent to scaffold a new task directory and evaluator contract.
Example prompt:
```text
Use shinka-setup to scaffold a new task in examples/my_task.
Language: python.
Goal: maximize <metric>.
```
Illustration (setup flow):
Expected output:
- `initial.<ext>` with evolve block
- `evaluate.py` producing `metrics.json` + `correct.json`
- optional `run_evo.py` / `shinka.yaml` scaffolds when requested
## 5) Run Skill Walkthrough (`shinka-run`)
Use `shinka_run` for agent-driven evolution loops.
Minimal batch:
```bash
shinka_run \
--task-dir examples/my_task \
--results_dir results/my_task_agent \
--num_generations 10
```
With core knobs via `--set`:
```bash
shinka_run \
--task-dir examples/my_task \
--results_dir results/my_task_agent \
--num_generations 20 \
--set evo.max_api_costs=0.5 \
--set evo.llm_models='["gpt-5-mini","gpt-5-nano"]' \
--set db.num_islands=3 \
--set db.parent_selection_strategy=weighted
```
Illustration (run flow):
## 6) Inspect Skill Walkthrough (`shinka-inspect`)
Use `shinka-inspect` after one or more batches to generate an agent-ready context file.
Minimal:
```bash
python skills/shinka-inspect/scripts/inspect_best_programs.py \
--results-dir results/my_task_agent \
--k 5
```
With filters and explicit output:
```bash
python skills/shinka-inspect/scripts/inspect_best_programs.py \
--results-dir results/my_task_agent \
--k 8 \
--min-generation 10 \
--max-code-chars 5000 \
--out results/my_task_agent/inspect/top_programs.md
```
Output:
- default file: `results/my_task_agent/shinka_inspect_context.md`
- contains ranking + code snippets for top programs
- designed to be loaded directly into coding-agent context
## 7) Batch Iteration Rules (Important)
When using `shinka-run` skill:
- unless user explicitly requests fully autonomous execution, ask for config confirmation between batches
- keep `--results_dir` the same across continuation batches so prior state can reload
- change `--results_dir` only when intentionally forking a new run
## 8) Quick Validation Checklist
Before first run:
- `shinka_run --help` works
- task dir has `evaluate.py` + `initial.<ext>`
- API keys are available in environment
- skill files are installed under `~/.claude/skills` and/or `~/.codex/skills`
After each batch:
- check run artifacts/logs under the chosen `results_dir`
- review score and correctness trend
- run `shinka-inspect` and review the generated context markdown
- choose next batch config (budget, models, islands, attempts, generations)
|