codex-skill-admin

Codex スキル管理

Codex の公式スキル設定 API を使用してください。スキルを無効化するために SKILL.md のフロントマターを編集しないでください。また、ユーザーから明示的にアンインストールを依頼されない限り、プラグインをアンインストールしないでください。

クイックスタート

通常の作業には、同梱のスクリプトを使用してください。

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"

スクリプトは一時的な localhost 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. --apply を付けずに disable-unused --days 30 を実行し、ドライランの出力を確認します。
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 のタブ数を使用しないでください。この数には、無効化されたものを含む、検出されたすべての 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"

直接設定

特定の skill の切り替えには、一覧表示するか、対象の名前／パスを別の方法で確認してから set を使用してください。

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 を読みます。