Cortex · measured skills and rules for Claude Code
Cortex treats every skill or rule as a hypothesis and tests it. It turns your real sessions into pass/fail tasks, proposes one skill or rule from the corrections you keep making, runs Claude with and without it in throwaway clones of your repository, and keeps it only if it wins something and breaks nothing.
Collect what keeps going wrong → measure one fix against the real jobs → remove whatever stopped pulling its weight.
Everything below is built from these.
check.sh that answers pass or fail.lessons.md for each time you had to correct Claude.claude -p run of a task, in a throwaway clone of your repository. Rollouts are the only thing that costs money.Each runs on its own rhythm. Together they form one closed loop.
You just fixed a bug. The environment is still warm and you remember exactly what broke. Harvest freezes that moment into a reusable test before you close the session, because rebuilding it later is far more work. It takes about a minute, and it never writes a skill.
cortex preflight proves it: the check must fail before the fix and pass after. Each correction becomes one line in lessons.md. No skill is written yet.
nothing to harvest. A task that cannot tell broken from fixed is quarantined with its reason, because a bad test silently corrupts every later score.
Evolve looks for one problem that keeps recurring. If nothing recurs it stops, and that costs nothing. Otherwise it writes one skill or rule for it, in the tier the evidence points to, then runs your tasks both ways, without it and with it, several times each, in throwaway clones of your repository (several at once, sized to your free RAM and CPUs). A script reads the results and decides. No opinion is involved.
.evolve/candidate/. It is not live yet. A free check confirms that a task can load it.
cortex scope
How many tasks will this candidate be injected into? A rule fires in every task it reaches, and each unrelated one is a chance to break something. It warns, you decide, and the sweep runs either way.
Dashed = advice only. With the optional Jev judge it also estimates how many of those tasks are really about the candidate.
cortex score applies the gates below. It contains no model of any kind.
An example confirm with five tasks, three runs per task in each arm. A filled dot is a run that passed. The verdict is read task by task, never as an average.
| task | base | cand | what the scorer sees |
|---|---|---|---|
| task 01 | passed every run before, so it is protected. It held. | ||
| task 02 | +2 runs | ||
| task 03 | protected. It held. | ||
| task 04 | +2 runs | ||
| task 05 | unchanged |
Every always-on skill's description sits in Claude's context on every turn. Prune measures what removing a skill or rule would really cost, on a snapshot that never touches your live files, and deletes only what costs nothing. It also narrows: a skill used in one area only moves to a path-gated skill or a rule that loads only there. A newer model may already do what an old skill teaches, which is why this runs again after every upgrade. Nothing runs until you approve the plan: it shows the rollouts, time, tokens and cost first.
prune.max_items, 3 by default): overlaps, narrow wins, the largest always-on descriptions. Items no task can measure are skipped. You see the cost and say yes first.
Not everything should sit in context on every turn. Evolve picks the narrowest tier that still loads before the mistake happens.
Injected in full when Claude reads a matching file. Claude has no choice, and it costs nothing until then.
For a short, hard "never do this" about existing files in one area.
Offered when Claude reads or writes a matching file. Claude sees its name and one-line description, and must choose to open it.
For a procedure in one area, including creating new files there.
Its description is in context on every turn, and Claude must choose it. This is the only tier with a permanent cost.
For a moment with no area, such as "before reporting done".
Some problems are not a skill at all. A fact Claude breaks during unrelated work belongs in CLAUDE.md, and a check that must always run is a hook. For those, Evolve makes the change, records it in the journal and runs no sweep: there is nothing to compare.
the thinking behind it
The overview showed the workflow. These are the ideas that make it trustworthy. Each one is something you already know from everyday life.
Like a checkpoint in a video game. When you fix something, Cortex saves the "before", so it can drop Claude back into that exact broken moment and see how it copes, with or without a given skill, as many times as it likes.
Two identical plates. One has the new spice, one doesn't, and everything else is the same. If the spiced plate wins, it was the spice. A new skill is judged the same way: the same jobs, run with it and without it, side by side.
Take an ingredient out of the recipe. If the dish tastes exactly the same, it wasn't doing anything, so drop it. Skills get the same treatment, because every always-on one you keep costs the agent a little attention on every single turn.
Harvest feeds evolve, evolve feeds prune, and the loop keeps turning. Each turn adds one measured item, removes one, or changes nothing, and all three are fine outcomes.
Each command is a fresh session with no memory of the last one. These files on disk are the memory: written by one command, read by the next. Commit .evolve/ with your repository.
cortex score.cortex skills.