darwin-skill: When Git Becomes the Fitness Function for AI Skills
An autonomous optimization loop that tests `SKILL.md`, scores what works, and reverts what doesn’t, so agent skills evolve by evidence instead of vibes.
- darwin-skill treats each skill edit as a hypothesis and uses Git to keep only the versions that score better.
- The repo’s real unit of optimization is `SKILL.md`, not source code or a generic prompt blob.
- Its rubric matters because structural polish alone is not enough, and effectiveness has to be tested by a separate evaluator.
- The result card and human checkpoints turn a cold optimization loop into something legible, reviewable, and trustworthy.
The ratchet that never forgets
The whole repo is built around a simple but sharp rule: if a change makes the skill worse, it does not survive. That is the ratchet. A skill file can mutate, but Git is the boundary that keeps bad mutations from becoming history.
That changes the emotional contract of AI iteration. Most prompt workflows ask you to trust the next draft. darwin-skill asks you to prove the draft improved the outcome, then either keep it or roll it back.
What darwin-skill is actually optimizing
The target is not a model, and not a prompt in the loose sense. It is `SKILL.md`, the instruction file that defines how an agent should behave. That matters because skills are accumulating assets. As a team adds more of them, manual editing becomes a maintenance burden instead of a craft.
# The thing being optimized
- `SKILL.md`: the skill definition and operating rules
- `test-prompts.json`: the cases used to probe the skill
- `results.tsv`: the score log that records each round
- Git commit history: the rollback line when a change fails
That file-centric view is the real pivot. The repo treats skill instructions as living artifacts that can be improved the same way software can, but with stronger discipline around measurement and reversal.
Why the rubric matters more than the rewrite
The most important design choice is not the rewrite step. It is the score. darwin-skill splits evaluation into structural quality and actual effectiveness, then forces test prompts to exist before edits begin. That blocks the usual trap where a prettier instruction set gets mistaken for a better one.
| Dimension | What it checks | Why it matters |
|---|---|---|
| Structural quality | Markdown clarity, workflow design, checkpoints, and instruction specificity | A skill that is hard to read is already expensive to maintain |
| Effectiveness | Whether the skill performs better on real test prompts | A polished file that fails in practice is still a failure |
| Independent scoring | A separate sub-agent evaluates the change | Self-grading would reward the edit agent’s own preferences |
| Pre-generated tests | `test-prompts.json` comes before the rewrite | It prevents the target from shifting after the fact |
A useful way to read the rubric is as two different kinds of truth. Structural scoring can inspect the file itself. Effectiveness scoring has to run the skill against a test set, then compare the output to a baseline. That split is what keeps the system honest.
The 5-phase loop, step by step
The workflow is narrow on purpose. It does one thing, measures it, and refuses to blur the result. That makes the loop feel less like a chatbot and more like a controlled experiment.
1. Initialize a clean optimization branch
2. Generate `test-prompts.json` before editing
3. Establish a baseline score
4. Fix the lowest-scoring dimension
5. Re-score, then keep or revert
That sequence matters because it forces causality. If the score rises, the new version earns its place. If it falls, Git removes the evidence and the system moves on.
Why the scores are split between structure and effectiveness
| Scoring path | What it can see | What it cannot see |
|---|---|---|
| Structural analysis | The Markdown itself | Whether the skill actually behaves well in use |
| Effectiveness testing | Live behavior on test prompts | The deeper writing quality that only human readers may notice |
| Combined rubric | Balance between clean design and practical output | False confidence from either half alone |
实测表现权重最高（25分）。Skill 写得再漂亮，跑出来效果不好就是零。
That line gets to the center of the design. Structure is necessary, but it is not the point. The point is whether the skill actually works when another agent tries to use it.
The result card is not decoration
The HTML templates and screenshot pipeline are not cosmetic extras. They make the optimization legible. A score delta in a TSV file is useful, but a clean result card gives the team something to inspect, compare, and trust.
Generating illustration...
That last mile matters more than people think. Metrics tell you whether a loop ran. A result card tells you whether someone will care enough to continue running it.
像训练模型一样优化你的 Agent Skills。
How darwin-skill differs from autoresearch
The lineage is obvious, but the target changed. Karpathy’s autoresearch optimizes research code. darwin-skill optimizes agent skill files. The shared idea is ratcheted improvement, but the artifact, the evaluation surface, and the user payoff are different.
| Project | Optimizes | Evaluation | Rollback logic | Primary value |
|---|---|---|---|---|
| autorresearch | Research code and experimental loops | Scientific or model-training metrics | Keep only measurable gains | Better research automation |
| darwin-skill | `SKILL.md` and related skill assets | Rubric scores plus live skill tests | Git revert on regression | Better agent behavior through selection |
| Manual skill editing | Human-written instructions | Ad hoc judgment | None beyond memory | Fast starts, weak consistency |
Why the human stays in the loop
达尔文.skill —— 一个让你的Skill无限进化的系统：评估→改进→测试→保留或回滚 | Autoresearch-inspired autonomous skill optimization for Claude Code. Evaluate, improve, test, keep or revert.
The system is autonomous, but not reckless. It pauses for review because skill quality is partly numerical and partly contextual. A human checkpoint is not a weakness here. It is the acknowledgement that not every good instruction is obviously good on paper.
That is the quiet strength of the repo. It does not pretend that every agent decision can be reduced to a single score. It just makes the score good enough to steer the next move.
