# Evolve Skill Library

> Maintain a central personal Codex skill library across workspaces by capturing reusable project findings, triaging candidates, initializing new skills, preparing updates to stable skills, adding evaluations, releasing versions, installing validated packages, and reporting library health. Use when the user asks to preserve, harvest, distill, accumulate, maintain, improve, version, test, install, or publish reusable skills or lessons from completed work.

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

---


# Evolve Skill Library

Turn project experience into validated, versioned capability without polluting stable skills with untested notes.

## Locate the workbench

Resolve the central repository in this order:

1. an explicit user-provided path;
2. `CODEX_SKILL_WORKBENCH`;
3. `%USERPROFILE%/Desktop/codex-skill-workbench` on Windows;
4. `~/Desktop/codex-skill-workbench` elsewhere.

Confirm the repository contains `catalog.yaml`, `skills/`, `incubator/`, `inbox/`, `evals/`, and `tooling/` before changing it.

## Workflow

1. Inspect the completed task, changed files, verification output, failures, and corrections.
2. Extract only reusable procedures, deterministic scripts, references, templates, or acceptance checks.
3. Capture raw findings in `inbox/` with `scripts/capture-finding.py`. Do not edit a stable skill merely to record an unverified idea.
4. Triage each finding as: update an existing skill, create a new skill, retain as evidence, merge with another finding, or discard.
5. For a new skill, run `scripts/bootstrap-candidate.py`. For an existing stable skill, run `tooling/begin-skill-update.ps1` from the workbench.
6. Implement the candidate in `incubator/<skill-name>/`. Keep the package self-contained and concise.
7. Add or update realistic cases under `evals/<skill-name>/`. Test every bundled executable with a representative fixture.
8. Run repository validation and evaluation tooling.
9. Release the validated candidate with a semantic version, then install the stable copy.
10. Commit source, catalog, evaluations, and relevant inbox state together.

## Promotion threshold

Promote a finding when at least one condition holds:

- the same procedure was needed more than once;
- a deterministic script replaces repeated fragile code;
- a failure mode is likely to recur and has a clear verification check;
- the pattern materially improves quality, speed, or consistency across workspaces;
- the workflow contains domain knowledge that a fresh agent would not reliably infer.

Keep one-off project facts in project documentation or the inbox rather than a stable skill.

## Use bundled resources

- Run `scripts/capture-finding.py` to create a structured inbox entry.
- Run `scripts/library-status.py` to report released skills, incubator packages, inbox candidates, and Git state.
- Run `scripts/bootstrap-candidate.py` to initialize a new candidate through the system `skill-creator` initializer.

Read [references/finding-schema.md](references/finding-schema.md) when extracting a finding. Read [references/promotion-policy.md](references/promotion-policy.md) before creating or releasing a candidate. Read [references/cross-workspace-workflow.md](references/cross-workspace-workflow.md) when integrating contributions from multiple project directories.

## Integrity rules

- Treat the workbench as source of truth and `%USERPROFILE%/.codex/skills` as an installed target.
- Never maintain the installed copy by hand.
- Keep evaluation files and generated runs outside installable skill packages.
- Keep frontmatter limited to `name` and `description`; keep versions in `catalog.yaml`.
- Create new skills with the system `init_skill.py` helper.
- Regenerate or verify `agents/openai.yaml` after material trigger or scope changes.
- Validate before release, evaluate before stable status, and install only cataloged stable packages.
- Preserve project-specific evidence without copying unrelated project implementation into a general skill.

## Completion report

Report:

- findings captured or resolved;
- candidates created or updated;
- validation and evaluation results;
- released name and version;
- installed destination and package hash;
- Git commit or remaining uncommitted work.