Codex Skill Admin

Use Codex's official skill config API. Do not edit SKILL.md frontmatter to disable a skill, and do not uninstall plugins unless the user explicitly asks for uninstall.

Quick Start

Use the bundled script for normal work:

SKILL_DIR="${CODEX_SKILL_ADMIN_DIR:-$HOME/.agents/skills/codex-skill-admin}"
if [ ! -d "$SKILL_DIR" ]; then
  SKILL_DIR="${CODEX_HOME:-$HOME/.codex}/skills/codex-skill-admin"
fi
python3 "$SKILL_DIR/scripts/codex_skill_admin.py" list --cwd "$PWD"
python3 "$SKILL_DIR/scripts/codex_skill_admin.py" audit-unused --cwd "$PWD" --days 30
python3 "$SKILL_DIR/scripts/codex_skill_admin.py" disable-unused --cwd "$PWD" --days 30
python3 "$SKILL_DIR/scripts/codex_skill_admin.py" disable-unused --cwd "$PWD" --days 30 --apply
python3 "$SKILL_DIR/scripts/codex_skill_admin.py" disable-unused --cwd "$PWD" --days 10 --max-uses 2
python3 "$SKILL_DIR/scripts/codex_skill_admin.py" audit-unused --cwd "$PWD" --days 30 --exclude-session /path/to/session.jsonl
python3 "$SKILL_DIR/scripts/codex_skill_admin.py" verify --cwd "$PWD"

The script starts a temporary localhost codex app-server, calls:

• skills/list
• skills/config/write

It saves apply-mode backups under:

${CODEX_HOME:-$HOME/.codex}/backup/skill-disable-unused-YYYYMMDD-HHMMSS/

Workflow

1. Run list to get the current total, enabled, and disabled counts.
2. Run audit-unused --days 30 to inspect high-confidence recent usage.
3. Optionally add --max-uses N to include low-frequency skills. Example: --days 10 --max-uses 2 targets enabled skills used in at most 2 distinct recent session/source files.
4. Run disable-unused --days 30 without --apply and inspect the dry-run output.
5. If the user asked to close unused or low-frequency skills, run disable-unused --apply.
6. Verify with verify, or with list --force-reload plus prompt-count.
7. Report counts, backup path, threshold parameters, and any limits of the usage evidence.