Codex Skill Admin

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" 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.

System skills are preserved by default. Use --include-system only when the user explicitly asks to consider system skills too.

The Codex desktop Skills tab count is a total discovered skill count. It is expected to stay unchanged after disabling skills. Treat enabledCount and availableSkillCount as the token-load success metrics.

Usage Evidence

The audit is intentionally conservative:

• Count actual SKILL.md reads from recent Codex session tool calls.
• Count OMO dynamic session fingerprints that include SKILL.md.
• Count usage as distinct evidence source/session files, so repeated reads inside one session do not inflate usageCount.
• Ignore always-loaded "Available skills" lists, because they are not usage.

This is local evidence, not the product Profile page's server-side analytics.

If the same skill appears through multiple equivalent paths, set path aliases before auditing:

export CODEX_SKILL_ADMIN_PATH_ALIASES="/old/root=/new/root"

Use the platform path separator for multiple aliases.

Verification

After an apply run:

1. Run verify --cwd "$PWD".
2. Confirm enabledCount dropped and target skills appear in list --force-reload --disabled.
3. Confirm availableSkillCount dropped versus the pre-run count when disabled skills were previously prompt-visible.
4. Ignore the desktop UI tab count for token savings; it counts total discovered skills, including disabled ones.
5. If the result is wrong, run restore --backup-dir <backupDir> using the backup path from the apply output.

Backup files include local skill paths and usage evidence. Treat them as private machine-local diagnostics.

Restore

Restore a previous disable run:

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" restore --backup-dir "${CODEX_HOME:-$HOME/.codex}/backup/skill-disable-unused-YYYYMMDD-HHMMSS"

Direct Set

Use set for specific skill toggles only after listing or otherwise confirming the target name/path:

python3 "$SKILL_DIR/scripts/codex_skill_admin.py" set --name codex-skill-admin --no-enabled
python3 "$SKILL_DIR/scripts/codex_skill_admin.py" set --name codex-skill-admin --no-enabled --apply

Without --apply, set prints a dry run and writes nothing.

Manual Protocol Notes

Read references/app-server-protocol.md only when the script fails or the Codex app-server protocol changes.