myco:myco-skill-lifecycle git:20260625.1d84427A

Immutable. This exact content is served forever at /api/v1/blob/89d748614d38e74f.

---
name: myco:myco-skill-lifecycle
description: >-
  Use this skill when running or debugging the Myco skill lifecycle end to end:
  identifying candidates from vault knowledge, curating them through approval,
  generating `SKILL.md` files, and evolving existing skills as the vault grows.
  It applies to `skill-survey`, `skill-generate`, `skill-evolve`, and any work
  on the Skills dashboard, including cases where candidates appear but no
  skills materialize, surveys return zero results, or generated skills need
  refreshes.
managed_by: myco
user-invocable: true
allowed-tools:
  - Read
  - Edit
  - Write
  - Bash
  - Grep
  - Glob
---

# Myco Skill Lifecycle: Survey → Approve → Generate → Evolve

The skill lifecycle is a four-phase pipeline that turns raw vault knowledge into structured, reusable SKILL.md files on disk.

## Pipeline Overview

```
vault spores → [Survey] → candidates → [Approve] → approved → [Generate] → SKILL.md files → [Evolve] → updated SKILL.md
```

- **Survey** (`skill-survey`): Scans vault spores for clusters of repeated knowledge worth encoding as skills. Produces `skill_candidates` with status `identified`.
- **Approve** (Skills dashboard): Human review step. Candidates must reach `approved` status before skill-generate will act on them.
- **Generate** (`skill-generate`): Writes SKILL.md files to `.agents/skills/<name>/` from approved candidates.
- **Evolve** (`skill-evolve`): Identifies STALE skills and rewrites them with new vault knowledge.

## Scheduling Defaults (Asymmetric by Design)

- `skill-survey`: `enabled: true` — auto-runs during idle. Passive discovery; no mutation.
- `skill-generate`: `enabled: false` — requires explicit opt-in via Agent Tasks page.
- `skill-evolve`: `enabled: false` — requires explicit opt-in via Agent Tasks page.

This asymmetry is intentional: let the system build candidate evidence passively, but keep the generative and mutative steps user-driven until the user trusts the output quality.

## Phase 1: Survey

**Task:** `skill-survey` | **Default:** auto-enabled

Survey searches vault spores and sessions for recurring knowledge clusters. A good candidate captures a procedure or pattern a developer would benefit from knowing in advance — not a description of activity.

**Diagnosing zero results:**
- Vault needs a minimum evidence threshold (~20+ active spores from multiple sessions)
- Check that `skill-survey` is enabled and has a recent `Last Run` (Agent Tasks page)
- If candidates appear but all are `dismissed`, review dismissal rationale — thresholds may need tuning

## Phase 2: Approve

**Tool:** Skills dashboard (`/skills` route) | **Manual step**

Review the `identified` candidate pool:
1. Read the topic and rationale — confirm it captures a real, reusable procedure
2. Rename if the topic is vague (names become directory names, so clarity matters)
3. Set `approved` to queue for generation, or `dismissed` to remove

A task run with zero approved candidates is a no-op for skill-generate and skill-evolve.

## Phase 3: Generate

**Task:** `skill-generate` | **Default:** disabled

Writes SKILL.md files from approved candidates. Each write goes through the `vault_write_skill` quality gate:

**Gate enforces:**
- YAML frontmatter with all required fields: `name` (myco: prefix), `description`, `managed_by: myco`, `user-invocable`, `allowed-tools`
- `allowed-tools` must contain **Claude Code tool names only** — `vault_*` names cause immediate rejection with a clear error message
- `managed_by: myco`
- ≤500 lines

**Valid allowed-tools values:** `Read, Edit, Write, Bash, Grep, Glob`

**Invalid allowed-tools values (rejected):** Any `vault_*` name — vault_create_spore, vault_search_semantic, vault_write_skill, vault_spores, vault_state, etc.

**Frontmatter regression risk:** When skill-generate rewrites an existing skill mid-session (correction pass), it regenerates frontmatter from scratch. Fields like `user-invocable` and `allowed-tools` can be silently dropped if the prompt omits them. The quality gate enforces field presence — but not that values are correct. Verify `allowed-tools` values after any generate run that touches existing skills.

## Phase 4: Evolve

**Task:** `skill-evolve` | **Default:** disabled

Compares active skills against recent vault knowledge to find STALE skills, then rewrites them.

### Bias Toward CURRENT

**The evolve phase defaults to CURRENT.** STALE requires a *substantive factual change* — new behavior, a fixed bug, a changed API, or a discovered gotcha that the current skill gets wrong. Cosmetic phrasing differences alone are not sufficient.

Without this bar, LLM rewrites create a regression loop:
- Descriptions get shorter → triggering coverage degrades silently
- Detailed sections get consolidated → diagnostic value is lost (e.g., machine_id regression diagnosis, budget sizing math removed)
- Phrasing becomes generic → precision is lost

The rewritten skill passes validation but is structurally degraded. If in doubt, classify CURRENT.

### Evolve Constraints (Both Must Be Satisfied)

When rewriting a STALE skill:

1. **Do NOT shorten the description.** The description controls triggering coverage. Only change it if the trigger condition is factually wrong — never condense for brevity.
2. **Do NOT restructure correct sections.** Only modify the specific sections affected by the new knowledge. Preserve accurate content verbatim.

### Evolve Phase: allowed-tools Contamination Risk

`skill-evolve.yaml` instructs the LLM to "preserve ALL existing frontmatter fields." This rule faithfully copies errors — if the source skill already has vault_* names in `allowed-tools`, the preserve instruction propagates them into every subsequent evolution. The preservation rule is not a validator.

**Fix:** Always verify that `allowed-tools` contains only Claude Code tool names before writing — even when the frontmatter was copied from the prior version. The vault_write_skill gate will catch it, but it's better to fix proactively.

### Budget Sizing for skill-evolve

Each skill rewrite costs ~8–10 agent turns (read current skill + 2–3 knowledge searches + write). Budget must be sized for worst-case STALE count:

```
Assess phase: ~1.5 turns/skill × (number of active skills)
Evolve phase: ~10 turns/rewrite × (number of STALE skills)
```

With 3 STALE skills:
- Assess: ~13 turns | Evolve: ~30 turns | Total: ~43 turns

**Recommended task configuration:**
```yaml
maxTurns: 60          # sum of phase budgets (20 assess + 35 evolve + 5 overhead)
timeoutSeconds: 1800  # 3 rewrites × ~5 min + assess time
```

**Phase budgets:**
```yaml
assess phase: maxTurns: 20
evolve phase: maxTurns: 35
```

**Silent timeout failure mode:** If `maxTurns` is too low, the run ends "normally" but stops mid-rewrite with no error message pointing to the budget constraint. The failure is invisible unless you check whether the expected STALE skills were actually rewritten.

## Common Issues

### Candidates present but no skills appear
- Verify candidates have `approved` status (not just `identified`)
- Confirm skill-generate has been enabled and run for the candidate
- Check skill-generate run logs for quality gate rejections (most common: missing frontmatter fields, vault_* in allowed-tools)

### Skills aren't triggered by Claude Code
- Check the frontmatter `description` — is it specific enough to match the current context?
- Confirm `user-invocable: true` is present
- Confirm `.agents/skills/<name>/SKILL.md` exists on disk

### skill-evolve degraded a skill on rewrite
- Root cause: STALE classification had no minimum bar; cosmetic phrasing triggered a rewrite
- Check for shortened description, consolidated sections, or generic phrasing in the evolved version
- Restore from previous generation via vault_skill_records lineage if needed
- Verify skill-evolve.yaml has bias-toward-CURRENT directive and substantive-change threshold

### vault_write_skill rejects allowed-tools
- The error names the failing field
- Replace all vault_* names with Claude Code tools: `Read, Edit, Write, Bash, Grep, Glob`
- Check whether contamination propagated from a prior version via preserve-frontmatter