# Evo

> AI self-evolution — scan project, pin baselines, learn from failures, restore with wisdom. Use when the user wants to: understand a project, pin a clean baseline, restore context, learn from a failed or successful approach, or inject project knowledge. Examples: "scan this project", "pin this baseline", "restore", "learn from this failure", "remember that payment uses Redis"

- Skill: `lxiny-zy/evo` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add lxiny-zy/evo`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lxiny-zy/evo/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Lxiny-zy (https://skillmd.com/u/lxiny-zy)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/lxiny-zy/evo

---


# /evo — AI Self-Evolution

Parse arguments then route to the correct mode file. Each mode file contains full instructions.

## Argument Parsing

```
/evo                    → mode: scan, depth: standard (auto: full/incremental/self-test)
/evo deep               → mode: scan, depth: deep
/evo help               → print the command quick reference below, then stop (no scan)

/evo pin                → mode: anchor, ANCHOR_SUB=create, ANCHOR_NAME=(empty)
/evo pin <name>         → mode: anchor, ANCHOR_SUB=create, ANCHOR_NAME=name
/evo pin <name> <desc>  → mode: anchor, ANCHOR_SUB=create, ANCHOR_NAME=name, ANCHOR_DESC=rest
/evo pin list           → mode: anchor, ANCHOR_SUB=list
/evo pin diff [name]    → mode: anchor, ANCHOR_SUB=diff, ANCHOR_NAME=name or empty
/evo pin rm <name>      → mode: anchor, ANCHOR_SUB=delete, ANCHOR_NAME=name

/evo back               → mode: restore, ANCHOR_NAME=(empty)
/evo back <name>        → mode: restore, ANCHOR_NAME=name
/evo back --no-learn    → mode: restore, NO_LEARN=yes (flag works with or without a name)

/evo learn              → mode: learn, DESCRIPTION=(empty)
/evo learn <desc>       → mode: learn, DESCRIPTION=rest of args
/evo learn + <knowledge>→ mode: teach, KNOWLEDGE=rest after "+"

/evo st | status        → run: bash scripts/snap.sh status (then stop)
```

**Rules (first match wins):**
0. First arg is `help`, `--help`, `-h`, or `?` → print the quick reference below, then stop
1. First arg is `pin` → anchor mode
   - Second arg `list` or `ls` → anchor/list
   - Second arg `diff` → anchor/diff (third arg = name, optional)
   - Second arg `rm` → anchor/delete (third arg = name, REQUIRED)
   - Otherwise → anchor/create (second arg = name if present, rest = description)
2. First arg is `back` → restore
   - Strip `--no-learn` from anywhere in the remaining args → `NO_LEARN=yes`
   - What remains (if anything) = `ANCHOR_NAME`; empty means restore mode asks or defaults
3. First arg is `learn`:
   - If second arg is `+` → **teach** mode (rest after `+` = KNOWLEDGE)
   - Otherwise → **learn** mode (rest = DESCRIPTION)
4. First arg is `st` or `status` → status (run script, done)
5. First arg is `deep` → scan with deep depth
6. No args or anything else → scan with standard depth

## Quick Reference (for `/evo help`)

```
/evo                     Scan project (auto: full / incremental / self-test)
/evo deep                Deep scan with per-module analysis
/evo pin [name [desc]]   Freeze current understanding (+code) as a baseline.
                         Empty name → auto-named baseline-<timestamp>
/evo pin list            List pinned baselines
/evo pin diff [name]     Cognitive diff: current snapshot vs a pin
/evo pin rm <name>       Delete a pin
/evo back [name]         Auto-capture lesson, then restore a baseline (+wisdom)
/evo back --no-learn     Restore without capturing a lesson first
/evo learn [desc]        Extract a lesson from the current conversation
/evo learn + <text>      Inject knowledge the AI cannot discover from code
/evo st                  Status: version, snapshot age, pins, lessons, include tier
```

## Routing

After determining the mode, **read the corresponding mode file** and follow its instructions exactly:

| Mode | File to read | Key vars to substitute |
|------|-------------|----------------------|
| scan | `modes/scan.md` | `{{DEPTH}}` = standard \| deep |
| restore | `modes/restore.md` | `{{ANCHOR_NAME}}` = pin name or empty, `{{NO_LEARN}}` = yes or empty |
| learn | `modes/learn.md` | `{{DESCRIPTION}}` = user's description or empty, `{{QUIET}}` = empty |
| teach | `modes/teach.md` | `{{KNOWLEDGE}}` = user's knowledge text |
| anchor | `modes/anchor.md` | `{{ANCHOR_SUB}}`, `{{ANCHOR_NAME}}`, `{{ANCHOR_DESC}}` |

**Read the mode file**, substitute any `{{VARIABLES}}`, then execute the instructions within it.

Note: `restore` mode reads `modes/learn.md` itself (with `{{QUIET}}` = `yes`) to auto-capture a
lesson before restoring. `scan` mode similarly delegates to `modes/examine.md` for self-tests.

## Mechanical Operations

All git queries, file counting, meta.json I/O, token estimation, and status display are handled by `scripts/snap.sh`. Call it via Bash:

```bash
bash scripts/snap.sh <command> [args...]
```

Key commands: `git_info`, `has_snapshot`, `meta_read`, `meta_write`, `ensure_dirs`, `status`, `count_source_files`, `count_constraints`, `count_lessons`, `estimate_tokens`, `doc_header`, `include_block`, `anchor_create`, `anchor_list`, `anchor_get`, `anchor_delete`, `anchor_exists`, `anchor_active`, `anchor_set_active`, `anchor_resolve`, `anchor_picker`, `anchor_count`, `anchor_doc_list`, `code_capture`, `code_ref_exists`, `code_archive`, `code_restore`, `code_diff_stat`, `code_changed_files`, `code_missing_paths`.

## Code State

Pins freeze both understanding and the code it describes. Code lives in `refs/evo/pins/<safe_name>`
(built by `git stash create`, so uncommitted work is included and the working tree is never
touched). Restoring is always the user's explicit choice — see `modes/restore.md` Phase 2.5.

Two limits to respect and surface, never paper over:
- **Untracked files are not captured.** `git stash create` ignores them. `anchor_create` reports
  the count so the user can `git add` first.
- **`git gc --prune` with an aggressive expiry can still drop refs**, though `refs/evo/*` protects
  against normal gc. `code_ref_exists` returns "no" in that case; treat the pin as docs-only.

## Guidelines

- **Never** include conversational filler in generated documents. Every line conveys information.
- **Always** include file path references (e.g., `src/auth/middleware.ts:42`) in architecture docs.
- **Prefer** project-relative paths over absolute paths.
- Launch agents **in a single message** for maximum parallelism.
- Token estimates: `character_count / 4`.
- For non-git projects, skip git features gracefully.
- `.claude/snapshot/` should be in `.gitignore` unless user explicitly wants to version-control it.