skill-evolver

English | 简体中文

Skill-first workflow for evaluating and iterating a local Codex skill repository.

skill-evolver is a small suite of Codex Meta-skills backed by an npm CLI. The skills let Codex generate eval cases, score the current skill, identify a gap, make a minimal edit, and compare the candidate against the baseline. The CLI owns the engineering state machine; the skills own the AI work.

Published Entrypoints

• Skills collection: https://skills.sh/jax-ho/skill-evolver
• Source repository: https://github.com/jax-ho/skill-evolver
• CLI package: https://www.npmjs.com/package/@jaxho/skill-evolver
• Current CLI version: @jaxho/skill-evolver@0.1.1

Skill-first User Path

Install the Skill Evolver collection into Codex first:

npx --registry=https://registry.npmjs.org skills add jax-ho/skill-evolver --skill '*'

Then open a target skill repository that is a clean git repo and contains SKILL.md, and ask Codex to use skill-evolver. Codex runtime resolves the orchestrator and worker skills from the installed collection.

The orchestrator checks whether the skill-evolver CLI is available. If it is missing, the orchestrator attempts to install it from npm:

npm install -g @jaxho/skill-evolver --registry=https://registry.npmjs.org

After the CLI is available, the orchestrator runs the normal loop:

skill-evolver status
skill-evolver init
skill-evolver run

The user should not need to manually run the CLI for the normal path. Manual CLI commands are useful for debugging, automation, and release smoke tests.

What Gets Installed

The collection contains one orchestrator skill and five worker skills:

Skill	Role
skill-evolver	Orchestrates the CLI loop and delegates action requests.
skill-evolver-case-builder	Generates categorized eval case proposals.
skill-evolver-answer-runner	Produces baseline or candidate answers for cases.
skill-evolver-answer-judge	Writes judgment artifacts used by the CLI to build reports.
skill-evolver-gap-analyzer	Selects one actionable issue from eval/compare reports.
skill-evolver-skill-editor	Makes a minimal edit to the target skill.

The CLI writes all state under .skill-evolver/ inside the target skill repository. The target repository's git history remains the source of truth for versioning.

Target Repo Requirements

Run skill-evolver from the root of a target skill repository:

• The current directory must be a git repository.
• The current directory must contain SKILL.md.
• skill-evolver init requires a clean git worktree.

skill-evolver init initializes project state only; it does not validate worker skill installation paths. Worker skill resolution belongs to Codex runtime. Use skill-evolver doctor skills only as a best-effort local file path diagnostic when debugging a local environment.

CLI Commands

Manual command reference:

skill-evolver --help
skill-evolver init
skill-evolver status
skill-evolver run
skill-evolver doctor skills

skill-evolver run prints JSON action requests when a worker skill must act. The orchestrator skill reads those requests, invokes the named worker, and then runs the request's next_command.

Single-skill Fallback

If you need to install one skill at a time, use the same source with an explicit skill name:

npx --registry=https://registry.npmjs.org skills add jax-ho/skill-evolver --skill skill-evolver
npx --registry=https://registry.npmjs.org skills add jax-ho/skill-evolver --skill skill-evolver-case-builder
npx --registry=https://registry.npmjs.org skills add jax-ho/skill-evolver --skill skill-evolver-answer-runner
npx --registry=https://registry.npmjs.org skills add jax-ho/skill-evolver --skill skill-evolver-answer-judge
npx --registry=https://registry.npmjs.org skills add jax-ho/skill-evolver --skill skill-evolver-gap-analyzer
npx --registry=https://registry.npmjs.org skills add jax-ho/skill-evolver --skill skill-evolver-skill-editor

Local Source Checkout

From this repository:

bun install
bun run build
node dist/cli.js --help

For local source dogfood, prefer installing the public collection first, then testing the built CLI from this checkout.

Useful validation commands:

bun run build
bun run typecheck
bun test
node dist/cli.js --help

Release Notes

0.1.1 is the current public patch release. It fixes the Skill-first boundary so skill-evolver init no longer fails when the CLI cannot locate worker skills by local filesystem path. doctor skills remains available as a diagnostic and points users to the public collection install command.