# Skill Evolution

Use when running, reviewing or changing coco's self-evolution cycle: the 30-day loop...

- Repository: https://github.com/coco-research/coco (797 stars)
- Category: Git and review
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add coco-research/coco --skill skill-evolution -g -a claude-code -y`
Codex: `npx skills add coco-research/coco --skill skill-evolution -g -a codex -y`
Cursor: `npx skills add coco-research/coco --skill skill-evolution -g -a cursor -y`
Gemini CLI: `npx skills add coco-research/coco --skill skill-evolution -g -a gemini-cli -y`

## Description

Use when running, reviewing or changing coco's self-evolution cycle: the 30-day loop that observes how skills are actually used, proposes evidence-backed edits to them as one branch and one pull request, and lands nothing without the owner's merge. Also use when asked why a skill changed, what the loop would propose next, or how to reject a proposal so it is not raised again.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Skill Evolution

A cycle that improves this repository's own skills from observed use, and proposes every
change for a human to merge. It never writes to `main` and never merges.

**Status:** the scripts this file documents, `scripts/evolve.py` and the steps it runs, are
not on `main` yet, so the commands below do not run today. They land with plan tasks 2 to 9
in `.metagpt/plan.md`: task 2 `ledger.py` through task 8 `evolve.py`, and task 9
`run_fixtures.sh` with the CI join.

## The one rule

**The loop proposes. The owner decides.** There is no confidence level, budget or green gate
that lets it land a change on its own. This is a design invariant, not a setting: a system
that edits the repository that measures it has no natural stopping point.

## What a cycle does

Five steps, and only the second one calls a model.

| Step | Script | Model? | Output |
| --- | --- | --- | --- |
| 1. Observe | `scripts/observe.py` | no | `signals/<cycle>.json`, pinned to one commit |
| 2. Propose | `scripts/propose.py` | yes, one lane | `proposals/<id>.json` and `proposals/<id>.patch` |
| 3. Validate | `scripts/validate.py` | no | accept or refuse, with a reason |
| 4. Open | `scripts/evolve.py` | no | one branch, one pull request |
| 5. Record | `scripts/ledger.py` | no | a ledger row per event, and `CYCLE.md` |

Run it:

```
python3 scripts/evolve.py run --window 30d            # the real cycle, needs credentials
python3 scripts/evolve.py run --window 30d --dry-run   # stops before opening a branch
python3 scripts/evolve.py run --window 30d --lane stub # no network at all
python3 scripts/evolve.py status                       # last cycle, open proposals
```

## What the guard refuses

`validate.py` is the only thing standing between a model's output and a branch. It refuses,
with the reason named, when any of these hold:

The rest: https://github.com/coco-research/coco/blob/HEAD/skills/skill-evolution/SKILL.md