/skill-evolve

name: skill-evolve
description: Refine, create, or retire your own skills based on recurring patterns from past sessions
tools: [bash, read_file, write_file, edit_file, sub_agent]
core: true
origin: creator

Skill Evolution

You are evolving your own skills. This is the only skill that modifies other skills. Treat every cycle with care — what you write here shapes how every future yoyo session behaves.

When to use

**Only when invoked via `scripts/skill_evolve.sh`.** The harness gates on session count and cooldown; it sets up the audit-log worktree and composes the prompt. Do not run this skill opportunistically from inside a normal evolve session.

Hard rules (read first, every cycle)

These three rules cannot be violated. Each cycle either honors all three or writes a `refused` event and exits.

HARD RULE #1 — Eligible targets only (allow-list)

You may **refine, deprecate, or retire** only skills whose frontmatter declares **`origin: yoyo`**. Any other value, OR a missing `origin:` field, means the skill is off-limits. This is an allow-list: silence means "don't touch."

Three categories of skill exist:

| `origin:` value | Source | You may edit? | |---|---|---| | `creator` | Written by the human creator (Yuanhao or a fork creator) | **Never** | | `yoyo` | Written by yoyo (this skill, or in past evolutions like `social`/`family`/`release`) | Yes — eligible | | `marketplace`, `gh:user/repo`, etc. | Installed from a third party | **Never** — upstream owns it | | (missing) | Unknown provenance | **Never** (default-safe) |

Today the eligible set is exactly the skills whose SKILL.md declares `origin: yoyo`:

• `social`
• `family`
• `release`
• any skill you previously spawned (which inherit `origin: yoyo` from the Create template)

**Defense in depth**: if a skill has `core: true` set, refuse even if `origin: yoyo` is also somehow present. The two flags should never co-occur, but the conservative move is to honor the deny-flag.

If a recurring pattern suggests a non-eligible skill needs change (e.g., a core skill, or an installed marketplace skill), do not edit it. Instead, write a learning to `memory/learnings.jsonl` with `source: "skill-evolve"` and a clear pattern_key, and append a `meta-suggestion` block to `skills/_journal.md`. The human creator will decide.

HARD RULE #2 — Never edit yourself

You must **NEVER** modify `skills/skill-evolve/SKILL.md`. If you believe this skill needs improvement, append a `meta-suggestion` block to `skills/_journal.md` and stop:

## evt-XXXX meta-suggestion
- ts: <ISO8601>
- target: skills/skill-evolve/SKILL.md
- suggestion: <one-paragraph description>

HARD RULE #3 — One mutation per cycle

Each cycle produces **exactly one** of:

• a refinement diff (one skill, ≤30 added lines, ≤15 removed)
• a candidate skill draft (one new directory)
• a retirement (one `git mv` to `skills_attic/`, plus the pointer cleanup in step 5 → Retire, which is part of the same mutation, not a second one)
• a `NO-OP` event (you found nothing worth doing)

If you find yourself wanting to do two things, pick the one with the strongest evidence and write the second to `memory/learnings.jsonl` for next cycle.

HARD RULE #4 — Refine and Create events must declare an expected outcome

Every `refine` and `create` event in `skills/_journal.md` MUST include an `expected:` line — a freeform prose commitment naming (a) a concrete observable signal that should change, (b) a horizon (e.g. "within ~5 sessions" or "by next cycle"), and (c) a fallback move if the prediction does not hold.

If you cannot articulate all three, the edit is not justified by evidence: NO-OP the cycle instead of committing a refine/create without an `expected:` line. This is decision-observability discipline (paper: arxiv 2604.25850) at the cognitive layer — there is no validator, but a future cycle re-reads the line as informal evidence and a human reads it as an audit trail.

`expected:` is **forbidden** on `retire`, `revive`, `meta-suggestion`, `refused`, `NO-OP`, and `init` events (they do not ship a behavioral change, so there is nothing to predict).

The body of the line is freeform prose. See "Step 7 — append the event" for the template position and worked examples; see "What an `expected:` line must do (and must not be)" later in this document for the anti-patterns to refuse.

Glossary

• **session** — one run of `scripts/evolve.sh` (the main evolution loop). There are ~3 per day.
• **cycle** — one run of *this* skill, invoked from `scripts/skill_evolve.sh`. Cycles are gated by a session-counter and a 24h cooldown, so they fire roughly once every 5+ sessions.
• **real cycle** — a cycle that produced one of `refine | create | retire | meta-suggestion`. Excludes `init`, `refused`, and `NO-OP`.

Bootstrap (first three real cycles only)

We are mid-life, not at Day 1, so the cold-start rules from the original design are softened — but the first three real cycles still get extra constraints to let the loop settle.

To know which cycle you are in, count the non-init, non-refused, non-NO-OP entries in `skills/_journal.md`:

cycle_index=$(grep -E '^## .*evt-[0-9]+ (refine|create|retire|meta-suggestion)' skills/_journal.md | wc -l)
# cycle_index=0 → this is the first real cycle
# cycle_index=1 → second
# cycle_index=2 → third
# cycle_index>=3 → full lifecycle unlocked

• **First real cycle** (`cycle_index == 0`): only `refine` or `NO-OP` allowed. Do not create. Do not retire.
• **Second real cycle** (`cycle_index == 1`): `refine`, `create`, or `NO-OP`. No retirement yet.
• **Third real cycle onward** (`cycle_index >= 2`): full lifecycle unlocked (`refine` | `create` | `retire` | `NO-OP`).

(Note: the gate-counter at `.skill_evolve_counter` is unrelated to this — it just controls when the cycle fires, not what it can do.)

Lifecycle states

Every eligible skill carries a `status:` field in its frontmatter. Five states. **Important**: yoagent always loads