agent-skill-description-optimizer: Instructions file for Codex

AGENTS.md

Agent execution contract for this repo. Human explanation is canonical in README.md; reference it rather than duplicating it, and keep operator narration out of this file.

Purpose

Optimize a skill's description: frontmatter (the text that gates skill invocation). Evaluation and improvement both run through claude -p, so no ANTHROPIC_API_KEY is required. Entry point: optimize_description_v2.py (shim over the src/skill_optimizer/ package). Runtime: Python standard library only; interpreter floor Python 3.14+.

Invoke

Canonical cross-repo call (project-targeted uv pins the 3.14 interpreter):

uv run --project /ABSOLUTE/PATH/TO/agent-skill-description-optimizer \
  optimize-skill-description \
  --eval-set /ABSOLUTE/PATH/TO/eval.json \
  --skill-path /ABSOLUTE/PATH/TO/skill \
  --model MODEL_ID --report none --max-iterations 5 --verbose

1. Pass --report none for every headless run: stdout stays a single JSON object and no browser opens. Mandatory for a stdout-parsing caller.
2. Parse stdout as JSON; read best_description.
3. Apply it to the skill's SKILL.md frontmatter, or pass --write to apply it automatically (backs up to SKILL.md.bak; refuses an over---max-desc-chars winner).
4. Treat stderr as progress only — tail it, never parse it.

Equivalent in-repo forms: uv run optimize-skill-description ..., uv run python -m skill_optimizer ..., uv run python optimize_description_v2.py .... Direct execution requires a named 3.14+ interpreter (python3.14 optimize_description_v2.py ...). Full flag list: README.md.

Preconditions

Checked at startup, before any token spend or artifact write. Each failure exits 1 with a one-line stderr message and empty stdout (a stdout-parsing caller fails legibly, never on a JSONDecodeError or mid-run traceback):

Condition	Failure message prefix
claude on PATH and executable	claude CLI not found or not executable:
Interpreter is Python >=3.14	Requires Python >=3.14;
Eval set well-formed	Invalid eval set:
Holdout split satisfiable	Invalid holdout split:
--out and --results-dir not both set	--out and --results-dir are mutually exclusive
--iterations in [0, 50]	--iterations must be between 0 and 50