codex-skill-admin

Codex 技能管理

使用 Codex 官方技能配置 API。请勿编辑 SKILL.md frontmatter 来停用技能，也不要卸载插件，除非用户明确要求卸载。

快速开始

日常操作请使用随附脚本：

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"

该脚本会启动一个临时的本地主机 codex app-server，并调用：

• skills/list
• skills/config/write

脚本会将应用模式备份保存到：

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

工作流

1. 运行 list，获取当前启用、停用和总技能数。
2. 运行 audit-unused --days 30，检查近期可信度较高的使用记录。
3. 可选：添加 --max-uses N，以纳入低频技能。例如：--days 10 --max-uses 2 会筛选近期会话／来源文件中使用次数不超过 2 次的已启用技能。
4. 运行 disable-unused --days 30，不要添加 --apply，并检查试运行输出。
5. 如果用户要求关闭未使用或低频技能，则运行 disable-unused --apply。
6. 使用 verify 验证，或使用 list --force-reload 加 prompt-count 验证。
7. 报告数量、备份路径、阈值参数，以及使用记录的任何局限。

默认保留系统技能。只有用户明确要求同时考虑系统技能时，才使用 --include-system。

Codex 桌面应用的 Skills 选项卡显示的是发现的技能总数。停用技能后该数量预计不会变化。请将 enabledCount 和 availableSkillCount 作为令牌加载是否成功的指标。

使用情况证据

审计有意采取保守策略：

• 仅当 function_call 或 custom_tool_call 包含实际文件读取操作时，才计为读取。解析 functions.exec 包装器中的 cat 和 sed 等读取命令；结构化读取工具则从其路径输入中解析。
• 必须有匹配的工具结果。结果标记为成功、退出代码为 0，或包含非空输出时，计为 success；失败结果绝不计为使用。
• 按请求的时间范围筛选每个事件的时间戳。会话文件较新，并不代表其中的旧事件也较新。缺失或无法解析的时间戳会报告为 unknown，且不计为使用。
• usageCount 统计不同的证据会话/源文件数。同一会话中重复成功读取会增加 evidenceCount，但不会增加 usageCount。
• 将失败、未匹配、未知和不支持的读取意图分别保存在审计字段中。在证据可分类之前，这些记录会阻止受影响的已启用 Skill 成为禁用候选项。
• 忽略文本中的提及、常规审计/可用 Skills 列表中的 SKILL.md 路径，以及没有结构化工具事件的 OMO 特征。只有保留相同调用/结果证据的 OMO 事件才会计入。

这些是本地证据，并非产品 Profile 页面上的服务端分析数据。

audit-unused 和 disable-unused 接受可重复使用的 --exclude-session PATH 参数。设置后，它们也会读取 CODEX_SKILL_ADMIN_SESSION、CODEX_SESSION_FILE、CODEX_SESSION_PATH、CODEX_SESSION_ID 和 CODEX_THREAD_ID，因此无需复制私有会话数据即可排除当前审计会话。默认的 --exclude-current-audit 设置会忽略调用此脚本自身 audit-unused 或 disable-unused 命令的调用；只有在检查该调用本身时才使用 --no-exclude-current-audit。被排除的会话会计入 excludedSessionCount，且不会贡献证据。

审计 JSON 保留现有的 usedEnabled、disableCandidates、usageCount 和 evidenceCount 字段。此外，它还会报告每个路径的 readIntent、unknown、failed 和 unsupported 证据，以及 uncertainEnabled、rawReadIntentSkillPathCount、rawUnknownSkillPathCount、rawFailedSkillPathCount、unsupportedEvidenceCount、outsideWindowCount 和 missingTimestampCount。disableCandidates 包含没有已证实使用记录且没有不确定读取意图的已启用 Skills；不确定或不支持的记录绝不会被悄然当作零使用处理。

如果同一 Skill 通过多个等效路径出现，请在审计前设置路径别名：

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

多个别名请使用平台的路径分隔符。

验证

应用后：

1. 运行 verify --cwd "$PWD"。
2. 确认 enabledCount 已下降，且目标 Skills 出现在 list --force-reload --disabled 中。
3. 如果禁用的 Skills 之前在提示词中可见，请确认 availableSkillCount 与运行前相比已下降。
4. 请勿根据桌面 UI 标签页数量判断 Token 节省情况；该数量统计发现的全部 Skills，包括已禁用的 Skills。
5. 如果结果不正确，请使用应用输出中的备份路径运行 restore --backup-dir <backupDir>。

备份文件包含本地 Skill 路径和使用情况证据。请将其视为私有的本机诊断数据。

还原

还原之前的禁用操作：

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"

直接设置

仅在列出或以其他方式确认目标名称/路径后，才使用 set 单独切换特定 Skill：

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

不加 --apply 时，set 会打印试运行结果，不会写入任何内容。

手动协议说明

只有在脚本失败或 Codex app-server 协议发生变化时，才阅读 references/app-server-protocol.md。