codex-skill-admin

name	codex-skill-admin
description	Codex-only skill administration for auditing, enabling, disabling, restoring, and verifying local Codex skills. Use when the user asks to manage Codex skills, reduce skill token load, close unused skills without uninstalling them, restore disabled skills, inspect current skill visibility, or automate skill enablement through Codex's official app-server protocol.

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.