codex-skill-admin
Skill787 starsChanged 4 months agoMITView on GitHub
核对、启停或恢复Codex Skill可见性与加载开销;不卸载插件。
In this repository20 other files it gives its agents.
- AGENTS.mdAGENTS.md
- codex-cli-model-bridgeSkill
- codex-doctorSkill
- codex-external-handoffSkill
- codex-handoffSkill
- codex-image-genSkill
- codex-model-routing-teamSkill
- codex-theme-studioSkill
- enterprise-clone-builderSkill
- gpt56-sol-pro-consultSkill
- html-expressSkill
- leadbookSkill
- light-plan-and-workSkill
- scholar-stickersSkill
- skill-open-sourcerSkill
- web-clipperSkill
- wechat-article-searchSkill
- wechat-stylerSkill
- workbuddy-cli-model-bridgeSkill
- wxmp-article-harvesterSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. About 0 are common, 5 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Use Codex's official skill config API.
- Distinctive: line 12
Use the bundled script for normal work:
- Very specific: line 41
Run list to get the current total, enabled, and disabled counts.
- Very specific: line 42
Run audit-unused --days 30 to inspect high-confidence recent usage.
- Very specific: line 44
Run disable-unused --days 30 without --apply and inspect the dry-run output.
- Very specific: line 45
If the user asked to close unused or low-frequency skills, run disable-unused --apply.
- Very specific: line 46
Verify with verify, or with list --force-reload plus prompt-count.
- Distinctive: line 61
Keep failed, unmatched, unknown, and unsupported read intents in separate audit fields.
- Distinctive: line 70
If the same skill appears through multiple equivalent paths, set path aliases before auditing:
- Distinctive: line 76
Use the platform path separator for multiple aliases.
- Distinctive: line 80
After an apply run:
- Very specific: line 86
If the result is wrong, run restore --backup-dir <backupDir> using the backup path from the apply output.
- Very specific: line 104
Use set for specific skill toggles only after listing or otherwise confirming the target name/path:
- Very specific: line 115
Read references/app-server-protocol.md only when the script fails or the Codex app-server protocol changes.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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/listskills/config/write
It saves apply-mode backups under:
${CODEX_HOME:-$HOME/.codex}/backup/skill-disable-unused-YYYYMMDD-HHMMSS/Workflow
- Run
listto get the current total, enabled, and disabled counts. - Run
audit-unused --days 30to inspect high-confidence recent usage. - Optionally add
--max-uses Nto include low-frequency skills. Example:--days 10 --max-uses 2targets enabled skills used in at most 2 distinct recent session/source files. - Run
disable-unused --days 30without--applyand inspect the dry-run output. - If the user asked to close unused or low-frequency skills, run
disable-unused --apply. - Verify with
verify, or withlist --force-reloadplusprompt-count. - 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 a read only when a
function_callorcustom_tool_callcontains an actual file-read operation.functions.execwrappers are parsed for read commands such ascatandsed; structured read tools are parsed from their path input. - Require a matching tool result. A result marked successful, with exit code 0, or with non-empty output counts as
success; a failed result never counts as usage. - Filter each event timestamp by the requested window. A recent session file does not make an old event recent. Missing or unparseable timestamps are reported as
unknownand do not count as usage. - Count
usageCountas distinct evidence session/source files. Repeated successful reads in one session increaseevidenceCount, but do not inflateusageCount. - Keep failed, unmatched, unknown, and unsupported read intents in separate audit fields. They protect the affected enabled Skill from becoming a disable candidate until the evidence is classifiable.
- Ignore prose mentions,
SKILL.mdpaths in general audit/available-Skills listings, and OMO fingerprints without structured tool events. OMO events are counted only when they retain the same call/result evidence.
This is local evidence, not the product Profile page's server-side analytics.
audit-unused and disable-unused accept repeatable --exclude-session PATH arguments. They also read CODEX_SKILL_ADMIN_SESSION, CODEX_SESSION_FILE, CODEX_SESSION_PATH, CODEX_SESSION_ID, and CODEX_THREAD_ID when set, so the current audit session can be excluded without copying private session data. The default --exclude-current-audit setting ignores calls that invoke this script's own audit-unused or disable-unused command; use --no-exclude-current-audit only when inspecting that invocation itself. An excluded session is reported in excludedSessionCount and does not contribute evidence.
The audit JSON keeps the existing usedEnabled, disableCandidates, usageCount, and evidenceCount fields. It additionally reports the per-path readIntent, unknown, failed, and unsupported evidence, plus uncertainEnabled, rawReadIntentSkillPathCount, rawUnknownSkillPathCount, rawFailedSkillPathCount, unsupportedEvidenceCount, outsideWindowCount, and missingTimestampCount. disableCandidates contains enabled Skills with no proven usage and no uncertain read intent; an uncertain or unsupported record is never silently treated as zero use.
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:
- Run
verify --cwd "$PWD". - Confirm
enabledCountdropped and target skills appear inlist --force-reload --disabled. - Confirm
availableSkillCountdropped versus the pre-run count when disabled skills were previously prompt-visible. - Ignore the desktop UI tab count for token savings; it counts total discovered skills, including disabled ones.
- 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 --applyWithout --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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

