darwin-skill: a ratchet for optimizing Claude Code skills

The problem: structural review passes, real output does not

Skills written in the SKILL.md format are now supported across Claude Code, Codex, OpenClaw, Trae and CodeBuddy, and the README observes that manual maintenance stops scaling somewhere between ten and sixty skills. The usual review is purely structural: is the format right, are the steps numbered, do the paths resolve. A skill can pass all of that and still produce poor output, because nothing in a format check exercises the agent that reads it.

darwin-skill targets that gap. It scores structure through static analysis and scores effectiveness by running the skill against test prompts, and it keeps a revision only when the combined score rises. The intended user is someone who already owns a directory of skills and wants a repeatable procedure for improving them, rather than a one-off rewrite.

The autoresearch mapping and the 9-dimension score

The design is a direct translation of Andrej Karpathy's autoresearch. Where autoresearch uses a program.md to define objectives and constraints, darwin-skill uses its own SKILL.md. Where autoresearch treats train.py as the single editable asset, darwin-skill treats the target SKILL.md as that asset. The val_bpb metric becomes a weighted 9-dimension score out of 100, the git ratchet becomes a keep-or-revert decision, and the test set becomes test-prompts.json. The one mapping the README calls out as deliberately different is autonomy: autoresearch runs unattended, darwin-skill inserts a human.

Of the nine dimensions, three were added in version 2.0 from Microsoft Research's SkillLens paper, which the README describes as an empirically validated rubric. Failure Mechanism Encoding replaces a general error-handling dimension: known failure paths must be written into the skill explicitly instead of being covered by a generic instruction not to make mistakes. Actionable Specificity replaces a clarity dimension and bans phrases such as 建议, 可以考虑, 根据情况, 灵活把握 and 视情况而定. High-Risk Action Blacklist is the ninth dimension and requires destructive operations like rm, git reset --hard and force push to be named and forbidden in the skill text. The README states that effectiveness carries the highest weight, on the reasoning that a well-written skill which performs badly scores zero.

Installing it and running a first optimization

The README gives a single install command through the skills CLI. It fetches the skill from the alchaincyf/darwin-skill repository and places it where the agent tool can find it.

npx skills add alchaincyf/darwin-skill

If GitHub is not reachable, the README points to a zip download and says to unpack it so that SKILL.md sits in ~/.claude/skills/darwin-skill/. Once installed, the trigger is conversational: the README says to tell any Skill-capable agent tool to optimize all skills, or to optimize a specific one. There is no separate CLI to invoke.

Before the first run, the README's safety note asks you to work inside a git repository and to commit or stash your own local changes to the skill, so that darwin-skill can cleanly keep or revert its experimental edits. That precondition matters because the rollback path is git revert, not a hard reset. The project ships a test-prompts.json at the repository root, and the evaluation loop expects a test set of that kind for the skill being optimized.

The loop itself has five phases. Phase 1 is a baseline evaluation whose report you review to decide what to change. Phase 2 optimizes a single dimension and then hits a checkpoint that the README marks with a red indicator, where the system pauses and shows the diff and score change. Phase 2.5 runs the test prompts if you opt in. Phase 3 is a regression test that stops the run when the improvement falls below a threshold. The README also notes that you should review the checkpoint diff carefully whenever the skill touches shell commands, git operations, credentials, local files or release processes.

Why the ratchet only moves one way

Inside Phase 2 the system computes a weighted_gap as weight times (10 minus score) divided by 10, and picks the dimension with the largest gap. That formula is a deliberate choice: it stops a low-weight dimension from generating an impressive-looking gain that does not move the overall number. It then writes exactly one improvement for that dimension, commits, and starts two independent sub-agents to rescore. If the new score is higher the commit stays; otherwise the system runs git revert. The README forbids git reset --hard as a rollback method, listing it as the second of eight anti-patterns.

The ratchet is what makes the score monotonic. The README's illustration is a round that scores 75 against a current best of 78; it is reverted and the baseline stays at 78, so later rounds improve from there rather than from the failed attempt. Two further guards sit on top. A round that gains less than one point triggers an automatic early stop, described as a way to avoid padding the skill with redundant text just to move the number. And a dry-run ratio above 30 percent raises a warning. Judges are not reused between rounds, which the README attributes to avoiding anchoring effects.

The eight anti-patterns are worth reading as a design statement. The first is having the same AI both edit and evaluate, justified by the SkillLens figure that LLM self-evaluation reaches only 46.4 percent accuracy. Others ban changing more than one dimension per round, skipping test prompts before scoring, silently ignoring exceptions, and ignoring correlated dimension clusters. The README reports two optimization runs: a huashu-gpt-image skill moving from 80.8 to 91.5 to 91.65 with six independent judges in consensus, and darwin-skill's own self-evaluation moving from 86.05 to 92.05 to 92.7. Those are the project's own numbers, not a third-party measurement.

Where the design costs you, and when to reach for something else

The human-in-the-loop design is the project's stated differentiator from SkillOpt, and it is also its main cost. Every phase boundary is a pause, Phase 2 carries a mandatory checkpoint, and Phase 3 can halt the run. Optimizing sixty skills this way is not a background job; it is sixty review sessions. For a team that wants an optimizer to run overnight, that is the wrong shape.

The git dependency is a second constraint. The keep-or-revert decision is expressed as commits and git revert, so the target skill has to live in a repository with a clean working tree. A skill edited in place outside version control has no rollback path, and the README's safety note effectively makes version control a prerequisite rather than a suggestion.

The test-prompt requirement is the sharpest limit. Effectiveness dimensions are scored by running the skill against prompts, so a skill whose behaviour cannot be exercised that way, or for which no test set exists, loses access to the part of the rubric the README says carries the most weight. In that case the score is mostly a structural judgement, which is exactly the kind of review the project was built to move past.

SkillOpt is the real alternative and the README treats it as one. Microsoft Research's SkillOpt is described as a fully autonomous system that treats a skill as external trainable state for a frozen model, gating every edit behind independent validation; the README notes it is installable with pip install skillopt and that version 0.1.0 is on PyPI. The difference is not the scoring philosophy, since darwin-skill adopted SkillOpt's validation-gated framework, but who decides: SkillOpt proceeds on its own, darwin-skill stops and asks. The README also states that Microsoft listed darwin-skill in SkillOpt's integration list on 2026-06-03. If your objection to darwin-skill is the constant pausing, SkillOpt is the project that removes it.

Maintenance, licensing and what to check before committing

The repository is not archived and the last push was on 2026-09-18. The README dates version 2.0 to 2026-05-28 and describes it as a structural upgrade rather than an incremental one. The repository has no published GitHub releases, so the version badge in the README is the only version signal available, and there is no changelog to read for upgrade steps between 1.0 and 2.0.

On upgrades, the repository layout matters more than a version number. SKILL.md is the file that defines the evaluation criteria and constraints, so pulling a newer SKILL.md changes the rubric itself, and scores from an older run are not comparable to scores from a newer one. The docs, references, scripts and templates directories sit alongside it, and test-prompts.json at the root is the test set the loop consumes. Anyone upgrading should expect to re-baseline rather than resume from a previous score.

The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. That is a statement about the licence text, not legal advice; if you redistribute a modified SKILL.md inside a product, read the LICENSE file in the repository and get your own counsel on attribution.

Editorial conclusion

Adopt darwin-skill if you maintain a growing set of SKILL.md files in a git repository and you are willing to review a diff at every checkpoint; the ratchet only works when the working tree is clean and the skill is versioned. Do not adopt it if you want a fully autonomous optimizer, since the project deliberately pauses for human confirmation at each phase, or if the skill you want to improve cannot be exercised with test prompts. Before the first run, commit or stash your local skill edits and confirm that test-prompts.json exists for the skill under evaluation, because without a test set the effect dimensions have nothing to measure against.

Frequently asked questions

Official sources

1. alchaincyf/darwin-skill on GitHub
2. Issues
3. License: MIT
4. README