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 when extracting a finding. Read references/promotion-policy.md before creating or releasing a candidate. Read 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.